X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd.unit.xml;h=c20efe5527500232c288ede37fb460ee372d48fb;hp=c0da6523c4227659234a551988283144f87eb388;hb=f8a2ebbc503c23210300ade56c1fb71c85c40a59;hpb=78d54bd42b87818f5d0ef862d247f9db4844fadd diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index c0da6523c..c20efe552 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -44,7 +44,7 @@ systemd.unit - systemd unit configuration files + Unit configuration @@ -75,10 +75,10 @@ inspired by Microsoft Windows .ini files. - This man pages lists the common configuration + This man page lists the common configuration options of all the unit types. These options need to - be configured in the [Unit] resp. [Install] - section of the unit files. + be configured in the [Unit] or [Install] + sections of the unit files. In addition to the generic [Unit] and [Install] sections described here, each unit should have a @@ -258,6 +258,36 @@ Runtime socket dir This is either /run (for the system manager) or $XDG_RUNTIME_DIR (for user managers). + + %u + User name + This is the name of the configured user of the unit, or (if none is set) the user running the systemd instance. + + + %h + User home directory + This is the home directory of the configured user of the unit, or (if none is set) the user running the systemd instance. + + + %s + User shell + This is the shell of the configured user of the unit, or (if none is set) the user running the systemd instance. + + + %m + Machine ID + The machine ID of the running system, formatted as string. See machine-id5 for more information. + + + %b + Boot ID + The boot ID of the running system, formatted as string. See random4 for more information. + + + %H + Host name + The host name of the running system. + @@ -308,7 +338,15 @@ man:. For more information about the syntax of these URIs see - uri7. + uri7. The + URIs should be listed in order of + relevance, starting with the most + relevant. It is a good idea to first + reference documentation that explains + what the unit's purpose is, followed + by how it is configured, followed by + any other related + documentation. @@ -348,7 +386,15 @@ Requires= in order to achieve a system that is more robust when dealing with failing - services. + services. + + Note that dependencies of this + type may also be configured outside of + the unit configuration file by + adding a symlink to a + .requires/ directory + accompanying the unit file. For + details see above. @@ -380,7 +426,7 @@ Similar to Requires= - resp. RequiresOverridable=. However, + and RequiresOverridable=, respectively. However, if a unit listed here is not started already it will not be started and the transaction fails @@ -400,7 +446,9 @@ 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 + unit. + + Note that dependencies of this type may also be configured outside of the unit configuration file by adding a symlink to a @@ -410,12 +458,12 @@ - BindTo= + BindsTo= Configures requirement dependencies, very similar in style to Requires=, however - in addition to this behaviour it also + in addition to this behavior it also declares that this unit is stopped when any of the units listed suddenly disappears. Units can suddenly, @@ -426,6 +474,21 @@ systemd. + + PartOf= + + Configures dependencies + similar to Requires=, + but limited to stopping and restarting + of units. When systemd stops or restarts + the units listed here, the action is + propagated to this unit. + Note that this is a one way dependency - + changes to this unit do not affect the + listed units. + + + Conflicts= @@ -511,7 +574,7 @@ Before=. If two units have no ordering dependencies between them they are shut down - resp. started up simultaneously, and + or started up simultaneously, and no ordering takes place. @@ -527,8 +590,8 @@ - PropagateReloadTo= - PropagateReloadFrom= + PropagatesReloadTo= + ReloadPropagatedFrom= Lists one or more units where reload requests on the @@ -546,7 +609,7 @@ RequiresMountsFor= Takes a space - separated list of paths. Automatically + separated list of absolute paths. Automatically adds dependencies of type Requires= and After= for all @@ -617,13 +680,13 @@ Takes a boolean argument. If this unit can only be activated - (resp. deactivated) indirectly. In + or deactivated indirectly. In this case explicit start-up - (resp. termination) requested by the + or termination requested by the user is denied, however if it is - started (resp. stopped) as a + started or stopped as a dependency of another unit, start-up - (resp. termination) will succeed. This + or termination will succeed. This is mostly a safety feature to ensure that the user does not accidentally activate units that are not intended @@ -715,70 +778,99 @@ ConditionPathIsMountPoint= ConditionPathIsReadWrite= ConditionDirectoryNotEmpty= + ConditionFileNotEmpty= ConditionFileIsExecutable= ConditionKernelCommandLine= ConditionVirtualization= ConditionSecurity= ConditionCapability= + ConditionHost= ConditionNull= Before starting a unit verify that the specified condition is - true. With + true. If it is not true the starting + of the unit will be skipped, however + all ordering dependencies of it are + still respected. A failing condition + will not result in the unit being + moved into a failure state. The + condition is checked at the time the + queued start job is to be + executed. + + With ConditionPathExists= - a file existence condition can be + a file existence condition is 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 + not exist the condition will + fail. If the absolute path name passed + to ConditionPathExists= is prefixed with an exclamation mark - (!), the test is negated, and the unit + ('!'), 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= + exist. + + ConditionPathExistsGlob= + is similar to + ConditionPathExists=, + 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= + directory. + + ConditionPathIsSymbolicLink= is similar to ConditionPathExists= but verifies whether a certain path exists and is a symbolic - link. ConditionPathIsMountPoint= + link. + + ConditionPathIsMountPoint= is similar to ConditionPathExists= but verifies whether a certain path exists and is a mount - point. ConditionPathIsReadWrite= + point. + + ConditionPathIsReadWrite= is similar to ConditionPathExists= but verifies whether the underlying - file system is read and writable + file system is readable and writable (i.e. not mounted - read-only). ConditionFileIsExecutable= + read-only). + + ConditionDirectoryNotEmpty= is similar to ConditionPathExists= but verifies whether a certain path - exists, is a regular file and marked - executable. - ConditionDirectoryNotEmpty= + exists and is a non-empty + directory. + + ConditionFileNotEmpty= is similar to ConditionPathExists= but verifies whether a certain path - exists and is a non-empty - directory. Similarly + exists and refers to a regular file + with a non-zero size. + + ConditionFileIsExecutable= + is similar to + ConditionPathExists= + but verifies whether a certain path + exists, is a regular file and marked + executable. + + Similar, ConditionKernelCommandLine= may be used to check whether a specific kernel command line option is @@ -786,14 +878,16 @@ 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 + '='). 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= + matching. + + ConditionVirtualization= may be used to check whether the system is executed in a virtualized environment and optionally test @@ -803,7 +897,7 @@ any virtualized environment, or one of vm and container to test - against a specific type of + against a generic type of virtualization solution, or one of qemu, kvm, @@ -822,15 +916,18 @@ virtualization technologies are nested only the innermost is considered. The test may be negated by prepending an - exclamation mark. - ConditionSecurity= + 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= + mark. + + ConditionCapability= may be used to check whether the given capability exists in the capability bounding set of the service manager @@ -841,14 +938,32 @@ for details). Pass a capability name such as CAP_MKNOD, possibly prefixed with an exclamation - mark to negate the check. Finally, + mark to negate the check. + + ConditionHost= + may be used to match against the + host name or machine ID of the + host. This either takes a host name + string (optionally with shell style + globs) which is tested against the + locally set host name as returned by + gethostname2, + or a machine ID formatted as string + (see + machine-id5). + The test may be negated by prepending + an exclamation mark. + + 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 + 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 @@ -870,32 +985,16 @@ - 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. - + SourcePath= + A path to a + configuration file this unit has been + generated from. This is primarily + useful for implementation of generator + tools that convert configuration from + an external configuration file format + into native unit files. Thus + functionality should not be used in + normal units. @@ -923,30 +1022,7 @@ time, systemctl enable 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 - systemctl enable - command. 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. + to the unit file name. @@ -955,8 +1031,8 @@ Installs a symlink in the .wants/ - resp. .requires/ - subdirectory for a unit. This has the + or .requires/ + subdirectory for a unit, respectively. This has the effect that when the listed unit name is activated the unit listing it is activated