-<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
+<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY % entities SYSTEM "custom-entities.ent" >
<!--
SPDX-License-Identifier: LGPL-2.1+
-
- This file is part of systemd.
-
- Copyright 2010 Lennart Poettering
-
- systemd is free software; you can redistribute it and/or modify it
- under the terms of the GNU Lesser General Public License as published by
- the Free Software Foundation; either version 2.1 of the License, or
- (at your option) any later version.
-
- systemd is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- Lesser General Public License for more details.
-
- You should have received a copy of the GNU Lesser General Public License
- along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="systemd.unit">
<refentryinfo>
<title>systemd.unit</title>
<productname>systemd</productname>
-
- <authorgroup>
- <author>
- <contrib>Developer</contrib>
- <firstname>Lennart</firstname>
- <surname>Poettering</surname>
- <email>lennart@poettering.net</email>
- </author>
- </authorgroup>
</refentryinfo>
<refmeta>
<filename><replaceable>slice</replaceable>.slice</filename>,
<filename><replaceable>scope</replaceable>.scope</filename></para>
- <para><literallayout><filename>/etc/systemd/system.control/*</filename>
+ <refsect2>
+ <title>System Unit Search Path</title>
+
+ <para><literallayout><filename>/etc/systemd/system.control/*</filename>
<filename>/run/systemd/system.control/*</filename>
<filename>/run/systemd/transient/*</filename>
<filename>/run/systemd/generator.early/*</filename>
<filename>/etc/systemd/system/*</filename>
+<filename>/etc/systemd/systemd.attached/*</filename>
<filename>/run/systemd/system/*</filename>
+<filename>/run/systemd/systemd.attached/*</filename>
<filename>/run/systemd/generator/*</filename>
<filename>…</filename>
<filename>/usr/lib/systemd/system/*</filename>
-<filename>/run/systemd/generator.late/*</filename>
- </literallayout></para>
+<filename>/run/systemd/generator.late/*</filename></literallayout></para>
+ </refsect2>
- <para><literallayout><filename>~/.config/systemd/user.control/*</filename>
+ <refsect2>
+ <title>User Unit Search Path</title>
+ <para><literallayout><filename>~/.config/systemd/user.control/*</filename>
<filename>$XDG_RUNTIME_DIR/systemd/user.control/*</filename>
<filename>$XDG_RUNTIME_DIR/systemd/transient/*</filename>
<filename>$XDG_RUNTIME_DIR/systemd/generator.early/*</filename>
<filename>~/.local/share/systemd/user/*</filename>
<filename>…</filename>
<filename>/usr/lib/systemd/user/*</filename>
-<filename>$XDG_RUNTIME_DIR/systemd/generator.late/*</filename>
- </literallayout></para>
+<filename>$XDG_RUNTIME_DIR/systemd/generator.late/*</filename></literallayout></para>
+ </refsect2>
+
</refsynopsisdiv>
<refsect1>
<title>Description</title>
- <para>A unit configuration file encodes information about a
- service, a socket, a device, a mount point, an automount point, a
- swap file or partition, a start-up target, a watched file system
- path, a timer controlled and supervised by
- <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
- a resource management slice or
- a group of externally created processes. The syntax is inspired by
- <ulink
- url="http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG
- Desktop Entry Specification</ulink> <filename>.desktop</filename>
- files, which are in turn inspired by Microsoft Windows
- <filename>.ini</filename> files.</para>
+ <para>A unit file is a plain text ini-style file that encodes information about a service, a
+ socket, a device, a mount point, an automount point, a swap file or partition, a start-up
+ target, a watched file system path, a timer controlled and supervised by
+ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, a
+ resource management slice or a group of externally created processes. See
+ <citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for a general description of the syntax.</para>
<para>This man page lists the common configuration options of all
the unit types. These options need to be configured in the [Unit]
<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>
+ <para>Unit files can be parameterized by a single argument called the "instance name". The unit
+ is then constructed based on a "template file" which serves as the definition of multiple
+ services or other units. A template unit must have a single <literal>@</literal> at the end of
+ the name (right before the type suffix). The name of the full unit is formed by inserting the
+ instance name between <literal>@</literal> and the unit type suffix. In the unit file itself,
+ the instance parameter may be referred to using <literal>%i</literal> and other specifiers, see
+ below.</para>
+
<para>Unit files may contain additional options on top of those
listed here. If systemd encounters an unknown option, it will
write a warning log message but continue loading the unit. If an
do not need the prefix. Applications may use this to include
additional information in the unit files.</para>
- <para>Boolean arguments used in unit files can be written in
- various formats. For positive settings the strings
- <option>1</option>, <option>yes</option>, <option>true</option>
- and <option>on</option> are equivalent. For negative settings, the
- strings <option>0</option>, <option>no</option>,
- <option>false</option> and <option>off</option> are
- equivalent.</para>
-
- <para>Time span values encoded in unit files can be written in various formats. A stand-alone
- number specifies a time in seconds. If suffixed with a time unit, the unit is honored. A
- concatenation of multiple values with units is supported, in which case the values are added
- up. Example: <literal>50</literal> refers to 50 seconds; <literal>2min 200ms</literal> refers to
- 2 minutes and 200 milliseconds, i.e. 120200 ms. The following time units are understood:
- <literal>s</literal>, <literal>min</literal>, <literal>h</literal>, <literal>d</literal>,
- <literal>w</literal>, <literal>ms</literal>, <literal>us</literal>. For details see
- <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
-
- <para>Empty lines and lines starting with <literal>#</literal> or <literal>;</literal> are
- ignored. This may be used for commenting. Lines ending in a backslash are concatenated with the
- following line while reading and the backslash is replaced by a space character. This may be
- used to wrap long lines.</para>
-
<para>Units can be aliased (have an alternative name), by creating a symlink from the new name
to the existing name in one of the unit search paths. For example,
<filename>systemd-networkd.service</filename> has the alias
suffix is <filename>.requires/</filename> in this case.</para>
<para>Along with a unit file <filename>foo.service</filename>, a "drop-in" directory
- <filename>foo.service.d/</filename> may exist. All files with the suffix
- <literal>.conf</literal> from this directory will be parsed after the file itself is
- parsed. This is useful to alter or add configuration settings for a unit, without having to
- 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.</para>
-
- <para>In addition to <filename>/etc/systemd/system</filename>, the drop-in <literal>.d</literal>
+ <filename>foo.service.d/</filename> may exist. All files with the suffix <literal>.conf</literal> from this
+ directory will be parsed after the unit file itself is parsed. This is useful to alter or add configuration
+ settings for a unit, without having to modify unit files. Drop-in files must contain appropriate section
+ headers. For instantiated units, this logic will first look for the instance <literal>.d/</literal> subdirectory
+ (e.g. <literal>foo@bar.service.d/</literal>) and read its <literal>.conf</literal> files, followed by the template
+ <literal>.d/</literal> subdirectory (e.g. <literal>foo@.service.d/</literal>) and the <literal>.conf</literal>
+ files there. Moreover for units names containing dashes (<literal>-</literal>), the set of directories generated by
+ truncating the unit name after all dashes is searched too. Specifically, for a unit name
+ <filename>foo-bar-baz.service</filename> not only the regular drop-in directory
+ <filename>foo-bar-baz.service.d/</filename> is searched but also both <filename>foo-bar-.service.d/</filename> and
+ <filename>foo-.service.d/</filename>. This is useful for defining common drop-ins for a set of related units, whose
+ names begin with a common prefix. This scheme is particularly useful for mount, automount and slice units, whose
+ systematic naming structure is built around dashes as component separators. Note that equally named drop-in files
+ further down the prefix hierarchy override those further up,
+ i.e. <filename>foo-bar-.service.d/10-override.conf</filename> overrides
+ <filename>foo-.service.d/10-override.conf</filename>.</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
<filename>/run/systemd/system</filename> directories. Drop-in files in <filename>/etc</filename>
take precedence over those in <filename>/run</filename> which in turn take precedence over those
socket-based activation which make dependencies implicit,
resulting in a both simpler and more flexible system.</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
- systemd looks for a unit configuration file, it will
- first search for the literal unit name in the
- 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
- and the suffix) removed. Example: if a service
- <filename>getty@tty3.service</filename> is requested
- and no file by that name is found, systemd will look
- for <filename>getty@.service</filename> and
- instantiate a service from that configuration file if
- it is found.</para>
+ <para>As mentioned above, a unit may be instantiated from a template file. This allows creation
+ of 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 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 and the suffix) removed. Example: if a service
+ <filename>getty@tty3.service</filename> is requested and no file by that name is found, systemd
+ will look for <filename>getty@.service</filename> and instantiate a service from that
+ configuration file if it is found.</para>
<para>To refer to the instance string from within the
configuration file you may use the special <literal>%i</literal>
</refsect1>
<refsect1>
- <title>Implicit Dependencies</title>
-
- <para>A number of unit dependencies are implicitly established,
- depending on unit type and unit configuration. These implicit
- dependencies can make unit configuration file cleaner. For the
- implicit dependencies in each unit type, please refer to
- section "Implicit Dependencies" in respective man pages.</para>
-
- <para>For example, service units with <varname>Type=dbus</varname>
- automatically acquire dependencies of type <varname>Requires=</varname>
- and <varname>After=</varname> on <filename>dbus.socket</filename>. See
- <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- for details.</para>
- </refsect1>
-
- <refsect1>
- <title>Default Dependencies</title>
-
- <para>Default dependencies are similar to implicit dependencies,
- but can be turned on and off by setting
- <varname>DefaultDependencies=</varname> to <varname>yes</varname>
- (the default) and <varname>no</varname>, while implicit dependencies
- are always in effect. See section "Default Dependencies" in respective
- man pages for the effect of enabling
- <varname>DefaultDependencies=</varname> in each unit types.</para>
-
- <para>For example, target units will complement all configured
- dependencies of type <varname>Wants=</varname> or
- <varname>Requires=</varname> with dependencies of type
- <varname>After=</varname> unless <varname>DefaultDependencies=no</varname>
- is set in the specified units. See
- <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- for details. Note that this behavior can be turned off by setting
- <varname>DefaultDependencies=no</varname>.</para>
+ <title>Automatic dependencies</title>
+
+ <refsect2>
+ <title>Implicit Dependencies</title>
+
+ <para>A number of unit dependencies are implicitly established, depending on unit type and
+ unit configuration. These implicit dependencies can make unit configuration file cleaner. For
+ the implicit dependencies in each unit type, please refer to section "Implicit Dependencies"
+ in respective man pages.</para>
+
+ <para>For example, service units with <varname>Type=dbus</varname> automatically acquire
+ dependencies of type <varname>Requires=</varname> and <varname>After=</varname> on
+ <filename>dbus.socket</filename>. See
+ <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for details.</para>
+ </refsect2>
+
+ <refsect2>
+ <title>Default Dependencies</title>
+
+ <para>Default dependencies are similar to implicit dependencies, but can be turned on and off
+ by setting <varname>DefaultDependencies=</varname> to <varname>yes</varname> (the default) and
+ <varname>no</varname>, while implicit dependencies are always in effect. See section "Default
+ Dependencies" in respective man pages for the effect of enabling
+ <varname>DefaultDependencies=</varname> in each unit types.</para>
+
+ <para>For example, target units will complement all configured dependencies of type
+ <varname>Wants=</varname> or <varname>Requires=</varname> with dependencies of type
+ <varname>After=</varname> unless <varname>DefaultDependencies=no</varname> is set in the
+ specified units. See
+ <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for details. Note that this behavior can be turned off by setting
+ <varname>DefaultDependencies=no</varname>.</para>
+ </refsect2>
</refsect1>
<refsect1>
<row>
<entry><filename>/run/systemd/generator.early</filename></entry>
<entry>Generated units with high priority (see <replaceable>early-dir</replaceable> in <citerefentry
- ><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
+ ><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
</row>
<row>
<entry><filename>/etc/systemd/system</filename></entry>
<row>
<entry><filename>/run/systemd/generator</filename></entry>
<entry>Generated units with medium priority (see <replaceable>normal-dir</replaceable> in <citerefentry
- ><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
+ ><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
</row>
<row>
<entry><filename>/usr/local/lib/systemd/system</filename></entry>
<row>
<entry><filename>/run/systemd/generator.late</filename></entry>
<entry>Generated units with low priority (see <replaceable>late-dir</replaceable> in <citerefentry
- ><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
+ ><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
</row>
</tbody>
</tgroup>
<row>
<entry><filename>/run/systemd/generator.early</filename></entry>
<entry>Generated units with high priority (see <replaceable>early-dir</replaceable> in <citerefentry
- ><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
+ ><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
</row>
<row>
<entry><filename>$XDG_CONFIG_HOME/systemd/user</filename> or <filename>$HOME/.config/systemd/user</filename></entry>
<row>
<entry><filename>$XDG_RUNTIME_DIR/systemd/generator</filename></entry>
<entry>Generated units with medium priority (see <replaceable>normal-dir</replaceable> in <citerefentry
- ><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
+ ><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
</row>
<row>
<entry><filename>$XDG_DATA_HOME/systemd/user</filename> or <filename>$HOME/.local/share/systemd/user</filename></entry>
<row>
<entry><filename>$XDG_RUNTIME_DIR/systemd/generator.late</filename></entry>
<entry>Generated units with low priority (see <replaceable>late-dir</replaceable> in <citerefentry
- ><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
+ ><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
</row>
</tbody>
</tgroup>
<para>The set of load paths for the user manager instance may be augmented or
changed using various environment variables. And environment variables may in
turn be set using environment generators, see
- <citerefentry><refentrytitle>system.environment-generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+ <citerefentry><refentrytitle>systemd.environment-generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
In particular, <varname>$XDG_DATA_HOME</varname> and
<varname>$XDG_DATA_DIRS</varname> may be easily set using
<citerefentry><refentrytitle>systemd-environment-d-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
<varlistentry>
<term><varname>Description=</varname></term>
- <listitem><para>A free-form string describing the unit. This
- is intended for use in UIs to show descriptive information
- along with the unit name. The description should contain a
- name that means something to the end user. <literal>Apache2
- Web Server</literal> is a good example. Bad examples are
- <literal>high-performance light-weight HTTP server</literal>
- (too generic) or <literal>Apache2</literal> (too specific and
- meaningless for people who do not know
- Apache).</para></listitem>
+ <listitem><para>A human readable name for the unit. This is used by
+ <command>systemd</command> (and other UIs) as the label for the unit, so this string should
+ identify the unit rather than describe it, despite the name. <literal>Apache2 Web
+ Server</literal> is a good example. Bad examples are <literal>high-performance light-weight
+ HTTP server</literal> (too generic) or <literal>Apache2</literal> (too specific and
+ meaningless for people who do not know Apache). <command>systemd</command> will use this
+ string as a noun in status messages (<literal>Starting
+ <replaceable>description</replaceable>...</literal>, <literal>Started
+ <replaceable>description</replaceable>.</literal>, <literal>Reached target
+ <replaceable>description</replaceable>.</literal>, <literal>Failed to start
+ <replaceable>description</replaceable>.</literal>), so it should be capitalized, and should
+ not be a full sentence or a phrase with a continous verb. Bad examples include
+ <literal>exiting the container</literal> or <literal>updating the database once per
+ day.</literal>.</para>
+ </listitem>
</varlistentry>
<varlistentry>
<varlistentry>
<term><varname>Requisite=</varname></term>
- <listitem><para>Similar to <varname>Requires=</varname>.
- However, if the units listed here are not started already,
- they will not be started and the transaction will fail
- immediately.</para>
+ <listitem><para>Similar to <varname>Requires=</varname>. However, if the units listed here
+ are not started already, they will not be started and the starting of this unit will fail
+ immediately. <varname>Requisite=</varname> does not imply an ordering dependency, even if
+ both units are started in the same transaction. Hence this setting should usually be
+ combined with <varname>After=</varname>, to ensure this unit is not started before the other
+ unit.</para>
<para>When <varname>Requisite=b.service</varname> is used on
<filename>a.service</filename>, this dependency will show as
<para>If a unit A that conflicts with a unit B is scheduled to
be started at the same time as B, the transaction will either
- fail (in case both are required part of the transaction) or be
+ fail (in case both are required parts of the transaction) or 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 will be removed, or in case both are
+ that is not required will be removed, or in case both are
not required, the unit that conflicts will be started and the
unit that is conflicted is stopped.</para></listitem>
</varlistentry>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>FailureAction=</varname></term>
+ <term><varname>SuccessAction=</varname></term>
+
+ <listitem><para>Configure the action to take when the unit stops and enters a failed state or inactive state.
+ Takes one of <option>none</option>, <option>reboot</option>, <option>reboot-force</option>,
+ <option>reboot-immediate</option>, <option>poweroff</option>, <option>poweroff-force</option>,
+ <option>poweroff-immediate</option>, <option>exit</option>, and <option>exit-force</option>. In system mode,
+ all options are allowed. In user mode, only <option>none</option>, <option>exit</option>, and
+ <option>exit-force</option> are allowed. Both options default to <option>none</option>.</para>
+
+ <para>If <option>none</option> is set, no action will be triggered. <option>reboot</option> causes a reboot
+ following the normal shutdown procedure (i.e. equivalent to <command>systemctl reboot</command>).
+ <option>reboot-force</option> causes a forced reboot which will terminate all processes forcibly but should
+ cause no dirty file systems on reboot (i.e. equivalent to <command>systemctl reboot -f</command>) and
+ <option>reboot-immediate</option> causes immediate execution of the
+ <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> system call, which
+ might result in data loss (i.e. equivalent to <command>systemctl reboot -ff</command>). Similarly,
+ <option>poweroff</option>, <option>poweroff-force</option>, <option>poweroff-immediate</option> have the effect
+ of powering down the system with similar semantics. <option>exit</option> causes the manager to exit following
+ the normal shutdown procedure, and <option>exit-force</option> causes it terminate without shutting down
+ services. When <option>exit</option> or <option>exit-force</option> is used by default the exit status of the
+ main process of the unit (if this applies) is returned from the service manager. However, this may be overriden
+ with <varname>FailureActionExitStatus=</varname>/<varname>SuccessActionExitStatus=</varname>, see
+ below.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>FailureActionExitStatus=</varname></term>
+ <term><varname>SuccessActionExitStatus=</varname></term>
+
+ <listitem><para>Controls the exit status to propagate back to an invoking container manager (in case of a
+ system service) or service manager (in case of a user manager) when the
+ <varname>FailureAction=</varname>/<varname>SuccessAction=</varname> are set to <option>exit</option> or
+ <option>exit-force</option> and the action is triggered. By default the exit status of the main process of the
+ triggering unit (if this applies) is propagated. Takes a value in the range 0…255 or the empty string to
+ request default behaviour.</para></listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>JobTimeoutSec=</varname></term>
<term><varname>JobRunningTimeoutSec=</varname></term>
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
+ flushed out too. This means that configuring start rate limiting for a unit that is not referenced continuously
has no effect.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>StartLimitAction=</varname></term>
- <listitem><para>Configure the action to take if the rate limit configured with
- <varname>StartLimitIntervalSec=</varname> and <varname>StartLimitBurst=</varname> is hit. Takes one of
- <option>none</option>, <option>reboot</option>, <option>reboot-force</option>,
- <option>reboot-immediate</option>, <option>poweroff</option>, <option>poweroff-force</option> or
- <option>poweroff-immediate</option>. If <option>none</option> is set, hitting the rate limit will trigger no
- action besides that the start will not be permitted. <option>reboot</option> causes a reboot following the
- normal shutdown procedure (i.e. equivalent to <command>systemctl reboot</command>).
- <option>reboot-force</option> causes a forced reboot which will terminate all processes forcibly but should
- cause no dirty file systems on reboot (i.e. equivalent to <command>systemctl reboot -f</command>) and
- <option>reboot-immediate</option> causes immediate execution of the
- <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> system call, which
- might result in data loss. Similarly, <option>poweroff</option>, <option>poweroff-force</option>,
- <option>poweroff-immediate</option> have the effect of powering down the system with similar
- semantics. Defaults to <option>none</option>.</para></listitem>
+ <listitem><para>Configure an additional action to take if the rate limit configured with
+ <varname>StartLimitIntervalSec=</varname> and <varname>StartLimitBurst=</varname> is hit. Takes the same
+ values as the setting <varname>FailureAction=</varname>/<varname>SuccessAction=</varname> settings and executes
+ the same actions. If <option>none</option> is set, hitting the rate limit will trigger no action besides that
+ the start will not be permitted. Defaults to <option>none</option>.</para></listitem>
</varlistentry>
- <varlistentry>
- <term><varname>FailureAction=</varname></term>
- <term><varname>SuccessAction=</varname></term>
- <listitem><para>Configure the action to take when the unit stops and enters a failed state or inactive
- state. Takes the same values as the setting <varname>StartLimitAction=</varname> setting and executes the same
- actions (see
- <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>). Both options
- default to <option>none</option>.</para></listitem>
- </varlistentry>
<varlistentry>
<term><varname>RebootArgument=</varname></term>
<listitem><para>Before starting a unit, verify that the specified condition is true. If it is not true, the
starting of the unit will be (mostly silently) skipped, however all ordering dependencies of it are still
- respected. A failing condition will not result in the unit being moved into a failure state. The condition is
- checked at the time the queued start job is to be executed. Use condition expressions in order to silently skip
- units that do not apply to the local running system, for example because the kernel or runtime environment
- doesn't require its functionality. Use the various <varname>AssertArchitecture=</varname>,
- <varname>AssertVirtualization=</varname>, … options for a similar mechanism that puts the unit in a failure
- state and logs about the failed check (see below).</para>
+ respected. A failing condition will not result in the unit being moved into the <literal>failed</literal>
+ state. The condition is checked at the time the queued start job is to be executed. Use condition expressions
+ in order to silently skip units that do not apply to the local running system, for example because the kernel
+ or runtime environment doesn't require their functionality. Use the various
+ <varname>AssertArchitecture=</varname>, <varname>AssertVirtualization=</varname>, … options for a similar
+ mechanism that causes the job to fail (instead of being skipped) and results in logging about the failed check
+ (instead of being silently processed). For details about assertion conditions see below.</para>
<para><varname>ConditionArchitecture=</varname> may be used to
check whether the system is running on a specific
kernels into older versions provided by distributions. Hence, this check is inherently unportable and should
not be used for units which may be used on different distributions.</para>
- <para><varname>ConditionSecurity=</varname> may be used to
- check whether the given security module is enabled on the
+ <para><varname>ConditionSecurity=</varname> may be used to check
+ whether the given security technology is enabled on the
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
+ <varname>selinux</varname>, <varname>apparmor</varname>,
+ <varname>tomoyo</varname>, <varname>ima</varname>,
+ <varname>smack</varname>, <varname>audit</varname> and
+ <varname>uefi-secureboot</varname>. The test may be negated by
prepending an exclamation mark.</para>
<para><varname>ConditionCapability=</varname> may be used to
cgroup controller name (eg. <option>cpu</option>), verifying that it is
available for use on the system. For example, a particular controller
may not be available if it was disabled on the kernel command line with
- <literal>cgroup_disable=</literal><replaceable>controller</replaceable>.
- Multiple controllers may be passed with a space separating them; in
- this case the condition will only pass if all listed controllers are
- available for use. Controllers unknown to systemd are ignored. Valid
- controllers are <option>cpu</option>, <option>cpuacct</option>,
- <option>io</option>, <option>blkio</option>, <option>memory</option>,
+ <varname>cgroup_disable=controller</varname>. Multiple controllers may
+ be passed with a space separating them; in this case the condition will
+ only pass if all listed controllers are available for use. Controllers
+ unknown to systemd are ignored. Valid controllers are
+ <option>cpu</option>, <option>cpuacct</option>, <option>io</option>,
+ <option>blkio</option>, <option>memory</option>,
<option>devices</option>, and <option>pids</option>.</para>
<para>If multiple conditions are specified, the unit will be
<listitem><para>Similar to the <varname>ConditionArchitecture=</varname>,
<varname>ConditionVirtualization=</varname>, …, condition settings described above, these settings add
assertion checks to the start-up of the unit. However, unlike the conditions settings, any assertion setting
- that is not met results in failure of the start job (which means this is logged loudly). Use assertion
- expressions for units that cannot operate when specific requirements are not met, and when this is something
- the administrator or user should look into.</para></listitem>
+ that is not met results in failure of the start job (which means this is logged loudly). Note that hitting a
+ configured assertion does not cause the unit to enter the <literal>failed</literal> state (or in fact result in
+ any state change of the unit), it affects only the job queued for it. Use assertion expressions for units that
+ cannot operate when specific requirements are not met, and when this is something the administrator or user
+ should look into.</para>
+
+ <para>Note that neither assertion nor condition expressions result in unit state changes. Also note that both
+ are checked at the time the job is to be executed, i.e. long after depending jobs and it itself were
+ queued. Thus, neither condition nor assertion expressions are suitable for conditionalizing unit
+ dependencies.</para></listitem>
</varlistentry>
<varlistentry>
<para>Unit settings that create a relationship with a second unit usually show up
in properties of both units, for example in <command>systemctl show</command>
output. In some cases the name of the property is the same as the name of the
- configuration setting, but not always. This table lists the pairs of properties
+ configuration setting, but not always. This table lists the properties
that are shown on two units which are connected through some dependency, and shows
which property on "source" unit corresponds to which property on the "target" unit.
</para>
<entry><varname>ReloadPropagatedFrom=</varname></entry>
<entry><varname>PropagatesReloadTo=</varname></entry>
</row>
+ <row>
+ <entry><varname>Following=</varname></entry>
+ <entry>n/a</entry>
+ <entry>An automatic property</entry>
+ </row>
</tbody>
</tgroup>
</table>
<para>Note: <varname>Triggers=</varname> is created implicitly between a socket,
path unit, or an automount unit, and the unit they activate. By default a unit
- with the same name is triggered, but this can be overriden using
+ with the same name is triggered, but this can be overridden using
<varname>Sockets=</varname>, <varname>Service=</varname>, and <varname>Unit=</varname>
settings. See
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for details. <varname>TriggersBy=</varname> is created implicitly on the
triggered unit.</para>
+
+ <para>Note: <varname>Following=</varname> is used to group device aliases and points to the
+ "primary" device unit that systemd is using to track device state, usually corresponding to a
+ sysfs path. It does not show up in the "target" unit.</para>
</refsect1>
<refsect1>
</variablelist>
<para>The following specifiers are interpreted in the Install
- section: %n, %N, %p, %i, %U, %u, %m, %H, %b, %v. For their meaning
- see the next section.
+ section: %n, %N, %p, %i, %j, %g, %G, %U, %u, %m, %H, %b, %v. For their
+ meaning see the next section.
</para>
</refsect1>
</thead>
<tbody>
<row>
- <entry><literal>%n</literal></entry>
- <entry>Full unit name</entry>
- <entry></entry>
+ <entry><literal>%b</literal></entry>
+ <entry>Boot ID</entry>
+ <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry>
</row>
<row>
- <entry><literal>%N</literal></entry>
- <entry>Unescaped full unit name</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>
+ <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>%p</literal></entry>
- <entry>Prefix name</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>
+ <entry><literal>%E</literal></entry>
+ <entry>Configuration directory root</entry>
+ <entry>This is either <filename>/etc</filename> (for the system manager) or the path <literal>$XDG_CONFIG_HOME</literal> resolves to (for user managers).</entry>
</row>
<row>
- <entry><literal>%P</literal></entry>
- <entry>Unescaped prefix name</entry>
- <entry>Same as <literal>%p</literal>, but with escaping undone</entry>
+ <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>. This implements unescaping according to the rules for escaping absolute file system paths discussed above.</entry>
+ </row>
+ <row>
+ <entry><literal>%h</literal></entry>
+ <entry>User home directory</entry>
+ <entry>This is the home directory of the user running the service manager instance. In case of the system manager this resolves to <literal>/root</literal>.</entry>
+ </row>
+ <row>
+ <entry><literal>%H</literal></entry>
+ <entry>Host name</entry>
+ <entry>The hostname of the running system at the point in time the unit configuration is loaded.</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 of the unit name.</entry>
+ <entry>For instantiated units this is the string between the first <literal>@</literal> character and the type suffix. Empty for non-instantiated units.</entry>
</row>
<row>
<entry><literal>%I</literal></entry>
<entry>Unescaped instance name</entry>
- <entry>Same as <literal>%i</literal>, but with escaping undone</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 unescaped prefix name prepended with <filename>/</filename>. This implements unescaping according to the rules for escaping absolute file system paths discussed above.</entry>
+ <entry><literal>%j</literal></entry>
+ <entry>Final component of the prefix</entry>
+ <entry>This is the string between the last <literal>-</literal> and the end of the prefix name. If there is no <literal>-</literal>, this is the same as <literal>%p</literal>.</entry>
</row>
<row>
- <entry><literal>%t</literal></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>
+ <entry><literal>%J</literal></entry>
+ <entry>Unescaped final component of the prefix</entry>
+ <entry>Same as <literal>%j</literal>, but with escaping undone.</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>
+ <entry><literal>%L</literal></entry>
+ <entry>Log 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 noindex='true'>/log</filename> appended (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>
+ <entry><literal>%m</literal></entry>
+ <entry>Machine ID</entry>
+ <entry>The machine ID of the running system, formatted as string. See <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.</entry>
</row>
<row>
- <entry><literal>%L</literal></entry>
- <entry>Log 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 noindex='true'>/log</filename> appended (for user managers).</entry>
+ <entry><literal>%n</literal></entry>
+ <entry>Full unit name</entry>
+ <entry></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>
+ <entry><literal>%N</literal></entry>
+ <entry>Full unit name</entry>
+ <entry>Same as <literal>%n</literal>, but with the type suffix removed.</entry>
</row>
<row>
- <entry><literal>%U</literal></entry>
- <entry>User UID</entry>
- <entry>This is the numeric UID of the user running the service manager instance. In case of the system manager this resolves to <literal>0</literal>.</entry>
+ <entry><literal>%p</literal></entry>
+ <entry>Prefix name</entry>
+ <entry>For instantiated units, this refers to the string before the first <literal>@</literal> character of the unit name. For non-instantiated units, same as <literal>%N</literal>.</entry>
</row>
<row>
- <entry><literal>%h</literal></entry>
- <entry>User home directory</entry>
- <entry>This is the home directory of the user running the service manager instance. In case of the system manager this resolves to <literal>/root</literal>.</entry>
+ <entry><literal>%P</literal></entry>
+ <entry>Unescaped prefix name</entry>
+ <entry>Same as <literal>%p</literal>, but with escaping undone.</entry>
</row>
<row>
<entry><literal>%s</literal></entry>
<entry>This is the shell of the user running the service manager instance. In case of the system manager this resolves to <literal>/bin/sh</literal>.</entry>
</row>
<row>
- <entry><literal>%m</literal></entry>
- <entry>Machine ID</entry>
- <entry>The machine ID of the running system, formatted as string. See <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.</entry>
+ <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>%b</literal></entry>
- <entry>Boot ID</entry>
- <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry>
+ <entry><literal>%t</literal></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>%H</literal></entry>
- <entry>Host name</entry>
- <entry>The hostname of the running system at the point in time the unit configuration is loaded.</entry>
+ <entry><literal>%T</literal></entry>
+ <entry>Directory for temporary files</entry>
+ <entry>This is either <filename>/tmp</filename> or the path <literal>$TMPDIR</literal>, <literal>$TEMP</literal> or <literal>$TMP</literal> are set to.</entry>
+ </row>
+ <row>
+ <entry><literal>%g</literal></entry>
+ <entry>User group</entry>
+ <entry>This is the name of the group running the service manager instance. In case of the system manager this resolves to <literal>root</literal>.</entry>
+ </row>
+ <row>
+ <entry><literal>%G</literal></entry>
+ <entry>User GID</entry>
+ <entry>This is the numeric GID of the user running the service manager instance. In case of the system manager this resolves to <literal>0</literal>.</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>
+ </row>
+ <row>
+ <entry><literal>%U</literal></entry>
+ <entry>User UID</entry>
+ <entry>This is the numeric UID of the user running the service manager instance. In case of the system manager this resolves to <literal>0</literal>.</entry>
</row>
<row>
<entry><literal>%v</literal></entry>
<entry>Kernel release</entry>
<entry>Identical to <command>uname -r</command> output</entry>
</row>
+ <row>
+ <entry><literal>%V</literal></entry>
+ <entry>Directory for larger and persistent temporary files</entry>
+ <entry>This is either <filename>/var/tmp</filename> or the path <literal>$TMPDIR</literal>, <literal>$TEMP</literal> or <literal>$TMP</literal> are set to.</entry>
+ </row>
<row>
<entry><literal>%%</literal></entry>
<entry>Single percent sign</entry>
projects / thirdparty / systemd.git / blobdiff