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
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
</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
been generated from. This is primarily useful for
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>
projects / platform / upstream / systemd.git / commitdiff