1
0
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 2019-10-29 14:52:27 +01:00
parent c82a2b5b84
commit 337b733449

View File

@ -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
@ -1000,61 +998,63 @@
</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>
<term><varname>SourcePath=</varname></term>
<listitem><para>A path to a configuration file this unit has
been generated from. This is primarily useful for
implementation of generator tools that convert configuration
from an external configuration file format into native unit
files. This functionality should not be used in normal
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. -->
<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>
<varlistentry>
<term><varname>ConditionArchitecture=</varname></term>
<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
<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>,
@ -1083,26 +1083,28 @@
<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
<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>
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>
<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
<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>container</literal> to test against a generic type of virtualization solution, or one of
<literal>qemu</literal>,
<literal>kvm</literal>,
<literal>zvm</literal>,
@ -1126,189 +1128,263 @@
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>
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>
<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
<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>
The test may be negated by prepending an exclamation mark.</para>
</listitem>
</varlistentry>
<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>
<varlistentry>
<term><varname>ConditionKernelCommandLine=</varname></term>
<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>&lt;</literal>,
<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>&lt;</literal>,
<literal>&lt;=</literal>, <literal>=</literal>, <literal>!=</literal>, <literal>&gt;=</literal>,
<literal>&gt;</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>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>
<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>
<varlistentry>
<term><varname>ConditionSecurity=</varname></term>
<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
<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>
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>
<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>
<varlistentry>
<term><varname>ConditionACPower=</varname></term>
<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
<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>
to make sure they run before the stamp file's modification time gets reset indicating a completed
update.</para>
</listitem>
</varlistentry>
<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>
<varlistentry>
<term><varname>ConditionFirstBoot=</varname></term>
<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
<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>
<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>
<varlistentry>
<term><varname>ConditionPathExistsGlob=</varname></term>
<para><varname>ConditionPathIsDirectory=</varname> is similar
to <varname>ConditionPathExists=</varname> but verifies
whether a certain path exists and is a directory.</para>
<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>
<para><varname>ConditionPathIsSymbolicLink=</varname> is
similar to <varname>ConditionPathExists=</varname> but
verifies whether a certain path exists and is a symbolic
link.</para>
<varlistentry>
<term><varname>ConditionPathIsDirectory=</varname></term>
<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
<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>
<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>
<varlistentry>
<term><varname>ConditionPathIsSymbolicLink=</varname></term>
<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>
<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>
<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>
<varlistentry>
<term><varname>ConditionPathIsMountPoint=</varname></term>
<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>
<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>
<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>
<varlistentry>
<term><varname>ConditionPathIsReadWrite=</varname></term>
<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>&lt;</literal>, <literal>&lt;=</literal>, <literal>=</literal>,
<literal>!=</literal>, <literal>&gt;=</literal>, <literal>&gt;</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><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>
<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
<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>&lt;</literal>, <literal>&lt;=</literal>, <literal>=</literal>, <literal>!=</literal>,
<literal>&gt;=</literal>, <literal>&gt;</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
<literal>&gt;=</literal>, <literal>&gt;</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>&lt;</literal>, <literal>&lt;=</literal>, <literal>=</literal>, <literal>!=</literal>,
<literal>&gt;=</literal>, <literal>&gt;</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>
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>
@ -1336,34 +1412,18 @@
<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
been generated from. This is primarily useful for
implementation of generator tools that convert configuration
from an external configuration file format into native unit
files. This functionality should not be used in normal
units.</para></listitem>
<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>