<?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>
actual execution of the service program 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 program is invoked
+ effect of this service type is subject to a 5s timeout, after which the service program is invoked
anyway.</para></listitem>
</itemizedlist>
<varlistentry>
<term><varname>PIDFile=</varname></term>
- <listitem><para>Takes an absolute path referring to the PID file of the service. Usage of this option is
- recommended for services where <varname>Type=</varname> is set to <option>forking</option>. The service manager
- will read the PID of the main process of the service from this file after start-up of the service. The service
- manager will not write to the file configured here, although it will remove the file after the service has shut
- down if it still exists. The PID file does not need to be owned by a privileged user, but if it is owned by an
- unprivileged user additional safety restrictions are enforced: the file may not be a symlink to a file owned by
- a different user (neither directly nor indirectly), and the PID file must refer to a process already belonging
- to the service.</para></listitem>
+ <listitem><para>Takes a path referring to the PID file of the service. Usage of this option is recommended for
+ services where <varname>Type=</varname> is set to <option>forking</option>. The path specified typically points
+ to a file below <filename>/run/</filename>. If a relative path is specified it is hence prefixed with
+ <filename>/run/</filename>. The service manager will read the PID of the main process of the service from this
+ file after start-up of the service. The service manager will not write to the file configured here, although it
+ will remove the file after the service has shut down if it still exists. The PID file does not need to be owned
+ by a privileged user, but if it is owned by an unprivileged user additional safety restrictions are enforced:
+ the file may not be a symlink to a file owned by a different user (neither directly nor indirectly), and the
+ PID file must refer to a process already belonging to the service.</para></listitem>
</varlistentry>
<varlistentry>
<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>
<varname>RestartPreventExitStatus=</varname>.</para></listitem>
</varlistentry>
- <varlistentry>
- <term><varname>PermissionsStartOnly=</varname></term>
- <listitem><para>Takes a boolean argument. If true, the
- permission-related execution options, as configured with
- <varname>User=</varname> and similar options (see
- <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- for more information), are only applied to the process started
- with
- <varname>ExecStart=</varname>, and not to the various other
- <varname>ExecStartPre=</varname>,
- <varname>ExecStartPost=</varname>,
- <varname>ExecReload=</varname>,
- <varname>ExecStop=</varname>, and
- <varname>ExecStopPost=</varname>
- commands. If false, the setting is applied to all configured
- commands the same way. Defaults to false.</para></listitem>
- </varlistentry>
-
<varlistentry>
<term><varname>RootDirectoryStartOnly=</varname></term>
<listitem><para>Takes a boolean argument. If true, the root
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
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<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