]>
<!--
+ SPDX-License-Identifier: LGPL-2.1+
+
This file is part of systemd.
Copyright 2010 Lennart Poettering
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>
<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
+ <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, 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></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>
<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>
projects / thirdparty / systemd.git / blobdiff