X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsystemd.unit.xml;h=a06eed58618011b1225d589185af682bb4dc32c2;hb=b3eaa6288107210a84d6d121036fb4b2f7283ee2;hp=7e657c64f700d8f09c1189a475965bf8d249e797;hpb=436c44a5d64ef136ead64e9b03c8c05cc573a61b;p=elogind.git
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index 7e657c64f..a06eed586 100644
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -48,15 +48,16 @@
- systemd.service
- systemd.socket
- systemd.device
- systemd.mount
- systemd.automount
- systemd.swap
- systemd.target
- systemd.path
- systemd.timer
+ systemd.service,
+ systemd.socket,
+ systemd.device,
+ systemd.mount,
+ systemd.automount,
+ systemd.swap,
+ systemd.target,
+ systemd.path,
+ systemd.timer,
+ systemd.snapshot
@@ -66,15 +67,128 @@
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 systemd1. The syntax is inspired by XDG
- .desktop files, which are in turn
- inspired by Microsoft Windows .ini
- files.
+ supervised by
+ systemd1. The
+ syntax is inspired by XDG
+ Desktop Entry Specification.desktop files, which are in turn
+ inspired by Microsoft Windows
+ .ini files.
This man pages lists the common configuration
options of the all unit types. These options need to
- be configured either in the [Unit] resp. [Install]
+ be configured in the [Unit] resp. [Install]
section of the unit files.
+
+ In addition to the generic [Unit] and [Install]
+ sections described here each unit should have a
+ type-specific section, e.g. [Service] for a service
+ unit. See the respective man pages for more
+ information.
+
+ 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.
+
+ Boolean arguments used in unit files can be
+ written in various formats. For positive settings the
+ strings , ,
+ and are
+ equivalent. For negative settings the strings
+ , ,
+ and are
+ equivalent.
+
+ 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 value 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.
+
+ Empty lines and lines starting with # or ; are
+ ignored. This may be used for commenting. Lines ending
+ in a backslash are concatenated with the following
+ 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 where listed in place of the
+ directive.
+
+ Along with a unit file
+ foo.service a directory
+ foo.service.wants/ may exist. All
+ units 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
+ systemd-install1
+ tool which reads information from the [Install]
+ section of unit files. (See below.)
+
+ Note that while systemd offers a flexible
+ dependency system between units it is recommended to
+ use this functionality only sparsely and instead rely
+ on techniques such as bus-based or socket-based
+ activation which makes dependencies implicit, which
+ both results in a simpler and more flexible
+ system.
+
+ Some unit names reflect paths existing in the
+ file system name space. Example: a device unit
+ dev-sda.device refers to a device
+ with the device node /dev/sda in
+ the file system namespace. If this applies a special
+ way to escape the path name is used, so that it is
+ usable as part of a file name. 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.
+
+ 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
+ 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
+ and the suffix) removed. Example: if a service
+ getty@tty3.service is requested
+ 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
+ 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 and
+ %I, for the full unit name, the
+ unescaped unit name, the prefix name, the unescaped
+ prefix name and the unescaped instance name,
+ respectively. The prefix name here refers to the
+ string before the @, i.e. "getty" in the example
+ above, where "tty3" is the instance name.
@@ -97,13 +211,23 @@
that this option is different from the
Alias= option from
the [Install] section mentioned
- below. See below for details
+ below. See below for details.
+
+
+ Description=
+ A free-form string
+ describing the unit. This is intended
+ for use in UIs to show descriptive
+ information along with the unit
+ name.
+
+
Requires=
- Requirement
+ Configures requirement
dependencies on other units. If this
units get activated the units listed
here will be activated as well. If one
@@ -112,9 +236,252 @@
be deactivated. This option may be
specified more than once, in which
case requirement dependencies for all
- listed names are created.
-
+ listed names are 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
+ After= or
+ Before= options. If
+ a unit
+ foo.service
+ requires a unit
+ bar.service as
+ configured with
+ Requires= and no
+ ordering is configured with
+ After= or
+ Before=, then both
+ units will be started simultaneously
+ and without any delay between them if
+ foo.service is
+ activated. Often it is a better choice
+ to use Wants=
+ instead of
+ Requires= in order
+ to achieve a system that is more
+ robust when dealing with failing
+ services.
+
+
+
+
+ RequiresOverridable=
+
+ Similar to
+ Requires=.
+ Dependencies listed in
+ RequiresOverridable=
+ which cannot be fulfilled or fail to
+ start are ignored iff the startup was
+ explicitly requested by the user. If
+ 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
+ must be fulfilled and otherwise the
+ transaction fails. Hence, this option
+ may be used to configure dependencies
+ that are normally honored unless the
+ user explicitly starts up the unit, in
+ which case whether they failed or not
+ is irrelevant.
+
+
+
+ Requisite=
+ RequisiteOverridable=
+
+ Similar to
+ Requires=
+ resp. RequiresOverridable=. However,
+ if a unit listed here is not started
+ already it will not be started and the
+ transaction fails
+ immediately.
+
+
+
+ Wants=
+
+ A weaker version of
+ Requires=. A unit
+ listed in this option will be started
+ if the configuring unit is. However,
+ it the listed unit fails to start up
+ or cannot be added to the transaction
+ this has no impact on the validity of
+ 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
+ type may also be configured outside of
+ the unit configuration file by
+ adding a symlink to a
+ .wants/ directory
+ accompanying the unit file. For
+ details see above.
+
+
+
+ Conflicts=
+
+ Configures negative
+ requirement dependencies. If a unit
+ that has a
+ Conflicts= 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
+ After= and
+ Before= ordering
+ dependencies.
+
+
+
+ Before=
+ After=
+
+ Configures ordering
+ dependencies between units. If a unit
+ foo.service
+ contains a setting
+
+ and both units are being started
+ bar.service's
+ start-up is delayed until
+ foo.service is
+ started up. Note that this setting is
+ independent of and orthogonal to the
+ requirement dependencies as configured
+ by Requires=. It is
+ a common pattern to include a unit
+ name in both the
+ After= and
+ Requires= option in
+ which case the unit listed will be
+ started before the unit that is
+ configured with these options. This
+ option may be specified more than
+ once, in which case ordering
+ dependencies for all listed names are
+ created. After= is
+ the inverse of
+ Before=, i.e. while
+ After= ensures that
+ the configured unit is started after
+ the listed unit finished starting up,
+ Before= ensures the
+ opposite, i.e. that the configured
+ unit is fully started up before the
+ listed unit is started. Note that when
+ two units with an ordering dependency
+ between them are shut down, the
+ inverse of of the start-up order is
+ applied. i.e. if a unit is configured
+ with After= on
+ another unit, the former is stopped
+ before the latter if both are shut
+ down. If one unit with an ordering
+ dependency on another unit is shut
+ down while the latter is started up,
+ the shut down is ordered before the
+ start-up regardless whether the
+ ordering dependency is actually of
+ type After= or
+ Before=. If two
+ units have no ordering dependencies
+ between them they are shut down
+ resp. started up simultaneously, and
+ no ordering takes
+ place.
+
+
+
+ RecursiveStop=
+
+ Takes a boolean
+ argument. If and
+ the unit stops without this being
+ requested by the user all units
+ depending on it will be stopped as
+ well. (e.g. if a service exits or
+ crashes on its own behalf, units using
+ it will be stopped) Note that normally
+ if a unit stops without user request
+ units depending on it will not be
+ terminated. Only if the user requested
+ shutdown of a unit all units depending
+ on the unit will be shut down as well
+ and at the same time. Defaults to
+ .
+
+
+
+ StopWhenUnneeded=
+
+ Takes a boolean
+ argument. If
+ this unit will be stopped when it is
+ no longer used. Note that in order to
+ minimize the work to be executed
+ systemd will by default not stop units
+ unless they are conflicting with other
+ units, or the user explicitly
+ requested their shut down. If this
+ option is set a unit will be
+ automatically cleaned up if no other
+ active unit requires it. Defaults to
+ .
+
+
+
+ OnlyByDependency=
+
+ Takes a boolean
+ argument. If
+ this unit may only be activated
+ indirectly. In this case explicit
+ start-up requested by the user is
+ denied, however if it is started as
+ dependency of another unit start-up
+ will succeed. This is mostly a safety
+ feature to ensure that the user does
+ not accidentally activate units that are
+ not intended to be activated
+ explicitly. This option defaults to
+ .
+
+
+
+ DefaultDependencies=
+
+ Takes a boolean
+ argument. If
+ (the default), a few default
+ dependencies will implicitly be
+ created for the unit. The actual
+ dependencies created depend on the
+ unit type. For example, for service
+ units, these dependencies ensure that
+ the service is started only after
+ basic system initialization is
+ complete and is properly terminated on
+ system shutdown. See the respective
+ man pages for details. Generally, only
+ services involved with early boot or
+ late shutdown should set this option
+ to . It is
+ highly recommended to leave this
+ option enabled for the majority of
+ common units. If set to
+ this option
+ does not disable all implicit
+ dependencies, just non-essential
+ ones.
+
Unit file may include a [Install] section, which
@@ -123,7 +490,7 @@
systemd1
during runtime. It is used exclusively by the
systemd-install1
- during installation of a unit:
+ tool during installation of a unit:
@@ -136,7 +503,7 @@
name. This option may be specified
more than once, in which case all
listed names are used. At installation
- time
+ time,
systemd-install
will create symlinks from these names
to the unit file name. Note that this
@@ -148,18 +515,52 @@
unconditionally if the unit is
loaded. The names from
Alias= apply only
- if the unit is actually installed with
- the systemd-install
+ if the unit has actually been
+ installed with the
+ systemd-install
tool. Also, if systemd searches for a
unit, it will discover symlinked alias
- names, but not names configured only
- with Names=. 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.
+ 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.
+
+
+
+ WantedBy=
+
+ Installs a symlink in
+ the .wants/
+ subdirectory for a unit. This has the
+ effect that when the listed unit name
+ is activated the unit listing it is
+ activated
+ too. WantedBy=foo.service
+ in a service
+ bar.service is
+ mostly equivalent to
+ Alias=foo.service.wants/bar.service
+ in the same file.
+
+
+
+ Also=
+
+ Additional units to
+ install when this unit is
+ installed. If the user requests
+ installation of a unit with this
+ option configured
+ systemd-install
+ will automatically install units
+ listed in this option as
+ well.
@@ -180,7 +581,8 @@
systemd.swap5,
systemd.target5,
systemd.path5,
- systemd.timer5
+ systemd.timer5,
+ systemd.snapshot5