X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd.unit.xml;h=e59c1a16c4d828d4530b50bcd8322509c168a012;hp=26272c441026f5256045cc098cd55e9a93de0d2b;hb=6daf4f9001d87da9e92c04ff606b454c209f0951;hpb=62adf224d1d3e225de072a2815dd50e973230f5c diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 26272c441..e59c1a16c 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 @@ -186,6 +189,19 @@ respectively. 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. @@ -226,7 +242,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 +286,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 +321,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 +341,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 +376,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 +406,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 +426,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,32 +463,55 @@ 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 . @@ -464,7 +528,7 @@ units, these dependencies ensure that the service is started only after basic system initialization is - complete and is properly terminated on + completed and is properly terminated on system shutdown. See the respective man pages for details. Generally, only services involved with early boot or @@ -479,6 +543,48 @@ 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. + + Unit file may include a [Install] section, which @@ -486,7 +592,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: @@ -501,7 +609,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 @@ -514,8 +622,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 @@ -553,8 +661,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. @@ -568,7 +676,6 @@ systemd1, systemctl8, - systemd-install1, systemd.special7, systemd.service5, systemd.socket5,