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 continously. 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
</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
</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>TimeoutAbortSec=</varname></term>
+ <listitem><para>This option configures the time to wait for the service to terminate when it was aborted due to a
+ watchdog timeout (see <varname>WatchdogSec=</varname>). If the service has a short <varname>TimeoutStopSec=</varname>
+ this option can be used to give the system more time to write a core dump of the service. Upon expiration the service
+ will be forcibly terminated by <constant>SIGKILL</constant> (see <varname>KillMode=</varname> in
+ <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). The core file will
+ be truncated in this case. Use <varname>TimeoutAbortSec=</varname> to set a sensible timeout for the core dumping per
+ service that is large enough to write all expected data while also being short enough to handle the service failure
+ in due time.
+ </para>
+
+ <para>Takes a unit-less value in seconds, or a time span value such as "5min 20s". Pass an empty value to skip
+ the dedicated watchdog abort timeout handling and fall back <varname>TimeoutStopSec=</varname>. Pass
+ <literal>infinity</literal> to disable the timeout logic. Defaults to <varname>DefaultTimeoutAbortSec=</varname> from
+ the manager configuration file (see
+ <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
+ </para>
+
+ <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
+ <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>).
+ </para></listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>TimeoutSec=</varname></term>
<listitem><para>A shorthand for configuring both
</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></listitem>
</varlistentry>
<varlistentry>
inverse of the <varname>Sockets=</varname> setting of the
<filename>.service</filename> it refers to.</para>
- <para>This option may appear more than once, in which case the
- list of socket units is merged. If the empty string is
- assigned to this option, the list of sockets is reset, and all
- prior uses of this setting will have no
- effect.</para></listitem>
+ <para>This option may appear more than once, in which case the list of socket units is merged. Note
+ that once set, clearing the list of sockets again (for example, by assigning the empty string to this
+ option) is not supported.</para></listitem>
</varlistentry>
<varlistentry>
above.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>OOMPolicy=</varname></term>
+
+ <listitem><para>Configure the Out-Of-Memory (OOM) killer policy. On Linux, when memory becomes scarce
+ the kernel might decide to kill a running process in order to free up memory and reduce memory
+ pressure. This setting takes one of <constant>continue</constant>, <constant>stop</constant> or
+ <constant>kill</constant>. If set to <constant>continue</constant> and a process of the service is
+ killed by the kernel's OOM killer this is logged but the service continues running. If set to
+ <constant>stop</constant> the event is logged but the service is terminated cleanly by the service
+ 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
+ <constant>continue</constant>.</para>
+
+ <para>Use the <varname>OOMScoreAdjust=</varname> setting to configure whether processes of the unit
+ shall be considered preferred or less preferred candidates for process termination by the Linux OOM
+ killer logic. See
+ <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
+ details.</para></listitem>
+ </varlistentry>
+
</variablelist>
<para>Check
projects / thirdparty / systemd.git / blobdiff