Copyright 2010 Lennart Poettering
systemd is free software; you can redistribute it and/or modify it
- under the terms of the GNU General Public License as published by
- the Free Software Foundation; either version 2 of the License, or
+ under the terms of the GNU Lesser General Public License as published by
+ the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- General Public License for more details.
+ Lesser General Public License for more details.
- You should have received a copy of the GNU General Public License
+ You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refnamediv>
<refname>systemd.unit</refname>
- <refpurpose>systemd unit configuration files</refpurpose>
+ <refpurpose>Unit configuration</refpurpose>
</refnamediv>
<refsynopsisdiv>
<para>If a line starts with <option>.include</option>
followed by a file name, the specified file will be
parsed at this point. Make sure that the file that is
- included has the appropiate section headers before
+ included has the appropriate section headers before
any directives.</para>
<para>Along with a unit file
<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>
name.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>Documentation=</varname></term>
+ <listitem><para>A space separated list
+ of URIs referencing documentation for
+ this unit or its
+ configuration. Accepted are only URIs
+ of the types
+ <literal>http://</literal>,
+ <literal>https://</literal>,
+ <literal>file:</literal>,
+ <literal>info:</literal>,
+ <literal>man:</literal>. For more
+ information about the syntax of these
+ URIs see
+ <citerefentry><refentrytitle>uri</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para></listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>Requires=</varname></term>
<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>
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>
state.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>PropagatesReloadTo=</varname></term>
+ <term><varname>ReloadPropagatedFrom=</varname></term>
+
+ <listitem><para>Lists one or more
+ units where reload requests on the
+ unit will be propagated to/on the
+ other unit will be propagated
+ from. Issuing a reload request on a
+ unit will automatically also enqueue a
+ reload request on all units that the
+ reload request shall be propagated to
+ via these two
+ settings.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>RequiresMountsFor=</varname></term>
+
+ <listitem><para>Takes a space
+ separated list of absolute paths. Automatically
+ adds dependencies of type
+ <varname>Requires=</varname> and
+ <varname>After=</varname> for all
+ mount units required to access the
+ specified path.</para></listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>OnFailureIsolate=</varname></term>
<term><varname>ConditionPathIsDirectory=</varname></term>
<term><varname>ConditionPathIsSymbolicLink=</varname></term>
<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>ConditionFileIsExecutable=</varname>
+ point.</para>
+
+ <para><varname>ConditionPathIsReadWrite=</varname>
is similar to
<varname>ConditionPathExists=</varname>
- but verifies whether a certain path
- exists, is a regular file and marked
- executable.
- <varname>ConditionDirectoryNotEmpty=</varname>
+ but verifies whether the underlying
+ file system is readable and writable
+ (i.e. not mounted
+ read-only).</para>
+
+ <para><varname>ConditionDirectoryNotEmpty=</varname>
is similar to
<varname>ConditionPathExists=</varname>
but verifies whether a certain path
exists and is a non-empty
- directory. Similarly
+ directory.</para>
+
+ <para><varname>ConditionFileNotEmpty=</varname>
+ is similar to
+ <varname>ConditionPathExists=</varname>
+ but verifies whether a certain path
+ 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>,
<varname>chroot</varname>,
<varname>openvz</varname>,
<varname>lxc</varname>,
- <varname>systemd-nspawn</varname>,
- <varname>pidns</varname> to test
- against a specific implementation. If
- multiple virtualization technologies
- are nested only the innermost is
- considered. The test may be negated by
- prepending an exclamation mark.
- <varname>ConditionSecurity=</varname>
+ <varname>lxc-libvirt</varname>,
+ <varname>systemd-nspawn</varname> to
+ test against a specific
+ implementation. If multiple
+ virtualization technologies are nested
+ only the innermost is considered. The
+ test may be negated by prepending an
+ 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
</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>
+ <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. Thus
+ functionality should not be used in
+ normal units.</para></listitem>
</varlistentry>
</variablelist>
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>
<term><varname>WantedBy=</varname></term>
+ <term><varname>RequiredBy=</varname></term>
<listitem><para>Installs a symlink in
the <filename>.wants/</filename>
+ resp. <filename>.requires/</filename>
subdirectory for a unit. This has the
effect that when the listed unit name
is activated the unit listing it is
~ianmdlvl / elogind.git / blobdiff