<refnamediv>
<refname>systemd.unit</refname>
- <refpurpose>systemd unit configuration files</refpurpose>
+ <refpurpose>Unit configuration</refpurpose>
</refnamediv>
<refsynopsisdiv>
inspired by Microsoft Windows
<filename>.ini</filename> files.</para>
- <para>This man pages lists the common configuration
+ <para>This man page lists the common configuration
options of all the unit types. These options need to
- be configured in the [Unit] resp. [Install]
- section of the unit files.</para>
+ be configured in the [Unit] or [Install]
+ sections of the unit files.</para>
<para>In addition to the generic [Unit] and [Install]
sections described here, each unit should have a
<entry>Runtime socket dir</entry>
<entry>This is either /run (for the system manager) or $XDG_RUNTIME_DIR (for user managers).</entry>
</row>
+ <row>
+ <entry><literal>%u</literal></entry>
+ <entry>User name</entry>
+ <entry>This is the name of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry>
+ </row>
+ <row>
+ <entry><literal>%h</literal></entry>
+ <entry>User home directory</entry>
+ <entry>This is the home directory of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry>
+ </row>
+ <row>
+ <entry><literal>%s</literal></entry>
+ <entry>User shell</entry>
+ <entry>This is the shell of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry>
+ </row>
+ <row>
+ <entry><literal>%m</literal></entry>
+ <entry>Machine ID</entry>
+ <entry>The machine ID of the running system, formatted as string. See <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.</entry>
+ </row>
+ <row>
+ <entry><literal>%b</literal></entry>
+ <entry>Boot ID</entry>
+ <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry>
+ </row>
+ <row>
+ <entry><literal>%H</literal></entry>
+ <entry>Host name</entry>
+ <entry>The host name of the running system.</entry>
+ </row>
</tbody>
</tgroup>
</table>
<literal>man:</literal>. For more
information about the syntax of these
URIs see
- <citerefentry><refentrytitle>uri</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para></listitem>
+ <citerefentry><refentrytitle>uri</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
+ URIs should be listed in order of
+ relevance, starting with the most
+ relevant. It is a good idea to first
+ reference documentation that explains
+ what the unit's purpose is, followed
+ by how it is configured, followed by
+ any other related
+ documentation.</para></listitem>
</varlistentry>
<varlistentry>
<varname>Requires=</varname> in order
to achieve a system that is more
robust when dealing with failing
- services.</para></listitem>
+ services.</para>
+
+ <para>Note that dependencies of this
+ type may also be configured outside of
+ the unit configuration file by
+ adding a symlink to a
+ <filename>.requires/</filename> directory
+ accompanying the unit file. For
+ details see above.</para></listitem>
</varlistentry>
<varlistentry>
<listitem><para>Similar to
<varname>Requires=</varname>
- resp. <varname>RequiresOverridable=</varname>. However,
+ and <varname>RequiresOverridable=</varname>, respectively. However,
if a unit listed here is not started
already it will not be started and the
transaction fails
the transaction as a whole. This is
the recommended way to hook start-up
of one unit to the start-up of another
- unit. Note that dependencies of this
+ unit.</para>
+
+ <para>Note that dependencies of this
type may also be configured outside of
the unit configuration file by
adding a symlink to a
</varlistentry>
<varlistentry>
- <term><varname>BindTo=</varname></term>
+ <term><varname>BindsTo=</varname></term>
<listitem><para>Configures requirement
dependencies, very similar in style to
<varname>Requires=</varname>, however
- in addition to this behaviour it also
+ in addition to this behavior it also
declares that this unit is stopped
when any of the units listed suddenly
disappears. Units can suddenly,
systemd.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>PartOf=</varname></term>
+
+ <listitem><para>Configures dependencies
+ similar to <varname>Requires=</varname>,
+ but limited to stopping and restarting
+ of units. When systemd stops or restarts
+ the units listed here, the action is
+ propagated to this unit.
+ Note that this is a one way dependency -
+ changes to this unit do not affect the
+ listed units.
+ </para></listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>Conflicts=</varname></term>
<varname>Before=</varname>. If two
units have no ordering dependencies
between them they are shut down
- resp. started up simultaneously, and
+ or started up simultaneously, and
no ordering takes
place. </para></listitem>
</varlistentry>
</varlistentry>
<varlistentry>
- <term><varname>PropagateReloadTo=</varname></term>
- <term><varname>PropagateReloadFrom=</varname></term>
+ <term><varname>PropagatesReloadTo=</varname></term>
+ <term><varname>ReloadPropagatedFrom=</varname></term>
<listitem><para>Lists one or more
units where reload requests on the
<term><varname>RequiresMountsFor=</varname></term>
<listitem><para>Takes a space
- separated list of paths. Automatically
+ separated list of absolute paths. Automatically
adds dependencies of type
<varname>Requires=</varname> and
<varname>After=</varname> for all
<listitem><para>Takes a boolean
argument. If <option>true</option>
this unit can only be activated
- (resp. deactivated) indirectly. In
+ or deactivated indirectly. In
this case explicit start-up
- (resp. termination) requested by the
+ or termination requested by the
user is denied, however if it is
- started (resp. stopped) as a
+ started or stopped as a
dependency of another unit, start-up
- (resp. termination) will succeed. This
+ or termination will succeed. This
is mostly a safety feature to ensure
that the user does not accidentally
activate units that are not intended
<term><varname>ConditionPathIsMountPoint=</varname></term>
<term><varname>ConditionPathIsReadWrite=</varname></term>
<term><varname>ConditionDirectoryNotEmpty=</varname></term>
+ <term><varname>ConditionFileNotEmpty=</varname></term>
<term><varname>ConditionFileIsExecutable=</varname></term>
<term><varname>ConditionKernelCommandLine=</varname></term>
<term><varname>ConditionVirtualization=</varname></term>
<term><varname>ConditionSecurity=</varname></term>
<term><varname>ConditionCapability=</varname></term>
+ <term><varname>ConditionHost=</varname></term>
<term><varname>ConditionNull=</varname></term>
<listitem><para>Before starting a unit
verify that the specified condition is
- true. With
+ true. If it is not true the starting
+ of the unit will be skipped, however
+ all ordering dependencies of it are
+ still respected. A failing condition
+ will not result in the unit being
+ moved into a failure state. The
+ condition is checked at the time the
+ queued start job is to be
+ executed.</para>
+
+ <para>With
<varname>ConditionPathExists=</varname>
- a file existence condition can be
+ a file existence condition is
checked before a unit is started. If
the specified absolute path name does
- not exist, startup of a unit will not
- actually happen, however the unit is
- still useful for ordering purposes in
- this case. The condition is checked at
- the time the queued start job is to be
- executed. If the absolute path name
- passed to
+ not exist the condition will
+ fail. If the absolute path name passed
+ to
<varname>ConditionPathExists=</varname>
is prefixed with an exclamation mark
- (!), the test is negated, and the unit
+ ('!'), the test is negated, and the unit
is only started if the path does not
- exist.
- <varname>ConditionPathExistsGlob=</varname>
- works in a similar way, but checks for
- the existence of at least one file or
- directory matching the specified
- globbing
- pattern. <varname>ConditionPathIsDirectory=</varname>
+ exist.</para>
+
+ <para><varname>ConditionPathExistsGlob=</varname>
+ is similar to
+ <varname>ConditionPathExists=</varname>,
+ but checks for the existence of at
+ least one file or directory matching
+ the specified globbing pattern.</para>
+
+ <para><varname>ConditionPathIsDirectory=</varname>
is similar to
<varname>ConditionPathExists=</varname>
but verifies whether a certain path
exists and is a
- directory. <varname>ConditionPathIsSymbolicLink=</varname>
+ directory.</para>
+
+ <para><varname>ConditionPathIsSymbolicLink=</varname>
is similar to
<varname>ConditionPathExists=</varname>
but verifies whether a certain path
exists and is a symbolic
- link. <varname>ConditionPathIsMountPoint=</varname>
+ link.</para>
+
+ <para><varname>ConditionPathIsMountPoint=</varname>
is similar to
<varname>ConditionPathExists=</varname>
but verifies whether a certain path
exists and is a mount
- point. <varname>ConditionPathIsReadWrite=</varname>
+ point.</para>
+
+ <para><varname>ConditionPathIsReadWrite=</varname>
is similar to
<varname>ConditionPathExists=</varname>
but verifies whether the underlying
- file system is read and writable
+ file system is readable and writable
(i.e. not mounted
- read-only). <varname>ConditionFileIsExecutable=</varname>
+ read-only).</para>
+
+ <para><varname>ConditionDirectoryNotEmpty=</varname>
is similar to
<varname>ConditionPathExists=</varname>
but verifies whether a certain path
- exists, is a regular file and marked
- executable.
- <varname>ConditionDirectoryNotEmpty=</varname>
+ exists and is a non-empty
+ directory.</para>
+
+ <para><varname>ConditionFileNotEmpty=</varname>
is similar to
<varname>ConditionPathExists=</varname>
but verifies whether a certain path
- exists and is a non-empty
- directory. Similarly
+ exists and refers to a regular file
+ with a non-zero size.</para>
+
+ <para><varname>ConditionFileIsExecutable=</varname>
+ is similar to
+ <varname>ConditionPathExists=</varname>
+ but verifies whether a certain path
+ exists, is a regular file and marked
+ executable.</para>
+
+ <para>Similar,
<varname>ConditionKernelCommandLine=</varname>
may be used to check whether a
specific kernel command line option is
exclamation mark unset). The argument
must either be a single word, or an
assignment (i.e. two words, separated
- by the equality sign). In the former
+ '='). 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. <varname>ConditionVirtualization=</varname>
+ matching.</para>
+
+ <para><varname>ConditionVirtualization=</varname>
may be used to check whether the
system is executed in a virtualized
environment and optionally test
any virtualized environment, or one of
<varname>vm</varname> and
<varname>container</varname> to test
- against a specific type of
+ against a generic type of
virtualization solution, or one of
<varname>qemu</varname>,
<varname>kvm</varname>,
virtualization technologies are nested
only the innermost is considered. The
test may be negated by prepending an
- exclamation mark.
- <varname>ConditionSecurity=</varname>
+ exclamation mark.</para>
+
+ <para><varname>ConditionSecurity=</varname>
may be used to check whether the given
security module is enabled on the
system. Currently the only recognized
value is <varname>selinux</varname>.
The test may be negated by prepending
an exclamation
- mark. <varname>ConditionCapability=</varname>
+ mark.</para>
+
+ <para><varname>ConditionCapability=</varname>
may be used to check whether the given
capability exists in the capability
bounding set of the service manager
for details). Pass a capability name
such as <literal>CAP_MKNOD</literal>,
possibly prefixed with an exclamation
- mark to negate the check. Finally,
+ mark to negate the check.</para>
+
+ <para><varname>ConditionHost=</varname>
+ may be used to match against the
+ host name or machine ID of the
+ host. This either takes a host name
+ string (optionally with shell style
+ globs) which is tested against the
+ locally set host name as returned by
+ <citerefentry><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
+ or a machine ID formatted as string
+ (see
+ <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
+ The test may be negated by prepending
+ an exclamation mark.</para>
+
+ <para>Finally,
<varname>ConditionNull=</varname> may
be used to add a constant condition
check value to the unit. It takes a
boolean argument. If set to
<varname>false</varname> the condition
will always fail, otherwise
- succeed. If multiple conditions are
+ succeed.</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
symlinks.</para></listitem>
</varlistentry>
- <varlistentry>
- <term><varname>Names=</varname></term>
-
- <listitem><para>Additional names for
- this unit. The names listed here must
- have the same suffix (i.e. type) as
- the unit file name. This option may be
- specified more than once, in which
- case all listed names are used. Note
- that this option is different from the
- <varname>Alias=</varname> option from
- the [Install] section mentioned
- below. See below for details. Note
- that in almost all cases this option
- is not what you want. A symlink alias
- in the file system is generally
- preferable since it can be used as
- lookup key. If a unit with a symlinked
- alias name is not loaded and needs to
- be it is easily found via the
- symlink. However, if a unit with an
- alias name configured with this
- setting is not loaded it will not be
- discovered. This settings' only use is
- in conjunction with service
- instances.</para>
- </listitem>
- </varlistentry>
-
<varlistentry>
<term><varname>SourcePath=</varname></term>
<listitem><para>A path to a
time,
<command>systemctl enable</command>
will create symlinks from these names
- to the unit file name. Note that this
- is different from the
- <varname>Names=</varname> option from
- the [Unit] section mentioned above:
- The names from
- <varname>Names=</varname> apply
- unconditionally if the unit is
- loaded. The names from
- <varname>Alias=</varname> apply only
- if the unit has actually been
- installed with the
- <command>systemctl enable</command>
- command. Also, if systemd searches for a
- unit, it will discover symlinked alias
- names as configured with
- <varname>Alias=</varname>, but not
- names configured with
- <varname>Names=</varname> only. It is
- a common pattern to list a name in
- both options. In this case, a unit
- will be active under all names if
- installed, but also if not installed
- but requested explicitly under its
- main name.</para></listitem>
+ to the unit file name.</para></listitem>
</varlistentry>
<varlistentry>
<listitem><para>Installs a symlink in
the <filename>.wants/</filename>
- resp. <filename>.requires/</filename>
- subdirectory for a unit. This has the
+ or <filename>.requires/</filename>
+ subdirectory for a unit, respectively. This has the
effect that when the listed unit name
is activated the unit listing it is
activated
~ianmdlvl / elogind.git / blobdiff