<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+<!ENTITY % entities SYSTEM "custom-entities.ent" >
+%entities;
+]>
<!--
This file is part of systemd.
</refnamediv>
<refsynopsisdiv>
- <para><filename>systemd.service</filename>,
- <filename>systemd.socket</filename>,
- <filename>systemd.device</filename>,
- <filename>systemd.mount</filename>,
- <filename>systemd.automount</filename>,
- <filename>systemd.swap</filename>,
- <filename>systemd.target</filename>,
- <filename>systemd.path</filename>,
- <filename>systemd.timer</filename>,
- <filename>systemd.snapshot</filename></para>
+ <para><filename><replaceable>service</replaceable>.service</filename>,
+ <filename><replaceable>socket</replaceable>.socket</filename>,
+ <filename><replaceable>device</replaceable>.device</filename>,
+ <filename><replaceable>mount</replaceable>.mount</filename>,
+ <filename><replaceable>automount</replaceable>.automount</filename>,
+ <filename><replaceable>swap</replaceable>.swap</filename>,
+ <filename><replaceable>target</replaceable>.target</filename>,
+ <filename><replaceable>path</replaceable>.path</filename>,
+ <filename><replaceable>timer</replaceable>.timer</filename>,
+ <filename><replaceable>snapshot</replaceable>.snapshot</filename></para>
+
+ <para><literallayout><filename>/etc/systemd/system/*</filename>
+<filename>/run/systemd/system/*</filename>
+<filename>/usr/lib/systemd/system/*</filename>
+<filename>...</filename>
+ </literallayout></para>
+
+ <para><literallayout><filename>/etc/systemd/user/*</filename>
+<filename>/run/systemd/user/*</filename>
+<filename>/usr/lib/systemd/user/*</filename>
+<filename>...</filename>
+ </literallayout></para>
</refsynopsisdiv>
<refsect1>
<para>A unit configuration file encodes information
about a service, a socket, a device, a mount point, an
automount point, a swap file or partition, a start-up
- target, a file system path or a timer controlled and
+ target, a file system path, or a timer controlled and
supervised by
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>. The
syntax is inspired by <ulink
sections described here, each unit may have a
type-specific section, e.g. [Service] for a service
unit. See the respective man pages for more
- information.</para>
+ information:
+ <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+ </para>
+
+ <para>Unit files are loaded from a set of paths
+ determined during compilation, described in the next section.
+ </para>
<para>Unit files may contain additional options on top
of those listed here. If systemd encounters an unknown
<para>Along with a unit file
<filename>foo.service</filename> a directory
<filename>foo.service.d/</filename> may exist. All
- files with the suffix <filename>.conf</filename> from
+ files with the suffix <literal>.conf</literal> from
this directory will be parsed after the file itself is
parsed. This is useful to alter or add configuration
settings to a unit, without having to modify their
directive.</para>
<para>If a line starts with <option>.include</option>
- followed by a file name, the specified file will be
+ followed by a filename, the specified file will be
parsed at this point. Make sure that the file that is
included has the appropriate section headers before
any directives.</para>
<para>Note that while systemd offers a flexible
dependency system between units it is recommended to
- use this functionality only sparsely and instead rely
+ use this functionality only sparingly and instead rely
on techniques such as bus-based or socket-based
- activation which makes dependencies implicit, which
- both results in a simpler and more flexible
- system.</para>
+ activation which make dependencies implicit, resulting
+ in a both simpler and more flexible system.</para>
<para>Some unit names reflect paths existing in the
- file system name space. Example: a device unit
+ file system namespace. Example: a device unit
<filename>dev-sda.device</filename> refers to a device
- with the device node <filename>/dev/sda</filename> in
+ with the device node <filename noindex='true'>/dev/sda</filename> in
the file system namespace. If this applies a special
way to escape the path name is used, so that the
- result is usable as part of a file name. Basically,
+ result is usable as part of a filename. Basically,
given a path, "/" is replaced by "-", and all
unprintable characters and the "-" are replaced by
C-style "\x20" escapes. The root directory "/" is
systemd looks for a unit configuration file it will
first search for the literal unit name in the
filesystem. If that yields no success and the unit
- name contains an @ character, systemd will look for a
+ name contains an <literal>@</literal> character, systemd will look for a
unit template that shares the same name but with the
- instance string (i.e. the part between the @ character
+ instance string (i.e. the part between the <literal>@</literal> character
and the suffix) removed. Example: if a service
<filename>getty@tty3.service</filename> is requested
and no file by that name is found, systemd will look
</refsect1>
+ <refsect1>
+ <title>Unit Load Path</title>
+
+ <para>Unit files are loaded from a set of paths
+ determined during compilation, described in the two
+ tables below. Unit files found in directories higher
+ in the hierarchy override files with the same name
+ lower in the hierarchy, thus allowing overrides.
+ </para>
+
+ <para>When systemd is running in user mode
+ (<option>--user</option>) and the variable
+ <varname>$SYSTEMD_UNIT_PATH</varname> is set, this
+ contents of this variable overrides the unit load
+ path.
+ </para>
+
+ <table>
+ <title>
+ Load path when running in system mode (<option>--system</option>).
+ </title>
+
+ <tgroup cols='2'>
+ <colspec colname='path' />
+ <colspec colname='expl' />
+ <thead>
+ <row>
+ <entry>Path</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><filename>/run/systemd/generator.early</filename></entry>
+ <entry>Generated units (early)</entry>
+ </row>
+ <row>
+ <entry><filename>/etc/systemd/system</filename></entry>
+ <entry>Local configuration</entry>
+ </row>
+ <row>
+ <entry><filename>/run/systemd/systemd</filename></entry>
+ <entry>Volatile units</entry>
+ </row>
+ <row>
+ <entry><filename>/run/systemd/generator</filename></entry>
+ <entry>Generated units (middle)</entry>
+ </row>
+ <row>
+ <entry><filename>/usr/local/lib/systemd/system</filename></entry>
+ <entry>Units for local packages</entry>
+ </row>
+ <row>
+ <entry><filename>/usr/lib/systemd/system</filename></entry>
+ <entry>Units for installed packages</entry>
+ </row>
+ <row>
+ <entry><filename>/run/systemd/generator.late</filename></entry>
+ <entry>Generated units (late)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table>
+ <title>
+ Load path when running in session mode (<option>--user</option>).
+ </title>
+
+ <tgroup cols='2'>
+ <colspec colname='path' />
+ <colspec colname='expl' />
+ <thead>
+ <row>
+ <entry>Path</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><filename>/tmp/systemd-generator.early.<replaceable>XXXXXX</replaceable></filename></entry>
+ <entry>Generated units (early)</entry>
+ </row>
+ <row>
+ <entry><filename>/etc/systemd/user</filename></entry>
+ <entry>Local configuration</entry>
+ </row>
+ <row>
+ <entry><filename>/run/systemd/user</filename></entry>
+ <entry>Volatile units</entry>
+ </row>
+ <row>
+ <entry><filename>/tmp/systemd-generator.<replaceable>XXXXXX</replaceable></filename></entry>
+ <entry>Generated units (middle)</entry>
+ </row>
+ <row>
+ <entry><filename>/usr/local/lib/systemd/user</filename></entry>
+ <entry>Units for local packages</entry>
+ </row>
+ <row>
+ <entry><filename>/usr/lib/systemd/user</filename></entry>
+ <entry>Units for installed packages</entry>
+ </row>
+ <row>
+ <entry><filename>/tmp/systemd-generator.late.<replaceable>XXXXXX</replaceable></filename></entry>
+ <entry>Generated units (late)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>Additional units might be loaded into systemd
+ ("linked") from directories not on the unit load
+ path. See the <command>link</command> command for
+ <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+ </para>
+ </refsect1>
+
<refsect1>
<title>Options</title>
<varlistentry>
<term><varname>Documentation=</varname></term>
- <listitem><para>A space separated list
+ <listitem><para>A space-separated list
of URIs referencing documentation for
this unit or its
configuration. Accepted are only URIs
<literal>info:</literal>,
<literal>man:</literal>. For more
information about the syntax of these
- URIs see
+ URIs, see
<citerefentry><refentrytitle>uri</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
URIs should be listed in order of
relevance, starting with the most
option may be specified more than once
in which case the specified list of
URIs is merged. If the empty string is
- assigned to this option the list is
+ assigned to this option, the list is
reset and all prior assignments will
have no effect.</para></listitem>
</varlistentry>
<listitem><para>Lists one or more
units that are activated when this
unit enters the
- '<literal>failed</literal>'
+ <literal>failed</literal>
state.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>RequiresMountsFor=</varname></term>
- <listitem><para>Takes a space
- separated list of absolute paths. Automatically
+ <listitem><para>Takes a space-separated
+ list of absolute paths. Automatically
adds dependencies of type
<varname>Requires=</varname> and
<varname>After=</varname> for all
highly recommended to leave this
option enabled for the majority of
common units. If set to
- <option>false</option> this option
+ <option>false</option>, this option
does not disable all implicit
dependencies, just non-essential
ones.</para></listitem>
time. If this time limit is reached
the job will be cancelled, the unit
however will not change state or even
- enter the '<literal>failed</literal>'
+ enter the <literal>failed</literal>
mode. This value defaults to 0 (job
timeouts disabled), except for device
units. NB: this timeout is independent
to
<varname>ConditionPathExists=</varname>
is prefixed with an exclamation mark
- ('!'), the test is negated, and the unit
+ (<literal>!</literal>), the test is negated, and the unit
is only started if the path does not
exist.</para>
exclamation mark unset). The argument
must either be a single word, or an
assignment (i.e. two words, separated
- '='). In the former
+ <literal>=</literal>). In the former
case the kernel command line is
searched for the word appearing as is,
or as left hand side of an
<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>.
+ system. Currently the recognized values
+ values are <varname>selinux</varname>,
+ <varname>apparmor</varname>,
+ <varname>ima</varname> and
+ <varname>smack</varname>.
The test may be negated by prepending
an exclamation
mark.</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
+ hostname or machine ID of the
+ host. This either takes a hostname
string (optionally with shell style
globs) which is tested against the
- locally set host name as returned by
+ locally set hostname as returned by
<citerefentry><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
or a machine ID formatted as string
(see
time,
<command>systemctl enable</command>
will create symlinks from these names
- to the unit file name.</para></listitem>
+ to the unit filename.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>WantedBy=</varname></term>
<term><varname>RequiredBy=</varname></term>
- <listitem><para>Installs a symlink in
- the <filename>.wants/</filename>
- 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
- too. <command>WantedBy=foo.service</command>
+ <listitem><para>A symbolic link is
+ created in the
+ <filename>.wants/</filename> or
+ <filename>.requires/</filename> folder
+ of the listed unit when this unit is
+ activated by <command>systemctl
+ enable</command>. This has the effect
+ that a dependency of type
+ <varname>Wants=</varname> or
+ <varname>Requires=</varname> is added
+ from the listed unit to the current
+ unit. The primary result is that the
+ current unit will be started when the
+ listed unit is started. See the
+ description of
+ <varname>Wants=</varname> and
+ <varname>Requires=</varname> in the
+ [Unit] section for details.</para>
+
+ <para><command>WantedBy=foo.service</command>
in a service
<filename>bar.service</filename> is
mostly equivalent to
<command>Alias=foo.service.wants/bar.service</command>
- in the same file.</para></listitem>
+ in the same file. In case of template
+ units, <command>systemctl enable</command>
+ must be called with an instance name, and
+ this instance will be added to the
+ <filename>.wants/</filename> or
+ <filename>.requires/</filename> list
+ of the listed unit.
+ E.g. <command>WantedBy=getty.target</command>
+ in a service
+ <filename>getty@.service</filename>
+ will result in <command>systemctl
+ enable getty@tty2.service</command>
+ creating a
+ <filename>getty.target.wants/getty@tty2.service</filename>
+ link to <filename>getty@.service</filename>.
+ </para></listitem>
</varlistentry>
<varlistentry>
<term><varname>Also=</varname></term>
<listitem><para>Additional units to
- install when this unit is
- installed. If the user requests
- installation of a unit with this
- option configured,
+ install/deinstall when this unit is
+ installed/deinstalled. If the user
+ requests installation/deinstallation
+ of a unit with this option configured,
<command>systemctl enable</command>
- will automatically install units
- listed in this option as
+ and <command>systemctl
+ disable</command> will automatically
+ install/uninstall units listed in this option as
well.</para></listitem>
</varlistentry>
</variablelist>
+ <para>The following specifiers are interpreted in the
+ Install section: %n, %N, %p, %i, %U, %u, %m, %H, %b.
+ For their meaning see the next section.
+ </para>
</refsect1>
<refsect1>
<row>
<entry><literal>%i</literal></entry>
<entry>Instance name</entry>
- <entry>For instantiated units: this is the string between the @ character and the suffix.</entry>
+ <entry>For instantiated units: this is the string between the <literal>@</literal> character and the suffix.</entry>
</row>
<row>
<entry><literal>%I</literal></entry>
</row>
<row>
<entry><literal>%f</literal></entry>
- <entry>Unescaped file name</entry>
- <entry>This is either the unescaped instance name (if applicable) with / prepended (if applicable), or the prefix name similarly prepended with /.</entry>
+ <entry>Unescaped filename</entry>
+ <entry>This is either the unescaped instance name (if applicable) with <filename>/</filename> prepended (if applicable), or the prefix name similarly prepended with <filename>/</filename>.</entry>
</row>
<row>
<entry><literal>%c</literal></entry>
</row>
<row>
<entry><literal>%r</literal></entry>
- <entry>Root control group path of systemd</entry>
- <entry></entry>
+ <entry>Root control group path where units are placed.</entry>
+ <entry>For system instances this usually resolves to <filename>/system</filename>, except in containers, where the path might be prefixed with the container's root control group.</entry>
</row>
<row>
<entry><literal>%R</literal></entry>
- <entry>Parent directory of the root control group path of systemd</entry>
- <entry></entry>
+ <entry>Parent directory of the control group path where units are placed.</entry>
+ <entry>For system instances this usually resolves to <filename>/</filename>, except in containers, where this resolves to the container's root directory. This specifier is particularly useful in the <varname>ControlGroup=</varname> setting (see <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>).</entry>
</row>
<row>
<entry><literal>%t</literal></entry>
<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>
+ <entry>This is the shell of the configured user of the unit, or (if none is set) the user running the systemd instance. If the user is <literal>root</literal> (UID equal to 0), the shell configured in account database is ignored and <filename>/bin/sh</filename> is always used.</entry>
</row>
<row>
<entry><literal>%m</literal></entry>
<row>
<entry><literal>%H</literal></entry>
<entry>Host name</entry>
- <entry>The host name of the running system.</entry>
+ <entry>The hostname of the running system.</entry>
+ </row>
+ <row>
+ <entry><literal>%%</literal></entry>
+ <entry>Escaped %</entry>
+ <entry>Single percent sign.</entry>
</row>
</tbody>
</tgroup>
~ianmdlvl / elogind.git / blobdiff