<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for the common options of all unit configuration files. The common
configuration items are configured in the generic
- <literal>[Unit]</literal> and <literal>[Install]</literal>
+ [Unit] and [Install]
sections. The service specific configuration options are
- configured in the <literal>[Service]</literal> section.</para>
+ configured in the [Service] section.</para>
<para>Additional options are listed in
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<refsect1>
<title>Options</title>
- <para>Service files must include a <literal>[Service]</literal>
+ <para>Service files must include a [Service]
section, which carries information about the service and the
process it supervises. A number of options that may be used in
this section are shared with other unit types. These options are
<citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
and
<citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
- The options specific to the <literal>[Service]</literal> section
+ The options specific to the [Service] section
of service units are the following:</para>
<variablelist class='unit-directives'>
main process of the service. systemd will proceed with starting follow-up units as soon as the parent
process exits.</para></listitem>
- <listitem><para>Behavior of <option>oneshot</option> is similar to <option>simple</option>; however, the
- service manager will consider the unit started after the main process exits. It will then start follow-up
- units. <varname>RemainAfterExit=</varname> is particularly useful for this type of
- service. <varname>Type=</varname><option>oneshot</option> is the implied default if neither
- <varname>Type=</varname> nor <varname>ExecStart=</varname> are specified.</para></listitem>
+ <listitem><para>Behavior of <option>oneshot</option> is similar to <option>simple</option>;
+ however, the service manager will consider the unit up after the main process exits. It will then
+ start follow-up units. <varname>RemainAfterExit=</varname> is particularly useful for this type
+ of service. <varname>Type=</varname><option>oneshot</option> is the implied default if neither
+ <varname>Type=</varname> nor <varname>ExecStart=</varname> are specified. Note that if this
+ option is used without <varname>RemainAfterExit=</varname> the service will never enter
+ <literal>active</literal> unit state, but directly transition from <literal>activating</literal>
+ to <literal>deactivating</literal> or <literal>dead</literal> since no process is configured that
+ shall run continuously. In particular this means that after a service of this type ran (and which
+ has <varname>RemainAfterExit=</varname> not set) it will not show up as started afterwards, but
+ as dead.</para></listitem>
<listitem><para>Behavior of <option>dbus</option> is similar to <option>simple</option>; however, it is
expected that the service acquires a name on the D-Bus bus, as configured by
this 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 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></listitem>
+ <option>main</option>.</para></listitem>
<listitem><para>Behavior of <option>idle</option> is very similar to <option>simple</option>; however,
actual execution of the service program is delayed until all active jobs are dispatched. This may be used
<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>
+
+ <para>Note that the execution of <varname>ExecStartPost=</varname> is taken into account for the purpose of
+ <varname>Before=</varname>/<varname>After=</varname> ordering constraints.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>ExecCondition=</varname></term>
+ <listitem><para>Optional commands that are executed before the command(s) in <varname>ExecStartPre=</varname>.
+ Syntax is the same as for <varname>ExecStart=</varname>, except that multiple command lines are allowed and the
+ commands are executed one after the other, serially.</para>
+
+ <para>The behavior is like an <varname>ExecStartPre=</varname> and condition check hybrid: when an
+ <varname>ExecCondition=</varname> command exits with exit code 1 through 254 (inclusive), the remaining
+ commands are skipped and the unit is <emphasis>not</emphasis> marked as failed. However, if an
+ <varname>ExecCondition=</varname> command exits with 255 or abnormally (e.g. timeout, killed by a
+ signal, etc.), the unit will be considered failed (and remaining commands will be skipped). Exit code of 0 or
+ those matching <varname>SuccessExitStatus=</varname> will continue execution to the next command(s).</para>
+
+ <para>The same recommendations about not running long-running processes in <varname>ExecStartPre=</varname>
+ also applies to <varname>ExecCondition=</varname>. <varname>ExecCondition=</varname> will also run the commands
+ in <varname>ExecStopPost=</varname>, as part of stopping the service, in the case of any non-zero or abnormal
+ exits, like the ones described above.</para>
</listitem>
</varlistentry>
of the daemon, and may be used for command lines like the
following:</para>
- <programlisting>/bin/kill -HUP $MAINPID</programlisting>
+ <programlisting>ExecReload=kill -HUP $MAINPID</programlisting>
<para>Note however that reloading a daemon by sending a signal
(as with the example line above) is usually not a good choice,
other. It is strongly recommended to set
<varname>ExecReload=</varname> to a command that not only
triggers a configuration reload of the daemon, but also
- synchronously waits for it to complete.</para>
+ synchronously waits for it to complete. For example,
+ <citerefentry project='mankier'><refentrytitle>dbus-broker</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ uses the following:</para>
+
+ <programlisting>ExecReload=busctl call org.freedesktop.DBus \
+ /org/freedesktop/DBus org.freedesktop.DBus \
+ ReloadConfig
+</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>ExecStop=</varname></term>
- <listitem><para>Commands to execute to stop the service
- started via <varname>ExecStart=</varname>. This argument takes
- multiple command lines, following the same scheme as described
- for <varname>ExecStart=</varname> above. Use of this setting
- is optional. After the commands configured in this option are
- run, it is implied that the service is stopped, and any processes
- remaining for it are terminated
- according to the <varname>KillMode=</varname> setting (see
+ <listitem><para>Commands to execute to stop the service started via
+ <varname>ExecStart=</varname>. This argument takes multiple command lines, following the same scheme
+ as described for <varname>ExecStart=</varname> above. Use of this setting is optional. After the
+ commands configured in this option are run, it is implied that the service is stopped, and any
+ processes remaining for it are terminated according to the <varname>KillMode=</varname> setting (see
<citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
- If this option is not specified, the process is terminated by
- sending the signal specified in <varname>KillSignal=</varname>
- when service stop is requested. Specifier and environment
- variable substitution is supported (including
+ If this option is not specified, the process is terminated by sending the signal specified in
+ <varname>KillSignal=</varname> or <varname>RestartKillSignal=</varname> when service stop is
+ requested. Specifier and environment 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 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 it is usually not sufficient to specify a command for this setting that only asks the
+ service to terminate (for example, by sending some form of termination signal to 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> or
+ <varname>RestartKillSignal=</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
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>
+ details.</para>
+
+ <para>Note that the execution of <varname>ExecStopPost=</varname> is taken into account for the purpose of
+ <varname>Before=</varname>/<varname>After=</varname> ordering constraints.</para></listitem>
</varlistentry>
<varlistentry>
<varlistentry>
<term><varname>TimeoutStartSec=</varname></term>
- <listitem><para>Configures the time to wait for start-up. If a
- daemon service does not signal start-up completion within the
- 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>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
- timeout is disabled by default (see
+ <listitem><para>Configures the time to wait for start-up. If a daemon service does not signal start-up
+ completion within the configured time, the service will be considered failed and will be shut down again. The
+ precise action depends on the <varname>TimeoutStartFailureMode=</varname> option. Takes a unit-less value in
+ seconds, or a time span value such as "5min 20s". Pass <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 timeout is disabled by default (see
<citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
</para>
<para>If a service of <varname>Type=notify</varname> sends <literal>EXTEND_TIMEOUT_USEC=…</literal>, this may cause
the start time to be extended beyond <varname>TimeoutStartSec=</varname>. The first receipt of this message
- must occur before <varname>TimeoutStartSec=</varname> is exceeded, and once the start time has exended beyond
+ must occur before <varname>TimeoutStartSec=</varname> is exceeded, and once the start time has extended beyond
<varname>TimeoutStartSec=</varname>, the service manager will allow the service to continue to start, provided
the service repeats <literal>EXTEND_TIMEOUT_USEC=…</literal> within the interval specified until the service
startup status is finished by <literal>READY=1</literal>. (see
<varlistentry>
<term><varname>TimeoutStopSec=</varname></term>
<listitem><para>This option serves two purposes. First, it configures the time to wait for each
- <constant>ExecStop=</constant> command. If any of them times out, subsequent <constant>ExecStop=</constant> commands
- are skipped and the service will be terminated by <constant>SIGTERM</constant>. If no <constant>ExecStop=</constant>
- commands are specified, the service gets the <constant>SIGTERM</constant> immediately. Second, it configures the time
+ <varname>ExecStop=</varname> command. If any of them times out, subsequent <varname>ExecStop=</varname> commands
+ are skipped and the service will be terminated by <constant>SIGTERM</constant>. If no <varname>ExecStop=</varname>
+ commands are specified, the service gets the <constant>SIGTERM</constant> immediately. This default behavior
+ can be changed by the <varname>TimeoutStopFailureMode=</varname> option. Second, it configures the time
to wait for the service itself to stop. If it doesn't terminate in the specified time, it will be forcibly terminated
by <constant>SIGKILL</constant> (see <varname>KillMode=</varname> in
<citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
<para>If a service of <varname>Type=notify</varname> sends <literal>EXTEND_TIMEOUT_USEC=…</literal>, this may cause
the stop time to be extended beyond <varname>TimeoutStopSec=</varname>. The first receipt of this message
- must occur before <varname>TimeoutStopSec=</varname> is exceeded, and once the stop time has exended beyond
+ must occur before <varname>TimeoutStopSec=</varname> is exceeded, and once the stop time has extended beyond
<varname>TimeoutStopSec=</varname>, the service manager will allow the service to continue to stop, provided
the service repeats <literal>EXTEND_TIMEOUT_USEC=…</literal> within the interval specified, or terminates itself
(see <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>).
<para>If a service of <varname>Type=notify</varname> handles <constant>SIGABRT</constant> itself (instead of relying
on the kernel to write a core dump) it can send <literal>EXTEND_TIMEOUT_USEC=…</literal> to
extended the abort time beyond <varname>TimeoutAbortSec=</varname>. The first receipt of this message
- must occur before <varname>TimeoutAbortSec=</varname> is exceeded, and once the abort time has exended beyond
+ must occur before <varname>TimeoutAbortSec=</varname> is exceeded, and once the abort time has extended beyond
<varname>TimeoutAbortSec=</varname>, the service manager will allow the service to continue to abort, provided
the service repeats <literal>EXTEND_TIMEOUT_USEC=…</literal> within the interval specified, or terminates itself
(see <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>).
</varlistentry>
<varlistentry>
- <term><varname>TimeoutCleanSec=</varname></term>
- <listitem><para>Configures a timeout on the clean-up operation requested through <command>systemctl
- clean …</command>, see
- <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
- details. Takes the usual time values and defaults to <constant>infinity</constant>, i.e. by default
- no time-out is applied. If a time-out is configured the clean operation will be aborted forcibly when
- the time-out is reached, potentially leaving resources on disk.</para></listitem>
+ <term><varname>TimeoutStartFailureMode=</varname></term>
+ <term><varname>TimeoutStopFailureMode=</varname></term>
+
+ <listitem><para>These options configure the action that is taken in case a daemon service does not signal
+ start-up within its configured <varname>TimeoutStartSec=</varname>, respectively if it does not stop within
+ <varname>TimeoutStopSec=</varname>. Takes one of <option>terminate</option>, <option>abort</option> and
+ <option>kill</option>. Both options default to <option>terminate</option>.</para>
+
+ <para>If <option>terminate</option> is set the service will be gracefully terminated by sending the signal
+ specified in <varname>KillSignal=</varname> (defaults to <constant>SIGTERM</constant>, see
+ <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). If the
+ service does not terminate the <varname>FinalKillSignal=</varname> is sent after
+ <varname>TimeoutStopSec=</varname>. If <option>abort</option> is set, <varname>WatchdogSignal=</varname> is sent
+ instead and <varname>TimeoutAbortSec=</varname> applies before sending <varname>FinalKillSignal=</varname>.
+ This setting may be used to analyze services that fail to start-up or shut-down intermittently.
+ By using <option>kill</option> the service is immediately terminated by sending
+ <varname>FinalKillSignal=</varname> without any further timeout. This setting can be used to expedite the
+ shutdown of failing services.
+ </para></listitem>
</varlistentry>
<varlistentry>
<para>If a service of <varname>Type=notify</varname> sends <literal>EXTEND_TIMEOUT_USEC=…</literal>, this may cause
the runtime to be extended beyond <varname>RuntimeMaxSec=</varname>. The first receipt of this message
- must occur before <varname>RuntimeMaxSec=</varname> is exceeded, and once the runtime has exended beyond
+ must occur before <varname>RuntimeMaxSec=</varname> is exceeded, and once the runtime has extended beyond
<varname>RuntimeMaxSec=</varname>, the service manager will allow the service to continue to run, provided
the service repeats <literal>EXTEND_TIMEOUT_USEC=…</literal> within the interval specified until the service
shutdown is achieved by <literal>STOPPING=1</literal> (or termination). (see
<varlistentry>
<term><varname>SuccessExitStatus=</varname></term>
- <listitem><para>Takes a list of exit status definitions that,
- when returned by the main service process, will be considered
- successful termination, in addition to the normal successful
- exit code 0 and the signals <constant>SIGHUP</constant>,
- <constant>SIGINT</constant>, <constant>SIGTERM</constant>, and
- <constant>SIGPIPE</constant>. Exit status definitions can
- either be numeric exit codes or termination signal names,
- separated by spaces. For example:
-
- <programlisting>SuccessExitStatus=1 2 8 SIGKILL</programlisting>
-
- ensures that exit codes 1, 2, 8 and
- the termination signal <constant>SIGKILL</constant> are
- considered clean service terminations.
- </para>
- <para>This option may appear more than once, in which case the
- list of successful exit statuses is merged. If the empty
- string is assigned to this option, the list is reset, all
- prior assignments of this option will have no
- effect.</para></listitem>
+ <listitem><para>Takes a list of exit status definitions that, when returned by the main service
+ process, will be considered successful termination, in addition to the normal successful exit status
+ 0 and the signals <constant>SIGHUP</constant>, <constant>SIGINT</constant>,
+ <constant>SIGTERM</constant>, and <constant>SIGPIPE</constant>. Exit status definitions can be
+ numeric termination statuses, termination status names, or termination signal names, separated by
+ spaces. See the Process Exit Codes section in
+ <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
+ a list of termination status names (for this setting only the part without the
+ <literal>EXIT_</literal> or <literal>EX_</literal> prefix should be used). See <citerefentry
+ project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
+ a list of signal names.</para>
+
+ <para>Note that this setting does not change the mapping between numeric exit statuses and their
+ names, i.e. regardless how this setting is used 0 will still be mapped to <literal>SUCCESS</literal>
+ (and thus typically shown as <literal>0/SUCCESS</literal> in tool outputs) and 1 to
+ <literal>FAILURE</literal> (and thus typically shown as <literal>1/FAILURE</literal>), and so on. It
+ only controls what happens as effect of these exit statuses, and how it propagates to the state of
+ the service as a whole.</para>
+
+ <para>This option may appear more than once, in which case the list of successful exit statuses is
+ merged. If the empty string is assigned to this option, the list is reset, all prior assignments of
+ this option will have no effect.</para>
+
+ <example>
+ <title>A service with the <varname>SuccessExitStatus=</varname> setting</title>
+
+ <programlisting>SuccessExitStatus=TEMPFAIL 250 SIGUSR1</programlisting>
+
+ <para>Exit status 75 (<constant>TEMPFAIL</constant>), 250, and the termination signal
+ <constant>SIGUSR1</constant> are considered clean service terminations.</para>
+ </example>
+
+ <para>Note: <command>systemd-analyze exit-status</command> may be used to list exit statuses and
+ translate between numerical status values and names.</para></listitem>
</varlistentry>
<varlistentry>
<option>exec</option>. Conversely, if an auxiliary process of the unit sends an
<function>sd_notify()</function> message and immediately exits, the service manager might not be able to
properly attribute the message to the unit, and thus will ignore it, even if
- <varname>NotifyAccess=</varname><option>all</option> is set for it.</para></listitem>
+ <varname>NotifyAccess=</varname><option>all</option> is set for it.</para>
+
+ <para>Hence, to eliminate all race conditions involving lookup of the client's unit and attribution of notifications
+ to units correctly, <function>sd_notify_barrier()</function> may be used. This call acts as a synchronization point
+ and ensures all notifications sent before this call have been picked up by the service manager when it returns
+ successfully. Use of <function>sd_notify_barrier()</function> is needed for clients which are not invoked by the
+ service manager, otherwise this synchronization mechanism is unnecessary for attribution of notifications to the
+ unit.</para></listitem>
</varlistentry>
<varlistentry>
manager. If set to <constant>kill</constant> and one of the service's processes is killed by the OOM
killer the kernel is instructed to kill all remaining processes of the service, too. Defaults to the
setting <varname>DefaultOOMPolicy=</varname> in
- <citerefentry><refentrytitle>system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> is
- set to, except for services where <varname>Delegate=</varname> is turned on, where it defaults to
+ <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ is set to, except for services where <varname>Delegate=</varname> is turned on, where it defaults to
<constant>continue</constant>.</para>
<para>Use the <varname>OOMScoreAdjust=</varname> setting to configure whether processes of the unit
<para>Basic environment variable substitution is supported. Use
<literal>${FOO}</literal> as part of a word, or as a word of its
- own, on the command line, in which case it will be replaced by the
- value of the environment variable including all whitespace it
- contains, resulting in a single argument. Use
- <literal>$FOO</literal> as a separate word on the command line, in
+ own, on the command line, in which case it will be erased and replaced
+ by the exact value of the environment variable (if any) including all
+ whitespace it contains, always resulting in exactly a single argument.
+ Use <literal>$FOO</literal> as a separate word on the command line, in
which case it will be replaced by the value of the environment
variable split at whitespace, resulting in zero or more arguments.
For this type of expansion, quotes are respected when splitting
<para><varname>Type=</varname><option>oneshot</option> are the
only service units that may have more than one
- <varname>ExecStart=</varname> specified. They will be executed
- in order until either they are all successful or one of them
- fails.</para>
+ <varname>ExecStart=</varname> specified. For units with multiple
+ commands (<varname index="false">Type=oneshot</varname>), all commands will be run again.</para>
+ <para> For <varname index="false">Type=oneshot</varname>, <varname>Restart=</varname><option>always</option>
+ and <varname>Restart=</varname><option>on-success</option> are <emphasis>not</emphasis> allowed.</para>
</example>
<example>
WantedBy=multi-user.target</programlisting>
<para>For <emphasis>bus-activatable</emphasis> services, do not
- include a <literal>[Install]</literal> section in the systemd
+ include a [Install] section in the systemd
service file, but use the <varname>SystemdService=</varname>
option in the corresponding DBus service file, for example
(<filename>/usr/share/dbus-1/system-services/org.example.simple-dbus-service.service</filename>):</para>
projects / thirdparty / systemd.git / blobdiff