Merge pull request #13867 from keszybz/man-condition
Refactor description of conditons
This commit is contained in:
Yu Watanabe
GitHub
commit
afa1a54eb5
|
|
@ -516,7 +516,6 @@
|
|||
type of unit:</para>
|
||||
|
||||
<variablelist class='unit-directives'>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>Description=</varname></term>
|
||||
<listitem><para>A human readable name for the unit. This is used by
|
||||
|
|
@ -990,7 +989,6 @@
|
|||
the start will not be permitted. Defaults to <option>none</option>.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>RebootArgument=</varname></term>
|
||||
<listitem><para>Configure the optional argument for the
|
||||
|
|
@ -999,361 +997,6 @@
|
|||
works just like the optional argument to <command>systemctl reboot</command> command.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>ConditionArchitecture=</varname></term>
|
||||
<term><varname>ConditionVirtualization=</varname></term>
|
||||
<term><varname>ConditionHost=</varname></term>
|
||||
<term><varname>ConditionKernelCommandLine=</varname></term>
|
||||
<term><varname>ConditionKernelVersion=</varname></term>
|
||||
<term><varname>ConditionSecurity=</varname></term>
|
||||
<term><varname>ConditionCapability=</varname></term>
|
||||
<term><varname>ConditionACPower=</varname></term>
|
||||
<term><varname>ConditionNeedsUpdate=</varname></term>
|
||||
<term><varname>ConditionFirstBoot=</varname></term>
|
||||
<term><varname>ConditionPathExists=</varname></term>
|
||||
<term><varname>ConditionPathExistsGlob=</varname></term>
|
||||
<term><varname>ConditionPathIsDirectory=</varname></term>
|
||||
<term><varname>ConditionPathIsSymbolicLink=</varname></term>
|
||||
<term><varname>ConditionPathIsMountPoint=</varname></term>
|
||||
<term><varname>ConditionPathIsReadWrite=</varname></term>
|
||||
<term><varname>ConditionDirectoryNotEmpty=</varname></term>
|
||||
<term><varname>ConditionFileNotEmpty=</varname></term>
|
||||
<term><varname>ConditionFileIsExecutable=</varname></term>
|
||||
<term><varname>ConditionUser=</varname></term>
|
||||
<term><varname>ConditionGroup=</varname></term>
|
||||
<term><varname>ConditionControlGroupController=</varname></term>
|
||||
<term><varname>ConditionMemory=</varname></term>
|
||||
<term><varname>ConditionCPUs=</varname></term>
|
||||
|
||||
<!-- We do not document ConditionNull= here, as it is not particularly useful and probably just
|
||||
confusing. -->
|
||||
|
||||
<listitem><para>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 <literal>failed</literal>
|
||||
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
|
||||
<varname>AssertArchitecture=</varname>, <varname>AssertVirtualization=</varname>, … 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.</para>
|
||||
|
||||
<para>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 (<literal>|</literal>)
|
||||
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
|
||||
<varname>ConditionPathIsSymbolicLink=</varname>, 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 <command>condition</command> verb of
|
||||
<citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
||||
can be used to test condition and assert expressions.</para>
|
||||
|
||||
<para><varname>ConditionArchitecture=</varname> may be used to
|
||||
check whether the system is running on a specific
|
||||
architecture. Takes one of
|
||||
<literal>x86</literal>,
|
||||
<literal>x86-64</literal>,
|
||||
<literal>ppc</literal>,
|
||||
<literal>ppc-le</literal>,
|
||||
<literal>ppc64</literal>,
|
||||
<literal>ppc64-le</literal>,
|
||||
<literal>ia64</literal>,
|
||||
<literal>parisc</literal>,
|
||||
<literal>parisc64</literal>,
|
||||
<literal>s390</literal>,
|
||||
<literal>s390x</literal>,
|
||||
<literal>sparc</literal>,
|
||||
<literal>sparc64</literal>,
|
||||
<literal>mips</literal>,
|
||||
<literal>mips-le</literal>,
|
||||
<literal>mips64</literal>,
|
||||
<literal>mips64-le</literal>,
|
||||
<literal>alpha</literal>,
|
||||
<literal>arm</literal>,
|
||||
<literal>arm-be</literal>,
|
||||
<literal>arm64</literal>,
|
||||
<literal>arm64-be</literal>,
|
||||
<literal>sh</literal>,
|
||||
<literal>sh64</literal>,
|
||||
<literal>m68k</literal>,
|
||||
<literal>tilegx</literal>,
|
||||
<literal>cris</literal>,
|
||||
<literal>arc</literal>,
|
||||
<literal>arc-be</literal> to test
|
||||
against a specific architecture. The architecture is
|
||||
determined from the information returned by
|
||||
<citerefentry project='man-pages'><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry>
|
||||
and is thus subject to
|
||||
<citerefentry><refentrytitle>personality</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
|
||||
Note that a <varname>Personality=</varname> setting in the
|
||||
same unit file has no effect on this condition. A special
|
||||
architecture name <literal>native</literal> is mapped to the
|
||||
architecture the system manager itself is compiled for. The
|
||||
test may be negated by prepending an exclamation mark.</para>
|
||||
|
||||
<para><varname>ConditionVirtualization=</varname> 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
|
||||
<literal>vm</literal> and
|
||||
<literal>container</literal> to test against a generic type of
|
||||
virtualization solution, or one of
|
||||
<literal>qemu</literal>,
|
||||
<literal>kvm</literal>,
|
||||
<literal>zvm</literal>,
|
||||
<literal>vmware</literal>,
|
||||
<literal>microsoft</literal>,
|
||||
<literal>oracle</literal>,
|
||||
<literal>xen</literal>,
|
||||
<literal>bochs</literal>,
|
||||
<literal>uml</literal>,
|
||||
<literal>bhyve</literal>,
|
||||
<literal>qnx</literal>,
|
||||
<literal>openvz</literal>,
|
||||
<literal>lxc</literal>,
|
||||
<literal>lxc-libvirt</literal>,
|
||||
<literal>systemd-nspawn</literal>,
|
||||
<literal>docker</literal>,
|
||||
<literal>podman</literal>,
|
||||
<literal>rkt</literal>,
|
||||
<literal>wsl</literal>,
|
||||
<literal>acrn</literal> to test
|
||||
against a specific implementation, or
|
||||
<literal>private-users</literal> to check whether we are running in a user namespace. See
|
||||
<citerefentry><refentrytitle>systemd-detect-virt</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
||||
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.</para>
|
||||
|
||||
<para><varname>ConditionHost=</varname> 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
|
||||
<citerefentry><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
|
||||
or a machine ID formatted as string (see
|
||||
<citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
|
||||
The test may be negated by prepending an exclamation
|
||||
mark.</para>
|
||||
|
||||
<para><varname>ConditionKernelCommandLine=</varname> 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 <literal>=</literal>). 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.</para>
|
||||
|
||||
<para><varname>ConditionKernelVersion=</varname> may be used to check whether the kernel version (as
|
||||
reported by <command>uname -r</command>) 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 <literal><</literal>,
|
||||
<literal><=</literal>, <literal>=</literal>, <literal>!=</literal>, <literal>>=</literal>,
|
||||
<literal>></literal> a relative version comparison is done, otherwise the specified string is
|
||||
matched with shell-style globs.</para>
|
||||
|
||||
<para>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.</para>
|
||||
|
||||
<para><varname>ConditionSecurity=</varname> may be used to check
|
||||
whether the given security technology is enabled on the
|
||||
system. Currently, the recognized values are
|
||||
<literal>selinux</literal>, <literal>apparmor</literal>,
|
||||
<literal>tomoyo</literal>, <literal>ima</literal>,
|
||||
<literal>smack</literal>, <literal>audit</literal> and
|
||||
<literal>uefi-secureboot</literal>. The test may be negated by
|
||||
prepending an exclamation mark.</para>
|
||||
|
||||
<para><varname>ConditionCapability=</varname> 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
|
||||
<citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
|
||||
for details). Pass a capability name such as
|
||||
<literal>CAP_MKNOD</literal>, possibly prefixed with an
|
||||
exclamation mark to negate the check.</para>
|
||||
|
||||
<para><varname>ConditionACPower=</varname> 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 <literal>true</literal>,
|
||||
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
|
||||
<literal>false</literal>, the condition will hold only if
|
||||
there is at least one AC connector known and all AC connectors
|
||||
are disconnected from a power source.</para>
|
||||
|
||||
<para><varname>ConditionNeedsUpdate=</varname> takes one of
|
||||
<filename>/var</filename> or <filename>/etc</filename> as
|
||||
argument, possibly prefixed with a <literal>!</literal> (for
|
||||
inverting the condition). This condition may be used to
|
||||
conditionalize units on whether the specified directory
|
||||
requires an update because <filename>/usr</filename>'s
|
||||
modification time is newer than the stamp file
|
||||
<filename>.updated</filename> in the specified directory. This
|
||||
is useful to implement offline updates of the vendor operating
|
||||
system resources in <filename>/usr</filename> that require
|
||||
updating of <filename>/etc</filename> or
|
||||
<filename>/var</filename> on the next following boot. Units
|
||||
making use of this condition should order themselves before
|
||||
<citerefentry><refentrytitle>systemd-update-done.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
|
||||
to make sure they run before the stamp file's modification
|
||||
time gets reset indicating a completed update.</para>
|
||||
|
||||
<para><varname>ConditionFirstBoot=</varname> takes a boolean argument. This condition may be used to
|
||||
conditionalize units on whether the system is booting up with an unpopulated <filename>/etc</filename>
|
||||
directory (specifically: an <filename>/etc</filename> with no <filename>/etc/machine-id</filename>). This may
|
||||
be used to populate <filename>/etc</filename> on the first boot after factory reset, or when a new system
|
||||
instance boots up for the first time.</para>
|
||||
|
||||
<para>With <varname>ConditionPathExists=</varname> 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
|
||||
<varname>ConditionPathExists=</varname> is prefixed with an
|
||||
exclamation mark (<literal>!</literal>), the test is negated,
|
||||
and the unit is only started if the path does not
|
||||
exist.</para>
|
||||
|
||||
<para><varname>ConditionPathExistsGlob=</varname> is similar
|
||||
to <varname>ConditionPathExists=</varname>, but checks for the
|
||||
existence of at least one file or directory matching the
|
||||
specified globbing pattern.</para>
|
||||
|
||||
<para><varname>ConditionPathIsDirectory=</varname> is similar
|
||||
to <varname>ConditionPathExists=</varname> but verifies
|
||||
whether a certain path exists and is a directory.</para>
|
||||
|
||||
<para><varname>ConditionPathIsSymbolicLink=</varname> is
|
||||
similar to <varname>ConditionPathExists=</varname> but
|
||||
verifies whether a certain path exists and is a symbolic
|
||||
link.</para>
|
||||
|
||||
<para><varname>ConditionPathIsMountPoint=</varname> is similar
|
||||
to <varname>ConditionPathExists=</varname> but verifies
|
||||
whether a certain path exists and is a mount point.</para>
|
||||
|
||||
<para><varname>ConditionPathIsReadWrite=</varname> is similar
|
||||
to <varname>ConditionPathExists=</varname> but verifies
|
||||
whether the underlying file system is readable and writable
|
||||
(i.e. not mounted read-only).</para>
|
||||
|
||||
<para><varname>ConditionDirectoryNotEmpty=</varname> is
|
||||
similar to <varname>ConditionPathExists=</varname> but
|
||||
verifies whether a certain path exists and is a non-empty
|
||||
directory.</para>
|
||||
|
||||
<para><varname>ConditionFileNotEmpty=</varname> is similar to
|
||||
<varname>ConditionPathExists=</varname> but verifies whether a
|
||||
certain path exists and refers to a regular file with a
|
||||
non-zero size.</para>
|
||||
|
||||
<para><varname>ConditionFileIsExecutable=</varname> is similar
|
||||
to <varname>ConditionPathExists=</varname> but verifies
|
||||
whether a certain path exists, is a regular file and marked
|
||||
executable.</para>
|
||||
|
||||
<para><varname>ConditionUser=</varname> takes a numeric
|
||||
<literal>UID</literal>, a UNIX user name, or the special value
|
||||
<literal>@system</literal>. This condition may be used to check
|
||||
whether the service manager is running as the given user. The
|
||||
special value <literal>@system</literal> 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.</para>
|
||||
|
||||
<para><varname>ConditionGroup=</varname> is similar
|
||||
to <varname>ConditionUser=</varname> 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 <literal>@system</literal>.</para>
|
||||
|
||||
<para><varname>ConditionControlGroupController=</varname> takes a
|
||||
cgroup controller name (eg. <literal>cpu</literal>), 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
|
||||
<varname>cgroup_disable=controller</varname>. 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
|
||||
<literal>cpu</literal>, <literal>cpuacct</literal>, <literal>io</literal>,
|
||||
<literal>blkio</literal>, <literal>memory</literal>,
|
||||
<literal>devices</literal>, and <literal>pids</literal>.</para>
|
||||
|
||||
<para><varname>ConditionMemory=</varname> 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 <literal><</literal>, <literal><=</literal>, <literal>=</literal>,
|
||||
<literal>!=</literal>, <literal>>=</literal>, <literal>></literal>. 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.</para>
|
||||
|
||||
<para><varname>ConditionCPUs=</varname> 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
|
||||
<literal><</literal>, <literal><=</literal>, <literal>=</literal>, <literal>!=</literal>,
|
||||
<literal>>=</literal>, <literal>></literal>. 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.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>AssertArchitecture=</varname></term>
|
||||
<term><varname>AssertVirtualization=</varname></term>
|
||||
<term><varname>AssertHost=</varname></term>
|
||||
<term><varname>AssertKernelCommandLine=</varname></term>
|
||||
<term><varname>AssertKernelVersion=</varname></term>
|
||||
<term><varname>AssertSecurity=</varname></term>
|
||||
<term><varname>AssertCapability=</varname></term>
|
||||
<term><varname>AssertACPower=</varname></term>
|
||||
<term><varname>AssertNeedsUpdate=</varname></term>
|
||||
<term><varname>AssertFirstBoot=</varname></term>
|
||||
<term><varname>AssertPathExists=</varname></term>
|
||||
<term><varname>AssertPathExistsGlob=</varname></term>
|
||||
<term><varname>AssertPathIsDirectory=</varname></term>
|
||||
<term><varname>AssertPathIsSymbolicLink=</varname></term>
|
||||
<term><varname>AssertPathIsMountPoint=</varname></term>
|
||||
<term><varname>AssertPathIsReadWrite=</varname></term>
|
||||
<term><varname>AssertDirectoryNotEmpty=</varname></term>
|
||||
<term><varname>AssertFileNotEmpty=</varname></term>
|
||||
<term><varname>AssertFileIsExecutable=</varname></term>
|
||||
<term><varname>AssertUser=</varname></term>
|
||||
<term><varname>AssertGroup=</varname></term>
|
||||
<term><varname>AssertControlGroupController=</varname></term>
|
||||
|
||||
<listitem><para>Similar to the <varname>ConditionArchitecture=</varname>,
|
||||
<varname>ConditionVirtualization=</varname>, …, 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 <literal>failed</literal> 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.</para>
|
||||
|
||||
<para>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.</para>
|
||||
|
||||
<para>The <command>condition</command> verb of
|
||||
<citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
||||
can be used to test condition and assert expressions.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>SourcePath=</varname></term>
|
||||
<listitem><para>A path to a configuration file this unit has
|
||||
|
|
@ -1364,6 +1007,423 @@
|
|||
units.</para></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
<refsect2>
|
||||
<title>Conditions and Asserts</title>
|
||||
|
||||
<para>Unit files may also include a number of <varname noindex="true">Condition…=</varname> and
|
||||
<varname noindex="true">Assert…=</varname> 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 <literal>failed</literal>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>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 (<literal>|</literal>) after the equals
|
||||
sign (<literal>Condition…=|…</literal>), 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.</para>
|
||||
|
||||
<para>The <varname>AssertArchitecture=</varname>, <varname>AssertVirtualization=</varname>, … 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.</para>
|
||||
|
||||
<para>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.</para>
|
||||
|
||||
<para>The <command>condition</command> verb of
|
||||
<citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry> can
|
||||
be used to test condition and assert expressions.</para>
|
||||
|
||||
<para>Except for <varname>ConditionPathIsSymbolicLink=</varname>, all path checks follow symlinks.</para>
|
||||
|
||||
<variablelist class='unit-directives'>
|
||||
<!-- We do not document ConditionNull= here, as it is not particularly useful and probably just
|
||||
confusing. -->
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>ConditionArchitecture=</varname></term>
|
||||
|
||||
<listitem><para>Check whether the system is running on a specific architecture. Takes one of
|
||||
<literal>x86</literal>,
|
||||
<literal>x86-64</literal>,
|
||||
<literal>ppc</literal>,
|
||||
<literal>ppc-le</literal>,
|
||||
<literal>ppc64</literal>,
|
||||
<literal>ppc64-le</literal>,
|
||||
<literal>ia64</literal>,
|
||||
<literal>parisc</literal>,
|
||||
<literal>parisc64</literal>,
|
||||
<literal>s390</literal>,
|
||||
<literal>s390x</literal>,
|
||||
<literal>sparc</literal>,
|
||||
<literal>sparc64</literal>,
|
||||
<literal>mips</literal>,
|
||||
<literal>mips-le</literal>,
|
||||
<literal>mips64</literal>,
|
||||
<literal>mips64-le</literal>,
|
||||
<literal>alpha</literal>,
|
||||
<literal>arm</literal>,
|
||||
<literal>arm-be</literal>,
|
||||
<literal>arm64</literal>,
|
||||
<literal>arm64-be</literal>,
|
||||
<literal>sh</literal>,
|
||||
<literal>sh64</literal>,
|
||||
<literal>m68k</literal>,
|
||||
<literal>tilegx</literal>,
|
||||
<literal>cris</literal>,
|
||||
<literal>arc</literal>,
|
||||
<literal>arc-be</literal>, or
|
||||
<literal>native</literal>.</para>
|
||||
|
||||
<para>The architecture is determined from the information returned by
|
||||
<citerefentry project='man-pages'><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry>
|
||||
and is thus subject to
|
||||
<citerefentry><refentrytitle>personality</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
|
||||
Note that a <varname>Personality=</varname> setting in the same unit file has no effect on this
|
||||
condition. A special architecture name <literal>native</literal> is mapped to the architecture the
|
||||
system manager itself is compiled for. The test may be negated by prepending an exclamation
|
||||
mark.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>ConditionArchitecture=</varname></term>
|
||||
|
||||
<listitem><para>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
|
||||
<literal>vm</literal> and
|
||||
<literal>container</literal> to test against a generic type of virtualization solution, or one of
|
||||
<literal>qemu</literal>,
|
||||
<literal>kvm</literal>,
|
||||
<literal>zvm</literal>,
|
||||
<literal>vmware</literal>,
|
||||
<literal>microsoft</literal>,
|
||||
<literal>oracle</literal>,
|
||||
<literal>xen</literal>,
|
||||
<literal>bochs</literal>,
|
||||
<literal>uml</literal>,
|
||||
<literal>bhyve</literal>,
|
||||
<literal>qnx</literal>,
|
||||
<literal>openvz</literal>,
|
||||
<literal>lxc</literal>,
|
||||
<literal>lxc-libvirt</literal>,
|
||||
<literal>systemd-nspawn</literal>,
|
||||
<literal>docker</literal>,
|
||||
<literal>podman</literal>,
|
||||
<literal>rkt</literal>,
|
||||
<literal>wsl</literal>,
|
||||
<literal>acrn</literal> to test
|
||||
against a specific implementation, or
|
||||
<literal>private-users</literal> to check whether we are running in a user namespace. See
|
||||
<citerefentry><refentrytitle>systemd-detect-virt</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
||||
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.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>ConditionHost=</varname></term>
|
||||
|
||||
<listitem><para><varname>ConditionHost=</varname> 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
|
||||
<citerefentry><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>, or
|
||||
a machine ID formatted as string (see
|
||||
<citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
|
||||
The test may be negated by prepending an exclamation mark.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>ConditionKernelCommandLine=</varname></term>
|
||||
|
||||
<listitem><para><varname>ConditionKernelCommandLine=</varname> 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
|
||||
<literal>=</literal>). 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.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>ConditionKernelVersion=</varname></term>
|
||||
|
||||
<listitem><para><varname>ConditionKernelVersion=</varname> may be used to check whether the kernel
|
||||
version (as reported by <command>uname -r</command>) 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 <literal><</literal>,
|
||||
<literal><=</literal>, <literal>=</literal>, <literal>!=</literal>, <literal>>=</literal>,
|
||||
<literal>></literal> a relative version comparison is done, otherwise the specified string is
|
||||
matched with shell-style globs.</para>
|
||||
|
||||
<para>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.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>ConditionSecurity=</varname></term>
|
||||
|
||||
<listitem><para><varname>ConditionSecurity=</varname> may be used to check whether the given
|
||||
security technology is enabled on the system. Currently, the recognized values are
|
||||
<literal>selinux</literal>, <literal>apparmor</literal>, <literal>tomoyo</literal>,
|
||||
<literal>ima</literal>, <literal>smack</literal>, <literal>audit</literal> and
|
||||
<literal>uefi-secureboot</literal>. The test may be negated by prepending an exclamation
|
||||
mark.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>ConditionCapability=</varname></term>
|
||||
|
||||
<listitem><para>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
|
||||
<citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
|
||||
for details). Pass a capability name such as <literal>CAP_MKNOD</literal>, possibly prefixed with
|
||||
an exclamation mark to negate the check.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>ConditionACPower=</varname></term>
|
||||
|
||||
<listitem><para>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 <literal>true</literal>,
|
||||
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 <literal>false</literal>, the
|
||||
condition will hold only if there is at least one AC connector known and all AC connectors are
|
||||
disconnected from a power source.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>ConditionNeedsUpdate=</varname></term>
|
||||
|
||||
<listitem><para>Takes one of <filename>/var</filename> or <filename>/etc</filename> as argument,
|
||||
possibly prefixed with a <literal>!</literal> (to inverting the condition). This condition may be
|
||||
used to conditionalize units on whether the specified directory requires an update because
|
||||
<filename>/usr</filename>'s modification time is newer than the stamp file
|
||||
<filename>.updated</filename> in the specified directory. This is useful to implement offline
|
||||
updates of the vendor operating system resources in <filename>/usr</filename> that require updating
|
||||
of <filename>/etc</filename> or <filename>/var</filename> on the next following boot. Units making
|
||||
use of this condition should order themselves before
|
||||
<citerefentry><refentrytitle>systemd-update-done.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
|
||||
to make sure they run before the stamp file's modification time gets reset indicating a completed
|
||||
update.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>ConditionFirstBoot=</varname></term>
|
||||
|
||||
<listitem><para>Takes a boolean argument. This condition may be used to conditionalize units on
|
||||
whether the system is booting up with an unpopulated <filename>/etc</filename> directory
|
||||
(specifically: an <filename>/etc</filename> with no <filename>/etc/machine-id</filename>). This may
|
||||
be used to populate <filename>/etc</filename> on the first boot after factory reset, or when a new
|
||||
system instance boots up for the first time.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>ConditionPathExists=</varname></term>
|
||||
|
||||
<listitem><para>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
|
||||
<varname>ConditionPathExists=</varname> is prefixed with an exclamation mark
|
||||
(<literal>!</literal>), the test is negated, and the unit is only started if the path does not
|
||||
exist.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>ConditionPathExistsGlob=</varname></term>
|
||||
|
||||
<listitem><para><varname>ConditionPathExistsGlob=</varname> is similar to
|
||||
<varname>ConditionPathExists=</varname>, but checks for the existence of at least one file or
|
||||
directory matching the specified globbing pattern.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>ConditionPathIsDirectory=</varname></term>
|
||||
|
||||
<listitem><para><varname>ConditionPathIsDirectory=</varname> is similar to
|
||||
<varname>ConditionPathExists=</varname> but verifies that a certain path exists and is a
|
||||
directory.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>ConditionPathIsSymbolicLink=</varname></term>
|
||||
|
||||
<listitem><para><varname>ConditionPathIsSymbolicLink=</varname> is similar to
|
||||
<varname>ConditionPathExists=</varname> but verifies that a certain path exists and is a symbolic
|
||||
link.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>ConditionPathIsMountPoint=</varname></term>
|
||||
|
||||
<listitem><para><varname>ConditionPathIsMountPoint=</varname> is similar to
|
||||
<varname>ConditionPathExists=</varname> but verifies that a certain path exists and is a mount
|
||||
point.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>ConditionPathIsReadWrite=</varname></term>
|
||||
|
||||
<listitem><para><varname>ConditionPathIsReadWrite=</varname> is similar to
|
||||
<varname>ConditionPathExists=</varname> but verifies that the underlying file system is readable
|
||||
and writable (i.e. not mounted read-only).</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>ConditionDirectoryNotEmpty=</varname></term>
|
||||
|
||||
<listitem><para><varname>ConditionDirectoryNotEmpty=</varname> is similar to
|
||||
<varname>ConditionPathExists=</varname> but verifies that a certain path exists and is a non-empty
|
||||
directory.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>ConditionFileNotEmpty=</varname></term>
|
||||
|
||||
<listitem><para><varname>ConditionFileNotEmpty=</varname> is similar to
|
||||
<varname>ConditionPathExists=</varname> but verifies that a certain path exists and refers to a
|
||||
regular file with a non-zero size.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>ConditionFileIsExecutable=</varname></term>
|
||||
|
||||
<listitem><para><varname>ConditionFileIsExecutable=</varname> is similar to
|
||||
<varname>ConditionPathExists=</varname> but verifies that a certain path exists, is a regular file,
|
||||
and marked executable.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>ConditionUser=</varname></term>
|
||||
|
||||
<listitem><para><varname>ConditionUser=</varname> takes a numeric <literal>UID</literal>, a UNIX
|
||||
user name, or the special value <literal>@system</literal>. This condition may be used to check
|
||||
whether the service manager is running as the given user. The special value
|
||||
<literal>@system</literal> 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.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>ConditionGroup=</varname></term>
|
||||
|
||||
<listitem><para><varname>ConditionGroup=</varname> is similar to <varname>ConditionUser=</varname>
|
||||
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
|
||||
<literal>@system</literal>.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>ConditionControlGroupController=</varname></term>
|
||||
|
||||
<listitem><para>Verify that the given cgroup controller (eg. <literal>cpu</literal>) 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 <varname>cgroup_disable=controller</varname>. 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 <literal>cpu</literal>, <literal>cpuacct</literal>, <literal>io</literal>,
|
||||
<literal>blkio</literal>, <literal>memory</literal>, <literal>devices</literal>, and
|
||||
<literal>pids</literal>.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>ConditionMemory=</varname></term>
|
||||
|
||||
<listitem><para>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
|
||||
<literal><</literal>, <literal><=</literal>, <literal>=</literal>, <literal>!=</literal>,
|
||||
<literal>>=</literal>, <literal>></literal>. 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.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>ConditionCPUs=</varname></term>
|
||||
|
||||
<listitem><para>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
|
||||
<literal><</literal>, <literal><=</literal>, <literal>=</literal>, <literal>!=</literal>,
|
||||
<literal>>=</literal>, <literal>></literal>. 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.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>AssertArchitecture=</varname></term>
|
||||
<term><varname>AssertVirtualization=</varname></term>
|
||||
<term><varname>AssertHost=</varname></term>
|
||||
<term><varname>AssertKernelCommandLine=</varname></term>
|
||||
<term><varname>AssertKernelVersion=</varname></term>
|
||||
<term><varname>AssertSecurity=</varname></term>
|
||||
<term><varname>AssertCapability=</varname></term>
|
||||
<term><varname>AssertACPower=</varname></term>
|
||||
<term><varname>AssertNeedsUpdate=</varname></term>
|
||||
<term><varname>AssertFirstBoot=</varname></term>
|
||||
<term><varname>AssertPathExists=</varname></term>
|
||||
<term><varname>AssertPathExistsGlob=</varname></term>
|
||||
<term><varname>AssertPathIsDirectory=</varname></term>
|
||||
<term><varname>AssertPathIsSymbolicLink=</varname></term>
|
||||
<term><varname>AssertPathIsMountPoint=</varname></term>
|
||||
<term><varname>AssertPathIsReadWrite=</varname></term>
|
||||
<term><varname>AssertDirectoryNotEmpty=</varname></term>
|
||||
<term><varname>AssertFileNotEmpty=</varname></term>
|
||||
<term><varname>AssertFileIsExecutable=</varname></term>
|
||||
<term><varname>AssertUser=</varname></term>
|
||||
<term><varname>AssertGroup=</varname></term>
|
||||
<term><varname>AssertControlGroupController=</varname></term>
|
||||
|
||||
<listitem><para>Similar to the <varname>ConditionArchitecture=</varname>,
|
||||
<varname>ConditionVirtualization=</varname>, …, 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
|
||||
<literal>failed</literal> 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.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</refsect2>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
Loading…
Reference in New Issue