X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsystemd.unit.xml;h=953a2897ad488074839bf6f2f90f6bac449ea27e;hb=55c0b89c575fcb2c075286d444ed4fb1cf8c8563;hp=4e1d9f30700bf8ae2805087f035003ea654fa1a7;hpb=ead8e4788ee31bbdc38b4cd3c6e71c8a95bbc95a;p=elogind.git
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index 4e1d9f307..953a2897a 100644
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -8,16 +8,16 @@
Copyright 2010 Lennart Poettering
systemd is free software; you can redistribute it and/or modify it
- under the terms of the GNU General Public License as published by
- the Free Software Foundation; either version 2 of the License, or
+ 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
- General Public License for more details.
+ Lesser General Public License for more details.
- You should have received a copy of the GNU General Public License
+ You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see .
-->
@@ -44,7 +44,7 @@
systemd.unit
- systemd unit configuration files
+ Unit configuration
@@ -75,13 +75,13 @@
inspired by Microsoft Windows
.ini files.
- This man pages lists the common configuration
+ This man page lists the common configuration
options of all the unit types. These options need to
- be configured in the [Unit] resp. [Install]
- section of the unit files.
+ be configured in the [Unit] or [Install]
+ sections of the unit files.In addition to the generic [Unit] and [Install]
- sections described here, each unit should have a
+ sections described here, each unit may have a
type-specific section, e.g. [Service] for a service
unit. See the respective man pages for more
information.
@@ -106,12 +106,14 @@
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: "50" refers to 50
+ unit, the unit is honored. A concatenation of multiple
+ values with units is supported, in which case the
+ values are added up. Example: "50" refers to 50
seconds; "2min 200ms" refers to 2 minutes plus 200
milliseconds, i.e. 120200ms. The following time units
- are understood: s, min, h, d, w, ms, us.
+ are understood: s, min, h, d, w, ms, us. For details
+ see
+ systemd.time7.
Empty lines and lines starting with # or ; are
ignored. This may be used for commenting. Lines ending
@@ -119,27 +121,41 @@
line while reading and the backslash is replaced by a
space character. This may be used to wrap long lines.
- If a line starts with
- followed by a file name, the specified file will be
- read as if its contents were listed in place of the
- directive.
-
Along with a unit file
- foo.service a directory
+ foo.service the directory
foo.service.wants/ may exist. All
- units symlinked from such a directory are implicitly
- added as dependencies of type
+ unit files symlinked from such a directory are
+ implicitly added as dependencies of type
Wanted= to the unit. This is useful
to hook units into the start-up of other units,
- without having to modify their unit configuration
- files. For details about the semantics of
- Wanted= see below. The preferred
- way to create symlinks in the
- .wants/ directory of a service is
- with the enable command of the
+ without having to modify their unit files. For details
+ about the semantics of Wanted= see
+ below. The preferred way to create symlinks in the
+ .wants/ directory of a unit file
+ is with the enable command of the
systemctl1
tool which reads information from the [Install]
- section of unit files. (See below.)
+ section of unit files (see below). A similar
+ functionality exists for Requires=
+ type dependencies as well, the directory suffix is
+ .requires/ in this case.
+
+ Along with a unit file
+ foo.service a directory
+ foo.service.d/ may exist. All
+ files with the suffix .conf from
+ this directory will be parsed after the file itself is
+ parsed. This is useful to alter or add configuration
+ 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.
+
+ If a line starts with
+ followed by a file name, 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
@@ -177,22 +193,12 @@
and no file by that name is found, systemd will look
for getty@.service and
instantiate a service from that configuration file if
- it is found. To refer to the instance string from
+ it is found.
+
+ To refer to the instance string from
within the configuration file you may use the special
%i specifier in many of the
- configuration options. Other specifiers that may be
- used are %n, %N,
- %p, %P,
- %I and %f, for
- the full unit name, the unescaped unit name, the
- prefix name, the unescaped prefix name, the unescaped
- instance name and the unescaped filename,
- respectively. The unescaped filename is either the
- unescaped instance name (if set) with / prepended (if
- necessary), or the prefix name similarly prepended
- with /. The prefix name here refers to the string
- before the @, i.e. "getty" in the example above, where
- "tty3" is the instance name.
+ configuration options. See below for details.
If a unit file is empty (i.e. has the file size
0) or is symlinked to /dev/null
@@ -206,6 +212,7 @@
Interface
Stability Promise.
+
@@ -216,21 +223,6 @@
dependent on the type of unit:
-
- Names=
-
- Additional names for
- this unit. 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. Note
- that this option is different from the
- Alias= option from
- the [Install] section mentioned
- below. See below for details.
-
- Description=
@@ -241,6 +233,36 @@
name.
+
+ Documentation=
+ A space separated list
+ of URIs referencing documentation for
+ this unit or its
+ configuration. Accepted are only URIs
+ of the types
+ http://,
+ https://,
+ file:,
+ info:,
+ man:. For more
+ information about the syntax of these
+ URIs see
+ uri7. The
+ URIs should be listed in order of
+ relevance, starting with the most
+ relevant. It is a good idea to first
+ reference documentation that explains
+ what the unit's purpose is, followed
+ by how it is configured, followed by
+ any other related documentation. This
+ option may be specified more than once
+ in which case the specified list of
+ URIs is merged. If the empty string is
+ assigned to this option the list is
+ reset and all prior assignments will
+ have no effect.
+
+
Requires=
@@ -278,7 +300,15 @@
Requires= in order
to achieve a system that is more
robust when dealing with failing
- services.
+ services.
+
+ Note that dependencies of this
+ type may also be configured outside of
+ the unit configuration file by
+ adding a symlink to a
+ .requires/ directory
+ accompanying the unit file. For
+ details see above.
@@ -310,7 +340,7 @@
Similar to
Requires=
- resp. RequiresOverridable=. However,
+ and RequiresOverridable=, respectively. However,
if a unit listed here is not started
already it will not be started and the
transaction fails
@@ -330,7 +360,9 @@
the transaction as a whole. This is
the recommended way to hook start-up
of one unit to the start-up of another
- unit. Note that dependencies of this
+ unit.
+
+ Note that dependencies of this
type may also be configured outside of
the unit configuration file by
adding a symlink to a
@@ -340,22 +372,37 @@
- BindTo=
+ BindsTo=Configures requirement
dependencies, very similar in style to
Requires=, however
- in addition to this behaviour it also
+ in addition to this behavior it also
declares that this unit is stopped
when any of the units listed suddenly
disappears. Units can suddenly,
unexpectedly disappear if a service
terminates on its own choice, a device
is unplugged or a mount point
- unmounted with involvement of
+ unmounted without involvement of
systemd.
+
+ PartOf=
+
+ Configures dependencies
+ similar to Requires=,
+ but limited to stopping and restarting
+ 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 -
+ changes to this unit do not affect the
+ listed units.
+
+
+
Conflicts=
@@ -441,7 +488,7 @@
Before=. If two
units have no ordering dependencies
between them they are shut down
- resp. started up simultaneously, and
+ or started up simultaneously, and
no ordering takes
place.
@@ -456,6 +503,72 @@
state.
+
+ PropagatesReloadTo=
+ ReloadPropagatedFrom=
+
+ 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.
+
+
+
+ RequiresMountsFor=
+
+ 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.
+
+
+
+ OnFailureIsolate=
+
+ Takes a boolean
+ argument. If the
+ unit listed in
+ OnFailure= will be
+ enqueued in isolation mode, i.e. all
+ units that are not its dependency will
+ be stopped. If this is set only a
+ single unit may be listed in
+ OnFailure=. Defaults
+ to
+ .
+
+
+
+ IgnoreOnIsolate=
+
+ Takes a boolean
+ argument. If
+ this unit will not be stopped when
+ isolating another unit. Defaults to
+ .
+
+
+
+ IgnoreOnSnapshot=
+
+ Takes a boolean
+ argument. If
+ this unit will not be included in
+ snapshots. Defaults to
+ for device and
+ snapshot units,
+ for the others.
+
+
StopWhenUnneeded=
@@ -481,13 +594,13 @@
Takes a boolean
argument. If
this unit can only be activated
- (resp. deactivated) indirectly. In
+ or deactivated indirectly. In
this case explicit start-up
- (resp. termination) requested by the
+ or termination requested by the
user is denied, however if it is
- started (resp. stopped) as a
+ started or stopped as a
dependency of another unit, start-up
- (resp. termination) will succeed. This
+ or termination will succeed. This
is mostly a safety feature to ensure
that the user does not accidentally
activate units that are not intended
@@ -573,45 +686,251 @@
ConditionPathExists=
+ ConditionPathExistsGlob=
+ ConditionPathIsDirectory=
+ ConditionPathIsSymbolicLink=
+ ConditionPathIsMountPoint=
+ ConditionPathIsReadWrite=
+ ConditionDirectoryNotEmpty=
+ ConditionFileNotEmpty=
+ ConditionFileIsExecutable=ConditionKernelCommandLine=
+ ConditionVirtualization=
+ ConditionSecurity=
+ ConditionCapability=
+ ConditionHost=
+ ConditionACPower=
+ ConditionNull=Before starting a unit
verify that the specified condition is
- true. With
+ 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
+ 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.
+
+ With
ConditionPathExists=
- a file existance condition can be
+ a file existence condition is
checked before a unit is started. If
the specified absolute path name does
- not exist startup of a unit will not
- actually happen, however the unit is
- still useful for ordering purposes in
- this case. The condition is checked at
- the time the queued start job is to be
- executed. If the absolute path name
- passed to
+ not exist the condition will
+ fail. If the absolute path name passed
+ to
ConditionPathExists=
is prefixed with an exclamation mark
- (!), the test is negated, and the unit
- only started if the path does not
- exist. Similarly
+ ('!'), the test is negated, and the unit
+ is only started if the path does not
+ exist.
+
+ ConditionPathExistsGlob=
+ is similar to
+ ConditionPathExists=,
+ but checks for the existence of at
+ least one file or directory matching
+ the specified globbing pattern.
+
+ ConditionPathIsDirectory=
+ is similar to
+ ConditionPathExists=
+ but verifies whether a certain path
+ exists and is a
+ directory.
+
+ ConditionPathIsSymbolicLink=
+ is similar to
+ ConditionPathExists=
+ but verifies whether a certain path
+ exists and is a symbolic
+ link.
+
+ ConditionPathIsMountPoint=
+ is similar to
+ ConditionPathExists=
+ but verifies whether a certain path
+ exists and is a mount
+ point.
+
+ ConditionPathIsReadWrite=
+ is similar to
+ ConditionPathExists=
+ but verifies whether the underlying
+ file system is readable and writable
+ (i.e. not mounted
+ read-only).
+
+ ConditionDirectoryNotEmpty=
+ is similar to
+ ConditionPathExists=
+ but verifies whether a certain path
+ exists and is a non-empty
+ directory.
+
+ ConditionFileNotEmpty=
+ is similar to
+ ConditionPathExists=
+ but verifies whether a certain path
+ exists and refers to a regular file
+ with a non-zero size.
+
+ ConditionFileIsExecutable=
+ is similar to
+ ConditionPathExists=
+ but verifies whether a certain path
+ exists, is a regular file and marked
+ executable.
+
+ Similar,
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, seperated
- by the equality sign). In the former
- case the kernel command line is search
- 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. If multiple conditions
- are specified the unit will be
- executed iff at least one of them
- applies (i.e. a logical OR is
- applied).
+ 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,
+ 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 only recognized
+ value is selinux.
+ 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
+ host name or machine ID of the
+ host. This either takes a host name
+ string (optionally with shell style
+ globs) which is tested against the
+ locally set host name 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
+ 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
+ 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
+ pipe symbol must be passed first, the
+ exclamation second. Except for
+ ConditionPathIsSymbolicLink=,
+ all path checks follow symlinks. If
+ any of these options is assigned the
+ empty string the list of conditions is
+ reset completely, all previous
+ condition settings (of any kind) will
+ have no effect.
+
+
+
+ SourcePath=
+ A path to a
+ configuration file this unit has been
+ generated from. This is primarily
+ useful for implementation of generator
+ tools that convert configuration from
+ an external configuration file format
+ into native unit files. Thus
+ functionality should not be used in
+ normal units.
@@ -639,38 +958,17 @@
time,
systemctl enable
will create symlinks from these names
- to the unit file name. Note that this
- is different from the
- Names= option from
- the [Unit] section mentioned above:
- The names from
- Names= apply
- unconditionally if the unit is
- loaded. The names from
- Alias= apply only
- if the unit has actually been
- installed with the
- systemctl enable
- command. Also, if systemd searches for a
- unit, it will discover symlinked alias
- names as configured with
- Alias=, but not
- names configured with
- Names= only. It is
- a common pattern to list a name in
- both options. In this case, a unit
- will be active under all names if
- installed, but also if not installed
- but requested explicitly under its
- main name.
+ to the unit file name.
WantedBy=
+ RequiredBy=Installs a symlink in
the .wants/
- subdirectory for a unit. This has the
+ or .requires/
+ subdirectory for a unit, respectively. This has the
effect that when the listed unit name
is activated the unit listing it is
activated
@@ -699,6 +997,124 @@
+
+ Specifiers
+
+ Many settings resolve specifiers which may be
+ used to write generic unit files referring to runtime
+ or unit parameters that are replaced when the unit
+ files are loaded. The following specifiers are
+ understood:
+
+
+ Specifiers available in unit files
+
+
+
+
+
+
+ Specifier
+ Meaning
+ Details
+
+
+
+
+ %n
+ Full unit name
+
+
+
+ %N
+ Unescaped full unit name
+
+
+
+ %p
+ Prefix name
+ For instantiated units this refers to the string before the @. For non-instantiated units this refers to to the name of the unit with the type suffix removed.
+
+
+ %P
+ Unescaped prefix name
+
+
+
+ %i
+ Instance name
+ For instantiated units: this is the string between the @ character and the suffix.
+
+
+ %I
+ Unescaped instance name
+
+
+
+ %f
+ Unescaped file name
+ This is either the unescaped instance name (if applicable) with / prepended (if applicable), or the prefix name similarly prepended with /.
+
+
+ %c
+ Control group path of the unit
+
+
+
+ %r
+ Root control group path of systemd
+
+
+
+ %R
+ Parent directory of the root control group path of systemd
+
+
+
+ %t
+ Runtime socket dir
+ This is either /run (for the system manager) or $XDG_RUNTIME_DIR (for user managers).
+
+
+ %u
+ User name
+ This is the name of the configured user of the unit, or (if none is set) the user running the systemd instance.
+
+
+ %U
+ User UID
+ This is the UID of the configured user of the unit, or (if none is set) the user running the systemd instance.
+
+
+ %h
+ User home directory
+ This is the home directory of the configured user of the unit, or (if none is set) the user running the systemd instance.
+
+
+ %s
+ User shell
+ This is the shell of the configured user of the unit, or (if none is set) the user running the systemd instance.
+
+
+ %m
+ Machine ID
+ The machine ID of the running system, formatted as string. See machine-id5 for more information.
+
+
+ %b
+ Boot ID
+ The boot ID of the running system, formatted as string. See random4 for more information.
+
+
+ %H
+ Host name
+ The host name of the running system.
+
+
+
+