man: document unit load paths

So far we didn't document control, transient, dbus config, or generator paths.
But those paths are visible to users, and they need to understand why systemd
loads units from those paths, and how the precedence hierarchy looks.
The whole thing is a bit messy, since the list of paths is quite long.
I made the tables a bit shorter by combining rows for the alternatives
where $XDG_* is set and the fallback.

In various places, tags are split like <element
  param="blah">
this. This is necessary to keep everyting in one logical XML line so that
docbook renders the table properly.

Replaces #8050.

2 files changed, 149 insertions, 48 deletions

diff --git a/man/systemd.generator.xml b/man/systemd.generator.xml
index 7ed6a2dc82..a41e43df0f 100644
--- a/man/systemd.generator.xml
+++ b/man/systemd.generator.xml
@@ -76,14 +76,33 @@
 
   <refsect1>
     <title>Description</title>
-    <para>Generators are small executables that live in <filename>&systemgeneratordir;/</filename> and other
-    directories listed above.
-    <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> will execute those
-    binaries very early at bootup and at configuration reload time — before unit files are loaded.  Generators may
-    dynamically generate unit files (regular ones, instances as well as templates) and unit file
-    <filename>.d/</filename> drop-ins, or create symbolic links to unit files to add additional dependencies or
-    instantiate existing templates, thus extending or overriding existing definitions. Their main purpose is to convert
-    configuration files that are not native unit files dynamically into native unit files.</para>
+    <para>Generators are small executables that live in
+    <filename>&systemgeneratordir;/</filename> and other directories listed above.
+    <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+    will execute those binaries very early at bootup and at configuration reload time
+    — before unit files are loaded. Their main purpose is to convert configuration
+    that is not native into dynamically generated unit files.</para>
+
+    <para>Each generator is called with three directory paths that are to be used for
+    generator output. In these three directories, generators may dynamically generate
+    unit files (regular ones, instances, as well as templates), unit file
+    <filename>.d/</filename> drop-ins, and create symbolic links to unit files to add
+    additional dependencies, create aliases, or instantiate existing templates. Those
+    directories are included in the unit load path of
+    <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+    allowing generated configuration to extend or override existing
+    definitions.</para>
+
+    <para>Directory paths for generator output differ by priority:
+    <filename>…/generator.early</filename> has priority higher than the admin
+    configuration in <filename>/etc</filename>, while
+    <filename>…/generator</filename> has lower priority than
+    <filename>/etc</filename> but higher than vendor configuration in
+    <filename>/usr</filename>, and <filename>…/generator.late</filename> has priority
+    lower than all other configuration. See the next section and the discussion of
+    unit load paths and unit overriding in
+    <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+    </para>
 
     <para>Generators are loaded from a set of paths determined during
     compilation, as listed above. System and user generators are loaded
@@ -110,40 +129,45 @@
   </refsect1>
 
   <refsect1>
-    <title>Writing generators</title>
+    <title>Output directories</title>
 
-    <para>Generators are invoked with three arguments: paths to
-    runtime directories where generators can place their generated
-    unit files or symlinks.</para>
+    <para>Generators are invoked with three arguments: paths to directories where
+    generators can place their generated unit files or symlinks. By default those
+    paths are runtime directories that are included in the search path of
+    <command>systemd</command>, but a generator may be called with different paths
+    for debugging purposes.</para>
 
     <orderedlist>
       <listitem>
         <para><parameter>normal-dir</parameter></para>
-        <para>argv[1] may be used to override unit files in
-        <filename>/usr</filename>, but not those in
-        <filename>/run</filename> or in <filename>/etc</filename>.
-        This means that unit files placed
-        in this directory take precedence over vendor unit
-        configuration but not over native user/administrator unit
-        configuration.</para>
+        <para>In normal use this is <filename>/run/systemd/generator</filename> in
+        case of the system generators and
+        <filename>$XDG_RUNTIME_DIR/generator</filename> in case of the user
+        generators. Unit files placed in this directory take precedence over vendor
+        unit configuration but not over native user/administrator unit configuration.
+        </para>
       </listitem>
 
       <listitem>
         <para><parameter>early-dir</parameter></para>
