X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsystemd.unit.xml;h=47c50315ae941e58d5b923da3b8e89a355d37d8c;hb=cb0dac0548e5e51ba21618bfe4711dc1a2bbcfb5;hp=d43f288b81edf280b14699d49f291e14436978ea;hpb=9cc2c8b763fb4b9ddda95756a727a438a0d2a012;p=elogind.git

diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index d43f288b8..47c50315a 100644
--- 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"
-        "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.
@@ -48,16 +51,28 @@
         </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>
@@ -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
-                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
@@ -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
-                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
@@ -159,11 +189,10 @@
 
                 <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
@@ -215,6 +244,153 @@
 
         </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 session 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</entry>
+                      </row>
+                      <row>
+                        <entry><filename>&SYSTEM_CONFIG_UNIT_PATH;</filename></entry>
+                        <entry morerows='1'>Local configuration</entry>
+                      </row>
+                      <row>
+                        <entry><filename>/etc/systemd/system</filename></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</entry>
+                      </row>
+                      <row>
+                        <entry><filename>/usr/local/lib/systemd/system</filename></entry>
+                        <entry>Units for local packages</entry>
+                      </row>
+                      <row>
+                        <entry><filename>&systemunitdir;</filename></entry>
+                        <entry>Systemd package configuration</entry>
+                      </row>
+                      <row>
+                        <entry><filename>/usr/lib/systemd/system</filename></entry>
+                        <entry morerows='1'>Units for installed packages</entry>
+                      </row>
+                      <row>
+                        <entry><filename>/lib/systemd/system</filename></entry>
+                      </row>
+                      <row>
+                        <entry><filename>/run/systemd/generator.late</filename></entry>
+                        <entry>Generated units</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</entry>
+                      </row>
+                      <row>
+                        <entry><filename>&USER_CONFIG_UNIT_PATH;</filename></entry>
+                        <entry morerows='1'>Local configuration</entry>
+                      </row>
+                      <row>
+                        <entry><filename>/etc/systemd/user</filename></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</entry>
+                      </row>
+                      <row>
+                        <entry><filename>/usr/local/lib/systemd/user</filename></entry>
+                        <entry morerows='1'>Units for local packages</entry>
+                      </row>
+                      <row>
+                        <entry><filename>/usr/local/share/systemd/user</filename></entry>
+                      </row>
+                      <row>
+                        <entry><filename>&userunitdir;</filename></entry>
+                        <entry>Systemd package configuration</entry>
+                      </row>
+                      <row>
+                        <entry><filename>/usr/lib/systemd/user</filename></entry>
+                        <entry morerows='1'>Units for installed packages</entry>
+                      </row>
+                      <row>
+                        <entry><filename>/usr/share/systemd/user</filename></entry>
+                      </row>
+                      <row>
+                        <entry><filename>/tmp/systemd-generator.late.<replaceable>XXXXXX</replaceable></filename></entry>
+                        <entry>Generated units</entry>
+                      </row>
+                    </tbody>
+                  </tgroup>
+                </table>
+
+                <para>Note: the paths listed above are set at
+                compilation time and differ between distributions. The
+                "authorative" list is printed by
+                <command>systemd</command> at during start and daemon
+                reconfiguration.</para>
+
+                <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>
 
@@ -222,7 +398,7 @@
                 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>
@@ -254,8 +430,13 @@
                                 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>
@@ -907,8 +1088,12 @@
                                 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>
@@ -935,7 +1120,7 @@
                 <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>
 
@@ -986,6 +1171,10 @@
                         </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>
@@ -1084,7 +1273,14 @@
                       <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>
@@ -1101,6 +1297,11 @@
                         <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>