<?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>
carries generic information about the unit that is not
dependent on the type of unit:</para>
- <variablelist>
+ <variablelist class='unit-directives'>
<varlistentry>
<term><varname>Description=</varname></term>
<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
reference documentation that explains
what the unit's purpose is, followed
by how it is configured, followed by
- any other related
- documentation.</para></listitem>
+ any other related documentation. This
+ 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
+ reset and all prior assignments will
+ have no effect.</para></listitem>
</varlistentry>
<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
<varname>xen</varname>,
<varname>bochs</varname>,
<varname>chroot</varname>,
+ <varname>uml</varname>,
<varname>openvz</varname>,
<varname>lxc</varname>,
<varname>lxc-libvirt</varname>,
<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
pipe symbol must be passed first, the
exclamation second. Except for
<varname>ConditionPathIsSymbolicLink=</varname>,
- all path checks follow
- symlinks.</para></listitem>
+ 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>
</varlistentry>
<varlistentry>
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
tool during installation of a unit:</para>
- <variablelist>
+ <variablelist class='unit-directives'>
<varlistentry>
<term><varname>Alias=</varname></term>
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> directory
+ 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, %v.
+ 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>%v</literal></entry>
+ <entry>Kernel release</entry>
+ <entry>Identical to <command>uname -r</command> output.</entry>
+ </row>
+ <row>
+ <entry><literal>%%</literal></entry>
+ <entry>Escaped %</entry>
+ <entry>Single percent sign.</entry>
</row>
</tbody>
</tgroup>
<citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>1</manvolnum></citerefentry>
</para>
</refsect1>
~ianmdlvl / elogind.git / blobdiff