do not need the prefix. Applications may use this to include
additional information in the unit files.</para>
- <para>Units can be aliased (have an alternative name), by creating a symlink from the new name
- to the existing name in one of the unit search paths. For example,
- <filename>systemd-networkd.service</filename> has the alias
- <filename>dbus-org.freedesktop.network1.service</filename>, created during installation as the
- symlink <filename>/usr/lib/systemd/system/dbus-org.freedesktop.network1.service</filename>. In
- addition, unit files may specify aliases through the <varname>Alias=</varname> directive in the
- [Install] section; those aliases are only effective when the unit is enabled. When the unit is
- enabled, symlinks will be created for those names, and removed when the unit is disabled. For
- example, <filename>reboot.target</filename> specifies
- <varname>Alias=ctrl-alt-del.target</varname>, so when enabled it will be invoked whenever
- CTRL+ALT+DEL is pressed. Alias names may be used in commands like <command>enable</command>,
- <command>disable</command>, <command>start</command>, <command>stop</command>,
- <command>status</command>, …, and in unit dependency directives <varname>Wants=</varname>,
- <varname>Requires=</varname>, <varname>Before=</varname>, <varname>After=</varname>, …, with the
- limitation that aliases specified through <varname>Alias=</varname> are only effective when the
- unit is enabled. Aliases cannot be used with the <command>preset</command> command.</para>
+ <para>Units can be aliased (have an alternative name), by creating a symlink from the new name to the
+ existing name in one of the unit search paths. For example, <filename>systemd-networkd.service</filename>
+ has the alias <filename>dbus-org.freedesktop.network1.service</filename>, created during installation as
+ a symlink, so when <command>systemd</command> is asked through D-Bus to load
+ <filename>dbus-org.freedesktop.network1.service</filename>, it'll load
+ <filename>systemd-networkd.service</filename>. Alias names may be used in commands like
+ <command>enable</command>, <command>disable</command>, <command>start</command>, <command>stop</command>,
+ <command>status</command>, and similar, and in all unit dependency directives, including
+ <varname>Wants=</varname>, <varname>Requires=</varname>, <varname>Before=</varname>,
+ <varname>After=</varname>. Aliases cannot be used with the <command>preset</command> command.</para>
+
+ <para>Unit files may specify aliases through the <varname>Alias=</varname> directive in the [Install]
+ section. When the unit is enabled, symlinks will be created for those names, and removed when the unit is
+ disabled. For example, <filename>reboot.target</filename> specifies
+ <varname>Alias=ctrl-alt-del.target</varname>, so when enabled, the symlink
+ <filename>/etc/systemd/systemd/ctrl-alt-del.service</filename> pointing to the
+ <filename>reboot.target</filename> file will be created, and when
+ <keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>Del</keycap></keycombo> is invoked,
+ <command>systemd</command> will look for the <filename>ctrl-alt-del.service</filename> and execute
+ <filename>reboot.service</filename>. <command>systemd</command> does not look at the [Install] section at
+ all during normal operation, so any directives in that section only have an effect through the symlinks
+ created during enablement.</para>
<para>Along with a unit file <filename>foo.service</filename>, the directory
- <filename>foo.service.wants/</filename> may exist. All unit files symlinked from such a
- directory are implicitly added as dependencies of type <varname>Wants=</varname> to the unit.
- This is useful to hook units into the start-up of other units, without having to modify their
- unit files. For details about the semantics of <varname>Wants=</varname>, see below. The
- preferred way to create symlinks in the <filename>.wants/</filename> directory of a unit file is
- with the <command>enable</command> command of the
- <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- tool which reads information from the [Install] section of unit files (see below). A similar
- functionality exists for <varname>Requires=</varname> type dependencies as well, the directory
- suffix is <filename>.requires/</filename> in this case.</para>
+ <filename>foo.service.wants/</filename> may exist. All unit files symlinked from such a directory are
+ implicitly added as dependencies of type <varname>Wants=</varname> to the unit. Similar functionality
+ exists for <varname>Requires=</varname> type dependencies as well, the directory suffix is
+ <filename>.requires/</filename> in this case. This functionality is useful to hook units into the
+ start-up of other units, without having to modify their unit files. For details about the semantics of
+ <varname>Wants=</varname>, see below. The preferred way to create symlinks in the
+ <filename>.wants/</filename> or <filename>.requires/</filename> directory of a unit file is by embedding
+ the dependency in [Install] section of the target unit, and creating the symlink in the file system with
+ the with the <command>enable</command> or <command>preset</command> commands of
+ <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
<para>Along with a unit file <filename>foo.service</filename>, a "drop-in" directory
<filename>foo.service.d/</filename> may exist. All files with the suffix <literal>.conf</literal> from this
<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>
<term><varname>DefaultDependencies=</varname></term>
<listitem><para>Takes a boolean argument. If
- <option>true</option>, (the default), a few default
+ <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
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>false</option>. It is highly recommended to
+ option to <option>no</option>. It is highly recommended to
leave this option enabled for the majority of common units. If
- set to <option>false</option>, this option does not disable
+ set to <option>no</option>, this option does not disable
all implicit dependencies, just non-essential
ones.</para></listitem>
</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>ConditionMemory=</varname></term>
<term><varname>ConditionCPUs=</varname></term>
- <!-- We do not document ConditionNull=
- here, as it is not particularly
- useful and probably just
+ <!-- We do not document ConditionNull= here, as it is not particularly useful and probably just
confusing. -->
<listitem><para>Before starting a unit, verify that the specified condition is true. If it is not true, the
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>If multiple conditions are specified, the unit will be executed if all of them apply (i.e. a
+ logical AND is applied). Condition checks can be prefixed with a pipe symbol (<literal>|</literal>)
+ in which case a condition becomes a triggering condition. If at least one triggering condition is
+ defined for a unit, then the unit will be executed if at least one of the triggering conditions apply
+ and all of the non-triggering conditions. If you prefix an argument with the pipe symbol and an
+ exclamation mark, the pipe symbol must be passed first, the exclamation second. Except for
+ <varname>ConditionPathIsSymbolicLink=</varname>, all path checks follow symlinks. If any of these
+ options is assigned the empty string, the list of conditions is reset completely, all previous
+ condition settings (of any kind) will have no effect. The <command>condition</command> verb of
+ <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ can be used to test condition and assert expressions.</para>
<para><varname>ConditionArchitecture=</varname> may be used to
check whether the system is running on a specific
<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
<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>
+ exclamation mark does not match it). The argument must be a list of (potentially quoted) expressions.
+ For each of the expressions, if it starts with one of <literal><</literal>,
+ <literal><=</literal>, <literal>=</literal>, <literal>!=</literal>, <literal>>=</literal>,
+ <literal>></literal> a relative version comparison is done, otherwise the specified string is
+ matched with shell-style globs.</para>
<para>Note that using the kernel version string is an unreliable way to determine which features are supported
by a kernel, because of the widespread practice of backporting drivers, features, and fixes from newer upstream
<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
- comparision operator. On physical systems the number of CPUs in the affinity mask of the service
+ 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).
- Condition checks can be prefixed with a pipe symbol (|) in
- which case a condition becomes a triggering condition. If at
- least one triggering condition is defined for a unit, then the
- unit will be executed if at least one of the triggering
- conditions apply and all of the non-triggering conditions. If
- you prefix an argument with the pipe symbol and an exclamation
- mark, the pipe symbol must be passed first, the exclamation
- second. Except for
- <varname>ConditionPathIsSymbolicLink=</varname>, all path
- checks follow symlinks. If any of these options is assigned
- the empty string, the list of conditions is reset completely,
- all previous condition settings (of any kind) will have no
- effect.</para></listitem>
+ the container and not the physically available ones.</para></listitem>
</varlistentry>
<varlistentry>
<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></listitem>
+ dependencies.</para>
+
+ <para>The <command>condition</command> verb of
+ <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ can be used to test condition and assert expressions.</para></listitem>
</varlistentry>
<varlistentry>
"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>
projects / thirdparty / systemd.git / blobdiff