X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsystemd.unit.xml;h=9704d6f2277a1b645f0c510739f04a33f3f44052;hb=78eb158a20e2bee772f6e49d8b432b98f68cbb55;hp=157530be38a3deae624ccb6bb82660856167e935;hpb=b8bde11658366290521e3d03316378b482600323;p=elogind.git
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index 157530be3..9704d6f22 100644
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -73,7 +73,10 @@
$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/*...
@@ -139,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
@@ -176,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
@@ -199,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
@@ -215,12 +229,17 @@
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
- unprintable characters and the "-" are replaced by
- C-style "\x20" 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.
+ given a path, "/" is replaced by "-" and all other
+ characters which are not ASCII alphanumerics are
+ replaced by C-style "\x2d" escapes (except that "_"
+ is never replaced and "." is only replaced when it
+ would be the first character in the escaped path).
+ The root directory "/" is encoded as single dash,
+ while otherwise the initial and ending "/" are removed
+ from all paths during transformation. This escaping
+ is reversible. Properly escaped paths can be generated
+ using the systemd-escape1
+ command.
Optionally, units may be instantiated from a
template file at runtime. This allows creation of
@@ -269,10 +288,12 @@
When systemd is running in user mode
() and the variable
- $SYSTEMD_UNIT_PATH is set, this
+ $SYSTEMD_UNIT_PATH is set, the
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.
@@ -332,13 +353,25 @@
<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>
@@ -394,7 +427,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
@@ -864,20 +897,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
@@ -887,7 +922,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>
@@ -898,6 +948,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>
@@ -907,7 +959,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
@@ -928,7 +984,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>,
@@ -937,7 +995,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>,
@@ -945,7 +1005,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
@@ -976,23 +1038,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
@@ -1027,14 +1093,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
@@ -1043,7 +1110,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
@@ -1066,6 +1133,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
@@ -1137,15 +1243,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
@@ -1171,6 +1268,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
@@ -1179,7 +1308,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>
@@ -1190,9 +1319,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
@@ -1204,7 +1334,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)
@@ -1284,6 +1414,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
@@ -1418,13 +1561,188 @@
+
+ Please note that specifiers
+ %U, %h,
+ %s are mostly useless when systemd
+ is running in system mode. PID 1 cannot query the
+ user account database for information, so the
+ specifiers only work as shortcuts for things which are
+ already specified in a different way in the unit
+ file. They are fully functional when systemd is
+ running in mode.
+
+
+
+ Examples
+
+
+ Allowing units to be enabled
+
+ The following snippet (highlighted)
+ allows a unit (e.g.
+ foo.service) to be
+ enabled via
+ systemctl enable:
+
+ [Unit]
+Description=Foo
+
+[Service]
+ExecStart=/usr/sbin/foo-daemon
+
+[Install]
+WantedBy=multi-user.target
+
+ After running
+ systemctl enable, a symlink
+ /etc/systemd/system/multi-user.target.wants/foo.service
+ linking to the actual unit will be created. It
+ tells systemd to pull in the unit when starting
+ multi-user.target. The
+ inverse systemctl disable
+ will remove that symlink again.
+
+
+
+ Overriding vendor settings
+
+ There are two methods of overriding
+ vendor settings in unit files: copying the unit
+ file from
+ /usr/lib/systemd/system
+ to /etc/systemd/system and
+ modifying the chosen settings. Alternatively,
+ one can create a directory named
+ unit.d/
+ within
+ /etc/systemd/system and
+ place a drop-in file
+ name.conf
+ there that only changes the specific settings
+ one is interested in. Note that multiple such
+ drop-in files are read if present.
+
+ The advantage of the first method is
+ that one easily overrides the complete unit,
+ the vendor unit is not parsed at all anymore.
+ It has the disadvantage that improvements to
+ the unit file by the vendor are not
+ automatically incorporated on updates.
+
+ The advantage of the second method is
+ that one only overrides the settings one
+ specifically wants, where updates to the unit
+ by the vendor automatically apply. This has the
+ disadvantage that some future updates by the
+ vendor might be incompatible with the local
+ changes.
+
+ Note that for drop-in files, if one wants
+ to remove entries from a setting that is parsed
+ as a list (and is not a dependency), such as
+ ConditionPathExists= (or
+ e.g. ExecStart= in service
+ units), one needs to first clear the list
+ before re-adding all entries except the one
+ that is to be removed. See below for an
+ example.
+
+ This also applies for user instances of
+ systemd, but with different locations for the
+ unit files. See the section on unit load paths
+ for further details.
+
+ Suppose there is a vendor-supplied unit
+ /usr/lib/systemd/system/httpd.service
+ with the following contents:
+
+ [Unit]
+Description=Some HTTP server
+After=remote-fs.target sqldb.service
+Requires=sqldb.service
+AssertPathExists=/srv/webserver
+
+[Service]
+Type=notify
+ExecStart=/usr/sbin/some-fancy-httpd-server
+Nice=5
+
+[Install]
+WantedBy=multi-user.target
+
+ Now one wants to change some settings as
+ an administrator: firstly, in the local setup,
+ /srv/webserver might not
+ exit, because the HTTP server is configured to
+ use /srv/www instead.
+ Secondly, the local configuration makes the
+ HTTP server also depend on a memory cache
+ service,
+ memcached.service, that
+ should be pulled in
+ (Requires=) and also be
+ ordered appropriately
+ (After=). Thirdly, in order
+ to harden the service a bit more, the
+ administrator would like to set the
+ PrivateTmp=
+ setting (see
+ systemd.service5
+ for details). And lastly, the administrator
+ would like to reset the niceness of the service
+ to its default value of 0.
+
+ The first possibility is to copy the unit
+ file to
+ /etc/systemd/system/httpd.service
+ and change the chosen settings:
+
+ [Unit]
+Description=Some HTTP server
+After=remote-fs.target sqldb.service memcached.service
+Requires=sqldb.service memcached.service
+AssertPathExists=/srv/www
+
+[Service]
+Type=notify
+ExecStart=/usr/sbin/some-fancy-httpd-server
+Nice=0
+PrivateTmp=yes
+
+[Install]
+WantedBy=multi-user.target
+
+ Alternatively, the administrator could
+ create a drop-in file
+ /etc/systemd/system/httpd.service.d/local.conf
+ with the following contents:
+
+ [Unit]
+After=memcached.service
+Requires=memcached.service
+# Reset all assertions and then re-add the condition we want
+AssertPathExists=
+AssertPathExists=/srv/www
+
+[Service]
+Nice=0
+PrivateTmp=yes
+
+ Note that dependencies
+ (After=, etc.) cannot be
+ reset to an empty list, so dependencies can
+ only be added in drop-ins. If you want to
+ remove dependencies, you have to override the
+ entire unit.
+ See Alsosystemd1,
- systemctl8,
+ systemctl1,
systemd.special7,
systemd.service5,
systemd.socket5,
@@ -1439,7 +1757,8 @@
systemd.scope5,
systemd.slice5,
systemd.time7,
- capabilities7,
+ systemd-analyze1,
+ capabilities7,
systemd.directives7,
uname1