X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsystemd.unit.xml;h=9704d6f2277a1b645f0c510739f04a33f3f44052;hb=d44efb621acfbd09973b7e63246536fd53405d4e;hp=02445703617bbf962ed29d4e26e7510597ee8cda;hpb=b040723ea412209e0edf54647fa5aa4287411507;p=elogind.git
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index 024457036..9704d6f22 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,13 +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.
- If a line starts with
- followed by a filename, the specified file will be
- parsed at this point. Make sure that the file that is
- included has the appropriate section headers before
- any directives.
+
Note that while systemd offers a flexible
dependency system between units it is recommended to
@@ -220,19 +229,24 @@
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
multiple units from a single configuration file. If
systemd looks for a unit configuration file, it will
first search for the literal unit name in the
- filesystem. If that yields no success and the unit
+ file system. If that yields no success and the unit
name contains an @ character, systemd will look for a
unit template that shares the same name but with the
instance string (i.e. the part between the @ character
@@ -274,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.
@@ -325,21 +341,37 @@
+
+ $XDG_CONFIG_HOME/systemd/user
+ User configuration (only used when $XDG_CONFIG_HOME is set)
+ $HOME/.config/systemd/user
- User configuration
+ User configuration (only used when $XDG_CONFIG_HOME is not set)/etc/systemd/userLocal configuration
+
+ $XDG_RUNTIME_DIR/systemd/user
+ Runtime units (only used when $XDG_RUNTIME_DIR is set)
+ /run/systemd/userRuntime units
+
+ $XDG_DATA_HOME/systemd/user
+ Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is set)
+
+
+ $HOME/.local/share/systemd/user
+ Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is not set)
+ /usr/lib/systemd/user
- Units of installed packages
+ Units of packages that have been installed system-wide
@@ -356,7 +388,7 @@
- Options
+ [Unit] Section OptionsUnit file may include a [Unit] section, which
carries generic information about the unit that is not
@@ -395,7 +427,7 @@
man:. For more
information about the syntax of these
URIs, see
- uri7. The
+ uri7. The
URIs should be listed in order of
relevance, starting with the most
relevant. It is a good idea to first
@@ -548,7 +580,7 @@
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.
@@ -706,13 +738,26 @@
RequiresMountsFor=
- Takes a space-separated
- list of absolute paths. Automatically
- adds dependencies of type
- Requires= and
- After= for all
+ Takes a
+ space-separated list of absolute
+ paths. Automatically adds dependencies
+ of type Requires=
+ and After= for all
mount units required to access the
- specified path.
+ specified path.
+
+ Mount points marked with
+ 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
+ (Requires= and
+ After= or
+ some other combination).
+
@@ -852,20 +897,22 @@
JobTimeoutSec=
-
- 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 failed
- mode. This value defaults to 0 (job
- timeouts disabled), except for device
+ JobTimeoutAction=
+ JobTimeoutRebootArgument=
+
+ 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
+ failed 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
- Timeout= in service
+ StartTimeoutSec= 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
@@ -875,10 +922,34 @@
timeout set with this option however
is useful to abort only the job
waiting for the unit state to
- change.
+ change.
+
+ JobTimeoutAction=
+ optionally configures an additional
+ action to take when the time-out is
+ hit. It takes the same values as the
+ per-service
+ StartLimitAction=
+ setting, see
+ systemd.service5
+ for details. Defaults to
+ . JobTimeoutRebootArgument=
+ configures an optional reboot string
+ to pass to the
+ reboot2
+ system call.
+ ConditionArchitecture=
+ ConditionVirtualization=
+ ConditionHost=
+ ConditionKernelCommandLine=
+ ConditionSecurity=
+ ConditionCapability=
+ ConditionACPower=
+ ConditionNeedsUpdate=
+ ConditionFirstBoot=ConditionPathExists=ConditionPathExistsGlob=ConditionPathIsDirectory=
@@ -888,13 +959,11 @@
ConditionDirectoryNotEmpty=ConditionFileNotEmpty=ConditionFileIsExecutable=
- ConditionKernelCommandLine=
- ConditionVirtualization=
- ConditionSecurity=
- ConditionCapability=
- ConditionHost=
- ConditionACPower=
- ConditionNull=
+
+
Before starting a unit
verify that the specified condition is
@@ -908,6 +977,201 @@
queued start job is to be
executed.
+ ConditionArchitecture=
+ may be used to check whether the
+ system is running on a specific
+ architecture. Takes one of
+ x86,
+ x86-64,
+ ppc,
+ ppc-le,
+ ppc64,
+ ppc64-le,
+ ia64,
+ parisc,
+ parisc64,
+ s390,
+ s390x,
+ sparc,
+ sparc64,
+ mips,
+ mips-le,
+ mips64,
+ mips64-le,
+ alpha,
+ arm,
+ arm-be,
+ arm64,
+ arm64-be,
+ sh,
+ sh64,
+ m86k,
+ tilegx,
+ cris to test
+ against a specific architecture. The
+ architecture is determined from the
+ information returned by
+ uname2
+ and is thus subject to
+ personality2. Note
+ that a Personality=
+ setting in the same unit file has no
+ effect on this condition. A special
+ architecture name
+ native is mapped to
+ the architecture the system manager
+ itself is compiled for. The test may
+ be negated by prepending an
+ exclamation mark.
+
+ ConditionVirtualization=
+ may be used to check whether the
+ system is executed in a virtualized
+ environment and optionally test
+ whether it is a specific
+ implementation. Takes either boolean
+ value to check if being executed in
+ any virtualized environment, or one of
+ vm and
+ container to test
+ against a generic type of
+ virtualization solution, or one of
+ qemu,
+ kvm,
+ zvm,
+ vmware,
+ microsoft,
+ oracle,
+ xen,
+ bochs,
+ uml,
+ openvz,
+ lxc,
+ lxc-libvirt,
+ systemd-nspawn,
+ docker to test
+ against a specific implementation. See
+ systemd-detect-virt1
+ 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.
+
+ ConditionHost=
+ may be used to match against the
+ hostname or machine ID of the
+ host. This either takes a hostname
+ string (optionally with shell style
+ globs) which is tested against the
+ locally set hostname as returned by
+ gethostname2,
+ or a machine ID formatted as string
+ (see
+ machine-id5).
+ The test may be negated by prepending
+ an exclamation mark.
+
+ ConditionKernelCommandLine=
+ may be used to check whether a
+ specific kernel command line option is
+ set (or if prefixed with the
+ exclamation mark unset). The argument
+ must either be a single word, or an
+ assignment (i.e. two words, separated
+ =). In the former
+ 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
+ exact assignment is looked for with
+ right and left hand side
+ matching.
+
+ ConditionSecurity=
+ may be used to check whether the given
+ security module is enabled on the
+ system. Currently the recognized
+ values values are
+ selinux,
+ apparmor,
+ ima,
+ smack and
+ audit. The test may
+ be negated by prepending an
+ exclamation mark.
+
+ ConditionCapability=
+ may be used to check whether the given
+ capability exists in the capability
+ bounding set of the service manager
+ (i.e. this does not check whether
+ capability is actually available in
+ the permitted or effective sets, see
+ capabilities7
+ for details). Pass a capability name
+ such as CAP_MKNOD,
+ possibly prefixed with an exclamation
+ mark to negate the check.
+
+ ConditionACPower=
+ may be used to check whether the
+ system has AC power, or is exclusively
+ battery powered at the time of
+ activation of the unit. This takes a
+ boolean argument. If set to
+ true, 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 false, the
+ condition will hold only if there is
+ at least one AC connector known and
+ all AC connectors are disconnected
+ from a power source.
+
+ ConditionNeedsUpdate=
+ takes one of /var
+ or /etc as
+ argument, possibly prefixed with a
+ ! (for inverting
+ the condition). This condition may be
+ used to conditionalize units on
+ whether the specified directory
+ requires an update because
+ /usr's
+ modification time is newer than the
+ stamp file
+ .updated in the
+ specified directory. This is useful to
+ implement offline updates of the
+ vendor operating system resources in
+ /usr that require
+ updating of /etc
+ or /var on the
+ next following boot. Units making use
+ of this condition should order
+ themselves before
+ systemd-update-done.service8,
+ to make sure they run before the stamp
+ files's modification time gets reset
+ indicating a completed update.
+
+ ConditionFirstBoot=
+ takes a boolean argument. This
+ condition may be used to
+ conditionalize units on whether the
+ system is booting up with an
+ unpopulated /etc
+ directory. This may be used to
+ populate /etc on
+ the first boot after factory reset, or
+ when a new system instances boots up
+ for the first time.
+
With
ConditionPathExists=
a file existence condition is
@@ -979,120 +1243,6 @@
exists, is a regular file and marked
executable.
- Similarly,
- ConditionKernelCommandLine=
- may be used to check whether a
- specific kernel command line option is
- set (or if prefixed with the
- exclamation mark unset). The argument
- must either be a single word, or an
- assignment (i.e. two words, separated
- =). In the former
- 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
- exact assignment is looked for with
- right and left hand side
- matching.
-
- ConditionVirtualization=
- may be used to check whether the
- system is executed in a virtualized
- environment and optionally test
- whether it is a specific
- implementation. Takes either boolean
- value to check if being executed in
- any virtualized environment, or one of
- vm and
- container to test
- against a generic type of
- virtualization solution, or one of
- qemu,
- kvm,
- vmware,
- microsoft,
- oracle,
- xen,
- bochs,
- chroot,
- uml,
- openvz,
- lxc,
- lxc-libvirt,
- systemd-nspawn 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.
-
- ConditionSecurity=
- may be used to check whether the given
- security module is enabled on the
- system. Currently the recognized values
- values are selinux,
- apparmor,
- ima and
- smack.
- The test may be negated by prepending
- an exclamation
- mark.
-
- ConditionCapability=
- may be used to check whether the given
- capability exists in the capability
- bounding set of the service manager
- (i.e. this does not check whether
- capability is actually available in
- the permitted or effective sets, see
- capabilities7
- for details). Pass a capability name
- such as CAP_MKNOD,
- possibly prefixed with an exclamation
- mark to negate the check.
-
- ConditionHost=
- may be used to match against the
- hostname or machine ID of the
- host. This either takes a hostname
- string (optionally with shell style
- globs) which is tested against the
- locally set hostname as returned by
- gethostname2,
- or a machine ID formatted as string
- (see
- machine-id5).
- The test may be negated by prepending
- an exclamation mark.
-
- ConditionACPower=
- may be used to check whether the
- system has AC power, or is exclusively
- battery powered at the time of
- activation of the unit. This takes a
- boolean argument. If set to
- true, 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 false, the
- condition will hold only if there is
- at least one AC connector known and
- all AC connectors are disconnected
- from a power source.
-
- Finally,
- ConditionNull= may
- be used to add a constant condition
- check value to the unit. It takes a
- boolean argument. If set to
- false, the condition
- will always fail, otherwise
- succeed.
-
If multiple conditions are
specified, the unit will be executed if
all of them apply (i.e. a logical AND
@@ -1118,6 +1268,38 @@
have no effect.
+
+ AssertArchitecture=
+ AssertVirtualization=
+ AssertHost=
+ AssertKernelCommandLine=
+ AssertSecurity=
+ AssertCapability=
+ AssertACPower=
+ AssertNeedsUpdate=
+ AssertFirstBoot=
+ AssertPathExists=
+ AssertPathExistsGlob=
+ AssertPathIsDirectory=
+ AssertPathIsSymbolicLink=
+ AssertPathIsMountPoint=
+ AssertPathIsReadWrite=
+ AssertDirectoryNotEmpty=
+ AssertFileNotEmpty=
+ AssertFileIsExecutable=
+
+ Similar to the
+ ConditionArchitecture=,
+ ConditionVirtualization=,
+ ... 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.
+
+
SourcePath=A path to a
@@ -1126,15 +1308,21 @@
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.
- Unit file may include a [Install] section, which
- carries installation information for the unit. This
- section is not interpreted by
+
+
+
+ [Install] Section Options
+
+ 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
@@ -1146,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)
@@ -1226,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
@@ -1360,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,
@@ -1381,7 +1757,8 @@
systemd.scope5,
systemd.slice5,
systemd.time7,
- capabilities7,
+ systemd-analyze1,
+ capabilities7,
systemd.directives7,
uname1