<?xml version='1.0'?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-
-<!--
- SPDX-License-Identifier: LGPL-2.1+
--->
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
<refentry id="systemd.service">
<refentryinfo>
about the incompatibilities, see the <ulink
url="https://www.freedesktop.org/wiki/Software/systemd/Incompatibilities">Incompatibilities
with SysV</ulink> document.</para>
+
+ <para>The <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ command allows creating <filename>.service</filename> and <filename>.scope</filename> units dynamically
+ and transiently from the command line.</para>
</refsect1>
<refsect1>
<entry>If the executable path 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 recorded, but has no further effect and is considered equivalent to success.</entry>
</row>
+ <row>
+ <entry><literal>:</literal></entry>
+ <entry>If the executable path is prefixed with <literal>:</literal>, environment variable substitution (as described by the "Command Lines" section below) is not applied.</entry>
+ </row>
+
<row>
<entry><literal>+</literal></entry>
<entry>If the executable path is prefixed with <literal>+</literal> then the process is executed with full privileges. In this mode privilege restrictions configured with <varname>User=</varname>, <varname>Group=</varname>, <varname>CapabilityBoundingSet=</varname> or the various file system namespacing options (such as <varname>PrivateDevices=</varname>, <varname>PrivateTmp=</varname>) are not applied to the invoked command line (but still affect any other <varname>ExecStart=</varname>, <varname>ExecStop=</varname>, … lines).</entry>
</tgroup>
</table>
- <para><literal>@</literal>, <literal>-</literal>, and one of
+ <para><literal>@</literal>, <literal>-</literal>, <literal>:</literal>, and one of
<literal>+</literal>/<literal>!</literal>/<literal>!!</literal> may be used together and they can appear in any
order. However, only one of <literal>+</literal>, <literal>!</literal>, <literal>!!</literal> may be used at a
time. Note that these prefixes are also supported for the other command line settings,
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. Also note that, service restart requests are
- implemented as stop operations followed by start operations. This means that <varname>ExecStop=</varname> and
- <varname>ExecStopPost=</varname> are executed during a service restart operation.</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>
+ service failed to start up correctly and is shut down again. Also note that the stop operation is always
+ performed if the service started successfully, even if the processes in the service terminated on their
+ own or were killed. The stop commands must be prepared to deal with that case. <varname>$MAINPID</varname>
+ will be unset if systemd knows that the main process exited by the time the stop commands are called.</para>
+
+ <para>Service restart requests are implemented as stop operations followed by start operations. This
+ means that <varname>ExecStop=</varname> and <varname>ExecStopPost=</varname> are executed during a
+ service restart operation.</para>
+
+ <para>It is recommended to use this setting for commands that communicate with the service requesting
+ clean termination. For post-mortem clean-up steps use <varname>ExecStopPost=</varname> instead.
+ </para></listitem>
</varlistentry>
<varlistentry>
</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
<varlistentry>
<term><varname>RestartPreventExitStatus=</varname></term>
- <listitem><para>Takes a list of exit status definitions that,
- when returned by the main service process, will prevent
- automatic service restarts, regardless of the restart setting
- configured with <varname>Restart=</varname>. Exit status
- definitions can either be numeric exit codes or termination
- signal names, and are separated by spaces. Defaults to the
- empty list, so that, by default, no exit status is excluded
- from the configured restart logic. For example:
+
+ <listitem><para>Takes a list of exit status definitions that, when returned by the main service
+ process, will prevent automatic service restarts, regardless of the restart setting configured with
+ <varname>Restart=</varname>. Exit status definitions can either be numeric exit codes or termination
+ signal names, and are separated by spaces. Defaults to the empty list, so that, by default, no exit
+ status is excluded from the configured restart logic. For example:
<programlisting>RestartPreventExitStatus=1 6 SIGABRT</programlisting>
- ensures that exit codes 1 and 6 and the termination signal
- <constant>SIGABRT</constant> will not result in automatic
- service restarting. This option may appear more than once, in
- which case the list of restart-preventing statuses is
- merged. If the empty string is assigned to this option, the
- list is reset and all prior assignments of this option will
- have no effect.</para></listitem>
+ ensures that exit codes 1 and 6 and the termination signal <constant>SIGABRT</constant> will not
+ result in automatic service restarting. This option may appear more than once, in which case the list
+ of restart-preventing statuses is merged. If the empty string is assigned to this option, the list is
+ reset and all prior assignments of this option will have no effect.</para>
+
+ <para>Note that this setting has no effect on processes configured via
+ <varname>ExecStartPre=</varname>, <varname>ExecStartPost=</varname>, <varname>ExecStop=</varname>,
+ <varname>ExecStopPost=</varname> or <varname>ExecReload=</varname>, but only on the main service
+ process, i.e. either the one invoked by <varname>ExecStart=</varname> or (depending on
+ <varname>Type=</varname>, <varname>PIDFile=</varname>, …) the otherwise configured main
+ process.</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
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>
</para>
</refsect1>
projects / thirdparty / systemd.git / blobdiff