X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd.unit.xml;h=2e298ca04f06caaa6318735a288c1bb4512eca9e;hp=07a73fd923e85761f1b070214b57c3030f2f38c7;hb=d55192add75584f55932ad463ee6b4cc30370c63;hpb=f7be6ffa926a0b81495ee201aba933824ab417a4
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index 07a73fd92..2e298ca04 100644
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -70,9 +70,13 @@
...
- $HOME/.config/systemd/user/*
+ $XDG_CONFIG_HOME/systemd/user/*
+$HOME/.config/systemd/user/*/etc/systemd/user/*
+$XDG_RUNTIME_DIR/systemd/user/*/run/systemd/user/*
+$XDG_DATA_HOME/systemd/user/*
+$HOME/.local/share/systemd/user/*/usr/lib/systemd/user/*...
@@ -138,10 +142,12 @@
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 option is prefixed
- with , it is ignored completely by
- systemd. Applications may use this to include
- additional information in the unit files.
+ continue loading the unit. If an option or section name
+ is prefixed with , it is ignored
+ completely by systemd. Options within an ignored
+ section do not need the prefix. Applications may use
+ this to include additional information in the unit
+ files.Boolean arguments used in unit files can be
written in various formats. For positive settings the
@@ -175,10 +181,10 @@
foo.service.wants/ may exist. All
unit files symlinked from such a directory are
implicitly added as dependencies of type
- Wanted= to the unit. This is useful
+ Wants= 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 Wanted=, see
+ about the semantics of Wants=, see
below. The preferred way to create symlinks in the
.wants/ directory of a unit file
is with the enable command of the
@@ -198,7 +204,16 @@
settings to a unit, without having to modify their
unit files. Make sure that the file that is included
has the appropriate section headers before any
- directive.
+ directive. Note that for instanced units this logic
+ will first look for the instance
+ .d/ subdirectory and read its
+ .conf files, followed by the
+ template .d/ subdirectory and reads
+ its .conf files.
+
+
Note that while systemd offers a flexible
dependency system between units it is recommended to
@@ -216,7 +231,7 @@
result is usable as part of a filename. Basically,
given a path, "/" is replaced by "-", and all
unprintable characters and the "-" are replaced by
- C-style "\x20" escapes. The root directory "/" is
+ C-style "\x2d" escapes. The root directory "/" is
encoded as single dash, while otherwise the initial
and ending "/" is removed from all paths during
transformation. This escaping is reversible.
@@ -270,8 +285,10 @@
() and the variable
$SYSTEMD_UNIT_PATH is set, this
contents of this variable overrides the unit load
- path.
-
+ path. If $SYSTEMD_UNIT_PATH ends
+ with an empty component (:), the
+ usual unit load path will be appended to the contents
+ of the variable.
@@ -319,21 +336,37 @@
</row>
</thead>
<tbody>
+ <row>
+ <entry><filename>$XDG_CONFIG_HOME/systemd/user</filename></entry>
+ <entry>User configuration (only used when $XDG_CONFIG_HOME is set)</entry>
+ </row>
<row>
<entry><filename>$HOME/.config/systemd/user</filename></entry>
- <entry>User configuration</entry>
+ <entry>User configuration (only used when $XDG_CONFIG_HOME is not set)</entry>
</row>
<row>
<entry><filename>/etc/systemd/user</filename></entry>
<entry>Local configuration</entry>
</row>
+ <row>
+ <entry><filename>$XDG_RUNTIME_DIR/systemd/user</filename></entry>
+ <entry>Runtime units (only used when $XDG_RUNTIME_DIR is set)</entry>
+ </row>
<row>
<entry><filename>/run/systemd/user</filename></entry>
<entry>Runtime units</entry>
</row>
+ <row>
+ <entry><filename>$XDG_DATA_HOME/systemd/user</filename></entry>
+ <entry>Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is set)</entry>
+ </row>
+ <row>
+ <entry><filename>$HOME/.local/share/systemd/user</filename></entry>
+ <entry>Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is not set)</entry>
+ </row>
<row>
<entry><filename>/usr/lib/systemd/user</filename></entry>
- <entry>Units of installed packages</entry>
+ <entry>Units of packages that have been installed system-wide</entry>
</row>
</tbody>
</tgroup>
@@ -389,7 +422,7 @@
<literal>man:</literal>. For more
information about the syntax of these
URIs, see
- <citerefentry><refentrytitle>uri</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
+ <citerefentry project='man-pages'><refentrytitle>uri</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
URIs should be listed in order of
relevance, starting with the most
relevant. It is a good idea to first
@@ -700,13 +733,26 @@
<varlistentry>
<term><varname>RequiresMountsFor=</varname></term>
- <listitem><para>Takes a space-separated
- list of absolute paths. Automatically
- adds dependencies of type
- <varname>Requires=</varname> and
- <varname>After=</varname> for all
+ <listitem><para>Takes a
+ space-separated list of absolute
+ paths. Automatically adds dependencies
+ of type <varname>Requires=</varname>
+ and <varname>After=</varname> for all
mount units required to access the
- specified path.</para></listitem>
+ specified path.</para>
+
+ <para>Mount points marked with
+ <option>noauto</option> are not
+ mounted automatically and will be
+ ignored for the purposes of this
+ option. If such a mount should be a
+ requirement for this unit,
+ direct dependencies on the mount
+ units may be added
+ (<varname>Requires=</varname> and
+ <varname>After=</varname> or
+ some other combination).
+ </para></listitem>
</varlistentry>
<varlistentry>
@@ -846,20 +892,22 @@
<varlistentry>
<term><varname>JobTimeoutSec=</varname></term>
-
- <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,
- the job will be cancelled, the unit
- however will not change state or even
- enter the <literal>failed</literal>
- mode. This value defaults to 0 (job
- timeouts disabled), except for device
+ <term><varname>JobTimeoutAction=</varname></term>
+ <term><varname>JobTimeoutRebootArgument=</varname></term>
+
+ <listitem><para>When a job for this
+ unit is queued a time-out may be
+ configured. 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> mode. This
+ value defaults to 0 (job timeouts
+ disabled), except for device
units. NB: this timeout is independent
from any unit-specific timeout (for
example, the timeout set with
- <varname>Timeout=</varname> in service
+ <varname>StartTimeoutSec=</varname> in service
units) as the job timeout has no
effect on the unit itself, only on the
job that might be pending for it. Or
@@ -869,7 +917,22 @@
timeout set with this option however
is useful to abort only the job
waiting for the unit state to
- change.</para></listitem>
+ change.</para>
+
+ <para><varname>JobTimeoutAction=</varname>
+ optionally configures an additional
+ action to take when the time-out is
+ hit. It takes the same values as the
+ per-service
+ <varname>StartLimitAction=</varname>
+ setting, see
+ <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for details. Defaults to
+ <option>none</option>. <varname>JobTimeoutRebootArgument=</varname>
+ configures an optional reboot string
+ to pass to the
+ <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+ system call.</para></listitem>
</varlistentry>
<varlistentry>
@@ -880,6 +943,8 @@
<term><varname>ConditionSecurity=</varname></term>
<term><varname>ConditionCapability=</varname></term>
<term><varname>ConditionACPower=</varname></term>
+ <term><varname>ConditionNeedsUpdate=</varname></term>
+ <term><varname>ConditionFirstBoot=</varname></term>
<term><varname>ConditionPathExists=</varname></term>
<term><varname>ConditionPathExistsGlob=</varname></term>
<term><varname>ConditionPathIsDirectory=</varname></term>
@@ -889,7 +954,11 @@
<term><varname>ConditionDirectoryNotEmpty=</varname></term>
<term><varname>ConditionFileNotEmpty=</varname></term>
<term><varname>ConditionFileIsExecutable=</varname></term>
- <term><varname>ConditionNull=</varname></term>
+
+ <!-- We don't document ConditionNull=
+ here as it is not particularly
+ useful and probably just
+ confusing. -->
<listitem><para>Before starting a unit
verify that the specified condition is
@@ -910,7 +979,9 @@
<varname>x86</varname>,
<varname>x86-64</varname>,
<varname>ppc</varname>,
+ <varname>ppc-le</varname>,
<varname>ppc64</varname>,
+ <varname>ppc64-le</varname>,
<varname>ia64</varname>,
<varname>parisc</varname>,
<varname>parisc64</varname>,
@@ -919,7 +990,9 @@
<varname>sparc</varname>,
<varname>sparc64</varname>,
<varname>mips</varname>,
+ <varname>mips-le</varname>,
<varname>mips64</varname>,
+ <varname>mips64-le</varname>,
<varname>alpha</varname>,
<varname>arm</varname>,
<varname>arm-be</varname>,
@@ -927,7 +1000,9 @@
<varname>arm64-be</varname>,
<varname>sh</varname>,
<varname>sh64</varname>,
- <varname>m86k</varname> to test
+ <varname>m86k</varname>,
+ <varname>tilegx</varname>,
+ <varname>cris</varname> to test
against a specific architecture. The
architecture is determined from the
information returned by
@@ -958,23 +1033,27 @@
virtualization solution, or one of
<varname>qemu</varname>,
<varname>kvm</varname>,
+ <varname>zvm</varname>,
<varname>vmware</varname>,
<varname>microsoft</varname>,
<varname>oracle</varname>,
<varname>xen</varname>,
<varname>bochs</varname>,
- <varname>chroot</varname>,
<varname>uml</varname>,
<varname>openvz</varname>,
<varname>lxc</varname>,
<varname>lxc-libvirt</varname>,
- <varname>systemd-nspawn</varname> to
- test against a specific
- implementation. If multiple
- virtualization technologies are nested,
- only the innermost is considered. The
- test may be negated by prepending an
- exclamation mark.</para>
+ <varname>systemd-nspawn</varname>,
+ <varname>docker</varname> to test
+ against a specific implementation. See
+ <citerefentry><refentrytitle>systemd-detect-virt</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ for a full list of known
+ virtualization technologies and their
+ identifiers. If multiple
+ virtualization technologies are
+ nested, only the innermost is
+ considered. The test may be negated by
+ prepending an exclamation mark.</para>
<para><varname>ConditionHost=</varname>
may be used to match against the
@@ -1001,7 +1080,7 @@
case the kernel command line is
searched for the word appearing as is,
or as left hand side of an
- assignment. In the latter case the
+ assignment. In the latter case, the
exact assignment is looked for with
right and left hand side
matching.</para>
@@ -1009,14 +1088,15 @@
<para><varname>ConditionSecurity=</varname>
may be used to check whether the given
security module is enabled on the
- system. Currently the recognized values
- values are <varname>selinux</varname>,
+ system. Currently the recognized
+ values values are
+ <varname>selinux</varname>,
<varname>apparmor</varname>,
- <varname>ima</varname> and
- <varname>smack</varname>.
- The test may be negated by prepending
- an exclamation
- mark.</para>
+ <varname>ima</varname>,
+ <varname>smack</varname> and
+ <varname>audit</varname>. The test may
+ be negated by prepending an
+ exclamation mark.</para>
<para><varname>ConditionCapability=</varname>
may be used to check whether the given
@@ -1025,7 +1105,7 @@
(i.e. this does not check whether
capability is actually available in
the permitted or effective sets, see
- <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
for details). Pass a capability name
such as <literal>CAP_MKNOD</literal>,
possibly prefixed with an exclamation
@@ -1048,6 +1128,45 @@
all AC connectors are disconnected
from a power source.</para>
+ <para><varname>ConditionNeedsUpdate=</varname>
+ takes one of <filename>/var</filename>
+ or <filename>/etc</filename> as
+ argument, possibly prefixed with a
+ <literal>!</literal> (for inverting
+ the condition). This condition may be
+ used to conditionalize units on
+ whether the specified directory
+ requires an update because
+ <filename>/usr</filename>'s
+ modification time is newer than the
+ stamp file
+ <filename>.updated</filename> in the
+ specified directory. This is useful to
+ implement offline updates of the
+ vendor operating system resources in
+ <filename>/usr</filename> that require
+ updating of <filename>/etc</filename>
+ or <filename>/var</filename> on the
+ next following boot. Units making use
+ of this condition should order
+ themselves before
+ <citerefentry><refentrytitle>systemd-update-done.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+ to make sure they run before the stamp
+ files's modification time gets reset
+ indicating a completed update.</para>
+
+ <para><varname>ConditionFirstBoot=</varname>
+ takes a boolean argument. This
+ condition may be used to
+ conditionalize units on whether the
+ system is booting up with an
+ unpopulated <filename>/etc</filename>
+ directory. This may be used to
+ populate <filename>/etc</filename> on
+ the first boot after factory reset, or
+ when a new system instances boots up
+ for the first time.</para>
+
<para>With
<varname>ConditionPathExists=</varname>
a file existence condition is
@@ -1119,15 +1238,6 @@
exists, is a regular file and marked
executable.</para>
- <para>Finally,
- <varname>ConditionNull=</varname> may
- 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
- will always fail, otherwise
- succeed.</para>
-
<para>If multiple conditions are
specified, the unit will be executed if
all of them apply (i.e. a logical AND
@@ -1153,6 +1263,38 @@
have no effect.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>AssertArchitecture=</varname></term>
+ <term><varname>AssertVirtualization=</varname></term>
+ <term><varname>AssertHost=</varname></term>
+ <term><varname>AssertKernelCommandLine=</varname></term>
+ <term><varname>AssertSecurity=</varname></term>
+ <term><varname>AssertCapability=</varname></term>
+ <term><varname>AssertACPower=</varname></term>
+ <term><varname>AssertNeedsUpdate=</varname></term>
+ <term><varname>AssertFirstBoot=</varname></term>
+ <term><varname>AssertPathExists=</varname></term>
+ <term><varname>AssertPathExistsGlob=</varname></term>
+ <term><varname>AssertPathIsDirectory=</varname></term>
+ <term><varname>AssertPathIsSymbolicLink=</varname></term>
+ <term><varname>AssertPathIsMountPoint=</varname></term>
+ <term><varname>AssertPathIsReadWrite=</varname></term>
+ <term><varname>AssertDirectoryNotEmpty=</varname></term>
+ <term><varname>AssertFileNotEmpty=</varname></term>
+ <term><varname>AssertFileIsExecutable=</varname></term>
+
+ <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 it was triggered by.</para></listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>SourcePath=</varname></term>
<listitem><para>A path to a
@@ -1161,7 +1303,7 @@
useful for implementation of generator
tools that convert configuration from
an external configuration file format
- into native unit files. Thus
+ into native unit files. This
functionality should not be used in
normal units.</para></listitem>
</varlistentry>
@@ -1172,9 +1314,10 @@
<refsect1>
<title>[Install] Section Options
- Unit file may include a [Install] section, which
- carries installation information for the unit. This
- section is not interpreted by
+ Unit file may include an
+ [Install] section, which carries
+ installation information for the unit. This section is
+ not interpreted by
systemd1
during runtime. It is used exclusively by the
enable and
@@ -1186,7 +1329,7 @@
Alias=
- A space-seperated list
+ A space-separated list
of additional names this unit shall be
installed under. The names listed here
must have the same suffix (i.e. type)
@@ -1266,6 +1409,19 @@
of unit names may be
given.
+
+
+ DefaultInstance=
+
+ In template unit files,
+ this specifies for which instance the
+ unit shall be enabled if the template
+ is enabled without any explicitly set
+ instance. This option has no effect in
+ non-template unit files. The specified
+ string must be usable as instance
+ identifier.
+ The following specifiers are interpreted in the
@@ -1406,7 +1562,7 @@
See Alsosystemd1,
- systemctl8,
+ systemctl1,
systemd.special7,
systemd.service5,
systemd.socket5,
@@ -1421,7 +1577,8 @@
systemd.scope5,
systemd.slice5,
systemd.time7,
- capabilities7,
+ systemd-verify1,
+ capabilities7,
systemd.directives7,
uname1