-        <para>argv[2] may be used to override unit files in
-        <filename>/usr</filename>, in <filename>/run</filename> and in
-        <filename>/etc</filename>. This means that unit files placed
-        in this directory take precedence over all configuration,
-        both vendor and user/administrator.</para>
+        <para>In normal use this is <filename>/run/systemd/generator.early</filename>
+        in case of the system generators and
+        <filename>$XDG_RUNTIME_DIR/generator.early</filename> in case of the user
+        generators. Unit files placed in this directory override unit files in
+        <filename>/usr</filename>, <filename>/run</filename> and
+        <filename>/etc</filename>. This means that unit files placed in this
+        directory take precedence over all normal configuration, both vendor and
+        user/administrator.</para>
       </listitem>
 
       <listitem>
         <para><parameter>late-dir</parameter></para>
-        <para>argv[3] may be used to extend the unit file tree without
-        overriding any other unit files. Any native configuration
-        files supplied by the vendor or user/administrator take
-        precedence over the generated ones placed in this directory.
-        </para>
+        <para>In normal use this is <filename>/run/systemd/generator.late</filename>
+        in case of the system generators and
+        <filename>$XDG_RUNTIME_DIR/generator.late</filename> in case of the user
+        generators. This directory may be used to extend the unit file tree without
+        overriding any other unit files. Any native configuration files supplied by
+        the vendor or user/administrator take precedence.</para>
       </listitem>
     </orderedlist>
 
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index 90ca378e84..0e27c5dd8e 100644
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -65,19 +65,31 @@
     <filename><replaceable>slice</replaceable>.slice</filename>,
     <filename><replaceable>scope</replaceable>.scope</filename></para>
 
