From 337b733449924860eb71190e6eff95729909ede6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Tue, 29 Oct 2019 14:52:27 +0100 Subject: [PATCH] man: split out description of Conditions and Assert to new section We slowly added many many conditions over the years, and the text became very hard to read, because all the terms were squished in one . This rearragnes the text into a new subsection, with minimal grammar changes and removal of repetitions. --- man/systemd.unit.xml | 774 +++++++++++++++++++++++-------------------- 1 file changed, 417 insertions(+), 357 deletions(-) diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index f6e9d2a17c..d868e6827b 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -516,7 +516,6 @@ type of unit: - Description= A human readable name for the unit. This is used by @@ -990,7 +989,6 @@ the start will not be permitted. Defaults to . - RebootArgument= Configure the optional argument for the @@ -999,361 +997,6 @@ works just like the optional argument to systemctl reboot command. - - ConditionArchitecture= - ConditionVirtualization= - ConditionHost= - ConditionKernelCommandLine= - ConditionKernelVersion= - ConditionSecurity= - ConditionCapability= - ConditionACPower= - ConditionNeedsUpdate= - ConditionFirstBoot= - ConditionPathExists= - ConditionPathExistsGlob= - ConditionPathIsDirectory= - ConditionPathIsSymbolicLink= - ConditionPathIsMountPoint= - ConditionPathIsReadWrite= - ConditionDirectoryNotEmpty= - ConditionFileNotEmpty= - ConditionFileIsExecutable= - ConditionUser= - ConditionGroup= - ConditionControlGroupController= - ConditionMemory= - ConditionCPUs= - - - - Before starting a unit, verify that the specified condition is true. If it is not true, the - starting of the unit will be (mostly silently) skipped, however all ordering dependencies of it are still - respected. A failing condition will not result in the unit being moved into the failed - state. The condition is checked at the time the queued start job is to be executed. Use condition expressions - in order to silently skip units that do not apply to the local running system, for example because the kernel - or runtime environment doesn't require their functionality. Use the various - AssertArchitecture=, AssertVirtualization=, … options for a similar - mechanism that causes the job to fail (instead of being skipped) and results in logging about the failed check - (instead of being silently processed). For details about assertion conditions see below. Units with failed - conditions are considered to be in a clean state and will be garbage collected if they are not referenced. - This means, that when queried, the condition failure may or may not show up in the state of the unit. - - 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 prefixed with a pipe symbol (|) - in which case a condition becomes a triggering condition. If at least one triggering condition is - defined for a unit, then the unit will be executed if at least one of the triggering conditions apply - and all of the non-triggering conditions. If you prefix an argument with the pipe symbol and an - exclamation mark, the pipe symbol must be passed first, the exclamation second. Except for - ConditionPathIsSymbolicLink=, all path checks follow symlinks. If any of these - options is assigned the empty string, the list of conditions is reset completely, all previous - condition settings (of any kind) will have no effect. The condition verb of - systemd-analyze1 - can be used to test condition and assert expressions. - - ConditionArchitecture= may be used to - check whether the system is running on a specific - architecture. Takes one of - x86, - x86-64, - ppc, - ppc-le, - ppc64, - ppc64-le, - ia64, - parisc, - parisc64, - s390, - s390x, - sparc, - sparc64, - mips, - mips-le, - mips64, - mips64-le, - alpha, - arm, - arm-be, - arm64, - arm64-be, - sh, - sh64, - m68k, - tilegx, - cris, - arc, - arc-be to test - against a specific architecture. The architecture is - determined from the information returned by - uname2 - and is thus subject to - personality2. - Note that a Personality= setting in the - same unit file has no effect on this condition. A special - architecture name native is mapped to the - architecture the system manager itself is compiled for. The - test may be negated by prepending an exclamation mark. - - ConditionVirtualization= may be used - to check whether the system is executed in a virtualized - environment and optionally test whether it is a specific - implementation. Takes either boolean value to check if being - executed in any virtualized environment, or one of - vm and - container to test against a generic type of - virtualization solution, or one of - qemu, - kvm, - zvm, - vmware, - microsoft, - oracle, - xen, - bochs, - uml, - bhyve, - qnx, - openvz, - lxc, - lxc-libvirt, - systemd-nspawn, - docker, - podman, - rkt, - wsl, - acrn to test - against a specific implementation, or - private-users to check whether we are running in a user namespace. See - systemd-detect-virt1 - for a full list of known virtualization technologies and their - identifiers. If multiple virtualization technologies are - nested, only the innermost is considered. The test may be - negated by prepending an exclamation mark. - - ConditionHost= may be used to match - against the hostname or machine ID of the host. This either - takes a hostname string (optionally with shell style globs) - which is tested against the locally set hostname as returned - by - gethostname2, - or a machine ID formatted as string (see - machine-id5). - The test may be negated by prepending an exclamation - mark. - - ConditionKernelCommandLine= may be - used to check whether a specific kernel command line option is - set (or if prefixed with the exclamation mark unset). The - argument must either be a single word, or an assignment (i.e. - two words, separated =). 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. - - ConditionKernelVersion= may be used to check whether the kernel version (as - reported by uname -r) matches a certain expression (or if prefixed with the - exclamation mark does not match it). The argument must be a list of (potentially quoted) expressions. - For each of the expressions, if it starts with one of <, - <=, =, !=, >=, - > a relative version comparison is done, otherwise the specified string is - matched with shell-style globs. - - Note that using the kernel version string is an unreliable way to determine which features are supported - by a kernel, because of the widespread practice of backporting drivers, features, and fixes from newer upstream - kernels into older versions provided by distributions. Hence, this check is inherently unportable and should - not be used for units which may be used on different distributions. - - ConditionSecurity= may be used to check - whether the given security technology is enabled on the - system. Currently, the recognized values are - selinux, apparmor, - tomoyo, ima, - smack, audit and - uefi-secureboot. The test may be negated by - prepending an exclamation mark. - - ConditionCapability= may be used to - check whether the given capability exists in the capability - bounding set of the service manager (i.e. this does not check - whether capability is actually available in the permitted or - effective sets, see - capabilities7 - for details). Pass a capability name such as - CAP_MKNOD, possibly prefixed with an - exclamation mark to negate the check. - - ConditionACPower= may be used to - check whether the system has AC power, or is exclusively - battery powered at the time of activation of the unit. This - takes a boolean argument. If set to true, - the condition will hold only if at least one AC connector of - the system is connected to a power source, or if no AC - connectors are known. Conversely, if set to - false, the condition will hold only if - there is at least one AC connector known and all AC connectors - are disconnected from a power source. - - ConditionNeedsUpdate= takes one of - /var or /etc as - argument, possibly prefixed with a ! (for - inverting the condition). This condition may be used to - conditionalize units on whether the specified directory - requires an update because /usr's - modification time is newer than the stamp file - .updated in the specified directory. This - is useful to implement offline updates of the vendor operating - system resources in /usr that require - updating of /etc or - /var on the next following boot. Units - making use of this condition should order themselves before - systemd-update-done.service8, - to make sure they run before the stamp file's modification - time gets reset indicating a completed update. - - ConditionFirstBoot= takes a boolean argument. This condition may be used to - conditionalize units on whether the system is booting up with an unpopulated /etc - directory (specifically: an /etc with no /etc/machine-id). This may - be used to populate /etc on the first boot after factory reset, or when a new system - instance boots up for the first time. - - With ConditionPathExists= a file - existence condition is checked before a unit is started. If - the specified absolute path name does 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 is only started if the path does not - 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= is - similar to ConditionPathExists= but - verifies whether a certain path exists and is a symbolic - link. - - ConditionPathIsMountPoint= is similar - to ConditionPathExists= but verifies - whether a certain path exists and is a mount point. - - ConditionPathIsReadWrite= is similar - to ConditionPathExists= but verifies - whether the underlying file system is readable and writable - (i.e. not mounted read-only). - - ConditionDirectoryNotEmpty= is - similar to ConditionPathExists= but - verifies whether a certain path exists and is a non-empty - directory. - - ConditionFileNotEmpty= is similar to - ConditionPathExists= but verifies whether a - certain path 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. - - ConditionUser= takes a numeric - UID, a UNIX user name, or the special value - @system. This condition may be used to check - whether the service manager is running as the given user. The - special value @system can be used to check - if the user id is within the system user range. This option is not - useful for system services, as the system manager exclusively - runs as the root user, and thus the test result is constant. - - ConditionGroup= is similar - to ConditionUser= but verifies that the - service manager's real or effective group, or any of its - auxiliary groups match the specified group or GID. This setting - does not have a special value @system. - - ConditionControlGroupController= takes a - cgroup controller name (eg. cpu), verifying that it is - available for use on the system. For example, a particular controller - may not be available if it was disabled on the kernel command line with - cgroup_disable=controller. Multiple controllers may - be passed with a space separating them; in this case the condition will - only pass if all listed controllers are available for use. Controllers - unknown to systemd are ignored. Valid controllers are - cpu, cpuacct, io, - blkio, memory, - devices, and pids. - - ConditionMemory= verifies if the specified amount of system memory is - available to the current system. Takes a memory size in bytes as argument, optionally prefixed with a - comparison operator <, <=, =, - !=, >=, >. On bare-metal systems - compares the amount of physical memory in the system with the specified size, adhering to the - specified comparison operator. In containers compares the amount of memory assigned to the container - instead. - - ConditionCPUs= verifies if the specified number of CPUs is available to the - current system. Takes a number of CPUs as argument, optionally prefixed with a comparison operator - <, <=, =, !=, - >=, >. Compares the number of CPUs in the CPU affinity mask - configured of the service manager itself with the specified number, adhering to the specified - comparison operator. On physical systems the number of CPUs in the affinity mask of the service - manager usually matches the number of physical CPUs, but in special and virtual environments might - differ. In particular, in containers the affinity mask usually matches the number of CPUs assigned to - the container and not the physically available ones. - - - - AssertArchitecture= - AssertVirtualization= - AssertHost= - AssertKernelCommandLine= - AssertKernelVersion= - AssertSecurity= - AssertCapability= - AssertACPower= - AssertNeedsUpdate= - AssertFirstBoot= - AssertPathExists= - AssertPathExistsGlob= - AssertPathIsDirectory= - AssertPathIsSymbolicLink= - AssertPathIsMountPoint= - AssertPathIsReadWrite= - AssertDirectoryNotEmpty= - AssertFileNotEmpty= - AssertFileIsExecutable= - AssertUser= - AssertGroup= - AssertControlGroupController= - - Similar to the ConditionArchitecture=, - ConditionVirtualization=, …, condition settings described above, these settings add - assertion checks to the start-up of the unit. However, unlike the conditions settings, any assertion setting - that is not met results in failure of the start job (which means this is logged loudly). Note that hitting a - configured assertion does not cause the unit to enter the failed state (or in fact result in - any state change of the unit), it affects only the job queued for it. Use assertion expressions for units that - cannot operate when specific requirements are not met, and when this is something the administrator or user - should look into. - - Note that neither assertion nor condition expressions result in unit state changes. Also note that both - are checked at the time the job is to be executed, i.e. long after depending jobs and it itself were - queued. Thus, neither condition nor assertion expressions are suitable for conditionalizing unit - dependencies. - - The condition verb of - systemd-analyze1 - can be used to test condition and assert expressions. - - SourcePath= A path to a configuration file this unit has @@ -1364,6 +1007,423 @@ units. + + + Conditions and Asserts + + Unit files may also include a number of Condition…= and + Assert…= settings. Before the unit is started, systemd will verify + that the specified conditions are true. If not, the starting of the unit will be (mostly silently) + skipped. Failing conditions will not result in the unit being moved into the failed + state. The conditions are checked at the time the queued start job is to be executed. The ordering + dependencies are still respected, so other units are still pulled in and ordered as if this unit was + successfully activated. Use condition expressions in order to skip units that do not apply to the local + system, for example because the kernel or runtime environment doesn't require their functionality. + + + 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 prefixed with a pipe symbol (|) in + which case a condition becomes a triggering condition. If at least one triggering condition is defined + for a unit, then the unit will be executed if at least one of the triggering conditions apply and all + of the non-triggering conditions. If you prefix an argument with the pipe symbol and an exclamation + mark, the pipe symbol must be passed first, the exclamation second. If any of these options is assigned + the empty string, the list of conditions is reset completely, all previous condition settings (of any + kind) will have no effect. + + The AssertArchitecture=, AssertVirtualization=, … options + provide a similar mechanism that causes the job to fail (instead of being skipped). The failed check is + logged. Units with failed conditions are considered to be in a clean state and will be garbage + collected if they are not referenced. This means that when queried, the condition failure may or may + not show up in the state of the unit. + + Note that neither assertion nor condition expressions result in unit state changes. Also note + that both are checked at the time the job is to be executed, i.e. long after depending jobs and it + itself were queued. Thus, neither condition nor assertion expressions are suitable for conditionalizing + unit dependencies. + + The condition verb of + systemd-analyze1 can + be used to test condition and assert expressions. + + Except for ConditionPathIsSymbolicLink=, all path checks follow symlinks. + + + + + + ConditionArchitecture= + + Check whether the system is running on a specific architecture. Takes one of + x86, + x86-64, + ppc, + ppc-le, + ppc64, + ppc64-le, + ia64, + parisc, + parisc64, + s390, + s390x, + sparc, + sparc64, + mips, + mips-le, + mips64, + mips64-le, + alpha, + arm, + arm-be, + arm64, + arm64-be, + sh, + sh64, + m68k, + tilegx, + cris, + arc, + arc-be, or + native. + + The architecture is determined from the information returned by + uname2 + and is thus subject to + personality2. + Note that a Personality= setting in the same unit file has no effect on this + condition. A special architecture name native is mapped to the architecture the + system manager itself is compiled for. The test may be negated by prepending an exclamation + mark. + + + + + ConditionArchitecture= + + Check whether the system is executed in a virtualized environment and optionally + test whether it is a specific implementation. Takes either boolean value to check if being executed + in any virtualized environment, or one of + vm and + container to test against a generic type of virtualization solution, or one of + qemu, + kvm, + zvm, + vmware, + microsoft, + oracle, + xen, + bochs, + uml, + bhyve, + qnx, + openvz, + lxc, + lxc-libvirt, + systemd-nspawn, + docker, + podman, + rkt, + wsl, + acrn to test + against a specific implementation, or + private-users to check whether we are running in a user namespace. See + systemd-detect-virt1 + for a full list of known virtualization technologies and their identifiers. If multiple + virtualization technologies are nested, only the innermost is considered. The test may be negated + by prepending an exclamation mark. + + + + + ConditionHost= + + ConditionHost= may be used to match against the hostname or + machine ID of the host. This either takes a hostname string (optionally with shell style globs) + which is tested against the locally set hostname as returned by + gethostname2, or + a machine ID formatted as string (see + machine-id5). + The test may be negated by prepending an exclamation mark. + + + + + ConditionKernelCommandLine= + + ConditionKernelCommandLine= may be used to check whether a + specific kernel command line option is set (or if prefixed with the exclamation mark — unset). The + argument must either be a single word, or an assignment (i.e. two words, separated by + =). 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. + + + + + ConditionKernelVersion= + + ConditionKernelVersion= may be used to check whether the kernel + version (as reported by uname -r) matches a certain expression (or if prefixed + with the exclamation mark does not match it). The argument must be a list of (potentially quoted) + expressions. For each of the expressions, if it starts with one of <, + <=, =, !=, >=, + > a relative version comparison is done, otherwise the specified string is + matched with shell-style globs. + + Note that using the kernel version string is an unreliable way to determine which features + are supported by a kernel, because of the widespread practice of backporting drivers, features, and + fixes from newer upstream kernels into older versions provided by distributions. Hence, this check + is inherently unportable and should not be used for units which may be used on different + distributions. + + + + + ConditionSecurity= + + ConditionSecurity= may be used to check whether the given + security technology is enabled on the system. Currently, the recognized values are + selinux, apparmor, tomoyo, + ima, smack, audit and + uefi-secureboot. The test may be negated by prepending an exclamation + mark. + + + + + ConditionCapability= + + Check whether the given capability exists in the capability bounding set of the + service manager (i.e. this does not check whether capability is actually available in the permitted + or effective sets, see + capabilities7 + for details). Pass a capability name such as CAP_MKNOD, possibly prefixed with + an exclamation mark to negate the check. + + + + + ConditionACPower= + + Check whether the system has AC power, or is exclusively battery powered at the + time of activation of the unit. This takes a boolean argument. If set to true, + the condition will hold only if at least one AC connector of the system is connected to a power + source, or if no AC connectors are known. Conversely, if set to false, the + condition will hold only if there is at least one AC connector known and all AC connectors are + disconnected from a power source. + + + + + ConditionNeedsUpdate= + + Takes one of /var or /etc as argument, + possibly prefixed with a ! (to inverting the condition). This condition may be + used to conditionalize units on whether the specified directory requires an update because + /usr's modification time is newer than the stamp file + .updated in the specified directory. This is useful to implement offline + updates of the vendor operating system resources in /usr that require updating + of /etc or /var on the next following boot. Units making + use of this condition should order themselves before + systemd-update-done.service8, + to make sure they run before the stamp file's modification time gets reset indicating a completed + update. + + + + + ConditionFirstBoot= + + Takes a boolean argument. This condition may be used to conditionalize units on + whether the system is booting up with an unpopulated /etc directory + (specifically: an /etc with no /etc/machine-id). This may + be used to populate /etc on the first boot after factory reset, or when a new + system instance boots up for the first time. + + + + + ConditionPathExists= + + Check for the exists of a file. If the specified absolute path name does 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 is only started if the path does not + exist. + + + + + ConditionPathExistsGlob= + + ConditionPathExistsGlob= is similar to + ConditionPathExists=, but checks for the existence of at least one file or + directory matching the specified globbing pattern. + + + + + ConditionPathIsDirectory= + + ConditionPathIsDirectory= is similar to + ConditionPathExists= but verifies that a certain path exists and is a + directory. + + + + + ConditionPathIsSymbolicLink= + + ConditionPathIsSymbolicLink= is similar to + ConditionPathExists= but verifies that a certain path exists and is a symbolic + link. + + + + + ConditionPathIsMountPoint= + + ConditionPathIsMountPoint= is similar to + ConditionPathExists= but verifies that a certain path exists and is a mount + point. + + + + + ConditionPathIsReadWrite= + + ConditionPathIsReadWrite= is similar to + ConditionPathExists= but verifies that the underlying file system is readable + and writable (i.e. not mounted read-only). + + + + + ConditionDirectoryNotEmpty= + + ConditionDirectoryNotEmpty= is similar to + ConditionPathExists= but verifies that a certain path exists and is a non-empty + directory. + + + + + ConditionFileNotEmpty= + + ConditionFileNotEmpty= is similar to + ConditionPathExists= but verifies that a certain path exists and refers to a + regular file with a non-zero size. + + + + + ConditionFileIsExecutable= + + ConditionFileIsExecutable= is similar to + ConditionPathExists= but verifies that a certain path exists, is a regular file, + and marked executable. + + + + + ConditionUser= + + ConditionUser= takes a numeric UID, a UNIX + user name, or the special value @system. This condition may be used to check + whether the service manager is running as the given user. The special value + @system can be used to check if the user id is within the system user + range. This option is not useful for system services, as the system manager exclusively runs as the + root user, and thus the test result is constant. + + + + + ConditionGroup= + + ConditionGroup= is similar to ConditionUser= + but verifies that the service manager's real or effective group, or any of its auxiliary groups, + match the specified group or GID. This setting does not support the special value + @system. + + + + + ConditionControlGroupController= + + Verify that the given cgroup controller (eg. cpu) is available + for use on the system. For example, a particular controller may not be available if it was disabled + on the kernel command line with cgroup_disable=controller. Multiple controllers + may be passed with a space separating them; in this case the condition will only pass if all listed + controllers are available for use. Controllers unknown to systemd are ignored. Valid controllers + are cpu, cpuacct, io, + blkio, memory, devices, and + pids. + + + + + ConditionMemory= + + Verify that the specified amount of system memory is available to the current + system. Takes a memory size in bytes as argument, optionally prefixed with a comparison operator + <, <=, =, !=, + >=, >. On bare-metal systems compares the amount of + physical memory in the system with the specified size, adhering to the specified comparison + operator. In containers compares the amount of memory assigned to the container instead. + + + + + ConditionCPUs= + + Verify that the specified number of CPUs is available to the current system. Takes + a number of CPUs as argument, optionally prefixed with a comparison operator + <, <=, =, !=, + >=, >. Compares the number of CPUs in the CPU affinity + mask configured of the service manager itself with the specified number, adhering to the specified + comparison operator. On physical systems the number of CPUs in the affinity mask of the service + manager usually matches the number of physical CPUs, but in special and virtual environments might + differ. In particular, in containers the affinity mask usually matches the number of CPUs assigned + to the container and not the physically available ones. + + + + AssertArchitecture= + AssertVirtualization= + AssertHost= + AssertKernelCommandLine= + AssertKernelVersion= + AssertSecurity= + AssertCapability= + AssertACPower= + AssertNeedsUpdate= + AssertFirstBoot= + AssertPathExists= + AssertPathExistsGlob= + AssertPathIsDirectory= + AssertPathIsSymbolicLink= + AssertPathIsMountPoint= + AssertPathIsReadWrite= + AssertDirectoryNotEmpty= + AssertFileNotEmpty= + AssertFileIsExecutable= + AssertUser= + AssertGroup= + AssertControlGroupController= + + Similar to the ConditionArchitecture=, + ConditionVirtualization=, …, condition settings described above, these settings + add assertion checks to the start-up of the unit. However, unlike the conditions settings, any + assertion setting that is not met results in failure of the start job (which means this is logged + loudly). Note that hitting a configured assertion does not cause the unit to enter the + failed state (or in fact result in any state change of the unit), it affects + only the job queued for it. Use assertion expressions for units that cannot operate when specific + requirements are not met, and when this is something the administrator or user should look + into. + + + +