X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsystemd.unit.xml;h=47ddece3149a173b8a861296942a230a5302349a;hb=c61e77d3eab2385fc7bbae0edef6b3c583a70ca8;hp=d6bb60486a2937b95fa48a13405efbb65f6850e5;hpb=58c16a1a3c49471e77393ab7dd92b10603c744b4;p=elogind.git
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index d6bb60486..47ddece31 100644
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -136,10 +136,13 @@
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.)
+ section of unit files. (See below.) A similar
+ functionality exists for Requires=
+ type dependencies as well, the directory suffix is
+ .requires/ in this case.
Note that while systemd offers a flexible
dependency system between units it is recommended to
@@ -154,14 +157,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
@@ -182,13 +185,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.
@@ -199,21 +219,6 @@
dependent on the type of unit:
-
- Names=
-
- Additional names for
- this unit. The names listed here must
- have the same suffix (i.e. type) as
- the unit file name. This option may be
- specified more than once, in which
- case all listed names are used. Note
- that this option is different from the
- Alias= option from
- the [Install] section mentioned
- below. See below for details.
-
- Description=
@@ -264,7 +269,6 @@
services.
-
RequiresOverridable=
@@ -323,6 +327,23 @@
details see above.
+
+ BindTo=
+
+ Configures requirement
+ dependencies, very similar in style to
+ Requires=, however
+ in addition to this behaviour it also
+ declares that this unit is stopped
+ when any of the units listed suddenly
+ disappears. Units can suddenly,
+ unexpectedly disappear if a service
+ terminates on its own choice, a device
+ is unplugged or a mount point
+ unmounted without involvement of
+ systemd.
+
+
Conflicts=
@@ -336,7 +357,22 @@
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.
@@ -399,23 +435,13 @@
- RecursiveStop=
+ OnFailure=
- Takes a boolean
- argument. If and
- 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 a user request,
- units depending on it will not be
- terminated. Only if the user requested
- shutdown of a unit, all units depending
- on that unit will be shut down as well
- and at the same time. Defaults to
- .
+ Lists one or more
+ units that are activated when this
+ unit enters the
+ 'failed'
+ state.
@@ -437,20 +463,43 @@
- OnlyByDependency=
+ RefuseManualStart=
+ RefuseManualStop=Takes a boolean
argument. If
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 a
+ (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
- 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
+ (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 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
.
@@ -482,6 +531,156 @@
ones.
+
+ 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=
+ ConditionPathIsDirectory=
+ ConditionDirectoryNotEmpty=
+ ConditionKernelCommandLine=
+ ConditionVirtualization=
+ ConditionNull=
+
+ 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. ConditionPathIsDirectory=
+ is similar to
+ ConditionPathExists=
+ but verifies whether a certain path
+ exists and is a directory.
+ ConditionDirectoryNotEmpty=
+ is similar to
+ ConditionPathExists=
+ but verifies whether a certain path
+ exists and is a non-empty
+ directory. 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, separated
+ by the equality sign). In the former
+ case the kernel command line is
+ searched 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. ConditionVirtualization=
+ may be used to check whether the
+ system is executed in a virtualized
+ environment and optionally test
+ whether it is a specific
+ implementation. Takes either boolean
+ value to check if being executed in
+ any virtual environment or one of the
+ qemu,
+ kvm,
+ vmware,
+ microsoft,
+ oracle,
+ xen,
+ pidns,
+ openvz to test
+ against a specific implementation. The
+ test may be negated by prepending an
+ exclamation mark. Finally,
+ ConditionNull= may
+ be used to add a constant condition
+ check value to the unit. It takes a
+ boolean argument. If set to
+ false the condition
+ will always fail, otherwise
+ succeed. If multiple conditions are
+ specified the unit will be executed if
+ all of them apply (i.e. a logical AND
+ is applied). Condition checks can be
+ prefixed with a pipe symbol (|) in
+ which case a condition becomes a
+ triggering condition. If at least one
+ triggering condition is defined for a
+ unit then the unit will be executed if
+ at least one of the triggering
+ conditions apply and all of the
+ non-triggering conditions. If you
+ prefix an argument with the pipe
+ symbol and an exclamation mark the
+ pipe symbol must be passed first, the
+ exclamation second.
+
+
+
+ Names=
+
+ Additional names for
+ this unit. The names listed here must
+ have the same suffix (i.e. type) as
+ the unit file name. This option may be
+ specified more than once, in which
+ case all listed names are used. Note
+ that this option is different from the
+ Alias= option from
+ the [Install] section mentioned
+ below. See below for details. Note
+ that in almost all cases this option
+ is not what you want. A symlink alias
+ in the file system is generally
+ preferable since it can be used as
+ lookup key. If a unit with a symlinked
+ alias name is not loaded and needs to
+ be it is easily found via the
+ symlink. However, if a unit with an
+ alias name configured with this
+ setting is not loaded it will not be
+ discovered. This settings' only use is
+ in conjunction with service
+ instances.
+
+ Unit file may include a [Install] section, which
@@ -489,7 +688,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:
@@ -504,7 +705,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
@@ -517,8 +718,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
@@ -557,7 +758,7 @@
installed. If the user requests
installation of a unit with this
option configured,
- systemd-install
+ systemctl enable
will automatically install units
listed in this option as
well.
@@ -571,7 +772,6 @@
systemd1,
systemctl8,
- systemd-install1,
systemd.special7,
systemd.service5,
systemd.socket5,