<filename><replaceable>target</replaceable>.target</filename>,
<filename><replaceable>path</replaceable>.path</filename>,
<filename><replaceable>timer</replaceable>.timer</filename>,
- <filename><replaceable>snapshot</replaceable>.snapshot</filename></para>
+ <filename><replaceable>snapshot</replaceable>.snapshot</filename>,
+ <filename><replaceable>slice</replaceable>.slice</filename>,
+ <filename><replaceable>scope</replaceable>.scope</filename></para>
<para><literallayout><filename>/etc/systemd/system/*</filename>
<filename>/run/systemd/system/*</filename>
<filename>...</filename>
</literallayout></para>
- <para><literallayout><filename>/etc/systemd/user/*</filename>
+ <para><literallayout><filename>$HOME/.config/systemd/user/*</filename>
+<filename>/etc/systemd/user/*</filename>
<filename>/run/systemd/user/*</filename>
<filename>/usr/lib/systemd/user/*</filename>
<filename>...</filename>
<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 file system path, or a timer controlled and
- supervised by
- <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>. The
- syntax is inspired by <ulink
+ target, a watched file system path, a timer controlled
+ and supervised by
+ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ a temporary system state snapshot, 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
+ Desktop Entry Specification</ulink>
+ <filename>.desktop</filename> files, which are in turn
inspired by Microsoft Windows
<filename>.ini</filename> files.</para>
<citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+ <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+ <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 may contain additional options on top
of those listed here. If systemd encounters an unknown
- option it will write a warning log message but
+ option, it will write a warning log message but
continue loading the unit. If an option is prefixed
- with <option>X-</option> it is ignored completely by
+ with <option>X-</option>, it is ignored completely by
systemd. Applications may use this to include
additional information in the unit files.</para>
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
+ equivalent. For negative settings, the strings
<option>0</option>, <option>no</option>,
<option>false</option> and <option>off</option> are
equivalent.</para>
space character. This may be used to wrap long lines.</para>
<para>Along with a unit file
- <filename>foo.service</filename> the directory
+ <filename>foo.service</filename>, the directory
<filename>foo.service.wants/</filename> may exist. All
unit files symlinked from such a directory are
implicitly added as dependencies of type
<varname>Wanted=</varname> to the unit. This is useful
to hook units into the start-up of other units,
without having to modify their unit files. For details
- about the semantics of <varname>Wanted=</varname> see
+ about the semantics of <varname>Wanted=</varname>, see
below. The preferred way to create symlinks in the
<filename>.wants/</filename> directory of a unit file
is with the <command>enable</command> command of the
<filename>.requires/</filename> in this case.</para>
<para>Along with a unit file
- <filename>foo.service</filename> a directory
+ <filename>foo.service</filename>, a 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
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
+ 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
<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
+ 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
name contains an <literal>@</literal> character, systemd will look for a
configuration options. See below for details.</para>
<para>If a unit file is empty (i.e. has the file size
- 0) or is symlinked to <filename>/dev/null</filename>
+ 0) or is symlinked to <filename>/dev/null</filename>,
its configuration will not be loaded and it appears
with a load state of <literal>masked</literal>, and
cannot be activated. Use this as an effective way to
<para>Unit files are loaded from a set of paths
determined during compilation, described in the two
- tables below. Unit files found in directories higher
- in the hierarchy override files with the same name
- lower in the hierarchy, thus allowing overrides.
- </para>
+ tables below. Unit files found in directories listed
+ earlier override files with the same name in
+ directories lower in the list.</para>
<para>When systemd is running in user mode
(<option>--user</option>) and the variable
</row>
</thead>
<tbody>
- <row>
- <entry><filename>/run/systemd/generator.early</filename></entry>
- <entry>Generated units (early)</entry>
- </row>
<row>
<entry><filename>/etc/systemd/system</filename></entry>
<entry>Local configuration</entry>
</row>
<row>
- <entry><filename>/run/systemd/systemd</filename></entry>
- <entry>Volatile units</entry>
- </row>
- <row>
- <entry><filename>/run/systemd/generator</filename></entry>
- <entry>Generated units (middle)</entry>
- </row>
- <row>
- <entry><filename>/usr/local/lib/systemd/system</filename></entry>
- <entry>Units for local packages</entry>
+ <entry><filename>/run/systemd/system</filename></entry>
+ <entry>Runtime units</entry>
</row>
<row>
<entry><filename>/usr/lib/systemd/system</filename></entry>
- <entry>Units for installed packages</entry>
- </row>
- <row>
- <entry><filename>/run/systemd/generator.late</filename></entry>
- <entry>Generated units (late)</entry>
+ <entry>Units of installed packages</entry>
</row>
</tbody>
</tgroup>
<table>
<title>
- Load path when running in session mode (<option>--user</option>).
+ Load path when running in user mode (<option>--user</option>).
</title>
<tgroup cols='2'>
</thead>
<tbody>
<row>
- <entry><filename>/tmp/systemd-generator.early.<replaceable>XXXXXX</replaceable></filename></entry>
- <entry>Generated units (early)</entry>
+ <entry><filename>$HOME/.config/systemd/user</filename></entry>
+ <entry>User configuration</entry>
</row>
<row>
<entry><filename>/etc/systemd/user</filename></entry>
</row>
<row>
<entry><filename>/run/systemd/user</filename></entry>
- <entry>Volatile units</entry>
- </row>
- <row>
- <entry><filename>/tmp/systemd-generator.<replaceable>XXXXXX</replaceable></filename></entry>
- <entry>Generated units (middle)</entry>
- </row>
- <row>
- <entry><filename>/usr/local/lib/systemd/user</filename></entry>
- <entry>Units for local packages</entry>
+ <entry>Runtime units</entry>
</row>
<row>
<entry><filename>/usr/lib/systemd/user</filename></entry>
- <entry>Units for installed packages</entry>
- </row>
- <row>
- <entry><filename>/tmp/systemd-generator.late.<replaceable>XXXXXX</replaceable></filename></entry>
- <entry>Generated units (late)</entry>
+ <entry>Units of installed packages</entry>
</row>
</tbody>
</tgroup>
<para>Additional units might be loaded into systemd
("linked") from directories not on the unit load
path. See the <command>link</command> command for
- <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+ <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. Also,
+ some units are dynamically created via generators
+ <ulink
+ url="http://www.freedesktop.org/wiki/Software/systemd/Generators/">Generators</ulink>.
</para>
</refsect1>
describing the unit. This is intended
for use in UIs to show descriptive
information along with the unit
- name.</para></listitem>
+ 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>
</varlistentry>
<varlistentry>
of the other units gets deactivated or
its activation fails, this unit will
be deactivated. This option may be
- specified more than once, in which
- case requirement dependencies for all
- listed names are created. Note that
- requirement dependencies do not
+ specified more than once or multiple
+ space-separated units may be specified
+ in one option in which case
+ requirement dependencies for all
+ listed names will be created. Note
+ that requirement dependencies do not
influence the order in which services
are started or stopped. This has to be
configured independently with the
the start-up was pulled in indirectly
by some dependency or automatic
start-up of units that is not
- requested by the user this dependency
+ requested by the user, this dependency
must be fulfilled and otherwise the
transaction fails. Hence, this option
may be used to configure dependencies
<term><varname>RequisiteOverridable=</varname></term>
<listitem><para>Similar to
- <varname>Requires=</varname>
- and <varname>RequiresOverridable=</varname>, respectively. However,
- if a unit listed here is not started
- already it will not be started and the
- transaction fails
- immediately.</para></listitem>
+ <varname>Requires=</varname> and
+ <varname>RequiresOverridable=</varname>,
+ respectively. However, if the units
+ listed here are not started already
+ they will not be started and the
+ transaction will fail immediately.
+ </para></listitem>
</varlistentry>
<varlistentry>
<term><varname>Wants=</varname></term>
<listitem><para>A weaker version of
- <varname>Requires=</varname>. A unit
+ <varname>Requires=</varname>. Units
listed in this option will be started
if the configuring unit is. However,
- if the listed unit fails to start up
+ if the listed units fail to start
or cannot be added to the transaction
this has no impact on the validity of
the transaction as a whole. This is
<para>Note that dependencies of this
type may also be configured outside of
- the unit configuration file by
- adding a symlink to a
+ the unit configuration file by adding
+ symlinks to a
<filename>.wants/</filename> directory
accompanying the unit file. For
details see above.</para></listitem>
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>
<varlistentry>
<term><varname>Conflicts=</varname></term>
- <listitem><para>Configures negative
+ <listitem><para>A space-separated list
+ of unit names. Configures negative
requirement dependencies. If a unit
- has a
- <varname>Conflicts=</varname> setting
- on another unit, starting the former
- will stop the latter and vice
+ has a <varname>Conflicts=</varname>
+ setting on another unit, starting the
+ former will stop the latter and vice
versa. Note that this setting is
independent of and orthogonal to the
<varname>After=</varname> and
<term><varname>Before=</varname></term>
<term><varname>After=</varname></term>
- <listitem><para>Configures ordering
+ <listitem><para>A space-separated list
+ of unit names. Configures ordering
dependencies between units. If a unit
<filename>foo.service</filename>
contains a setting
type <varname>After=</varname> or
<varname>Before=</varname>. If two
units have no ordering dependencies
- between them they are shut down
- or started up simultaneously, and
- no ordering takes
+ between them, they are shut down or
+ started up simultaneously, and no
+ ordering takes
place. </para></listitem>
</varlistentry>
<varlistentry>
<term><varname>OnFailure=</varname></term>
- <listitem><para>Lists one or more
- units that are activated when this
- unit enters the
+ <listitem><para>A space-separated list
+ of one or more units that are
+ activated when this unit enters the
<literal>failed</literal>
state.</para></listitem>
</varlistentry>
<term><varname>PropagatesReloadTo=</varname></term>
<term><varname>ReloadPropagatedFrom=</varname></term>
- <listitem><para>Lists one or more
- units where reload requests on the
- unit will be propagated to/on the
- other unit will be propagated
- from. Issuing a reload request on a
- unit will automatically also enqueue a
- reload request on all units that the
- reload request shall be propagated to
- via these two
- settings.</para></listitem>
+ <listitem><para>A space-separated list
+ of one or more units where reload
+ requests on this unit will be
+ propagated to, or reload requests on
+ the other unit will be propagated to
+ this unit, respectively. Issuing a
+ reload request on a unit will
+ automatically also enqueue a reload
+ request on all units that the reload
+ request shall be propagated to via
+ these two settings.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>JoinsNamespaceOf=</varname></term>
+
+ <listitem><para>For units that start
+ processes (such as service units),
+ lists one or more other units whose
+ network and/or temporary file
+ namespace to join. This only applies
+ to unit types which support the
+ <varname>PrivateNetwork=</varname> and
+ <varname>PrivateTmp=</varname>
+ 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
+ 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
+ defined which namespace is
+ joined. Note that this setting only
+ has an effect if
+ <varname>PrivateNetwork=</varname>
+ and/or <varname>PrivateTmp=</varname>
+ is enabled for both the unit that
+ joins the namespace and the unit whose
+ namespace is joined.</para></listitem>
</varlistentry>
<varlistentry>
</varlistentry>
<varlistentry>
- <term><varname>OnFailureIsolate=</varname></term>
-
- <listitem><para>Takes a boolean
- argument. If <option>true</option> the
- unit listed in
+ <term><varname>OnFailureJobMode=</varname></term>
+
+ <listitem><para>Takes a value of
+ <literal>fail</literal>,
+ <literal>replace</literal>,
+ <literal>replace-irreversibly</literal>,
+ <literal>isolate</literal>,
+ <literal>flush</literal>,
+ <literal>ignore-dependencies</literal>
+ or
+ <literal>ignore-requirements</literal>. Defaults
+ to
+ <literal>replace</literal>. Specifies
+ how the units listed in
<varname>OnFailure=</varname> will be
- enqueued in isolation mode, i.e. all
- units that are not its dependency will
- be stopped. If this is set only a
+ enqueued. See
+ <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
+ <option>--job-mode=</option> option
+ for details on the possible values. If
+ this is set to
+ <literal>isolate</literal>, only a
single unit may be listed in
- <varname>OnFailure=</varname>. Defaults
- to
- <option>false</option>.</para></listitem>
+ <varname>OnFailure=</varname>..</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>IgnoreOnIsolate=</varname></term>
<listitem><para>Takes a boolean
- argument. If <option>true</option>
+ argument. If <option>true</option>,
this unit will not be stopped when
isolating another unit. Defaults to
<option>false</option>.</para></listitem>
<term><varname>IgnoreOnSnapshot=</varname></term>
<listitem><para>Takes a boolean
- argument. If <option>true</option>
+ argument. If <option>true</option>,
this unit will not be included in
snapshots. Defaults to
<option>true</option> for device and
<term><varname>StopWhenUnneeded=</varname></term>
<listitem><para>Takes a boolean
- argument. If <option>true</option>
+ argument. If <option>true</option>,
this unit will be stopped when it is
no longer used. Note that in order to
minimize the work to be executed,
<term><varname>RefuseManualStop=</varname></term>
<listitem><para>Takes a boolean
- argument. If <option>true</option>
+ argument. If <option>true</option>,
this unit can only be activated
or deactivated indirectly. In
- this case explicit start-up
+ this case, explicit start-up
or termination requested by the
user is denied, however if it is
started or stopped as a
<term><varname>AllowIsolate=</varname></term>
<listitem><para>Takes a boolean
- argument. If <option>true</option>
+ argument. If <option>true</option>,
this unit may be used with the
<command>systemctl isolate</command>
- command. Otherwise this will be
+ command. Otherwise, this will be
refused. It probably is a good idea to
leave this disabled except for target
units that shall be used similar to
<term><varname>DefaultDependencies=</varname></term>
<listitem><para>Takes a boolean
- argument. If <option>true</option>
+ argument. If <option>true</option>,
(the default), a few default
dependencies will implicitly be
created for the unit. The actual
<listitem><para>When clients are
waiting for a job of this unit to
complete, time out after the specified
- time. If this time limit is reached
+ time. If this time limit is reached,
the job will be cancelled, the unit
however will not change state or even
enter the <literal>failed</literal>
<listitem><para>Before starting a unit
verify that the specified condition is
- true. If it is not true the starting
+ true. If it is not true, the starting
of the unit will be skipped, however
all ordering dependencies of it are
still respected. A failing condition
a file existence condition is
checked before a unit is started. If
the specified absolute path name does
- not exist the condition will
+ not exist, the condition will
fail. If the absolute path name passed
to
<varname>ConditionPathExists=</varname>
<varname>systemd-nspawn</varname> to
test against a specific
implementation. If multiple
- virtualization technologies are nested
+ virtualization technologies are nested,
only the innermost is considered. The
test may be negated by prepending an
exclamation mark.</para>
battery powered at the time of
activation of the unit. This takes a
boolean argument. If set to
- <varname>true</varname> the condition
+ <varname>true</varname>, the condition
will hold only if at least one AC
connector of the system is connected
to a power source, or if no AC
connectors are known. Conversely, if
- set to <varname>false</varname> the
+ set to <varname>false</varname>, the
condition will hold only if there is
at least one AC connector known and
all AC connectors are disconnected
be used to add a constant condition
check value to the unit. It takes a
boolean argument. If set to
- <varname>false</varname> the condition
+ <varname>false</varname>, the condition
will always fail, otherwise
succeed.</para>
<para>If multiple conditions are
- specified the unit will be executed if
+ specified, the unit will be executed if
all of them apply (i.e. a logical AND
is applied). Condition checks can be
prefixed with a pipe symbol (|) in
which case a condition becomes a
triggering condition. If at least one
triggering condition is defined for a
- unit then the unit will be executed if
+ unit, then the unit will be executed if
at least one of the triggering
conditions apply and all of the
non-triggering conditions. If you
prefix an argument with the pipe
- symbol and an exclamation mark the
+ symbol and an exclamation mark, the
pipe symbol must be passed first, the
exclamation second. Except for
<varname>ConditionPathIsSymbolicLink=</varname>,
all path checks follow symlinks. If
any of these options is assigned the
- empty string the list of conditions is
+ empty string, the list of conditions is
reset completely, all previous
condition settings (of any kind) will
have no effect.</para></listitem>
<varlistentry>
<term><varname>Alias=</varname></term>
- <listitem><para>Additional names this
- unit shall be installed under. The
- names listed here must have the same
- suffix (i.e. type) as the unit file
- name. This option may be specified
- more than once, in which case all
- listed names are used. At installation
- time,
- <command>systemctl enable</command>
- will create symlinks from these names
- to the unit filename.</para></listitem>
+ <listitem><para>A space-seperated list
+ of additional names this unit shall be
+ installed under. The names listed here
+ must have the same suffix (i.e. type)
+ as the unit file name. This option may
+ be specified more than once, in which
+ case all listed names are used. At
+ installation time, <command>systemctl
+ enable</command> will create symlinks
+ from these names to the unit
+ filename.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>WantedBy=</varname></term>
<term><varname>RequiredBy=</varname></term>
- <listitem><para>A symbolic link is
- created in the
- <filename>.wants/</filename> or
- <filename>.requires/</filename> folder
- of the listed unit when this unit is
- activated by <command>systemctl
- enable</command>. This has the effect
- that a dependency of type
- <varname>Wants=</varname> or
+ <listitem><para>This option may be
+ used more than once, or a
+ space-separated list of unit names may
+ be given. A symbolic link is created
+ in the <filename>.wants/</filename> or
+ <filename>.requires/</filename>
+ directory of each of the listed units
+ when this unit is installed by
+ <command>systemctl enable</command>.
+ This has the effect that a dependency
+ of type <varname>Wants=</varname> or
<varname>Requires=</varname> is added
from the listed unit to the current
unit. The primary result is that the
and <command>systemctl
disable</command> will automatically
install/uninstall units listed in this option as
- well.</para></listitem>
+ well.</para>
+
+ <para>This option may be used more
+ than once, or a space-separated list
+ of unit names may be
+ given.</para></listitem>
</varlistentry>
</variablelist>
<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>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>
</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. This specifier is particularly useful in the <varname>ControlGroup=</varname> setting (see <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>).</entry>
+ <entry>For system instances, this usually
+ resolves to <filename>/</filename>, except in
+ containers, where this resolves to the
+ container's root directory.</entry>
</row>
<row>
<entry><literal>%t</literal></entry>
<citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
<citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
~ianmdlvl / elogind.git / blobdiff