man: fix spacing issue in various man pages

[elogind.git] / man / systemd.unit.xml

diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index 953a2897ad488074839bf6f2f90f6bac449ea27e..1cfdac9267ef535216dbefc53f403bacb27aeb10 100644 (file)
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -1,6 +1,9 @@
 <?xml version='1.0'?> <!--*-nxml-*-->
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
 <?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.
 
 <!--
   This file is part of systemd.


@@ -48,16 +51,28 @@
         </refnamediv>
 
         <refsynopsisdiv>
         </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>
         </refsynopsisdiv>
 
         <refsect1>


@@ -66,7 +81,7 @@
                 <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
                 <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
                 supervised by
                 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>. The
                 syntax is inspired by <ulink


@@ -84,7 +99,22 @@
                 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
                 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>Unit files may contain additional options on top
                 of those listed here. If systemd encounters an unknown


@@ -159,16 +189,15 @@
 
                 <para>Note that while systemd offers a flexible
                 dependency system between units it is recommended to
 
                 <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
                 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
 
                 <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
                 <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,
                 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,


@@ -215,6 +244,124 @@
 
         </refsect1>
 
 
         </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>
 
         <refsect1>
                 <title>Options</title>
 


@@ -222,7 +369,7 @@
                 carries generic information about the unit that is not
                 dependent on the type of unit:</para>
 
                 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>Description=</varname></term>


@@ -499,7 +646,7 @@
                                 <listitem><para>Lists one or more
                                 units that are activated when this
                                 unit enters the
                                 <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>
 
                                 state.</para></listitem>
                         </varlistentry>
 


@@ -665,7 +812,7 @@
                                 time. If this time limit is reached
                                 the job will be cancelled, the unit
                                 however will not change state or even
                                 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
                                 mode. This value defaults to 0 (job
                                 timeouts disabled), except for device
                                 units. NB: this timeout is independent


@@ -724,7 +871,7 @@
                                 to
                                 <varname>ConditionPathExists=</varname>
                                 is prefixed with an exclamation mark
                                 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>
 
                                 is only started if the path does not
                                 exist.</para>
 


@@ -793,7 +940,7 @@
                                 exclamation mark unset). The argument
                                 must either be a single word, or an
                                 assignment (i.e. two words, separated
                                 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
                                 case the kernel command line is
                                 searched for the word appearing as is,
                                 or as left hand side of an


@@ -836,8 +983,11 @@
                                 <para><varname>ConditionSecurity=</varname>
                                 may be used to check whether the given
                                 security module is enabled on the
                                 <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>
                                 The test may be negated by prepending
                                 an exclamation
                                 mark.</para>


@@ -944,7 +1094,7 @@
                 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
                 tool during installation of a unit:</para>
 
                 <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>
 
                         <varlistentry>
                                 <term><varname>Alias=</varname></term>
 


@@ -984,17 +1134,22 @@
                                 <term><varname>Also=</varname></term>
 
                                 <listitem><para>Additional units to
                                 <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>
                                 <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>
 
                                 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>
         </refsect1>
 
         <refsect1>


@@ -1053,7 +1208,7 @@
                       <row>
                         <entry><literal>%f</literal></entry>
                         <entry>Unescaped file name</entry>
                       <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>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>%c</literal></entry>


@@ -1062,13 +1217,13 @@
                       </row>
                       <row>
                         <entry><literal>%r</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>
                       </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>
                       <row>
                         <entry><literal>%t</literal></entry>


@@ -1093,7 +1248,7 @@
                       <row>
                         <entry><literal>%s</literal></entry>
                         <entry>User shell</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>
                       <row>
                         <entry><literal>%m</literal></entry>


@@ -1110,6 +1265,11 @@
                         <entry>Host name</entry>
                         <entry>The host name of the running system.</entry>
                       </row>
                         <entry>Host name</entry>
                         <entry>The host name of the running system.</entry>
                       </row>

+                      <row>
+                        <entry><literal>%%</literal></entry>
+                        <entry>Escaped %</entry>
+                        <entry>Single percent sign.</entry>
+                      </row>

                     </tbody>
                   </tgroup>
                 </table>
                     </tbody>
                   </tgroup>
                 </table>