Merge pull request #13867 from keszybz/man-condition

Refactor description of conditons

1 files changed, 417 insertions, 357 deletions

diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index b3025ea09b..5acb5951cd 100644
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -516,7 +516,6 @@
     type of unit:</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,361 +998,6 @@
       </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>&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><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>&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>
-
-        <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>&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>
-      </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
         been generated from. This is primarily useful for
@@ -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>&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>
+          </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>&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>
+        </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>
+        </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>