X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsystemd.unit.xml;h=585145ab375f333fe7384b6373ec2d43c25c4105;hb=d5ca5f11857e87524f0b75a0959a74404f707f1a;hp=3509388c7de7f61969fbbf5b1b709a95c52d9ecc;hpb=4176e530794dc1f29c99d15a22be07ed83f4477c;p=elogind.git
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index 3509388c7..585145ab3 100644
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -56,7 +56,8 @@
systemd.swap,
systemd.target,
systemd.path,
- systemd.timer
+ systemd.timer,
+ systemd.snapshot
@@ -75,12 +76,12 @@
.ini files.
This man pages lists the common configuration
- options of the all unit types. These options need to
+ options of all the unit types. These options need to
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
+ 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.
@@ -94,7 +95,7 @@
additional information in the unit files.
Boolean arguments used in unit files can be
- written in various forms. For positive settings the
+ written in various formats. For positive settings the
strings , ,
and are
equivalent. For negative settings the strings
@@ -102,12 +103,25 @@
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 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.
+
Empty lines and lines starting with # or ; are
- ignored. This may be used for commenting.
+ 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
+ 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
@@ -122,8 +136,8 @@
Wanted= see below. The preferred
way to create symlinks in the
.wants/ directory of a service is
- with the
- systemd-install1
+ with the enable command of the
+ systemctl1
tool which reads information from the [Install]
section of unit files. (See below.)
@@ -134,6 +148,47 @@
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 the
+ result 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.
@@ -163,10 +218,10 @@
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.
+ describing the unit. This is intended
+ for use in UIs to show descriptive
+ information along with the unit
+ name.
@@ -174,7 +229,7 @@
Configures requirement
dependencies on other units. If this
- units get activated the units listed
+ unit gets activated, the units listed
here will be activated as well. If one
of the other units gets deactivated or
its activation fails, this unit will
@@ -218,7 +273,7 @@
Dependencies listed in
RequiresOverridable=
which cannot be fulfilled or fail to
- start are ignored iff the startup was
+ start are ignored if the startup was
explicitly requested by the user. If
the start-up was pulled in indirectly
by some dependency or automatic
@@ -253,7 +308,7 @@
Requires=. A unit
listed in this option will be started
if the configuring unit is. However,
- it the listed unit fails to start up
+ if 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
@@ -273,9 +328,9 @@
Configures negative
requirement dependencies. If a unit
- that has a
+ has a
Conflicts= setting
- on another unit starting the former
+ on another unit, starting the former
will stop the latter and vice
versa. Note that this setting is
independent of and orthogonal to the
@@ -293,7 +348,7 @@
foo.service
contains a setting
- and both units are being started
+ and both units are being started,
bar.service's
start-up is delayed until
foo.service is
@@ -323,7 +378,7 @@
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
+ inverse of the start-up order is
applied. i.e. if a unit is configured
with After= on
another unit, the former is stopped
@@ -343,22 +398,31 @@
place.
+
+ OnFailure=
+
+ Lists one or more
+ units that are activated when this
+ unit fails (i.e. enters maintenance
+ state).
+
+
RecursiveStop=Takes a boolean
argument. If and
- the unit stops without this being
- requested by the user all units
+ the unit stops without 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
+ if a unit stops without a 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
+ shutdown of a unit, all units depending
+ on that unit will be shut down as well
and at the same time. Defaults to
.
@@ -370,12 +434,12 @@
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
+ minimize the work to be executed,
+ systemd will not stop units by default
unless they are conflicting with other
units, or the user explicitly
requested their shut down. If this
- option is set a unit will be
+ option is set, a unit will be
automatically cleaned up if no other
active unit requires it. Defaults to
.
@@ -386,11 +450,11 @@
Takes a boolean
argument. If
- this unit may only be activated
+ this unit can 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
+ denied, however if it is started as a
+ 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
@@ -399,6 +463,75 @@
.
+
+ 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
+ completed 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.
+
+
+
+ IgnoreDependencyFailure=
+
+ Takes a boolean
+ argument. If and
+ a requirement dependency of this unit
+ fails to start up this unit will be
+ started nonetheless, ignoring that
+ failure. If
+ (the default) and a dependency unit
+ fails the unit will immediately fail
+ too and the job is removed.
+
+
+
+ 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 maintenance 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
+ units) as the job timeout has no effect
+ on the unit itself, only on the job
+ that might be pending for it. Or in
+ other words: unit-specific timeouts
+ are useful to abort unit state
+ changes, and revert them. The job
+ timeout set with this option however
+ is useful to abort only the job waiting
+ for the unit state to change.
+
+
Unit file may include a [Install] section, which
@@ -406,14 +539,16 @@
section is not interpreted by
systemd1
during runtime. It is used exclusively by the
- systemd-install1
+ enable and
+ disable commands of the
+ systemctl1
tool during installation of a unit:Alias=
- Additional names, this
+ Additional names this
unit shall be installed under. The
names listed here must have the same
suffix (i.e. type) as the unit file
@@ -421,7 +556,7 @@
more than once, in which case all
listed names are used. At installation
time,
- systemd-install
+ systemctl enable
will create symlinks from these names
to the unit file name. Note that this
is different from the
@@ -434,8 +569,8 @@
Alias= apply only
if the unit has actually been
installed with the
- systemd-install
- tool. Also, if systemd searches for a
+ systemctl enable
+ command. Also, if systemd searches for a
unit, it will discover symlinked alias
names as configured with
Alias=, but not
@@ -458,7 +593,7 @@
effect that when the listed unit name
is activated the unit listing it is
activated
- to. WantedBy=foo.service
+ too. WantedBy=foo.service
in a service
bar.service is
mostly equivalent to
@@ -473,8 +608,8 @@
install when this unit is
installed. If the user requests
installation of a unit with this
- option configured
- systemd-install
+ option configured,
+ systemctl enable
will automatically install units
listed in this option as
well.
@@ -488,7 +623,6 @@
systemd1,
systemctl8,
- systemd-install1,
systemd.special7,
systemd.service5,
systemd.socket5,
@@ -498,7 +632,8 @@
systemd.swap5,
systemd.target5,
systemd.path5,
- systemd.timer5
+ systemd.timer5,
+ systemd.snapshot5