kdbus: update to newest kdbus API

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

diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index d43f288b81edf280b14699d49f291e14436978ea..47c50315ae941e58d5b923da3b8e89a355d37d8c 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,11 +189,10 @@
 
                 <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
                 file system name space. Example: a device unit
 
                 <para>Some unit names reflect paths existing in the
                 file system name space. Example: a device unit


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


@@ -222,7 +398,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>


@@ -254,8 +430,13 @@
                                 reference documentation that explains
                                 what the unit's purpose is, followed
                                 by how it is configured, followed by
                                 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>
                         </varlistentry>
 
                         <varlistentry>


@@ -907,8 +1088,12 @@
                                 pipe symbol must be passed first, the
                                 exclamation second. Except for
                                 <varname>ConditionPathIsSymbolicLink=</varname>,
                                 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>
                         </varlistentry>
 
                         <varlistentry>


@@ -935,7 +1120,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>
 


@@ -986,6 +1171,10 @@
                         </varlistentry>
                 </variablelist>
 
                         </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>


@@ -1084,7 +1273,14 @@
                       <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>


@@ -1101,6 +1297,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>