<?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>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