]>
<!--
+ SPDX-License-Identifier: LGPL-2.1+
+
This file is part of systemd.
Copyright 2010 Lennart Poettering
modify unit files. Each drop-in file must have appropriate section headers. Note that for
instantiated units, this logic will first look for the instance <literal>.d/</literal>
subdirectory and read its <literal>.conf</literal> files, followed by the template
- <literal>.d/</literal> subdirectory and the <literal>.conf</literal> files there. Also note that
- settings from the <literal>[Install]</literal> section are not honored in drop-in unit files,
- and have no effect.</para>
+ <literal>.d/</literal> subdirectory and the <literal>.conf</literal> files there.</para>
<para>In addition to <filename>/etc/systemd/system</filename>, the drop-in <literal>.d</literal>
directories for system services can be placed in <filename>/usr/lib/systemd/system</filename> or
socket-based activation which make dependencies implicit,
resulting in a both simpler and more flexible system.</para>
- <para>Some unit names reflect paths existing in the file system
- namespace. Example: a device unit
- <filename>dev-sda.device</filename> refers to a device with the
- device node <filename noindex='true'>/dev/sda</filename> in the
- file system namespace. If this applies, a special way to escape
- the path name is used, so that the result is usable as part of a
- filename. Basically, given a path, "/" is replaced by "-", and all
- other characters which are not ASCII alphanumerics are replaced by
- C-style "\x2d" escapes (except that "_" is never replaced and "."
- is only replaced when it would be the first character in the
- escaped path). The root directory "/" is encoded as single dash,
- while otherwise the initial and ending "/" are removed from all
- paths during transformation. This escaping is reversible. Properly
- escaped paths can be generated using the
- <citerefentry><refentrytitle>systemd-escape</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- command.</para>
-
<para>Optionally, units may be instantiated from a
template file at runtime. This allows creation of
multiple units from a single configuration file. If
</refsect1>
+ <refsect1>
+ <title>String Escaping for Inclusion in Unit Names</title>
+
+ <para>Sometimes it is useful to convert arbitrary strings into unit names. To facilitate this, a method of string
+ escaping is used, in order to map strings containing arbitrary byte values (except NUL) into valid unit names and
+ their restricted character set. A common special case are unit names that reflect paths to objects in the file
+ system hierarchy. Example: a device unit <filename>dev-sda.device</filename> refers to a device with the device
+ node <filename noindex='true'>/dev/sda</filename> in the file system.</para>
+
+ <para>The escaping algorithm operates as follows: given a string, any <literal>/</literal> character is replaced by
+ <literal>-</literal>, and all other characters which are not ASCII alphanumerics or <literal>_</literal> are
+ replaced by C-style <literal>\x2d</literal> escapes. In addition, <literal>.</literal> is replaced with such a
+ C-style escape when it would appear as the first character in the escaped string.</para>
+
+ <para>When the input qualifies as absolute file system path, this algorithm is extended slightly: the path to the
+ root directory <literal>/</literal> is encoded as single dash <literal>-</literal>. In addition, any leading,
+ trailing or duplicate <literal>/</literal> characters are removed from the string before transformation. Example:
+ <filename>/foo//bar/baz/</filename> becomes <literal>foo-bar-baz</literal>.</para>
+
+ <para>This escaping is fully reversible, as long as it is known whether the escaped string was a path (the
+ unescaping results are different for paths and non-path strings). The
+ <citerefentry><refentrytitle>systemd-escape</refentrytitle><manvolnum>1</manvolnum></citerefentry> command may be
+ used to apply and reverse escaping on arbitrary strings. Use <command>systemd-escape --path</command> to escape
+ path strings, and <command>systemd-escape</command> without <option>--path</option> otherwise.</para>
+ </refsect1>
+
<refsect1>
<title>Implicit Dependencies</title>
</para>
</refsect1>
+ <refsect1>
+ <title>Unit Garbage Collection</title>
+
+ <para>The system and service manager loads a unit's configuration automatically when a unit is referenced for the
+ first time. It will automatically unload the unit configuration and state again when the unit is not needed anymore
+ ("garbage collection"). A unit may be referenced through a number of different mechanisms:</para>
+
+ <orderedlist>
+ <listitem><para>Another loaded unit references it with a dependency such as <varname>After=</varname>,
+ <varname>Wants=</varname>, …</para></listitem>
+
+ <listitem><para>The unit is currently starting, running, reloading or stopping.</para></listitem>
+
+ <listitem><para>The unit is currently in the <constant>failed</constant> state. (But see below.)</para></listitem>
+
+ <listitem><para>A job for the unit is pending.</para></listitem>
+
+ <listitem><para>The unit is pinned by an active IPC client program.</para></listitem>
+
+ <listitem><para>The unit is a special "perpetual" unit that is always active and loaded. Examples for perpetual
+ units are the root mount unit <filename>-.mount</filename> or the scope unit <filename>init.scope</filename> that
+ the service manager itself lives in.</para></listitem>
+
+ <listitem><para>The unit has running processes associated with it.</para></listitem>
+ </orderedlist>
+
+ <para>The garbage collection logic may be altered with the <varname>CollectMode=</varname> option, which allows
+ configuration whether automatic unloading of units that are in <constant>failed</constant> state is permissible,
+ see below.</para>
+
+ <para>Note that when a unit's configuration and state is unloaded, all execution results, such as exit codes, exit
+ signals, resource consumption and other statistics are lost, except for what is stored in the log subsystem.</para>
+
+ <para>Use <command>systemctl daemon-reload</command> or an equivalent command to reload unit configuration while
+ the unit is already loaded. In this case all configuration settings are flushed out and replaced with the new
+ configuration (which however might not be in effect immediately), however all runtime state is
+ saved/restored.</para>
+ </refsect1>
+
<refsect1>
<title>[Unit] Section Options</title>
ones.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>CollectMode=</varname></term>
+
+ <listitem><para>Tweaks the "garbage collection" algorithm for this unit. Takes one of <option>inactive</option>
+ or <option>inactive-or-failed</option>. If set to <option>inactive</option> the unit will be unloaded if it is
+ in the <constant>inactive</constant> state and is not referenced by clients, jobs or other units — however it
+ is not unloaded if it is in the <constant>failed</constant> state. In <option>failed</option> mode, failed
+ units are not unloaded until the user invoked <command>systemctl reset-failed</command> on them to reset the
+ <constant>failed</constant> state, or an equivalent command. This behaviour is altered if this option is set to
+ <option>inactive-or-failed</option>: in this case the unit is unloaded even if the unit is in a
+ <constant>failed</constant> state, and thus an explicitly resetting of the <constant>failed</constant> state is
+ not necessary. Note that if this mode is used unit results (such as exit codes, exit signals, consumed
+ resources, …) are flushed out immediately after the unit completed, except for what is stored in the logging
+ subsystem. Defaults to <option>inactive</option>.</para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>JobTimeoutSec=</varname></term>
<term><varname>JobRunningTimeoutSec=</varname></term>
</varlistentry>
<varlistentry>
- <term><varname>StartLimitIntervalSec=</varname></term>
- <term><varname>StartLimitBurst=</varname></term>
-
- <listitem><para>Configure unit start rate limiting. By default, units which are started more than 5 times
- within 10 seconds are not permitted to start any more times until the 10 second interval ends. With these two
- options, this rate limiting may be modified. Use <varname>StartLimitIntervalSec=</varname> to configure the
- checking interval (defaults to <varname>DefaultStartLimitIntervalSec=</varname> in manager configuration file,
- set to 0 to disable any kind of rate limiting). Use <varname>StartLimitBurst=</varname> to configure how many
- starts per interval are allowed (defaults to <varname>DefaultStartLimitBurst=</varname> in manager
- configuration file). These configuration options are particularly useful in conjunction with the service
- setting <varname>Restart=</varname> (see
+ <term><varname>StartLimitIntervalSec=<replaceable>interval</replaceable></varname></term>
+ <term><varname>StartLimitBurst=<replaceable>burst</replaceable></varname></term>
+
+ <listitem><para>Configure unit start rate limiting. Units which are started more than
+ <replaceable>burst</replaceable> times within an <replaceable>interval</replaceable> time interval are not
+ permitted to start any more. Use <varname>StartLimitIntervalSec=</varname> to configure the checking interval
+ (defaults to <varname>DefaultStartLimitIntervalSec=</varname> in manager configuration file, set it to 0 to
+ disable any kind of rate limiting). Use <varname>StartLimitBurst=</varname> to configure how many starts per
+ interval are allowed (defaults to <varname>DefaultStartLimitBurst=</varname> in manager configuration
+ file). These configuration options are particularly useful in conjunction with the service setting
+ <varname>Restart=</varname> (see
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>); however,
they apply to all kinds of starts (including manual), not just those triggered by the
<varname>Restart=</varname> logic. Note that units which are configured for <varname>Restart=</varname> and
which reach the start limit are not attempted to be restarted anymore; however, they may still be restarted
- manually at a later point, from which point on, the restart logic is again activated. Note that
- <command>systemctl reset-failed</command> will cause the restart rate counter for a service to be flushed,
- which is useful if the administrator wants to manually start a unit and the start limit interferes with
- that. Note that this rate-limiting is enforced after any unit condition checks are executed, and hence unit
- activations with failing conditions are not counted by this rate limiting. Slice, target, device and scope
- units do not enforce this setting, as they are unit types whose activation may either never fail, or may
- succeed only a single time.</para></listitem>
+ manually at a later point, after the <replaceable>interval</replaceable> has passed. From this point on, the
+ restart logic is activated again. Note that <command>systemctl reset-failed</command> will cause the restart
+ rate counter for a service to be flushed, which is useful if the administrator wants to manually start a unit
+ and the start limit interferes with that. Note that this rate-limiting is enforced after any unit condition
+ checks are executed, and hence unit activations with failing conditions do not count towards this rate
+ limit. This setting does not apply to slice, target, device, and scope units, since they are unit types whose
+ activation may either never fail, or may succeed only a single time.</para>
+
+ <para>When a unit is unloaded due to the garbage collection logic (see above) its rate limit counters are
+ flushed out too. This means that configuring start rate limiting for a unit that is not referenced continously
+ has no effect.</para></listitem>
</varlistentry>
<varlistentry>
system. Currently, the recognized values are
<varname>selinux</varname>,
<varname>apparmor</varname>,
+ <varname>tomoyo</varname>,
<varname>ima</varname>,
<varname>smack</varname> and
<varname>audit</varname>. The test may be negated by
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> during runtime; it is
used by the <command>enable</command> and <command>disable</command> commands of the
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> tool during
- installation of a unit. Note that settings in the <literal>[Install]</literal> section may not appear in
- <filename>.d/*.conf</filename> unit file drop-ins (see above).</para>
+ installation of a unit.</para>
<variablelist class='unit-directives'>
<varlistentry>
<row>
<entry><literal>%N</literal></entry>
<entry>Unescaped full unit name</entry>
- <entry>Same as <literal>%n</literal>, but with escaping undone</entry>
+ <entry>Same as <literal>%n</literal>, but with escaping undone. This undoes the escaping used when generating unit names from arbitrary strings (see above). </entry>
</row>
<row>
<entry><literal>%p</literal></entry>
<row>
<entry><literal>%f</literal></entry>
<entry>Unescaped filename</entry>
- <entry>This is either the unescaped instance name (if applicable) with <filename>/</filename> prepended (if applicable), or the unescaped prefix name prepended with <filename>/</filename>.</entry>
+ <entry>This is either the unescaped instance name (if applicable) with <filename>/</filename> prepended (if applicable), or the unescaped prefix name prepended with <filename>/</filename>. This implements unescaping according to the rules for escaping absolute file system paths discussed above.</entry>
</row>
<row>
<entry><literal>%t</literal></entry>
- <entry>Runtime directory</entry>
+ <entry>Runtime directory root</entry>
<entry>This is either <filename>/run</filename> (for the system manager) or the path <literal>$XDG_RUNTIME_DIR</literal> resolves to (for user managers).</entry>
</row>
<row>
+ <entry><literal>%S</literal></entry>
+ <entry>State directory root </entry>
+ <entry>This is either <filename>/var/lib</filename> (for the system manager) or the path <literal>$XDG_CONFIG_HOME</literal> resolves to (for user managers).</entry>
+ </row>
+ <row>
+ <entry><literal>%C</literal></entry>
+ <entry>Cache directory root </entry>
+ <entry>This is either <filename>/var/cache</filename> (for the system manager) or the path <literal>$XDG_CACHE_HOME</literal> resolves to (for user managers).</entry>
+ </row>
+ <row>
+ <entry><literal>%L</literal></entry>
+ <entry>Logs directory root </entry>
+ <entry>This is either <filename>/var/log</filename> (for the system manager) or the path <literal>$XDG_CONFIG_HOME</literal> resolves to with <filename>/log</filename> appended (for user managers).</entry>
+ </row>
+ <row>
<entry><literal>%u</literal></entry>
<entry>User name</entry>
<entry>This is the name of the user running the service manager instance. In case of the system manager this resolves to <literal>root</literal>.</entry>
projects / thirdparty / systemd.git / blobdiff