which configure resource control settings for the processes of the
service.</para>
- <para>If a service is requested under a certain name but no unit
- configuration file is found, systemd looks for a SysV init script
- by the same name (with the <filename>.service</filename> suffix
- removed) and dynamically creates a service unit from that script.
- This is useful for compatibility with SysV. Note that this
- compatibility is quite comprehensive but not 100%. For details
- about the incompatibilities, see the <ulink
- url="https://www.freedesktop.org/wiki/Software/systemd/Incompatibilities">Incompatibilities
- with SysV</ulink> document.</para>
+ <para>If SysV init compat is enabled, systemd automatically creates service units that wrap SysV init
+ scripts (the service name is the same as the name of the script, with a <literal>.service</literal>
+ suffix added); see
+ <citerefentry><refentrytitle>systemd-sysv-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
+ </para>
<para>The <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>
command allows creating <filename>.service</filename> and <filename>.scope</filename> units dynamically
<refsect1>
<title>Options</title>
- <para>Service files must include a [Service]
+ <para>Service unit files may include [Unit] and [Install] sections, which are described in
+ <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+ </para>
+
+ <para>Service unit 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
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>ExitType=</varname></term>
+
+ <listitem>
+ <para>Specifies when the manager should consider the service to be finished. One of <option>main</option> or
+ <option>cgroup</option>:</para>
+
+ <itemizedlist>
+ <listitem><para>If set to <option>main</option> (the default), the service manager
+ will consider the unit stopped when the main process, which is determined according to the
+ <varname>Type=</varname>, exits. Consequently, it cannot be used with
+ <varname>Type=</varname><option>oneshot</option>.</para></listitem>
+
+ <listitem><para>If set to <option>cgroup</option>, the service will be considered running as long as at
+ least one process in the cgroup has not exited.</para></listitem>
+ </itemizedlist>
+
+ <para>It is generally recommended to use <varname>ExitType=</varname><option>main</option> when a service has
+ a known forking model and a main process can reliably be determined. <varname>ExitType=</varname>
+ <option>cgroup</option> is meant for applications whose forking model is not known ahead of time and which
+ might not have a specific main process. It is well suited for transient or automatically generated services,
+ such as graphical applications inside of a desktop environment.</para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>RemainAfterExit=</varname></term>
</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>RuntimeRandomizedExtraSec=</varname></term>
+
+ <listitem><para>This option modifies <varname>RuntimeMaxSec=</varname> by increasing the maximum runtime by an
+ evenly distributed duration between 0 and the specified value (in seconds). If <varname>RuntimeMaxSec=</varname> is
+ unspecified, then this feature will be disabled.
+ </para></listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>WatchdogSec=</varname></term>
<listitem><para>Configures the watchdog timeout for a service.
If set to <option>no</option> (the default), the service will
not be restarted. If set to <option>on-success</option>, it
will be restarted only when the service process exits cleanly.
- In this context, a clean exit means an exit code of 0, or one
- of the signals
- <constant>SIGHUP</constant>,
- <constant>SIGINT</constant>,
- <constant>SIGTERM</constant> or
- <constant>SIGPIPE</constant>, and
- additionally, exit statuses and signals specified in
- <varname>SuccessExitStatus=</varname>. If set to
+ In this context, a clean exit means any of the following:
+ <itemizedlist>
+ <listitem><simpara>exit code of 0;</simpara></listitem>
+ <listitem><simpara>for types other than
+ <varname>Type=oneshot</varname>, one of the signals
+ <constant>SIGHUP</constant>,
+ <constant>SIGINT</constant>,
+ <constant>SIGTERM</constant>, or
+ <constant>SIGPIPE</constant>;</simpara></listitem>
+ <listitem><simpara>exit statuses and signals specified in
+ <varname>SuccessExitStatus=</varname>.</simpara></listitem>
+ </itemizedlist>
+ If set to
<option>on-failure</option>, the service will be restarted
when the process exits with a non-zero exit code, is
terminated by a signal (including on core dump, but excluding
<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>,
+ 0 and, except for <varname>Type=oneshot</varname>, 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
<term><varname>USBFunctionDescriptors=</varname></term>
<listitem><para>Configure the location of a file containing
<ulink
- url="https://www.kernel.org/doc/Documentation/usb/functionfs.txt">USB
+ url="https://docs.kernel.org/usb/functionfs.html">USB
FunctionFS</ulink> descriptors, for implementation of USB
gadget functions. This is used only in conjunction with a
socket unit with <varname>ListenUSBFunction=</varname>
<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
+ <listitem><para>Configure the out-of-memory (OOM) kernel killer policy. Note that the userspace OOM
+ killer
+ <citerefentry><refentrytitle>systemd-oomd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ is a more flexible solution that aims to prevent out-of-memory situations for the userspace, not just
+ the kernel.</para>
+
+ <para>On Linux, when memory becomes scarce to the point that the kernel has trouble allocating memory
+ for itself, it 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
+ killer the kernel is instructed to kill all remaining processes of the service too, by setting the
+ <filename>memory.oom.group</filename> attribute to <constant>1</constant>; also see <ulink
+ url="https://docs.kernel.org/admin-guide/cgroup-v2.html">kernel documentation</ulink>.
+ </para>
+
+ <para>Defaults to the setting <varname>DefaultOOMPolicy=</varname> in
<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>
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>
+ details.</para>
+
+ <para>This setting also applies to <command>systemd-oomd</command>. Similarly to the kernel OOM
+ kills, this setting determines the state of the service after <command>systemd-oomd</command> kills a
+ cgroup associated with the service.</para></listitem>
</varlistentry>
</variablelist>
- <para>Check
- <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- and
- <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- for more settings.</para>
-
+ <para id='shared-unit-options'>Check
+ <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, and
+ <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more
+ settings.</para>
</refsect1>
<refsect1>
<varname>ExecStop=</varname>, and
<varname>ExecStopPost=</varname> options.</para>
- <para>Multiple command lines may be concatenated in a single
- directive by separating them with semicolons (these semicolons
- must be passed as separate words). Lone semicolons may be escaped
- as <literal>\;</literal>.</para>
-
- <para>Each command line is split on whitespace, with the first item being the command to
- execute, and the subsequent items being the arguments. Double quotes ("…") and single quotes
- ('…') may be used to wrap a whole item (the opening quote may appear only at the beginning or
- after whitespace that is not quoted, and the closing quote must be followed by whitespace or the
- end of line), in which case everything until the next matching quote becomes part of the same
- argument. Quotes themselves are removed. C-style escapes are also supported. The table below
- contains the list of known escape patterns. Only escape patterns which match the syntax in the
- table are allowed; other patterns may be added in the future and unknown patterns will result in
- a warning. In particular, any backslashes should be doubled. Finally, a trailing backslash
- (<literal>\</literal>) may be used to merge lines.</para>
+ <para>Multiple command lines may be concatenated in a single directive by separating them with semicolons
+ (these semicolons must be passed as separate words). Lone semicolons may be escaped as
+ <literal>\;</literal>.</para>
+
+ <para>Each command line is unquoted using the rules described in "Quoting" section in
+ <citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
+ first item becomes the command to execute, and the subsequent items the arguments.</para>
<para>This syntax is inspired by shell syntax, but only the meta-characters and expansions
described in the following paragraphs are understood, and the expansion of variables is
<literal>>/dev/null</literal>,
<literal>&</literal>, <literal>;</literal>, and
<literal>ls</literal>.</para>
-
- <table>
- <title>C escapes supported in command lines and environment variables</title>
- <tgroup cols='2'>
- <colspec colname='escape' />
- <colspec colname='meaning' />
- <thead>
- <row>
- <entry>Literal</entry>
- <entry>Actual value</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>\a</literal></entry>
- <entry>bell</entry>
- </row>
- <row>
- <entry><literal>\b</literal></entry>
- <entry>backspace</entry>
- </row>
- <row>
- <entry><literal>\f</literal></entry>
- <entry>form feed</entry>
- </row>
- <row>
- <entry><literal>\n</literal></entry>
- <entry>newline</entry>
- </row>
- <row>
- <entry><literal>\r</literal></entry>
- <entry>carriage return</entry>
- </row>
- <row>
- <entry><literal>\t</literal></entry>
- <entry>tab</entry>
- </row>
- <row>
- <entry><literal>\v</literal></entry>
- <entry>vertical tab</entry>
- </row>
- <row>
- <entry><literal>\\</literal></entry>
- <entry>backslash</entry>
- </row>
- <row>
- <entry><literal>\"</literal></entry>
- <entry>double quotation mark</entry>
- </row>
- <row>
- <entry><literal>\'</literal></entry>
- <entry>single quotation mark</entry>
- </row>
- <row>
- <entry><literal>\s</literal></entry>
- <entry>space</entry>
- </row>
- <row>
- <entry><literal>\x<replaceable>xx</replaceable></literal></entry>
- <entry>character number <replaceable>xx</replaceable> in hexadecimal encoding</entry>
- </row>
- <row>
- <entry><literal>\<replaceable>nnn</replaceable></literal></entry>
- <entry>character number <replaceable>nnn</replaceable> in octal encoding</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
</refsect1>
<refsect1>
projects / thirdparty / systemd.git / blobdiff