From 11e299550e832659095d7bf833e4e8fc1971ef1e Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Thu, 24 Jun 2010 19:08:38 +0200 Subject: [PATCH 1/1] man: finish systemd.unit.5 --- man/systemd.unit.xml | 376 +++++++++++++++++++++++++++++++++++++++---- 1 file changed, 347 insertions(+), 29 deletions(-) diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 7e657c64f..99bd8b390 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -48,15 +48,15 @@ - systemd.service - systemd.socket - systemd.device - systemd.mount - systemd.automount - systemd.swap - systemd.target - systemd.path - systemd.timer + systemd.service, + systemd.socket, + systemd.device, + systemd.mount, + systemd.automount, + systemd.swap, + systemd.target, + systemd.path, + systemd.timer @@ -66,15 +66,74 @@ 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 files, which are in turn - inspired by Microsoft Windows .ini - files. + supervised by + systemd1. The + syntax is inspired by XDG + Desktop Entry Specificiation .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 - be configured either in the [Unit] resp. [Install] + 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. + + 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. @@ -97,13 +156,23 @@ that this option is different from the Alias= option from the [Install] section mentioned - below. See below for details + 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= - Requirement + Configures requirement dependencies on other units. If this units get activated the units listed here will be activated as well. If one @@ -112,9 +181,224 @@ be deactivated. This option may be specified more than once, in which case requirement dependencies for all - listed names are created. - + 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 honoured 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 accidently activate units that are + not intended to be activated + explicitly. This option defaults to + . + + Unit file may include a [Install] section, which @@ -123,7 +407,7 @@ systemd1 during runtime. It is used exclusively by the systemd-install1 - during installation of a unit: + tool during installation of a unit: @@ -148,18 +432,52 @@ unconditionally if the unit is loaded. The names from Alias= apply only - if the unit is actually installed with - the systemd-install + 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, but not names configured only - with Names=. 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. + 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. -- 2.30.2