X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd.unit.xml;h=99bd8b3906f06a9c7256b8636b8b59706ed8a034;hp=7e657c64f700d8f09c1189a475965bf8d249e797;hb=11e299550e832659095d7bf833e4e8fc1971ef1e;hpb=436c44a5d64ef136ead64e9b03c8c05cc573a61b
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index 7e657c64f..99bd8b390 100644
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -48,15 +48,15 @@
- 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
@@ -66,15 +66,74 @@
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 Specificiation.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 forms. For positive settings the
+ strings , ,
+ and are
+ equivalent. For negative settings the strings
+ , ,
+ and are
+ equivalent.
+
+ Empty lines and lines starting with # or ; are
+ ignored. This may be used for commenting.
+
+ 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.
@@ -97,13 +156,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 wanting 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 +181,224 @@
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 honoured 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 accidently activate units that are
+ not intended to be activated
+ explicitly. This option defaults to
+ .
+
+
Unit file may include a [Install] section, which
@@ -123,7 +407,7 @@
systemd1
during runtime. It is used exclusively by the
systemd-install1
- during installation of a unit:
+ tool during installation of a unit:
@@ -148,18 +432,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
+ to. 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.