X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsystemd.unit.xml;h=f72b947dca052ffefc7fe99d0eb344638a9b829d;hb=cbe1bded5fb719faf374bf63d36a80c6d13d2b19;hp=9c4269f3d2626ab1fbc5ead97a4e8f5378329768;hpb=0a715d9783602141671b5cc48a314fb124512476;p=elogind.git
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index 9c4269f3d..f72b947dc 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
@@ -179,13 +182,30 @@
%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.
+ %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.
+
+ If a unit file is empty (i.e. has the file size
+ 0) or is symlinked to /dev/null
+ its configuration will not be loaded and it appears
+ with a load state of masked, and
+ cannot be activated. Use this as an effective way to
+ fully disable a unit, making it impossible to start it
+ even manually.
+
+ The unit file format is covered by the
+ Interface
+ Stability Promise.
@@ -215,10 +235,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 +246,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 +290,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 +325,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 +345,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 +380,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 +410,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 +430,32 @@
place.
+
+ OnFailure=
+
+ Lists one or more
+ units that are activated when this
+ unit enters the
+ 'failed'
+ 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 +467,170 @@
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 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
+ .
+
+
+
+ AllowIsolate=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 may be used with the
+ systemctl isolate
+ command. Otherwise this will be
+ refused. It probably is a good idea to
+ leave this disabled except for target
+ units that shall be used similar to
+ runlevels in SysV init systems, just
+ as a precaution to avoid unusable
+ system states. 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
+ 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 the 'failed'
+ 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.
+
+
+
+ ConditionPathExists=
+ ConditionKernelCommandLine=
+
+ Before starting a unit
+ verify that the specified condition is
+ true. With
+ ConditionPathExists=
+ a file existance condition can be
+ 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
+ ConditionPathExists=
+ is prefixed with an exclamation mark
+ (!), the test is negated, and the unit
+ only started if the path does not
+ exist. Similarly
+ 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
+ apply (i.e. a logical OR is
+ applied).
+ Unit file may include a [Install] section, which
@@ -458,7 +638,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 +655,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 +668,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 +707,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 +722,6 @@
systemd1,
systemctl8,
- systemd-install1,
systemd.special7,
systemd.service5,
systemd.socket5,