<?xml version='1.0'?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY % entities SYSTEM "custom-entities.ent" >
%entities;
]>
-
-<!--
- SPDX-License-Identifier: LGPL-2.1+
--->
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
<refentry id="systemd.unit">
</row>
<row>
<entry><filename>/etc/systemd/system</filename></entry>
- <entry>Local configuration</entry>
+ <entry>System units created by the administrator</entry>
</row>
<row>
<entry><filename>/run/systemd/system</filename></entry>
</row>
<row>
<entry><filename>/usr/local/lib/systemd/system</filename></entry>
- <entry morerows="1">Units of installed packages</entry>
+ <entry>System units installed by the administrator </entry>
</row>
<row>
<entry><filename>/usr/lib/systemd/system</filename></entry>
+ <entry>System units installed by the distribution package manager</entry>
</row>
<row>
<entry><filename>/run/systemd/generator.late</filename></entry>
</row>
<row>
<entry><filename>/etc/systemd/user</filename></entry>
- <entry>Local configuration</entry>
+ <entry>User units created by the administrator</entry>
</row>
<row>
<entry><filename>$XDG_RUNTIME_DIR/systemd/user</filename></entry>
</row>
<row>
<entry><filename>/usr/local/lib/systemd/user</filename></entry>
- <entry morerows="1">Units of packages that have been installed system-wide</entry>
+ <entry>User units installed by the administrator</entry>
</row>
<row>
<entry><filename>/usr/lib/systemd/user</filename></entry>
+ <entry>User units installed by the distribution package manager</entry>
</row>
<row>
<entry><filename>$XDG_RUNTIME_DIR/systemd/generator.late</filename></entry>
<replaceable>description</replaceable>.</literal>, <literal>Reached target
<replaceable>description</replaceable>.</literal>, <literal>Failed to start
<replaceable>description</replaceable>.</literal>), so it should be capitalized, and should
- not be a full sentence or a phrase with a continous verb. Bad examples include
+ not be a full sentence or a phrase with a continuous verb. Bad examples include
<literal>exiting the container</literal> or <literal>updating the database once per
day.</literal>.</para>
</listitem>
<varlistentry>
<term><varname>JoinsNamespaceOf=</varname></term>
- <listitem><para>For units that start processes (such as
- service units), lists one or more other units whose network
- and/or temporary file namespace to join. This only applies to
- unit types which support the
- <varname>PrivateNetwork=</varname> and
+ <listitem><para>For units that start processes (such as service units), lists one or more other units
+ whose network and/or temporary file namespace to join. This only applies to unit types which support
+ the <varname>PrivateNetwork=</varname>, <varname>NetworkNamespacePath=</varname> and
<varname>PrivateTmp=</varname> directives (see
- <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- for details). If a unit that has this setting set is started,
- its processes will see the same <filename>/tmp</filename>,
- <filename>/var/tmp</filename> and network namespace as one
- listed unit that is started. If multiple listed units are
- already started, it is not defined which namespace is joined.
- Note that this setting only has an effect if
- <varname>PrivateNetwork=</varname> and/or
- <varname>PrivateTmp=</varname> is enabled for both the unit
- that joins the namespace and the unit whose namespace is
- joined.</para></listitem>
+ <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
+ details). If a unit that has this setting set is started, its processes will see the same
+ <filename>/tmp</filename>, <filename>/var/tmp</filename> and network namespace as one listed unit
+ that is started. If multiple listed units are already started, it is not defined which namespace is
+ joined. Note that this setting only has an effect if
+ <varname>PrivateNetwork=</varname>/<varname>NetworkNamespacePath=</varname> and/or
+ <varname>PrivateTmp=</varname> is enabled for both the unit that joins the namespace and the unit
+ whose namespace is joined.</para></listitem>
</varlistentry>
<varlistentry>
of powering down the system 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. However, this may be overriden
+ main process of the unit (if this applies) is returned from the service manager. However, this may be overridden
with <varname>FailureActionExitStatus=</varname>/<varname>SuccessActionExitStatus=</varname>, see
below.</para></listitem>
</varlistentry>
<term><varname>JobTimeoutSec=</varname></term>
<term><varname>JobRunningTimeoutSec=</varname></term>
- <listitem><para>When a job for this unit is queued, a time-out <varname>JobTimeoutSec=</varname> may be
+ <listitem><para>When a job for this unit is queued, a timeout <varname>JobTimeoutSec=</varname> may be
configured. Similarly, <varname>JobRunningTimeoutSec=</varname> starts counting when the queued job is actually
started. If either time limit is reached, the job will be cancelled, the unit however will not change state or
even enter the <literal>failed</literal> mode. This value defaults to <literal>infinity</literal> (job timeouts
<term><varname>JobTimeoutRebootArgument=</varname></term>
<listitem><para><varname>JobTimeoutAction=</varname> optionally configures an additional action to take when
- the time-out is hit, see description of <varname>JobTimeoutSec=</varname> and
+ the timeout is hit, see description of <varname>JobTimeoutSec=</varname> and
<varname>JobRunningTimeoutSec=</varname> above. It takes the same values as
<varname>StartLimitAction=</varname>. Defaults to <option>none</option>.
<varname>JobTimeoutRebootArgument=</varname> configures an optional reboot string to pass to the
<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
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.</para>
+ (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><varname>ConditionArchitecture=</varname> may be used to
check whether the system is running on a specific
architecture. Takes one of
- <varname>x86</varname>,
- <varname>x86-64</varname>,
- <varname>ppc</varname>,
- <varname>ppc-le</varname>,
- <varname>ppc64</varname>,
- <varname>ppc64-le</varname>,
- <varname>ia64</varname>,
- <varname>parisc</varname>,
- <varname>parisc64</varname>,
- <varname>s390</varname>,
- <varname>s390x</varname>,
- <varname>sparc</varname>,
- <varname>sparc64</varname>,
- <varname>mips</varname>,
- <varname>mips-le</varname>,
- <varname>mips64</varname>,
- <varname>mips64-le</varname>,
- <varname>alpha</varname>,
- <varname>arm</varname>,
- <varname>arm-be</varname>,
- <varname>arm64</varname>,
- <varname>arm64-be</varname>,
- <varname>sh</varname>,
- <varname>sh64</varname>,
- <varname>m68k</varname>,
- <varname>tilegx</varname>,
- <varname>cris</varname>,
- <varname>arc</varname>,
- <varname>arc-be</varname> to test
+ <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>
<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 <varname>native</varname> is mapped to the
+ 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>
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
- <varname>vm</varname> and
- <varname>container</varname> to test against a generic type of
+ <literal>vm</literal> and
+ <literal>container</literal> to test against a generic type of
virtualization solution, or one of
- <varname>qemu</varname>,
- <varname>kvm</varname>,
- <varname>zvm</varname>,
- <varname>vmware</varname>,
- <varname>microsoft</varname>,
- <varname>oracle</varname>,
- <varname>xen</varname>,
- <varname>bochs</varname>,
- <varname>uml</varname>,
- <varname>bhyve</varname>,
- <varname>qnx</varname>,
- <varname>openvz</varname>,
- <varname>lxc</varname>,
- <varname>lxc-libvirt</varname>,
- <varname>systemd-nspawn</varname>,
- <varname>docker</varname>,
- <varname>rkt</varname> to test
+ <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
- <varname>private-users</varname> to check whether we are running in a user namespace. See
+ <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
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 single string. If the string starts with one of <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><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 single string. If the string 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
<para><varname>ConditionSecurity=</varname> may be used to check
whether the given security technology is enabled on the
system. Currently, the recognized values are
- <varname>selinux</varname>, <varname>apparmor</varname>,
- <varname>tomoyo</varname>, <varname>ima</varname>,
- <varname>smack</varname>, <varname>audit</varname> and
- <varname>uefi-secureboot</varname>. The test may be negated by
+ <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
<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 <varname>true</varname>,
+ 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
- <varname>false</varname>, the condition will hold only if
+ <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>
does not have a special value <literal>@system</literal>.</para>
<para><varname>ConditionControlGroupController=</varname> takes a
- cgroup controller name (eg. <option>cpu</option>), verifying that it is
+ 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
- <option>cpu</option>, <option>cpuacct</option>, <option>io</option>,
- <option>blkio</option>, <option>memory</option>,
- <option>devices</option>, and <option>pids</option>.</para>
+ <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>
<para>If multiple conditions are specified, the unit will be
executed if all of them apply (i.e. a logical AND is applied).
"Forward" and "reverse" unit properties
</title>
- <tgroup cols='2'>
+ <tgroup cols='4'>
<colspec colname='forward' />
<colspec colname='reverse' />
- <colspec colname='notes' />
+ <colspec colname='fuse' />
+ <colspec colname='ruse' />
<thead>
<row>
<entry>"Forward" property</entry>
<entry>"Reverse" property</entry>
- <entry>Where used</entry>
+ <entry namest='fuse' nameend='ruse' valign='middle'>Where used</entry>
</row>
</thead>
<tbody>
<row>
<entry><varname>Before=</varname></entry>
<entry><varname>After=</varname></entry>
- <entry morerows='1' valign='middle'>Both are unit file options</entry>
+ <entry morerows='1' namest='fuse' nameend='ruse' valign='middle'>[Unit] section</entry>
</row>
<row>
<entry><varname>After=</varname></entry>
<row>
<entry><varname>Requires=</varname></entry>
<entry><varname>RequiredBy=</varname></entry>
- <entry>A unit file option; an option in the [Install] section</entry>
+ <entry>[Unit] section</entry>
+ <entry>[Install] section</entry>
</row>
<row>
<entry><varname>Wants=</varname></entry>
<entry><varname>WantedBy=</varname></entry>
- <entry>A unit file option; an option in the [Install] section</entry>
+ <entry>[Unit] section</entry>
+ <entry>[Install] section</entry>
</row>
<row>
<entry><varname>PartOf=</varname></entry>
<entry><varname>ConsistsOf=</varname></entry>
- <entry>A unit file option; an automatic property</entry>
+ <entry>[Unit] section</entry>
+ <entry>an automatic property</entry>
</row>
<row>
<entry><varname>BindsTo=</varname></entry>
<entry><varname>BoundBy=</varname></entry>
- <entry>A unit file option; an automatic property</entry>
+ <entry>[Unit] section</entry>
+ <entry>an automatic property</entry>
</row>
<row>
<entry><varname>Requisite=</varname></entry>
<entry><varname>RequisiteOf=</varname></entry>
- <entry>A unit file option; an automatic property</entry>
+ <entry>[Unit] section</entry>
+ <entry>an automatic property</entry>
</row>
<row>
<entry><varname>Triggers=</varname></entry>
<entry><varname>TriggeredBy=</varname></entry>
- <entry>Automatic properties, see notes below</entry>
+ <entry namest='fuse' nameend='ruse' valign='middle'>Automatic properties, see notes below</entry>
</row>
<row>
<entry><varname>Conflicts=</varname></entry>
<entry><varname>ConflictedBy=</varname></entry>
- <entry>A unit file option; an automatic property</entry>
+ <entry>[Unit] section</entry>
+ <entry>an automatic property</entry>
</row>
<row>
<entry><varname>PropagatesReloadTo=</varname></entry>
<entry><varname>ReloadPropagatedFrom=</varname></entry>
- <entry morerows='1' valign='middle'>Both are unit file options</entry>
+ <entry morerows='1' namest='fuse' nameend='ruse' valign='middle'>[Unit] section</entry>
</row>
<row>
<entry><varname>ReloadPropagatedFrom=</varname></entry>
<row>
<entry><literal>%h</literal></entry>
<entry>User home directory</entry>
- <entry>This is the home directory of the user running the service manager instance. In case of the system manager this resolves to <literal>/root</literal>.</entry>
+ <entry>This is the home directory of the <emphasis>user running the service manager instance</emphasis>. In case of the system manager this resolves to <literal>/root</literal>.
+
+Note that this setting is <emphasis>not</emphasis> influenced by the <varname>User=</varname> setting configurable in the [Service] section of the service unit.</entry>
</row>
<row>
<entry><literal>%H</literal></entry>
<row>
<entry><literal>%u</literal></entry>
<entry>User name</entry>
- <entry>This is the name of the user running the service manager instance. In case of the system manager this resolves to <literal>root</literal>.</entry>
+ <entry>This is the name of the <emphasis>user running the service manager instance</emphasis>. In case of the system manager this resolves to <literal>root</literal>.
+
+Note that this setting is <emphasis>not</emphasis> influenced by the <varname>User=</varname> setting configurable in the [Service] section of the service unit.</entry>
</row>
<row>
<entry><literal>%U</literal></entry>
<entry>User UID</entry>
- <entry>This is the numeric UID of the user running the service manager instance. In case of the system manager this resolves to <literal>0</literal>.</entry>
+ <entry>This is the numeric UID of the <emphasis>user running the service manager instance</emphasis>. In case of the system manager this resolves to <literal>0</literal>.
+
+Note that this setting is <emphasis>not</emphasis> influenced by the <varname>User=</varname> setting configurable in the [Service] section of the service unit.</entry>
</row>
<row>
<entry><literal>%v</literal></entry>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
projects / thirdparty / systemd.git / blobdiff