<varname>After=</varname> on
<filename>dbus.socket</filename>.</para>
- <para>Socket activated service are automatically ordered after
- their activated <filename>.socket</filename> units via an
- automatic <varname>After=</varname> dependency.</para>
-
- <para>Unless <varname>DefaultDependencies=</varname> is set to
- <option>false</option>, service units will implicitly have
- dependencies of type <varname>Requires=</varname> and
- <varname>After=</varname> on <filename>sysinit.target</filename>,
- a dependency of type <varname>After=</varname> on
- <filename>basic.target</filename> as well as dependencies of
- type <varname>Conflicts=</varname> and <varname>Before=</varname>
- on <filename>shutdown.target</filename>. These ensure that normal
- service units pull in basic system initialization, and are
- terminated cleanly prior to system shutdown. Only services
- involved with early boot or late system shutdown should disable
- this option.</para>
+ <para>Socket activated services are automatically ordered after
+ their activating <filename>.socket</filename> units via an
+ automatic <varname>After=</varname> dependency.
+ Services also pull in all <filename>.socket</filename> units
+ listed in <varname>Sockets=</varname> via automatic
+ <varname>Wants=</varname> and <varname>After=</varname> dependencies.</para>
+
+ <para>Unless <varname>DefaultDependencies=</varname> in the <literal>[Unit]</literal> is set to
+ <option>false</option>, service units will implicitly have dependencies of type <varname>Requires=</varname> and
+ <varname>After=</varname> on <filename>sysinit.target</filename>, a dependency of type <varname>After=</varname> on
+ <filename>basic.target</filename> as well as dependencies of type <varname>Conflicts=</varname> and
+ <varname>Before=</varname> on <filename>shutdown.target</filename>. These ensure that normal service units pull in
+ basic system initialization, and are terminated cleanly prior to system shutdown. Only services involved with early
+ boot or late system shutdown should disable this option.</para>
+
+ <para>Instanced service units (i.e. service units with an <literal>@</literal> in their name) are assigned by
+ default a per-template slice unit (see
+ <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>), named after the
+ template unit, containing all instances of the specific template. This slice is normally stopped at shutdown,
+ together with all template instances. If that is not desired, set <varname>DefaultDependencies=no</varname> in the
+ template unit, and either define your own per-template slice unit file that also sets
+ <varname>DefaultDependencies=no</varname>, or set <varname>Slice=system.slice</varname> (or another suitable slice)
+ in the template unit. Also see
+ <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
<para>Additional implicit dependencies may be added as result of
execution and resource control parameters as documented in
notification message has been sent. If this option is used,
<varname>NotifyAccess=</varname> (see below) should be set to
open access to the notification socket provided by systemd. If
- <varname>NotifyAccess=</varname> is not set, it will be
- implicitly set to <option>main</option>. Note that currently
+ <varname>NotifyAccess=</varname> is missing or set to
+ <option>none</option>, it will be forcibly set to
+ <option>main</option>. Note that currently
<varname>Type=</varname><option>notify</option> will not work
if used in combination with
<varname>PrivateNetwork=</varname><option>yes</option>.</para>
- <para>Behavior of <option>idle</option> is very similar to
- <option>simple</option>; however, actual execution of the
- service binary is delayed until all jobs are dispatched. This
- may be used to avoid interleaving of output of shell services
- with the status output on the console.</para>
+ <para>Behavior of <option>idle</option> is very similar to <option>simple</option>; however, actual execution
+ of the service binary is delayed until all active jobs are dispatched. This may be used to avoid interleaving
+ of output of shell services with the status output on the console. Note that this type is useful only to
+ improve console output, it is not useful as a general unit ordering tool, and the effect of this service type
+ is subject to a 5s time-out, after which the service binary is invoked anyway.</para>
</listitem>
</varlistentry>
</listitem>
</varlistentry>
- <varlistentry>
- <term><varname>BusPolicy=</varname></term>
-
- <listitem><para>If specified, a custom kdbus
- endpoint will be created and installed as the default bus node
- for the service. Such a custom endpoint can hold an own set of
- policy rules that are enforced on top of the bus-wide ones.
- The custom endpoint is named after the service it was created
- for, and its node will be bind-mounted over the default bus
- node location, so the service can only access the bus through
- its own endpoint. Note that custom bus endpoints default to a
- "deny all" policy. Hence, if at least one
- <varname>BusPolicy=</varname> directive is given, you have to
- make sure to add explicit rules for everything the service
- should be able to do.</para>
- <para>The value of this directive is comprised
- of two parts; the bus name, and a verb to
- specify to granted access, which is one of
- <option>see</option>,
- <option>talk</option>, or
- <option>own</option>.
- <option>talk</option> implies
- <option>see</option>, and <option>own</option>
- implies both <option>talk</option> and
- <option>see</option>.
- If multiple access levels are specified for the
- same bus name, the most powerful one takes
- effect.
- </para>
- <para>Examples:</para>
- <programlisting>BusPolicy=org.freedesktop.systemd1 talk</programlisting>
- <programlisting>BusPolicy=org.foo.bar see</programlisting>
- <para>This option is only available on kdbus enabled systems.</para>
- </listitem>
- </varlistentry>
-
<varlistentry>
<term><varname>ExecStart=</varname></term>
<listitem><para>Commands with their arguments that are
below (see section "Command Lines" below).
</para>
- <para>When <varname>Type=</varname> is not
- <option>oneshot</option>, only one command may and must be
- given. When <varname>Type=oneshot</varname> is used, zero or
- more commands may be specified. This can be specified by
- providing multiple command lines in the same directive, or
- alternatively, this directive may be specified more than once
- with the same effect. If the empty string is assigned to this
- option, the list of commands to start is reset, prior
- assignments of this option will have no effect. If no
- <varname>ExecStart=</varname> is specified, then the service
- must have <varname>RemainAfterExit=yes</varname> set.</para>
-
- <para>For each of the specified commands, the first argument
- must be an absolute path to an executable. Optionally, if this
- file name is prefixed with <literal>@</literal>, the second
- token will be passed as <literal>argv[0]</literal> to the
- executed process, followed by the further arguments specified.
- If the absolute filename is prefixed with
- <literal>-</literal>, an exit code of the command normally
- considered a failure (i.e. non-zero exit status or abnormal
- exit due to signal) is ignored and considered success. If both
- <literal>-</literal> and <literal>@</literal> are used, they
- can appear in either order.</para>
+ <para>Unless <varname>Type=</varname> is <option>oneshot</option>, exactly one command must be given. When
+ <varname>Type=oneshot</varname> is used, zero or more commands may be specified. Commands may be specified by
+ providing multiple command lines in the same directive, or alternatively, this directive may be specified more
+ than once with the same effect. If the empty string is assigned to this option, the list of commands to start
+ is reset, prior assignments of this option will have no effect. If no <varname>ExecStart=</varname> is
+ specified, then the service must have <varname>RemainAfterExit=yes</varname> and at least one
+ <varname>ExecStop=</varname> line set. (Services lacking both <varname>ExecStart=</varname> and
+ <varname>ExecStop=</varname> are not valid.)</para>
+
+ <para>For each of the specified commands, the first argument must be an absolute path to an
+ executable. Optionally, if this file name is prefixed with <literal>@</literal>, the second token will be
+ passed as <literal>argv[0]</literal> to the executed process, followed by the further arguments specified. If
+ the absolute filename is prefixed with <literal>-</literal>, an exit code of the command normally considered a
+ failure (i.e. non-zero exit status or abnormal exit due to signal) is ignored and considered success. If the
+ absolute path is prefixed with <literal>+</literal> then it is executed with full
+ privileges. <literal>@</literal>, <literal>-</literal>, and <literal>+</literal> may be used together and they
+ can appear in any order.</para>
<para>If more than one command is specified, the commands are
invoked sequentially in the order they appear in the unit
with a <literal>-</literal> exit successfully.</para>
<para><varname>ExecStartPost=</varname> commands are only run after
- the service has started, as determined by <varname>Type=</varname>
+ the service has started successfully, as determined by <varname>Type=</varname>
(i.e. the process has been started for <varname>Type=simple</varname>
or <varname>Type=idle</varname>, the process exits successfully for
<varname>Type=oneshot</varname>, the initial process exits successfully
used to start long-running processes. All processes forked
off by processes invoked via <varname>ExecStartPre=</varname> will
be killed before the next service process is run.</para>
+
+ <para>Note that if any of the commands specified in <varname>ExecStartPre=</varname>,
+ <varname>ExecStart=</varname>, or <varname>ExecStartPost=</varname> fail (and are not prefixed with
+ <literal>-</literal>, see above) or time out before the service is fully up, execution continues with commands
+ specified in <varname>ExecStopPost=</varname>, the commands in <varname>ExecStop=</varname> are skipped.</para>
</listitem>
</varlistentry>
variable substitution is supported (including
<varname>$MAINPID</varname>, see above).</para>
- <para>Note that it is usually not sufficient to specify a
- command for this setting that only asks the service to
- terminate (for example, by queuing some form of termination
- signal for it), but does not wait for it to do so. Since the
- remaining processes of the services are killed using
- <constant>SIGKILL</constant> immediately after the command
- exited, this would not result in a clean stop. The specified
- command should hence be a synchronous operation, not an
- asynchronous one.</para></listitem>
+ <para>Note that it is usually not sufficient to specify a command for this setting that only asks the service
+ to terminate (for example, by queuing some form of termination signal for it), but does not wait for it to do
+ so. Since the remaining processes of the services are killed according to <varname>KillMode=</varname> and
+ <varname>KillSignal=</varname> as described above immediately after the command exited, this may not result in
+ a clean stop. The specified command should hence be a synchronous operation, not an asynchronous one.</para>
+
+ <para>Note that the commands specified in <varname>ExecStop=</varname> are only executed when the service
+ started successfully first. They are not invoked if the service was never started at all, or in case its
+ start-up failed, for example because any of the commands specified in <varname>ExecStart=</varname>,
+ <varname>ExecStartPre=</varname> or <varname>ExecStartPost=</varname> failed (and weren't prefixed with
+ <literal>-</literal>, see above) or timed out. Use <varname>ExecStopPost=</varname> to invoke commands when a
+ service failed to start up correctly and is shut down again.</para>
+
+ <para>It is recommended to use this setting for commands that communicate with the service requesting clean
+ termination. When the commands specified with this option are executed it should be assumed that the service is
+ still fully up and is able to react correctly to all commands. For post-mortem clean-up steps use
+ <varname>ExecStopPost=</varname> instead.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>ExecStopPost=</varname></term>
- <listitem><para>Additional commands that are executed after
- the service was stopped. This includes cases where the
- commands configured in <varname>ExecStop=</varname> were used,
- where the service does not have any
- <varname>ExecStop=</varname> defined, or where the service
- exited unexpectedly. This argument takes multiple command
- lines, following the same scheme as described for
- <varname>ExecStart=</varname>. Use of these settings is
- optional. Specifier and environment variable substitution is
- supported.</para></listitem>
+ <listitem><para>Additional commands that are executed after the service is stopped. This includes cases where
+ the commands configured in <varname>ExecStop=</varname> were used, where the service does not have any
+ <varname>ExecStop=</varname> defined, or where the service exited unexpectedly. This argument takes multiple
+ command lines, following the same scheme as described for <varname>ExecStart=</varname>. Use of these settings
+ is optional. Specifier and environment variable substitution is supported. Note that – unlike
+ <varname>ExecStop=</varname> – commands specified with this setting are invoked when a service failed to start
+ up correctly and is shut down again.</para>
+
+ <para>It is recommended to use this setting for clean-up operations that shall be executed even when the
+ service failed to start up correctly. Commands configured with this setting need to be able to operate even if
+ the service failed starting up half-way and left incompletely initialized data around. As the service's
+ processes have been terminated already when the commands specified with this setting are executed they should
+ not attempt to communicate with them.</para>
+
+ <para>Note that all commands that are configured with this setting are invoked with the result code of the
+ service, as well as the main process' exit code and status, set in the <varname>$SERVICE_RESULT</varname>,
+ <varname>$EXIT_CODE</varname> and <varname>$EXIT_STATUS</varname> environment variables, see
+ <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
+ details.</para></listitem>
</varlistentry>
<varlistentry>
configured time, the service will be considered failed and
will be shut down again. Takes a unit-less value in seconds,
or a time span value such as "5min 20s". Pass
- <literal>0</literal> to disable the timeout logic. Defaults to
+ <literal>infinity</literal> to disable the timeout logic. Defaults to
<varname>DefaultTimeoutStartSec=</varname> from the manager
configuration file, except when
<varname>Type=oneshot</varname> is used, in which case the
<varname>KillMode=</varname> in
<citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
Takes a unit-less value in seconds, or a time span value such
- as "5min 20s". Pass <literal>0</literal> to disable the
+ as "5min 20s". Pass <literal>infinity</literal> to disable the
timeout logic. Defaults to
<varname>DefaultTimeoutStopSec=</varname> from the manager
configuration file (see
</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>RuntimeMaxSec=</varname></term>
+
+ <listitem><para>Configures a maximum time for the service to run. If this is used and the service has been
+ active for longer than the specified time it is terminated and put into a failure state. Note that this setting
+ does not have any effect on <varname>Type=oneshot</varname> services, as they terminate immediately after
+ activation completed. Pass <literal>infinity</literal> (the default) to configure no runtime
+ limit.</para></listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>WatchdogSec=</varname></term>
<listitem><para>Configures the watchdog timeout for a service.
or signal is specified in
<varname>RestartForceExitStatus=</varname> (see below).</para>
+ <para>Note that service restart is subject to unit start rate
+ limiting configured with <varname>StartLimitIntervalSec=</varname>
+ and <varname>StartLimitBurst=</varname>, see
+ <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for details.</para>
+
<para>Setting this to <option>on-failure</option> is the
recommended choice for long-running services, in order to
increase reliability by attempting automatic recovery from
notification socket, as accessible via the
<citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
call. Takes one of <option>none</option> (the default),
- <option>main</option> or <option>all</option>. If
- <option>none</option>, no daemon status updates are accepted
- from the service processes, all status update messages are
- ignored. If <option>main</option>, only service updates sent
- from the main process of the service are accepted. If
+ <option>main</option>, <option>exec</option> or
+ <option>all</option>. If <option>none</option>, no daemon status
+ updates are accepted from the service processes, all status
+ update messages are ignored. If <option>main</option>, only
+ service updates sent from the main process of the service are
+ accepted. If <option>exec</option>, only service updates sent
+ from any of the control processes originating from one of the
+ <varname>Exec*=</varname> commands are accepted. If
<option>all</option>, all services updates from all members of
the service's control group are accepted. This option should
be set to open access to the notification socket when using
effect.</para></listitem>
</varlistentry>
- <varlistentry>
- <term><varname>StartLimitInterval=</varname></term>
- <term><varname>StartLimitBurst=</varname></term>
-
- <listitem><para>Configure service start rate limiting. By
- default, services which are started more than 5 times within
- 10 seconds are not permitted to start any more times until the
- 10 second interval ends. With these two options, this rate
- limiting may be modified. Use
- <varname>StartLimitInterval=</varname> to configure the
- checking interval (defaults to
- <varname>DefaultStartLimitInterval=</varname> in manager
- configuration file, set to 0 to disable any kind of rate
- limiting). Use <varname>StartLimitBurst=</varname> to
- configure how many starts per interval are allowed (defaults
- to <varname>DefaultStartLimitBurst=</varname> in manager
- configuration file). These configuration options are
- particularly useful in conjunction with
- <varname>Restart=</varname>; however, they apply to all kinds
- of starts (including manual), not just those triggered by the
- <varname>Restart=</varname> logic. Note that units which are
- configured for <varname>Restart=</varname> and which reach the
- start limit are not attempted to be restarted anymore;
- however, they may still be restarted manually at a later
- point, from which point on, the restart logic is again
- activated. Note that <command>systemctl reset-failed</command>
- will cause the restart rate counter for a service to be
- flushed, which is useful if the administrator wants to
- manually start a service and the start limit interferes with
- that.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>StartLimitAction=</varname></term>
-
- <listitem><para>Configure the action to take if the rate limit
- configured with <varname>StartLimitInterval=</varname> and
- <varname>StartLimitBurst=</varname> is hit. Takes one of
- <option>none</option>,
- <option>reboot</option>,
- <option>reboot-force</option>,
- <option>reboot-immediate</option>,
- <option>poweroff</option>,
- <option>poweroff-force</option> or
- <option>poweroff-immediate</option>. If
- <option>none</option> is set, hitting the rate limit will
- trigger no action besides that the start will not be
- permitted. <option>reboot</option> causes a reboot following
- the normal shutdown procedure (i.e. equivalent to
- <command>systemctl reboot</command>).
- <option>reboot-force</option> causes a forced reboot which
- will terminate all processes forcibly but should cause no
- dirty file systems on reboot (i.e. equivalent to
- <command>systemctl reboot -f</command>) and
- <option>reboot-immediate</option> causes immediate execution
- of the
- <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
- system call, which might result in data loss. Similarly,
- <option>poweroff</option>, <option>poweroff-force</option>,
- <option>poweroff-immediate</option> have the effect of
- powering down the system with similar semantics. Defaults to
- <option>none</option>.</para></listitem>
- </varlistentry>
-
<varlistentry>
<term><varname>FailureAction=</varname></term>
- <listitem><para>Configure the action to take when the service
- enters a failed state. Takes the same values as
- <varname>StartLimitAction=</varname> and executes the same
- actions. Defaults to <option>none</option>. </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>RebootArgument=</varname></term>
- <listitem><para>Configure the optional argument for the
- <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
- system call if <varname>StartLimitAction=</varname> or
- <varname>FailureAction=</varname> is a reboot action. This
- works just like the optional argument to <command>systemctl
- reboot</command> command.</para></listitem>
+ <listitem><para>Configure the action to take when the service enters a failed state. Takes the same values as
+ the unit setting <varname>StartLimitAction=</varname> and executes the same actions (see
+ <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>). Defaults to
+ <option>none</option>. </para></listitem>
</varlistentry>
<varlistentry>
serialized to <filename>/run</filename> and the file
descriptors passed to the service manager, to allow restarts
without losing state. Defaults to 0, i.e. no file descriptors
- may be stored in the service manager by default. All file
+ may be stored in the service manager. All file
descriptors passed to the service manager from a specific
service are passed back to the service's main process on the
next service restart. Any file descriptors passed to the
service manager are automatically closed when POLLHUP or
POLLERR is seen on them, or when the service is fully stopped
- and no job queued or being executed for it.</para></listitem>
+ and no job is queued or being executed for it.</para></listitem>
</varlistentry>
<varlistentry>
must be passed as separate words). Lone semicolons may be escaped
as <literal>\;</literal>.</para>
- <para>Each command line is split on whitespace, with the first
- item being the command to execute, and the subsequent items being
- the arguments. Double quotes ("...") and single quotes ('...') may
- be used, in which case everything until the next matching quote
- becomes part of the same argument. C-style escapes are also
- supported. The table below contains the list of allowed escape
- patterns. Only patterns which match the syntax in the table are
- allowed; others will result in an error, and must be escaped by
- doubling the backslash. Quotes themselves are removed after
- parsing and escape sequences substituted. In addition, a trailing
- backslash (<literal>\</literal>) may be used to merge lines.
- </para>
+ <para>Each command line is split on whitespace, with the first item being the command to
+ execute, and the subsequent items being the arguments. Double quotes ("…") and single quotes
+ ('…') may be used, in which case everything until the next matching quote becomes part of the
+ same argument. Quotes themselves are removed. C-style escapes are also supported. The table
+ below contains the list of known escape patterns. Only escape patterns which match the syntax in
+ the table are allowed; other patterns may be added in the future and unknown patterns will
+ result in a warning. In particular, any backslashes should be doubled. Finally, a trailing
+ backslash (<literal>\</literal>) may be used to merge lines.</para>
<para>This syntax is intended to be very similar to shell syntax,
but only the meta-characters and expansions described in the
projects / thirdparty / systemd.git / blobdiff