</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>
+
<varlistentry>
<term><varname>ExecReload=</varname></term>
<listitem><para>Commands to execute to trigger a configuration
<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
<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>
+ <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. 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
</para></listitem>
</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>
- </varlistentry>
-
<varlistentry>
<term><varname>RuntimeMaxSec=</varname></term>
<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>
+ <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 be
+ numeric exit codes, termination code 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 codes 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>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>
+ effect.</para>
+
+ <example>
+ <title>A service with with the the <varname>SuccessExitStatus=</varname> setting</title>
+
+ <programlisting>SuccessExitStatus=TEMPFAIL 250 SIGUSR1</programlisting>
+
+ <para>Exit codes 75 (<constant>TEMPFAIL</constant>), 250, and the termination signal
+ <constant>SIGKILL</constant> are considered clean service terminations.</para>
+ </example>
+
+ <para>Note: <command>systemd-analyze exit-codes</command> may be used to list exit
+ codes and translate between numerical code values and names.</para></listitem>
</varlistentry>
<varlistentry>
<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>
projects / thirdparty / systemd.git / blobdiff