X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsystemd.unit.xml;h=bb11682fc62e560bff7170d23291d42136bb0232;hb=02ee865a462caa2aeeee673e90287a4c34b013fd;hp=9c4269f3d2626ab1fbc5ead97a4e8f5378329768;hpb=0a715d9783602141671b5cc48a314fb124512476;p=elogind.git
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index 9c4269f3d..bb11682fc 100644
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -76,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.
@@ -107,18 +107,21 @@
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
+ 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
@@ -133,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.)
@@ -151,14 +154,14 @@
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.
+ 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
@@ -215,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.
@@ -226,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
@@ -270,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
@@ -305,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
@@ -325,15 +328,30 @@
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
After= and
Before= ordering
- dependencies.
+ dependencies.
+
+ If a unit A that conflicts with
+ a unit B is scheduled to be started at
+ the same time as B, the transaction
+ will either fail (in case both are
+ required part of the transaction) or
+ be modified to be fixed (in case one
+ or both jobs are not a required part
+ of the transaction). In the latter
+ case the job that is not the required
+ will be removed, or in case both are
+ not required the unit that conflicts
+ will be started and the unit that is
+ conflicted is
+ stopped.
@@ -345,7 +363,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
@@ -375,7 +393,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
@@ -395,22 +413,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
.
@@ -422,35 +449,110 @@
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
.
- OnlyByDependency=
+ RefuseManualStart=
+ RefuseManualStop=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
+ this unit can only be activated
+ (resp. deactivated) indirectly. In
+ this case explicit start-up
+ (resp. termination) requested by the
+ user is denied, however if it is
+ started (resp. stopped) as a
+ dependency of another unit, start-up
+ (resp. termination) 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, and not
+ accidentally deactivate units that are
+ not intended to be deactivated.
+ These options default 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
+ 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
@@ -458,7 +560,9 @@
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:
@@ -473,7 +577,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
@@ -486,8 +590,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
@@ -525,8 +629,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.
@@ -540,7 +644,6 @@
systemd1,
systemctl8,
- systemd-install1,
systemd.special7,
systemd.service5,
systemd.socket5,