X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd.unit.xml;h=a03df65dcb50b24432a3e4606ebec0b3f26fbf00;hp=8a402d053d9a6e100cf60e2bd12c62fb12086981;hb=3b6fdb5b5afebc49a7e987e3e3bf7aa2615d1671;hpb=af62c704053b5d34672497eb5bdc4764ebbb5f4f diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 8a402d053..a03df65dc 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 @@ -70,17 +71,17 @@ systemd1. The syntax is inspired by XDG - Desktop Entry Specificiation .desktop files, which are in turn + Desktop Entry Specification .desktop files, which are in turn inspired by Microsoft Windows .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 @@ -102,12 +103,25 @@ and are equivalent. + 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 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 + 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 @@ -134,6 +148,47 @@ activation which makes dependencies implicit, which both results in a simpler and more flexible system. + + Some unit names reflect paths existing in the + file system name space. Example: a device unit + 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 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 + multiple units from a single configuration file. If + systemd looks for a unit configuration file it will + first search for the literal unit name in the + filesystem. If that yields no success and the unit + name contains an @ character, systemd will look for a + unit template that shares the same name but with the + instance string (i.e. the part between the @ character + and the suffix) removed. Example: if a service + getty@tty3.service is requested + 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 + 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. @@ -163,10 +218,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. @@ -174,7 +229,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 @@ -218,7 +273,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 @@ -227,7 +282,7 @@ must be fulfilled and otherwise the transaction fails. Hence, this option may be used to configure dependencies - that are normally honoured unless the + that are normally honored unless the user explicitly starts up the unit, in which case whether they failed or not is irrelevant. @@ -253,7 +308,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 @@ -273,9 +328,9 @@ 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 @@ -293,7 +348,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 @@ -323,7 +378,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 @@ -348,17 +403,17 @@ 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 . @@ -370,12 +425,12 @@ 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 . @@ -386,19 +441,60 @@ Takes a boolean argument. If - this unit may only be activated + 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 - dependency of another unit start-up + denied, however if it is started as a + dependency of another unit, start-up will succeed. This is mostly a safety feature to ensure that the user does - not accidently activate units that are + not accidentally activate units that are not intended to be activated explicitly. 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. + Unit file may include a [Install] section, which @@ -413,7 +509,7 @@ 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 @@ -458,7 +554,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 @@ -473,7 +569,7 @@ install when this unit is installed. If the user requests installation of a unit with this - option configured + option configured, systemd-install will automatically install units listed in this option as @@ -498,7 +594,8 @@ systemd.swap5, systemd.target5, systemd.path5, - systemd.timer5 + systemd.timer5, + systemd.snapshot5