X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd.unit.xml;h=da077e2097bfe37d77b28dcd8094e3c3ee657f64;hp=cfa1b09499288cc381f904fff27c501d0970d87b;hb=1f812feafb4b98d5cfa2934886bbdd43325780bb;hpb=d1ab0ca07372649dad70a0348d75e394f254e1b6 diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index cfa1b0949..da077e209 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -48,74 +48,506 @@ - systemd.service - systemd.socket - systemd.device - systemd.mount - systemd.automount - systemd.swap - systemd.target + systemd.service, + systemd.socket, + systemd.device, + systemd.mount, + systemd.automount, + systemd.swap, + systemd.target, + systemd.path, + systemd.timer Description A unit configuration file encodes information - about a service, a socket, a mount point, an automount - point, a swap file or patition, or a start-up target - controlled and supervised by systemd. The syntax is - inspired by XDG .desktop files, - which are in turn inspired by Windows + about a service, a socket, a device, a mount point, an + automount point, a swap file or partition, a start-up + target, a file system path or a timer controlled and + supervised by + systemd1. The + syntax is inspired by XDG + 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 various unit types. + options of the all 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 + type-specific section, e.g. [Service] for a service + unit. See the respective man pages for more + information. + + Unit files may contain additional options on top + of those listed here. If systemd encounters an unknown + option it will write a warning log message but + continue loading the unit. If an option is prefixed + with it is ignored completely by + systemd. Applications may use this to include + additional information in the unit files. + + Boolean arguments used in unit files can be + written in various forms. For positive settings the + strings , , + and are + equivalent. For negative settings the strings + , , + 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 concatentation of + multiple value 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. + + 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. + + Along with a unit file + foo.service a directory + foo.service.wants/ may exist. All + units symlinked from such a directory are implicitly + added as dependencies of type + Wanted= to the unit. This is useful + to hook units into the start-up of other units, + without having to modify their unit configuration + files. For details about the semantics of + Wanted= see below. The preferred + way to create symlinks in the + .wants/ directory of a service is + with the + systemd-install1 + tool which reads information from the [Install] + section of unit files. (See below.) + + Note that while systemd offers a flexible + dependency system between units it is recommended to + use this functionality only sparsely and instead rely + on techniques such as bus-based or socket-based + 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 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. 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. Options + Unit file may include a [Unit] section, which + carries generic information about the unit that is not + dependent on the type of unit: + - Names= - - Additional names for this unit. The names - listed here mus have the same suffix (i.e. type) - as the identifier name. This option may be - specified more than once. + 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. + + - Requires= - - Dependencies on other - units. If this units get - 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 be deactivated. This - option may be specified more - than once. - + Requires= + + Configures requirement + dependencies on other units. If this + units get 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 + be deactivated. This option may be + specified more than once, in which + case requirement dependencies for all + listed names are created. Note that + requirement dependencies do not + influence the order in which services + are started or stopped. This has to be + configured independently with the + After= or + Before= options. If + a unit + foo.service + requires a unit + bar.service as + configured with + Requires= and no + ordering is configured with + After= or + Before=, then both + units will be started simultaneously + and without any delay between them if + foo.service is + activated. Often it is a better choice + to use Wants= + instead of + Requires= in order + to achieve a system that is more + robust when dealing with failing + services. + + + + + RequiresOverridable= + + Similar to + Requires=. + Dependencies listed in + RequiresOverridable= + which cannot be fulfilled or fail to + start are ignored iff the startup was + explicitly requested by the user. If + the start-up was pulled in indirectly + by some dependency or automatic + start-up of units that is not + requested by the user this dependency + must be fulfilled and otherwise the + transaction fails. Hence, this option + may be used to configure dependencies + that are normally honored unless the + user explicitly starts up the unit, in + which case whether they failed or not + is irrelevant. + + + + Requisite= + RequisiteOverridable= + + Similar to + Requires= + resp. RequiresOverridable=. However, + if a unit listed here is not started + already it will not be started and the + transaction fails + immediately. + + + + Wants= + + A weaker version of + Requires=. A unit + listed in this option will be started + if the configuring unit is. However, + it 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 + the recommended way to hook start-up + of one unit to the start-up of another + unit. Note that dependencies of this + type may also be configured outside of + the unit configuration file by + adding a symlink to a + .wants/ directory + accompanying the unit file. For + details see above. + + + + Conflicts= + + Configures negative + requirement dependencies. If a unit + that has a + Conflicts= setting + 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. + + + + Before= + After= + + Configures ordering + dependencies between units. If a unit + foo.service + contains a setting + + and both units are being started + bar.service's + start-up is delayed until + foo.service is + started up. Note that this setting is + independent of and orthogonal to the + requirement dependencies as configured + by Requires=. It is + a common pattern to include a unit + name in both the + After= and + Requires= option in + which case the unit listed will be + started before the unit that is + configured with these options. This + option may be specified more than + once, in which case ordering + dependencies for all listed names are + created. After= is + the inverse of + Before=, i.e. while + After= ensures that + the configured unit is started after + the listed unit finished starting up, + Before= ensures the + opposite, i.e. that the configured + unit is fully started up before the + 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 + applied. i.e. if a unit is configured + with After= on + another unit, the former is stopped + before the latter if both are shut + down. If one unit with an ordering + dependency on another unit is shut + down while the latter is started up, + the shut down is ordered before the + start-up regardless whether the + ordering dependency is actually of + type After= or + Before=. If two + units have no ordering dependencies + between them they are shut down + resp. started up simultaneously, and + no ordering takes + place. + + + + RecursiveStop= + + 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 + . + + + + StopWhenUnneeded= + + Takes a boolean + 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 + unless they are conflicting with other + units, or the user explicitly + requested their shut down. If this + option is set a unit will be + automatically cleaned up if no other + active unit requires it. Defaults to + . + + + + OnlyByDependency= + + 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 + . + + + Unit file may include a [Install] section, which + carries installation information for the unit. This + section is not interpreted by + systemd1 + during runtime. It is used exclusively by the + systemd-install1 + tool during installation of a unit: + + + + Alias= + + Additional names, this + unit shall be installed under. 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. At installation + time, + systemd-install + will create symlinks from these names + to the unit file name. Note that this + is different from the + Names= option from + the [Unit] section mentioned above: + The names from + Names= apply + unconditionally if the unit is + loaded. The names from + Alias= apply only + if the unit has actually been + installed with the + systemd-install + tool. Also, if systemd searches for a + unit, it will discover symlinked alias + names as configured with + Alias=, but not + names configured with + Names= only. It is + a common pattern to list a name in + both options. In this case, a unit + will be active under all names if + installed, but also if not installed + but requested explicitly under its + main name. + + + + WantedBy= + + Installs a symlink in + the .wants/ + subdirectory for a unit. This has the + effect that when the listed unit name + is activated the unit listing it is + activated + to. WantedBy=foo.service + in a service + bar.service is + mostly equivalent to + Alias=foo.service.wants/bar.service + in the same file. + + + + Also= + + Additional units to + install when this unit is + installed. If the user requests + installation of a unit with this + option configured + systemd-install + will automatically install units + listed in this option as + well. + + + - See Also - - systemd8, - systemctl8 - systemd.service5 - systemd.socket5 - systemd.device5 - systemd.mount5 - systemd.automount5 - systemd.swap5 - systemd.target5 - + See Also + + systemd1, + systemctl8, + systemd-install1, + systemd.special7, + systemd.service5, + systemd.socket5, + systemd.device5, + systemd.mount5, + systemd.automount5, + systemd.swap5, + systemd.target5, + systemd.path5, + systemd.timer5 +