-    <para><literallayout><filename>/etc/systemd/system/*</filename>
+    <para><literallayout><filename>/etc/systemd/system.control/*</filename>
+<filename>/run/systemd/system.control/*</filename>
+<filename>/run/systemd/transient/*</filename>
+<filename>/run/systemd/generator.early/*</filename>
+<filename>/etc/systemd/system/*</filename>
 <filename>/run/systemd/system/*</filename>
-<filename>/usr/lib/systemd/system/*</filename>
+<filename>/run/systemd/generator/*</filename>
 <filename>…</filename>
+<filename>/usr/lib/systemd/system/*</filename>
+<filename>/run/systemd/generator.late/*</filename>
     </literallayout></para>
 
-    <para><literallayout><filename>~/.config/systemd/user/*</filename>
+    <para><literallayout><filename>~/.config/systemd/user.control/*</filename>
+<filename>$XDG_RUNTIME_DIR/systemd/user.control/*</filename>
+<filename>$XDG_RUNTIME_DIR/systemd/transient/*</filename>
+<filename>$XDG_RUNTIME_DIR/systemd/generator.early/*</filename>
+<filename>~/.config/systemd/user/*</filename>
 <filename>/etc/systemd/user/*</filename>
 <filename>$XDG_RUNTIME_DIR/systemd/user/*</filename>
 <filename>/run/systemd/user/*</filename>
+<filename>$XDG_RUNTIME_DIR/systemd/generator/*</filename>
 <filename>~/.local/share/systemd/user/*</filename>
-<filename>/usr/lib/systemd/user/*</filename>
 <filename>…</filename>
+<filename>/usr/lib/systemd/user/*</filename>
+<filename>$XDG_RUNTIME_DIR/systemd/generator.late/*</filename>
     </literallayout></para>
   </refsynopsisdiv>
 
@@ -343,6 +355,22 @@
         </thead>
         <tbody>
           <row>
+            <entry><filename>/etc/systemd/system.control</filename></entry>
+            <entry morerows="1">Persistent and transient configuration created using the dbus API</entry>
+          </row>
+          <row>
+            <entry><filename>/run/systemd/system.control</filename></entry>
+          </row>
+          <row>
+            <entry><filename>/run/systemd/transient</filename></entry>
+            <entry>Dynamic configuration for transient units</entry>
+          </row>
+          <row>
+            <entry><filename>/run/systemd/generator.early</filename></entry>
+            <entry>Generated units with high priority (see <replaceable>early-dir</replaceable> in <citerefentry
+            ><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
+          </row>
+          <row>
             <entry><filename>/etc/systemd/system</filename></entry>
             <entry>Local configuration</entry>
           </row>
@@ -351,8 +379,21 @@
             <entry>Runtime units</entry>
           </row>
           <row>
+            <entry><filename>/run/systemd/generator</filename></entry>
+            <entry>Generated units with medium priority (see <replaceable>normal-dir</replaceable> in <citerefentry
+            ><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
+          </row>
+          <row>
+            <entry><filename>/usr/local/lib/systemd/system</filename></entry>
+            <entry morerows="1">Units of installed packages</entry>
+          </row>
+          <row>
             <entry><filename>/usr/lib/systemd/system</filename></entry>
-            <entry>Units of installed packages</entry>
+          </row>
+          <row>
+            <entry><filename>/run/systemd/generator.late</filename></entry>
+            <entry>Generated units with low priority (see <replaceable>late-dir</replaceable> in <citerefentry
+            ><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
           </row>
         </tbody>
       </tgroup>
@@ -374,12 +415,25 @@
         </thead>
         <tbody>
           <row>
-            <entry><filename>$XDG_CONFIG_HOME/systemd/user</filename></entry>
-            <entry>User configuration (only used when $XDG_CONFIG_HOME is set)</entry>
+            <entry><filename>$XDG_CONFIG_HOME/systemd/user.control</filename> or <filename
+            >~/.config/systemd/user.control</filename></entry>
+            <entry morerows="1">Persistent and transient configuration created using the dbus API (<varname>$XDG_CONFIG_HOME</varname> is used if set, <filename>~/.config</filename> otherwise)</entry>
+          </row>
+          <row>
+            <entry><filename>$XDG_RUNTIME_DIR/systemd/user.control</filename></entry>
+          </row>
+          <row>
+            <entry><filename>/run/systemd/transient</filename></entry>
+            <entry>Dynamic configuration for transient units</entry>
+          </row>
+          <row>
+            <entry><filename>/run/systemd/generator.early</filename></entry>
+            <entry>Generated units with high priority (see <replaceable>early-dir</replaceable> in <citerefentry
+            ><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
           </row>
           <row>
-            <entry><filename>$HOME/.config/systemd/user</filename></entry>
-            <entry>User configuration (only used when $XDG_CONFIG_HOME is not set)</entry>
+            <entry><filename>$XDG_CONFIG_HOME/systemd/user</filename> or <filename>$HOME/.config/systemd/user</filename></entry>
+            <entry>User configuration (<varname>$XDG_CONFIG_HOME</varname> is used if set, <filename>~/.config</filename> otherwise)</entry>
           </row>
           <row>
             <entry><filename>/etc/systemd/user</filename></entry>
@@ -394,27 +448,50 @@
             <entry>Runtime units</entry>
           </row>
           <row>
-            <entry><filename>$XDG_DATA_HOME/systemd/user</filename></entry>
-            <entry>Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is set)</entry>
+            <entry><filename>$XDG_RUNTIME_DIR/systemd/generator</filename></entry>
+            <entry>Generated units with medium priority (see <replaceable>normal-dir</replaceable> in <citerefentry
+            ><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
           </row>
           <row>
-            <entry><filename>$HOME/.local/share/systemd/user</filename></entry>
-            <entry>Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is not set)</entry>
+            <entry><filename>$XDG_DATA_HOME/systemd/user</filename> or <filename>$HOME/.local/share/systemd/user</filename></entry>
+            <entry>Units of packages that have been installed in the home directory (<varname>$XDG_DATA_HOME</varname> is used if set, <filename>~/.local/share</filename> otherwise)</entry>
+          </row>
+          <row>
+            <entry><filename>$dir/systemd/user</filename> for each <varname noindex='true'>$dir</varname> in <varname>$XDG_DATA_DIRS</varname></entry>
+            <entry>Additional locations for installed user units, one for each entry in <varname>$XDG_DATA_DIRS</varname></entry>
+          </row>
+          <row>
+            <entry><filename>/usr/local/lib/systemd/user</filename></entry>
+            <entry morerows="1">Units of packages that have been installed system-wide</entry>
           </row>
           <row>
             <entry><filename>/usr/lib/systemd/user</filename></entry>
-            <entry>Units of packages that have been installed system-wide</entry>
+          </row>
+          <row>
+            <entry><filename>$XDG_RUNTIME_DIR/systemd/generator.late</filename></entry>
+            <entry>Generated units with low priority (see <replaceable>late-dir</replaceable> in <citerefentry
+            ><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</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
+    <para>The set of load paths for the user manager instance may be augmented or
+    changed using various environment variables. And environment variables may in
+    turn be set using environment generators, see
+    <citerefentry><refentrytitle>system.environment-generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+    In particular, <varname>$XDG_DATA_HOME</varname> and
+    <varname>$XDG_DATA_DIRS</varname> may be easily set using
+    <citerefentry><refentrytitle>systemd-environment-d-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
+    Thus, directories listed here are just the defaults. To see the actual list that
+    would be used based on compilation options and current environment use
+    <programlisting>systemd-analyze --user unit-paths</programlisting>
+    </para>
+
+    <para>Moreover, 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>.
-    Also, some units are dynamically created via a
-    <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
     </para>
   </refsect1>