X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd.unit.xml;h=39862cf7c89162e510f1bb35eb820c1aa47f5851;hp=d6bb60486a2937b95fa48a13405efbb65f6850e5;hb=761163046260b42c0bed075c17d43e0e6c3dd3a4;hpb=58c16a1a3c49471e77393ab7dd92b10603c744b4 diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index d6bb60486..39862cf7c 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -136,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.) @@ -154,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 @@ -182,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. @@ -264,7 +281,6 @@ services. - RequiresOverridable= @@ -323,6 +339,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 with involvement of + systemd. + + Conflicts= @@ -336,7 +369,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 +447,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 +475,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 +543,85 @@ 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= + ConditionKernelCommandLine= + 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. 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 + 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. 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 + iff at least one of them applies + (i.e. a logical OR is + applied). + Unit file may include a [Install] section, which @@ -489,7 +629,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 +646,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 +659,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 +699,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 +713,6 @@ systemd1, systemctl8, - systemd-install1, systemd.special7, systemd.service5, systemd.socket5,