mirror of
https://github.com/systemd/systemd.git
synced 2024-12-23 21:35:11 +03:00
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 <termitem>. This rearragnes the text into a new subsection, with minimal grammar changes and removal of repetitions.
This commit is contained in:
Zbigniew Jędrzejewski-Szmek
parent
c82a2b5b84
commit
337b733449
@ -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 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. 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>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user