X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd.unit.xml;h=3cc126b12aefa94e455b2e33431fcf3cd13a7c9a;hp=df8761391cc4edb560db7396df945e31c6ebfa4f;hb=fb0864e7b9c6d26269ccea6ec5c0fd921c029781;hpb=b2c20dd9583eb50e03dfb684ef15e018becc887b diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index df8761391..3cc126b12 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 @@ -105,20 +106,24 @@ 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 concatentation of - multiple value with units is supported, in which case + 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 - directive. + followed by a file name, the specified file will be + parsed at this point. Make sure that the file that is + included has the appropiate section headers before + any directives. Along with a unit file foo.service a directory @@ -132,10 +137,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 @@ -150,14 +158,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 @@ -173,18 +181,99 @@ 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 + 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. + configuration options. Other specifiers exist, the + full list is: + + + Specifiers available in unit files + + + + + + + Specifier + Meaning + Details + + + + + %n + Full unit name + + + + %N + Unescaped full unit name + + + + %p + Prefix name + This refers to the string before the @, i.e. "getty" in the example above, where "tty3" is the instance name. + + + %P + Unescaped prefix name + + + + %i + Instance name + This is the string between the @ character and the suffix. + + + %I + Unescaped instance name + + + + %f + Unescaped file name + This is either the unescaped instance name (if set) with / prepended (if necessary), or the prefix name similarly prepended with /. + + + %c + Control group path of the unit + + + + %r + Root control group path of systemd + + + + %R + Parent directory of the root control group path of systemd + + + + %t + Runtime socket dir + This is either /run (for the system manager) or $XDG_RUNTIME_DIR (for user managers). + + + +
+ + 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. @@ -195,29 +284,14 @@ 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= 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. @@ -225,7 +299,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 @@ -260,7 +334,6 @@ services. - RequiresOverridable= @@ -269,7 +342,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 @@ -304,7 +377,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 @@ -319,20 +392,52 @@ 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= 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. @@ -344,7 +449,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 @@ -374,7 +479,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,25 +500,69 @@ - RecursiveStop= + OnFailure= + + Lists one or more + units that are activated when this + unit enters the + 'failed' + state. + + + + PropagateReloadTo= + PropagateReloadFrom= + + Lists one or more + units where reload requests on the + unit will be propagated to/on the + other unit will be propagated + from. Issuing a reload request on a + unit will automatically also enqueue a + reload request on all units that the + reload request shall be propagated to + via these two + settings. + + + + OnFailureIsolate= Takes a boolean - argument. If and - the unit stops without this 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 - 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 - and at the same time. Defaults to + argument. If the + unit listed in + OnFailure= will be + enqueued in isolation mode, i.e. all + units that are not its dependency will + be stopped. If this is set only a + single unit may be listed in + OnFailure=. Defaults + to . + + IgnoreOnIsolate= + + Takes a boolean + argument. If + this unit will not be stopped when + isolating another unit. Defaults to + . + + + + IgnoreOnSnapshot= + + Takes a boolean + argument. If + this unit will not be included in + snapshots. Defaults to + for device and + snapshot units, + for the others. + + StopWhenUnneeded= @@ -421,35 +570,296 @@ 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 . + + 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 + . + + + + 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. + + + + 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= + ConditionPathExistsGlob= + ConditionPathIsDirectory= + ConditionPathIsSymbolicLink= + ConditionPathIsMountPoint= + ConditionDirectoryNotEmpty= + ConditionFileIsExecutable= + ConditionKernelCommandLine= + ConditionVirtualization= + ConditionSecurity= + ConditionCapability= + ConditionNull= + + Before starting a unit + verify that the specified condition is + true. With + ConditionPathExists= + a file existence 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 + is only started if the path does not + exist. + ConditionPathExistsGlob= + works in a similar way, but checks for + the existence of at least one file or + directory matching the specified + globbing + pattern. ConditionPathIsDirectory= + is similar to + ConditionPathExists= + but verifies whether a certain path + exists and is a + directory. ConditionPathIsSymbolicLink= + is similar to + ConditionPathExists= + but verifies whether a certain path + exists and is a symbolic + link. ConditionPathIsMountPoint= + is similar to + ConditionPathExists= + but verifies whether a certain path + exists and is a mount + point. ConditionFileIsExecutable= + is similar to + ConditionPathExists= + but verifies whether a certain path + exists, is a regular file and marked + executable. + 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 virtualized environment, or one of + vm and + container to test + against a specific type of + virtualization solution, or one of + qemu, + kvm, + vmware, + microsoft, + oracle, + xen, + bochs, + chroot, + openvz, + lxc, + lxc-libvirt, + systemd-nspawn to test + against a specific implementation. If + multiple virtualization technologies + are nested only the innermost is + considered. The test may be negated by + prepending an exclamation mark. + ConditionSecurity= + may be used to check whether the given + security module is enabled on the + system. Currently the only recognized + value is selinux. + The test may be negated by prepending + an exclamation + mark. ConditionCapability= + may be used to check whether the given + capability exists in the capability + bounding set of the service manager + (i.e. this does not check whether + capability is actually available in + the permitted or effective sets, see + capabilities7 + for details). Pass a capability name + such as CAP_MKNOD, + possibly prefixed with an exclamation + mark to negate the check. 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. Except for + ConditionPathIsSymbolicLink=, + all path checks follow + symlinks. + + + + 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 @@ -457,14 +867,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 @@ -472,7 +884,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 @@ -485,8 +897,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 @@ -509,7 +921,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 @@ -524,8 +936,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. @@ -539,7 +951,6 @@ systemd1, systemctl8, - systemd-install1, systemd.special7, systemd.service5, systemd.socket5, @@ -549,7 +960,9 @@ systemd.swap5, systemd.target5, systemd.path5, - systemd.timer5 + systemd.timer5, + systemd.snapshot5, + capabilities7