HALF ECHO LEARN / REFERENCE COLLECTION

v262.2

man/systemd.unit.xml

165,445 bytesGit mode 100644Download original fileLGPL-2.1-or-later

Git blob: 54d24961893748d6aa56d22aa57bf37d61254735

Lines 1001–2000 of 2,862

        longer used. Note that, in order to minimize the work to be
        executed, systemd will not stop units by default unless they
        are conflicting with other units, or the user explicitly
        requested their shut down. If this option is set, a unit will
        be automatically cleaned up if no other active unit requires
        it. Defaults to <option>false</option>.</para>
 
        <xi:include href="version-info.xml" xpointer="v201"/></listitem>
      </varlistentry>
 
      <varlistentry>
        <term><varname>RefuseManualStart=</varname></term>
        <term><varname>RefuseManualStop=</varname></term>
 
        <listitem><para>Takes a boolean argument. If
        <option>true</option>, this unit can only be activated or
        deactivated indirectly. In this case, explicit start-up or
        termination requested by the user is denied, however if it is
        started or stopped as a dependency of another unit, start-up
        or termination will succeed. This is mostly a safety feature
        to ensure that the user does not accidentally activate units
        that are not intended to be activated explicitly, and not
        accidentally deactivate units that are not intended to be
        deactivated. These options default to
        <option>false</option>.</para>
 
        <xi:include href="version-info.xml" xpointer="v201"/></listitem>
      </varlistentry>
 
      <varlistentry>
        <term><varname>AllowIsolate=</varname></term>
 
        <listitem><para>Takes a boolean argument. If
        <option>true</option>, this unit may be used with the
        <command>systemctl isolate</command> command. Otherwise, this
        will be refused. It probably is a good idea to leave this
        disabled except for target units that shall be used similar to
        runlevels in SysV init systems, just as a precaution to avoid
        unusable system states. This option defaults to
        <option>false</option>.</para>
 
        <xi:include href="version-info.xml" xpointer="v201"/></listitem>
      </varlistentry>
 
      <varlistentry>
        <term><varname>DefaultDependencies=</varname></term>
 
        <listitem><para>Takes a boolean argument. If
        <option>yes</option>, (the default), a few default
        dependencies will implicitly be created for the unit. The
        actual dependencies created depend on the unit type. For
        example, for service units, these dependencies ensure that the
        service is started only after basic system initialization is
        completed and is properly terminated on system shutdown. See
        the respective man pages for details. Generally, only services
        involved with early boot or late shutdown should set this
        option to <option>no</option>. It is highly recommended to
        leave this option enabled for the majority of common units. If
        set to <option>no</option>, this option does not disable
        all implicit dependencies, just non-essential
        ones.</para>
 
        <xi:include href="version-info.xml" xpointer="v201"/></listitem>
      </varlistentry>
 
      <varlistentry>
        <term><varname>SurviveFinalKillSignal=</varname></term>
 
        <listitem><para>Takes a boolean argument. Defaults to <option>no</option>. If <option>yes</option>,
        processes belonging to this unit will not be sent the final <literal>SIGTERM</literal> and
        <literal>SIGKILL</literal> signals during the final phase of the system shutdown process.
        This functionality replaces the older mechanism that allowed a program to set
        <literal>argv[0][0] = '@'</literal> as described at
        <ulink url="https://systemd.io/ROOT_STORAGE_DAEMONS">systemd and Storage Daemons for the Root File
        System</ulink>, which however continues to be supported.</para>
 
        <xi:include href="version-info.xml" xpointer="v255"/></listitem>
      </varlistentry>
 
      <varlistentry>
        <term><varname>CollectMode=</varname></term>
 
        <listitem><para>Tweaks the "garbage collection" algorithm for this unit. Takes one of <option>inactive</option>
        or <option>inactive-or-failed</option>. If set to <option>inactive</option> the unit will be unloaded if it is
        in the <constant>inactive</constant> state and is not referenced by clients, jobs or other units — however it
        is not unloaded if it is in the <constant>failed</constant> state. In <option>failed</option> mode, failed
        units are not unloaded until the user invoked <command>systemctl reset-failed</command> on them to reset the
        <constant>failed</constant> state, or an equivalent command. This behaviour is altered if this option is set to
        <option>inactive-or-failed</option>: in this case, the unit is unloaded even if the unit is in a
        <constant>failed</constant> state, and thus an explicitly resetting of the <constant>failed</constant> state is
        not necessary. Note that if this mode is used unit results (such as exit codes, exit signals, consumed
        resources, …) are flushed out immediately after the unit completed, except for what is stored in the logging
        subsystem. Defaults to <option>inactive</option>.</para>
 
        <para>Since v261, if <varname>FileDescriptorStorePreserve=</varname> is set to <option>yes</option>,
        and the unit has file descriptors stored, garbage collection will be disabled until the unit is
        removed, the service manager exits, or the file descriptors get <constant>EPOLLHUP</constant> or
        <constant>EPOLLERR</constant>.</para>
 
        <xi:include href="version-info.xml" xpointer="v236"/>
        </listitem>
      </varlistentry>
 
      <varlistentry>
        <term><varname>FailureAction=</varname></term>
        <term><varname>SuccessAction=</varname></term>
 
        <listitem><para>Configure the action to take when the unit stops and enters a failed state or
        inactive state.  Takes one of <option>none</option>, <option>reboot</option>,
        <option>reboot-force</option>, <option>reboot-immediate</option>, <option>poweroff</option>,
        <option>poweroff-force</option>, <option>poweroff-immediate</option>, <option>exit</option>,
        <option>exit-force</option>, <option>soft-reboot</option>, <option>soft-reboot-force</option>,
        <option>kexec</option>, <option>kexec-force</option>, <option>halt</option>,
        <option>halt-force</option> and <option>halt-immediate</option>. In system mode, all options are
        allowed. In user mode, only <option>none</option>, <option>exit</option>, and
        <option>exit-force</option> are allowed. Both options default to <option>none</option>.</para>
 
        <para>These actions are tied to the unit's state transitions and fire only when the unit actually
        transitions out of an <constant>active</constant> or <constant>activating</constant> state. As a
        consequence, <varname>Condition…=</varname> and <varname>Assert…=</varname> directives that fail do
        <emphasis>not</emphasis> trigger <varname>SuccessAction=</varname> or
        <varname>FailureAction=</varname>: they prevent activation in the first place, so no state transition
        occurs. By contrast, the <varname>ExecCondition=</varname> directive in
        <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
        runs as part of activation, so an <varname>ExecCondition=</varname> skip <emphasis>will</emphasis>
        trigger <varname>SuccessAction=</varname>.</para>
 
        <para>If <option>none</option> is set, no action will be triggered. <option>reboot</option> causes a
        reboot following the normal shutdown procedure (i.e. equivalent to <command>systemctl
        reboot</command>).  <option>reboot-force</option> causes a forced reboot which will terminate all
        processes forcibly but should cause no dirty file systems on reboot (i.e. equivalent to
        <command>systemctl reboot -f</command>) and <option>reboot-immediate</option> causes immediate
        execution of the
        <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> system
        call, which might result in data loss (i.e. equivalent to <command>systemctl reboot -ff</command>).
        Similarly, <option>poweroff</option>, <option>poweroff-force</option>,
        <option>poweroff-immediate</option>, <option>kexec</option>, <option>kexec-force</option>,
        <option>halt</option>, <option>halt-force</option> and <option>halt-immediate</option> have the
        effect of powering down the system, executing kexec, and halting the system respectively with similar
        semantics. <option>exit</option> causes the manager to exit following the normal shutdown procedure,
        and <option>exit-force</option> causes it terminate without shutting down services. When
        <option>exit</option> or <option>exit-force</option> is used by default the exit status of the main
        process of the unit (if this applies) is returned from the service manager. If there is no such
        status, <varname>FailureAction=</varname> returns 255 instead, while
        <varname>SuccessAction=</varname> leaves the exit status unchanged. However, this may be
        overridden with
        <varname>FailureActionExitStatus=</varname>/<varname>SuccessActionExitStatus=</varname>, see below.
        <option>soft-reboot</option> will trigger a userspace reboot operation.
        <option>soft-reboot-force</option> does that too, but does not go through the shutdown transaction
        beforehand.</para>
 
        <xi:include href="version-info.xml" xpointer="v236"/></listitem>
      </varlistentry>
 
      <varlistentry>
        <term><varname>FailureActionExitStatus=</varname></term>
        <term><varname>SuccessActionExitStatus=</varname></term>
 
        <listitem><para>Controls the exit status to propagate back to an invoking container manager (in case of a
        system service) or service manager (in case of a user manager) when the
        <varname>FailureAction=</varname>/<varname>SuccessAction=</varname> are set to <option>exit</option> or
        <option>exit-force</option> and the action is triggered. By default, the exit status of the main process of the
        triggering unit (if this applies) is propagated. Takes a value in the range 0…255 or the empty string to
        request default behaviour.</para>
 
        <xi:include href="version-info.xml" xpointer="v240"/></listitem>
      </varlistentry>
 
      <varlistentry>
        <term><varname>JobTimeoutSec=</varname></term>
        <term><varname>JobRunningTimeoutSec=</varname></term>
 
        <listitem><para><varname>JobTimeoutSec=</varname> specifies a timeout for the whole job that starts
        running when the job is queued. <varname>JobRunningTimeoutSec=</varname> specifies a timeout that
        starts running when the queued job is actually started. If either limit is reached, the job will be
        cancelled, the unit however will not change state or even enter the <literal>failed</literal> mode.
        </para>
 
        <para>Both settings take a time span with the default unit of seconds, but other units may be
        specified, see
        <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
        The default is <literal>infinity</literal> (job timeouts disabled), except for device units where
        <varname>JobRunningTimeoutSec=</varname> defaults to <varname>DefaultDeviceTimeoutSec=</varname>.
        </para>
 
        <para>Note: these timeouts are independent from any unit-specific timeouts (for example, the timeout
        set with <varname>TimeoutStartSec=</varname> in service units). The job timeout has no effect on the
        unit itself. Or in other words: unit-specific timeouts are useful to abort unit state changes, and
        revert them. The job timeout set with this option however is useful to abort only the job waiting for
        the unit state to change.</para>
 
        <xi:include href="version-info.xml" xpointer="v201"/>
        </listitem>
      </varlistentry>
 
      <varlistentry>
        <term><varname>JobTimeoutAction=</varname></term>
        <term><varname>JobTimeoutRebootArgument=</varname></term>
 
        <listitem><para><varname>JobTimeoutAction=</varname> optionally configures an additional action to
        take when the timeout is hit, see description of <varname>JobTimeoutSec=</varname> and
        <varname>JobRunningTimeoutSec=</varname> above. It takes the same values as
        <varname>FailureAction=</varname>/<varname>SuccessAction=</varname>. Defaults to
        <option>none</option>.</para>
 
        <para><varname>JobTimeoutRebootArgument=</varname> configures an optional reboot string to pass to
        the <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> system
        call.</para>
 
        <xi:include href="version-info.xml" xpointer="v240"/></listitem>
      </varlistentry>
 
      <varlistentry>
        <term><varname>StartLimitIntervalSec=<replaceable>interval</replaceable></varname></term>
        <term><varname>StartLimitBurst=<replaceable>burst</replaceable></varname></term>
 
        <listitem><para>Configure unit start rate limiting. Units which are started more than
        <replaceable>burst</replaceable> times within an <replaceable>interval</replaceable> time span are
        not permitted to start any more. Use <varname>StartLimitIntervalSec=</varname> to configure the
        checking interval and <varname>StartLimitBurst=</varname> to configure how many starts per interval
        are allowed.</para>
 
        <para><replaceable>interval</replaceable> is a time span with the default unit of seconds, but other
        units may be specified, see
        <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
        The special value <literal>infinity</literal> can be used to limit the total number of start
        attempts, even if they happen at large time intervals.
        Defaults to <varname>DefaultStartLimitIntervalSec=</varname> in manager configuration file, and may
        be set to 0 to disable any kind of rate limiting. <replaceable>burst</replaceable> is a number and
        defaults to <varname>DefaultStartLimitBurst=</varname> in manager configuration file.</para>
 
        <para>These configuration options are particularly useful in conjunction with the service setting
        <varname>Restart=</varname> (see
        <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>);
        however, they apply to all kinds of starts (including manual), not just those triggered by the
        <varname>Restart=</varname> logic.</para>
 
        <para>Note that units which are configured for <varname>Restart=</varname>, and which reach the start
        limit are not attempted to be restarted anymore; however, they may still be restarted manually or
        from a timer or socket at a later point, after the <replaceable>interval</replaceable> has passed.
        From that point on, the restart logic is activated again. <command>systemctl reset-failed</command>
        will cause the restart rate counter for a service to be flushed, which is useful if the administrator
        wants to manually start a unit and the start limit interferes with that. Rate-limiting is enforced
        after any unit condition checks are executed, and hence unit activations with failing conditions do
        not count towards the rate limit.</para>
 
        <para>When a unit is unloaded due to the garbage collection logic (see above) its rate limit counters
        are flushed out too. This means that configuring start rate limiting for a unit that is not
        referenced continuously has no effect.</para>
 
        <para>This setting does not apply to slice, target, device, and scope units, since they are unit
        types whose activation may either never fail, or may succeed only a single time.</para>
 
        <xi:include href="version-info.xml" xpointer="v229"/></listitem>
      </varlistentry>
 
      <varlistentry>
        <term><varname>StartLimitAction=</varname></term>
 
        <listitem><para>Configure an additional action to take if the rate limit configured with
        <varname>StartLimitIntervalSec=</varname> and <varname>StartLimitBurst=</varname> is hit. Takes the same
        values as the <varname>FailureAction=</varname>/<varname>SuccessAction=</varname> settings. If
        <option>none</option> is set, hitting the rate limit will trigger no action except that
        the start will not be permitted. Defaults to <option>none</option>.</para>
 
        <xi:include href="version-info.xml" xpointer="v229"/></listitem>
      </varlistentry>
 
      <varlistentry>
        <term><varname>RebootArgument=</varname></term>
        <listitem><para>Configure the optional argument for the
        <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> system call if
        <varname>StartLimitAction=</varname> or <varname>FailureAction=</varname> is a reboot action. This
        works just like the optional argument to <command>systemctl reboot</command> command.</para>
 
        <xi:include href="version-info.xml" xpointer="v229"/></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>
 
        <xi:include href="version-info.xml" xpointer="v201"/></listitem>
      </varlistentry>
    </variablelist>
 
    <refsect2>
      <title>Conditions and Asserts</title>
 
      <para>Unit files may also include a number of <varname index="false">Condition…=</varname> and <varname
      index="false">Assert…=</varname> settings. Before the unit is started, systemd will verify that the
      specified conditions and asserts are true. If not, the starting of the unit will be (mostly silently)
      skipped (in case of conditions), or aborted with an error message (in case of asserts). Failing
      conditions or asserts will not result in the unit being moved into the <literal>failed</literal>
      state. The conditions and asserts 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, and the conditions and asserts are executed the precise moment the
      unit would normally start and thus can validate system state after the units ordered before completed
      initialization. Use condition expressions for skipping units that do not apply to the local system, for
      example because the kernel or runtime environment does not 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 to become a
      <emphasis>triggering</emphasis> condition. If at least one triggering condition is defined for a unit,
      then the unit will be started if at least one of the triggering conditions of the unit applies and all
      of the regular (i.e. non-triggering) conditions apply. 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
      are similar to conditions but cause the start job to fail (instead of being skipped). The failed check
      is logged. Units with unmet 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'>
        <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>Use
          <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>
          for the complete list of known architectures.</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>
 
          <xi:include href="version-info.xml" xpointer="v201"/>
          </listitem>
        </varlistentry>
 
        <varlistentry>
          <term><varname>ConditionFirmware=</varname></term>
 
          <listitem><para>Check whether the system's firmware is of a certain type. The following values are
          possible:</para>
 
          <itemizedlist>
            <listitem><para><literal>uefi</literal> matches systems with EFI.</para></listitem>
 
            <listitem><para><literal>device-tree</literal> matches systems with a device tree.
            </para></listitem>
 
            <listitem><para><literal>device-tree-compatible(<replaceable>value</replaceable>)</literal>
            matches systems with a device tree that are compatible with <literal>value</literal>.
            </para></listitem>
 
            <listitem><para><literal>smbios-field(<replaceable>field</replaceable>
            <replaceable>operator</replaceable> <replaceable>value</replaceable>)</literal> matches systems
            with a SMBIOS field containing a certain value. <replaceable>field</replaceable> is the name of
            the SMBIOS field exposed as <literal>sysfs</literal> attribute file below
            <filename>/sys/class/dmi/id/</filename>. <replaceable>operator</replaceable> is one of
            <literal>&lt;</literal>, <literal>&lt;=</literal>, <literal>&gt;=</literal>,
            <literal>&gt;</literal>, <literal>==</literal>, <literal>&lt;&gt;</literal> for version
            comparisons, <literal>=</literal> and <literal>!=</literal> for literal string comparisons, or
            <literal>$=</literal>, <literal>!$=</literal> for shell-style glob comparisons.
            <replaceable>value</replaceable> is the expected value of the SMBIOS field value (possibly
            containing shell style globs in case <literal>$=</literal>/<literal>!$=</literal> is used).
            </para></listitem>
          </itemizedlist>
 
            <xi:include href="version-info.xml" xpointer="v249"/></listitem>
        </varlistentry>
 
        <varlistentry>
          <term><varname>ConditionVirtualization=</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>amazon</literal>,
          <literal>zvm</literal>,
          <literal>vmware</literal>,
          <literal>microsoft</literal>,
          <literal>oracle</literal>,
          <literal>powervm</literal>,
          <literal>xen</literal>,
          <literal>bochs</literal>,
          <literal>uml</literal>,
          <literal>bhyve</literal>,
          <literal>qnx</literal>,
          <literal>apple</literal>,
          <literal>sre</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>proot</literal>,
          <literal>pouch</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>
 
          <xi:include href="version-info.xml" xpointer="v244"/>
          </listitem>
        </varlistentry>
 
        <varlistentry>
          <term><varname>ConditionHost=</varname></term>
 
          <listitem><para><varname>ConditionHost=</varname> may be used to match against the hostname,
          machine ID, boot ID or product UUID 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 128bit ID or UUID, formatted as string. The latter is compared against machine ID, boot ID and the
          firmware product UUID if there is any. See
          <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
          details about the machine ID. The test may be negated by prepending an exclamation mark.</para>
 
          <xi:include href="version-info.xml" xpointer="v244"/>
          </listitem>
        </varlistentry>
 
        <varlistentry>
          <term><varname>ConditionFraction=</varname></term>
 
          <listitem><para><varname>ConditionFraction=</varname> may be used to enable a unit on a stable,
          pseudo-random subset of a fleet of machines. It is primarily useful for staged rollouts: the same
          unit (or drop-in) is distributed to every machine in a fleet, but only the configured fraction of
          them will actually have it enabled. The decision is derived locally from the machine ID (see
          <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>), so
          it requires no central coordination and is stable over time: a given machine always lands on the
          same side of the threshold.</para>
 
          <para>The argument consists of an optional <replaceable>tag</replaceable> followed by a percentage,
          separated by whitespace, for example <literal>30%</literal> or
          <literal>myrollout 30%</literal>. The percentage may include up to two decimal places (e.g.
          <literal>0.5%</literal>). The condition is satisfied on approximately the configured percentage of
          all machines; <literal>0%</literal> matches no machine and <literal>100%</literal> matches every
          machine.</para>
 
          <para>The optional tag is an arbitrary string (not containing whitespace) that is mixed into the
          derivation, so that independent rollouts select <emphasis>independent</emphasis> subsets of the
          fleet. Without it, all untagged <varname>ConditionFraction=</varname> checks would select the very
          same machines (the same machines would always be picked first). Use distinct tags for unrelated
          rollouts, and a shared tag to deliberately target the same machines across several units.</para>
 
          <para>The test may be negated by prepending an exclamation mark, in which case it is satisfied on the
          complementary fraction of machines (e.g. <literal>!myrollout 30%</literal> matches the other ≈70%).
          If the machine ID cannot be determined, the condition fails.</para>
 
          <xi:include href="version-info.xml" xpointer="v261"/>
          </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. This operates on the kernel command line
          communicated to userspace via <filename>/proc/cmdline</filename>, except when the service manager
          is invoked as payload of a container manager, in which case the command line of <filename>PID
          1</filename> is used instead (i.e. <filename>/proc/1/cmdline</filename>).</para>
 
          <xi:include href="version-info.xml" xpointer="v244"/>
          </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. The argument must be a list of (potentially quoted)
          expressions. Each expression starts with one of <literal>=</literal> or <literal>!=</literal> for
          string comparisons, <literal>&lt;</literal>, <literal>&lt;=</literal>, <literal>==</literal>,
          <literal>&lt;&gt;</literal>, <literal>&gt;=</literal>, <literal>&gt;</literal> for version
          comparisons, or <literal>$=</literal>, <literal>!$=</literal> for a shell-style glob match. If no
          operator is specified, <literal>$=</literal> is implied.</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>
 
          <xi:include href="version-info.xml" xpointer="v244"/>
          </listitem>
        </varlistentry>
 
        <varlistentry>
          <term><varname>ConditionVersion=</varname></term>
 
          <listitem><para><varname>ConditionVersion=</varname> may be used to check whether a software
          version matches a certain expression, or if prefixed with the exclamation mark, does not match.
          The first argument is the software whose version has to be checked. Currently
          <literal>kernel</literal>, <literal>systemd</literal> and <literal>glibc</literal> are supported.
          If this argument is omitted, <literal>kernel</literal> is implied. The second argument must be a
          list of (potentially quoted) expressions. Each expression starts with one of <literal>=</literal>
          or <literal>!=</literal> for string comparisons, <literal>&lt;</literal>, <literal>&lt;=</literal>,
          <literal>==</literal>, <literal>&lt;&gt;</literal>, <literal>&gt;=</literal>,
          <literal>&gt;</literal> for version comparisons, or <literal>$=</literal>, <literal>!$=</literal>
          for a shell-style glob match. If no operator is specified, <literal>$=</literal> is implied.</para>
 
          <xi:include href="version-info.xml" xpointer="v258"/>
          </listitem>
        </varlistentry>
 
        <varlistentry>
          <term><varname>ConditionCredential=</varname></term>
 
          <listitem><para><varname>ConditionCredential=</varname> may be used to check whether a credential
          by the specified name was passed into the service manager. See <ulink
          url="https://systemd.io/CREDENTIALS">System and Service Credentials</ulink> for details about
          credentials. If used in services for the system service manager this may be used to conditionalize
          services based on system credentials passed in. If used in services for the per-user service
          manager this may be used to conditionalize services based on credentials passed into the
          <filename>unit@.service</filename> service instance belonging to the user. The argument must be a
          valid credential name.</para>
 
          <xi:include href="version-info.xml" xpointer="v252"/></listitem>
        </varlistentry>
 
        <varlistentry>
          <term><varname>ConditionEnvironment=</varname></term>
 
          <listitem><para><varname>ConditionEnvironment=</varname> may be used to check whether a specific
          environment variable is set (or if prefixed with the exclamation mark — unset) in the service
          manager's environment block.
 
          The argument may be a single word, to check if the variable with this name is defined in the
          environment block, or an assignment
          (<literal><replaceable>name</replaceable>=<replaceable>value</replaceable></literal>), to check if
          the variable with this exact value is defined. Note that the environment block of the service
          manager itself is checked, i.e. not any variables defined with <varname>Environment=</varname> or
          <varname>EnvironmentFile=</varname>, as described above. This is particularly useful when the
          service manager runs inside a containerized environment or as per-user service manager, in order to
          check for variables passed in by the enclosing container manager or PAM.</para>
 
          <xi:include href="version-info.xml" xpointer="v246"/>
          </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 following values are recognized:</para>
 
          <table>
            <title>Recognized security technologies</title>
 
            <tgroup cols='2'>
              <colspec colname='value'/>
              <colspec colname='description'/>
 
              <thead>
                <row>
                  <entry>Value</entry>
                  <entry>Description</entry>
                </row>
              </thead>
              <tbody>
                <row>
                  <entry>selinux</entry>
                  <entry>SELinux MAC</entry>
                </row>
                <row>
                  <entry>apparmor</entry>
                  <entry>AppArmor MAC</entry>
                </row>
                <row>
                  <entry>tomoyo</entry>
                  <entry>Tomoyo MAC</entry>
                </row>
                <row>
                  <entry>smack</entry>
                  <entry>SMACK MAC</entry>
                </row>
                <row>
                  <entry>ima</entry>
                  <entry>Integrity Measurement Architecture (IMA)</entry>
                </row>
                <row>
                  <entry>audit</entry>
                  <entry>Linux Audit Framework</entry>
                </row>
                <row>
                  <entry>uefi-secureboot</entry>
                  <entry>UEFI SecureBoot</entry>
                </row>
                <row>
                  <entry>tpm2</entry>
                  <entry>Trusted Platform Module 2.0 (TPM2) (with full UEFI support, including the TCG PC Client
                  Platform Firmware Profile)</entry>
                </row>
                <row>
                  <entry>cvm</entry>
                  <entry>Confidential virtual machine (SEV/TDX)</entry>
                </row>
                <row>
                  <entry>measured-uki</entry>
                  <entry>Unified Kernel Image with PCR 11 Measurements, as per <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry>. <xi:include href="version-info.xml" xpointer="v255"/></entry>
                </row>
                <row>
                  <entry>measured-os</entry>
                  <entry>OS PCR measurements enabled. This is typically equivalent to <varname>measured-uki</varname>, however may also be set explicitly via the <varname>systemd.tpm2_measured_os=</varname> kernel command line switch, see <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details. The various system services doing boot and runtime measurements are conditioned on this flag. <xi:include href="version-info.xml" xpointer="v261"/></entry>
                </row>
              </tbody>
            </tgroup>
          </table>
 
          <para>The test may be negated by prepending an exclamation mark.</para>
 
          <xi:include href="version-info.xml" xpointer="v244"/>
          </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>
 
          <xi:include href="version-info.xml" xpointer="v244"/>
          </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>
 
          <xi:include href="version-info.xml" xpointer="v244"/>
          </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 invert 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>If the <varname>systemd.condition_needs_update=</varname> option is specified on the kernel
          command line (taking a boolean), it will override the result of this condition check, taking
          precedence over any file modification time checks. If the kernel command line option is used,
          <filename>systemd-update-done.service</filename> will not have immediate effect on any following
          <varname>ConditionNeedsUpdate=</varname> checks, until the system is rebooted where the kernel
          command line option is not specified anymore.</para>
 
          <para>Note that to make this scheme effective, the timestamp of <filename>/usr/</filename> should
          be explicitly updated after its contents are modified. The kernel will automatically update
          modification timestamp on a directory only when immediate children of a directory are modified; an
          modification of nested files will not automatically result in mtime of <filename>/usr/</filename>
          being updated.</para>
 
          <para>Also note that if the update method includes a call to execute appropriate post-update steps
          itself, it should not touch the timestamp of <filename>/usr/</filename>. In a typical distribution
          packaging scheme, packages will do any required update steps as part of the installation or
          upgrade, to make package contents immediately usable. <varname>ConditionNeedsUpdate=</varname>
          should be used with other update mechanisms where such an immediate update does not
          happen.</para>
 
          <xi:include href="version-info.xml" xpointer="v244"/></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 for the first time. This roughly means that <filename>/etc/</filename>
          was unpopulated when the system started booting (for details, see "First Boot Semantics" in
          <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
          First Boot is considered finished (this condition will evaluate as false) after the manager
          has finished the startup phase.</para>
 
          <para>This condition 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>Note that the service manager itself will perform setup steps during First Boot: it will
          initialize
          <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> and
          preset all units, enabling or disabling them according to the
          <citerefentry><refentrytitle>systemd.preset</refentrytitle><manvolnum>5</manvolnum></citerefentry>
          settings. Additional setup may be performed via units with
          <varname>ConditionFirstBoot=yes</varname>.</para>
 
          <para>For robustness, units with <varname>ConditionFirstBoot=yes</varname> should order themselves
          before <filename>first-boot-complete.target</filename> and pull in this passive target with
          <varname>Wants=</varname>. This ensures that in a case of an aborted first boot, these units will
          be re-run during the next system startup.</para>
 
          <para>If the <varname>systemd.condition_first_boot=</varname> option is specified on the kernel
          command line (taking a boolean), it will override the result of this condition check, taking
          precedence over <filename>/etc/machine-id</filename> existence checks.</para>
 
          <xi:include href="version-info.xml" xpointer="v244"/>
          </listitem>
        </varlistentry>
 
        <varlistentry>
          <term><varname>ConditionPathExists=</varname></term>
 
          <listitem><para>Check for the existence of a path. This applies to any file system object (such as a
          regular file, directory, device node, FIFO, or socket), not only regular files. Symbolic links
          are followed, so a broken symbolic link is not considered to exist. 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>
 
          <xi:include href="version-info.xml" xpointer="v244"/>
          </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>
 
          <xi:include href="version-info.xml" xpointer="v244"/>
          </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>
 
          <xi:include href="version-info.xml" xpointer="v244"/>
          </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>
 
          <xi:include href="version-info.xml" xpointer="v244"/>
          </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>
 
          <xi:include href="version-info.xml" xpointer="v244"/>
          </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>
 
          <xi:include href="version-info.xml" xpointer="v244"/>
          </listitem>
        </varlistentry>
 
        <varlistentry>
          <term><varname>ConditionPathIsEncrypted=</varname></term>
 
          <listitem><para><varname>ConditionPathIsEncrypted=</varname> is similar to
          <varname>ConditionPathExists=</varname> but verifies that the underlying file system's backing
          block device is encrypted using dm-crypt/LUKS. Note that this check does not cover ext4
          per-directory encryption, and only detects block level encryption. Moreover, if the specified path
          resides on a file system on top of a loopback block device, only encryption above the loopback device is
          detected. It is not detected whether the file system backing the loopback block device is encrypted.</para>
 
          <xi:include href="version-info.xml" xpointer="v246"/>
          </listitem>
        </varlistentry>
 
        <varlistentry>
          <term><varname>ConditionPathIsSocket=</varname></term>
 
          <listitem><para><varname>ConditionPathIsSocket=</varname> is similar to
          <varname>ConditionPathExists=</varname> but verifies that a certain path exists and is a
          socket.</para>
 
          <xi:include href="version-info.xml" xpointer="v260"/>
          </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>
 
          <xi:include href="version-info.xml" xpointer="v244"/>
          </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>
 
          <xi:include href="version-info.xml" xpointer="v244"/>
          </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>
 
          <xi:include href="version-info.xml" xpointer="v244"/>
          </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>
 
          <xi:include href="version-info.xml" xpointer="v244"/>
          </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>
 
          <xi:include href="version-info.xml" xpointer="v244"/>
          </listitem>
        </varlistentry>
 
        <varlistentry>
          <term><varname>ConditionControlGroupController=</varname></term>
 
          <listitem><para>Check whether given cgroup controllers (e.g. <literal>cpu</literal>) are available
          for use on the system or whether the legacy v1 cgroup or the modern v2 cgroup hierarchy is used.
          </para>
 
          <para>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>io</literal>,
          <literal>memory</literal>, and <literal>pids</literal>. Even if available in the kernel, a
          particular controller may not be available if it was disabled on the kernel command line with
          <varname>cgroup_disable=controller</varname>.</para>
 
          <para>Alternatively, two special strings <literal>v1</literal> and <literal>v2</literal> may be
          specified (without any controller names). <literal>v2</literal> will pass if the unified v2 cgroup
          hierarchy is used, and <literal>v1</literal> will pass if the legacy v1 hierarchy or the hybrid
          hierarchy are used. Note that legacy or hybrid hierarchies have been deprecated. See
          <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
          more information.</para>
 
          <xi:include href="version-info.xml" xpointer="v244"/>
          </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> (or <literal>==</literal>),
          <literal>!=</literal> (or <literal>&lt;&gt;</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>
 
          <xi:include href="version-info.xml" xpointer="v244"/>
          </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> (or <literal>==</literal>),
          <literal>!=</literal> (or <literal>&lt;&gt;</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>
 
          <xi:include href="version-info.xml" xpointer="v244"/></listitem>
        </varlistentry>
 
        <varlistentry>
          <term><varname>ConditionCPUFeature=</varname></term>
 
          <listitem><para>On i386 and x86-64, verify that a given CPU feature is available via the
          <literal>CPUID</literal> instruction. It checks the leaves <literal>1</literal>,
          <literal>7</literal>, <literal>0x80000001</literal>, and <literal>0x80000007</literal>. Valid
          values are:
          <literal>fpu</literal>,
          <literal>vme</literal>,