diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index b3025ea09b..5acb5951cd 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 use a pipe symbol (|) after the equals + sign (Condition…=|…), which causes the 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. + + + + diff --git a/src/shared/module-util.c b/src/shared/module-util.c index a34fe8fb95..75c8ba2b78 100644 --- a/src/shared/module-util.c +++ b/src/shared/module-util.c @@ -36,7 +36,7 @@ int module_load_and_warn(struct kmod_ctx *ctx, const char *module, bool verbose) switch (state) { case KMOD_MODULE_BUILTIN: log_full(verbose ? LOG_INFO : LOG_DEBUG, - "Module '%s' is builtin", kmod_module_get_name(mod)); + "Module '%s' is built in", kmod_module_get_name(mod)); break; case KMOD_MODULE_LIVE: