<citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
+ <para>Various settings are allowed to be specified
+ more than once, in which case the interpretation
+ depends on the setting. Often, multiple settings form
+ a list, and setting to an empty value "resets", which
+ means that previous assignments are ignored. When this
+ is allowed, it is mentioned in the description of the
+ setting. Note that using multiple assignments to the
+ same value makes the unit file incompatible with
+ parsers for the XDG <filename>.desktop</filename> file
+ format.</para>
+
<para>Unit files are loaded from a set of paths
determined during compilation, described in the next section.
</para>
multiple units from a single configuration file. If
systemd looks for a unit configuration file, it will
first search for the literal unit name in the
- filesystem. If that yields no success and the unit
+ file system. If that yields no success and the unit
name contains an <literal>@</literal> character, systemd will look for a
unit template that shares the same name but with the
instance string (i.e. the part between the <literal>@</literal> character
what the unit's purpose is, followed
by how it is configured, followed by
any other related documentation. This
- option may be specified more than once
+ option may be specified more than once,
in which case the specified list of
URIs is merged. If the empty string is
assigned to this option, the list is
<varname>Requires=</varname> and
<varname>RequiresOverridable=</varname>,
respectively. However, if the units
- listed here are not started already
+ listed here are not started already,
they will not be started and the
transaction will fail immediately.
</para></listitem>
listed in this option will be started
if the configuring unit is. However,
if the listed units fail to start
- or cannot be added to the transaction
+ or cannot be added to the transaction,
this has no impact on the validity of
the transaction as a whole. This is
the recommended way to hook start-up
symlinks to a
<filename>.wants/</filename> directory
accompanying the unit file. For
- details see above.</para></listitem>
+ details, see above.</para></listitem>
</varlistentry>
<varlistentry>
<listitem><para>Configures requirement
dependencies, very similar in style to
<varname>Requires=</varname>, however
- in addition to this behavior it also
+ in addition to this behavior, it also
declares that this unit is stopped
when any of the units listed suddenly
disappears. Units can suddenly,
of units. When systemd stops or restarts
the units listed here, the action is
propagated to this unit.
- Note that this is a one way dependency —
+ Note that this is a one-way dependency —
changes to this unit do not affect the
listed units.
</para></listitem>
be modified to be fixed (in case one
or both jobs are not a required part
of the transaction). In the latter
- case the job that is not the required
+ case, the job that is not the required
will be removed, or in case both are
- not required the unit that conflicts
+ not required, the unit that conflicts
will be started and the unit that is
conflicted is
stopped.</para></listitem>
a common pattern to include a unit
name in both the
<varname>After=</varname> and
- <varname>Requires=</varname> option in
+ <varname>Requires=</varname> option, in
which case the unit listed will be
started before the unit that is
configured with these options. This
dependency on another unit is shut
down while the latter is started up,
the shut down is ordered before the
- start-up regardless whether the
+ start-up regardless of whether the
ordering dependency is actually of
type <varname>After=</varname> or
<varname>Before=</varname>. If two
directives (see
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for details). If a unit that has this
- setting set is started its processes
+ setting set is started, its processes
will see the same
<filename>/tmp</filename>,
<filename>/tmp/var</filename> and
network namespace as one listed unit
that is started. If multiple listed
- units are already started it is not
+ units are already started, it is not
defined which namespace is
joined. Note that this setting only
has an effect if
exists, is a regular file and marked
executable.</para>
- <para>Similar,
+ <para>Similarly,
<varname>ConditionKernelCommandLine=</varname>
may be used to check whether a
specific kernel command line option is
<row>
<entry><literal>%N</literal></entry>
<entry>Unescaped full unit name</entry>
- <entry></entry>
+ <entry>Same as <literal>%n</literal>, but with escaping undone</entry>
</row>
<row>
<entry><literal>%p</literal></entry>
<entry>Prefix name</entry>
- <entry>For instantiated units this refers to the string before the @. For non-instantiated units this refers to to the name of the unit with the type suffix removed.</entry>
+ <entry>For instantiated units, this refers to the string before the <literal>@</literal> character of the unit name. For non-instantiated units, this refers to the name of the unit with the type suffix removed.</entry>
</row>
<row>
<entry><literal>%P</literal></entry>
<entry>Unescaped prefix name</entry>
- <entry></entry>
+ <entry>Same as <literal>%p</literal>, but with escaping undone</entry>
</row>
<row>
<entry><literal>%i</literal></entry>
<entry>Instance name</entry>
- <entry>For instantiated units: this is the string between the <literal>@</literal> character and the suffix.</entry>
+ <entry>For instantiated units: this is the string between the <literal>@</literal> character and the suffix of the unit name.</entry>
</row>
<row>
<entry><literal>%I</literal></entry>
<entry>Unescaped instance name</entry>
- <entry></entry>
+ <entry>Same as <literal>%i</literal>, but with escaping undone</entry>
</row>
<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 prefix name similarly prepended with <filename>/</filename>.</entry>
+ <entry>This is either the unescaped instance name (if applicable) with <filename>/</filename> prepended (if applicable), or the prefix name prepended with <filename>/</filename>.</entry>
</row>
<row>
<entry><literal>%c</literal></entry>
<entry>Control group path of the unit</entry>
- <entry></entry>
+ <entry>This path does not include the <filename>/sys/fs/cgroup/systemd/</filename> prefix.</entry>
</row>
<row>
<entry><literal>%r</literal></entry>
- <entry>Root control group path where units are placed.</entry>
- <entry>For system instances, this usually resolves to <filename>/system</filename>, except in containers, where the path might be prefixed with the container's root control group.</entry>
+ <entry>Control group path of the slice the unit is placed in</entry>
+ <entry>This usually maps to the parent cgroup path of <literal>%c</literal>.</entry>
</row>
<row>
<entry><literal>%R</literal></entry>
- <entry>Parent directory of the control group path where units are placed.</entry>
- <entry>For system instances, this usually
- resolves to <filename>/</filename>, except in
- containers, where this resolves to the
- container's root directory.</entry>
+ <entry>Root control group path below which slices and units are placed</entry>
+ <entry>For system instances, this resolves to <filename>/</filename>, except in containers, where this maps to the container's root control group path.</entry>
</row>
<row>
<entry><literal>%t</literal></entry>
- <entry>Runtime socket dir</entry>
- <entry>This is either <filename>/run</filename> (for the system manager) or <literal>$XDG_RUNTIME_DIR</literal> (for user managers).</entry>
+ <entry>Runtime directory</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>%u</literal></entry>
<row>
<entry><literal>%U</literal></entry>
<entry>User UID</entry>
- <entry>This is the UID of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry>
+ <entry>This is the numeric UID of the configured user of the unit, or (if none is set) the user running the systemd user instance. Note that this specifier is not available for units run by the systemd system instance (as opposed to those run by a systemd user instance), unless the user has been configured as a numeric UID in the first place or the configured user is the root user.</entry>
</row>
<row>
<entry><literal>%h</literal></entry>
<entry>User home directory</entry>
- <entry>This is the home directory of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry>
+ <entry>This is the home directory of the configured user of the unit, or (if none is set) the user running the systemd user instance. Similar to <literal>%U</literal>, this specifier is not available for units run by the systemd system instance, unless the configured user is the root user.</entry>
</row>
<row>
<entry><literal>%s</literal></entry>
<entry>User shell</entry>
- <entry>This is the shell of the configured user of the unit, or (if none is set) the user running the systemd instance. If the user is <literal>root</literal> (UID equal to 0), the shell configured in account database is ignored and <filename>/bin/sh</filename> is always used.</entry>
+ <entry>This is the shell of the configured user of the unit, or (if none is set) the user running the systemd user instance. Similar to <literal>%U</literal>, this specifier is not available for units run by the systemd system instance, unless the configured user is the root user.</entry>
</row>
<row>
<entry><literal>%m</literal></entry>
<row>
<entry><literal>%H</literal></entry>
<entry>Host name</entry>
- <entry>The hostname of the running system.</entry>
+ <entry>The hostname of the running system at the point in time the unit configuation is loaded.</entry>
</row>
<row>
<entry><literal>%v</literal></entry>
<entry>Kernel release</entry>
- <entry>Identical to <command>uname -r</command> output.</entry>
+ <entry>Identical to <command>uname -r</command> output</entry>
</row>
<row>
<entry><literal>%%</literal></entry>
- <entry>Escaped %</entry>
- <entry>Single percent sign.</entry>
+ <entry>Single percent sign</entry>
+ <entry>Use <literal>%%</literal> in place of <literal>%</literal> to specify a single percent sign.</entry>
</row>
</tbody>
</tgroup>
~ianmdlvl / elogind.git / blobdiff