Skip to content

Commit b82f27e

Browse files
keszybzkeszybz
committed
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 systemd#8050.
1 parent 0d6671b commit b82f27e

File tree

2 files changed

+149
-48
lines changed

2 files changed

+149
-48
lines changed

‎man/systemd.generator.xml‎

Lines changed: 53 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -76,14 +76,33 @@
7676

7777
<refsect1>
7878
<title>Description</title>
79-
<para>Generators are small executables that live in <filename>&systemgeneratordir;/</filename> and other
80-
directories listed above.
81-
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> will execute those
82-
binaries very early at bootup and at configuration reload time — before unit files are loaded. Generators may
83-
dynamically generate unit files (regular ones, instances as well as templates) and unit file
84-
<filename>.d/</filename> drop-ins, or create symbolic links to unit files to add additional dependencies or
85-
instantiate existing templates, thus extending or overriding existing definitions. Their main purpose is to convert
86-
configuration files that are not native unit files dynamically into native unit files.</para>
79+
<para>Generators are small executables that live in
80+
<filename>&systemgeneratordir;/</filename> and other directories listed above.
81+
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
82+
will execute those binaries very early at bootup and at configuration reload time
83+
— before unit files are loaded. Their main purpose is to convert configuration
84+
that is not native into dynamically generated unit files.</para>
85+
86+
<para>Each generator is called with three directory paths that are to be used for
87+
generator output. In these three directories, generators may dynamically generate
88+
unit files (regular ones, instances, as well as templates), unit file
89+
<filename>.d/</filename> drop-ins, and create symbolic links to unit files to add
90+
additional dependencies, create aliases, or instantiate existing templates. Those
91+
directories are included in the unit load path of
92+
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
93+
allowing generated configuration to extend or override existing
94+
definitions.</para>
95+
96+
<para>Directory paths for generator output differ by priority:
97+
<filename>…/generator.early</filename> has priority higher than the admin
98+
configuration in <filename>/etc</filename>, while
99+
<filename>…/generator</filename> has lower priority than
100+
<filename>/etc</filename> but higher than vendor configuration in
101+
<filename>/usr</filename>, and <filename>…/generator.late</filename> has priority
102+
lower than all other configuration. See the next section and the discussion of
103+
unit load paths and unit overriding in
104+
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
105+
</para>
87106

88107
<para>Generators are loaded from a set of paths determined during
89108
compilation, as listed above. System and user generators are loaded
@@ -110,40 +129,45 @@
110129
</refsect1>
111130

112131
<refsect1>
113-
<title>Writing generators</title>
132+
<title>Output directories</title>
114133

115-
<para>Generators are invoked with three arguments: paths to
116-
runtime directories where generators can place their generated
117-
unit files or symlinks.</para>
134+
<para>Generators are invoked with three arguments: paths to directories where
135+
generators can place their generated unit files or symlinks. By default those
136+
paths are runtime directories that are included in the search path of
137+
<command>systemd</command>, but a generator may be called with different paths
138+
for debugging purposes.</para>
118139

119140
<orderedlist>
120141
<listitem>
121142
<para><parameter>normal-dir</parameter></para>
122-
<para>argv[1] may be used to override unit files in
123-
<filename>/usr</filename>, but not those in
124-
<filename>/run</filename> or in <filename>/etc</filename>.
125-
This means that unit files placed
126-
in this directory take precedence over vendor unit
127-
configuration but not over native user/administrator unit
128-
configuration.</para>
143+
<para>In normal use this is <filename>/run/systemd/generator</filename> in
144+
case of the system generators and
145+
<filename>$XDG_RUNTIME_DIR/generator</filename> in case of the user
146+
generators. Unit files placed in this directory take precedence over vendor
147+
unit configuration but not over native user/administrator unit configuration.
148+
</para>
129149
</listitem>
130150

131151
<listitem>
132152
<para><parameter>early-dir</parameter></para>
133-
<para>argv[2] may be used to override unit files in
134-
<filename>/usr</filename>, in <filename>/run</filename> and in
135-
<filename>/etc</filename>. This means that unit files placed
136-
in this directory take precedence over all configuration,
137-
both vendor and user/administrator.</para>
153+
<para>In normal use this is <filename>/run/systemd/generator.early</filename>
154+
in case of the system generators and
155+
<filename>$XDG_RUNTIME_DIR/generator.early</filename> in case of the user
156+
generators. Unit files placed in this directory override unit files in
157+
<filename>/usr</filename>, <filename>/run</filename> and
158+
<filename>/etc</filename>. This means that unit files placed in this
159+
directory take precedence over all normal configuration, both vendor and
160+
user/administrator.</para>
138161
</listitem>
139162

140163
<listitem>
141164
<para><parameter>late-dir</parameter></para>
142-
<para>argv[3] may be used to extend the unit file tree without
143-
overriding any other unit files. Any native configuration
144-
files supplied by the vendor or user/administrator take
145-
precedence over the generated ones placed in this directory.
146-
</para>
165+
<para>In normal use this is <filename>/run/systemd/generator.late</filename>
166+
in case of the system generators and
167+
<filename>$XDG_RUNTIME_DIR/generator.late</filename> in case of the user
168+
generators. This directory may be used to extend the unit file tree without
169+
overriding any other unit files. Any native configuration files supplied by
170+
the vendor or user/administrator take precedence.</para>
147171
</listitem>
148172
</orderedlist>
149173

‎man/systemd.unit.xml‎

Lines changed: 96 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -65,19 +65,31 @@
6565
<filename><replaceable>slice</replaceable>.slice</filename>,
6666
<filename><replaceable>scope</replaceable>.scope</filename></para>
6767

68-
<para><literallayout><filename>/etc/systemd/system/*</filename>
68+
<para><literallayout><filename>/etc/systemd/system.control/*</filename>
69+
<filename>/run/systemd/system.control/*</filename>
70+
<filename>/run/systemd/transient/*</filename>
71+
<filename>/run/systemd/generator.early/*</filename>
72+
<filename>/etc/systemd/system/*</filename>
6973
<filename>/run/systemd/system/*</filename>
70-
<filename>/usr/lib/systemd/system/*</filename>
74+
<filename>/run/systemd/generator/*</filename>
7175
<filename>…</filename>
76+
<filename>/usr/lib/systemd/system/*</filename>
77+
<filename>/run/systemd/generator.late/*</filename>
7278
</literallayout></para>
7379

74-
<para><literallayout><filename>~/.config/systemd/user/*</filename>
80+
<para><literallayout><filename>~/.config/systemd/user.control/*</filename>
81+
<filename>$XDG_RUNTIME_DIR/systemd/user.control/*</filename>
82+
<filename>$XDG_RUNTIME_DIR/systemd/transient/*</filename>
83+
<filename>$XDG_RUNTIME_DIR/systemd/generator.early/*</filename>
84+
<filename>~/.config/systemd/user/*</filename>
7585
<filename>/etc/systemd/user/*</filename>
7686
<filename>$XDG_RUNTIME_DIR/systemd/user/*</filename>
7787
<filename>/run/systemd/user/*</filename>
88+
<filename>$XDG_RUNTIME_DIR/systemd/generator/*</filename>
7889
<filename>~/.local/share/systemd/user/*</filename>
79-
<filename>/usr/lib/systemd/user/*</filename>
8090
<filename>…</filename>
91+
<filename>/usr/lib/systemd/user/*</filename>
92+
<filename>$XDG_RUNTIME_DIR/systemd/generator.late/*</filename>
8193
</literallayout></para>
8294
</refsynopsisdiv>
8395

@@ -342,6 +354,22 @@
342354
</row>
343355
</thead>
344356
<tbody>
357+
<row>
358+
<entry><filename>/etc/systemd/system.control</filename></entry>
359+
<entry morerows="1">Persistent and transient configuration created using the dbus API</entry>
360+
</row>
361+
<row>
362+
<entry><filename>/run/systemd/system.control</filename></entry>
363+
</row>
364+
<row>
365+
<entry><filename>/run/systemd/transient</filename></entry>
366+
<entry>Dynamic configuration for transient units</entry>
367+
</row>
368+
<row>
369+
<entry><filename>/run/systemd/generator.early</filename></entry>
370+
<entry>Generated units with high priority (see <replaceable>early-dir</replaceable> in <citerefentry
371+
><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
372+
</row>
345373
<row>
346374
<entry><filename>/etc/systemd/system</filename></entry>
347375
<entry>Local configuration</entry>
@@ -350,9 +378,22 @@
350378
<entry><filename>/run/systemd/system</filename></entry>
351379
<entry>Runtime units</entry>
352380
</row>
381+
<row>
382+
<entry><filename>/run/systemd/generator</filename></entry>
383+
<entry>Generated units with medium priority (see <replaceable>normal-dir</replaceable> in <citerefentry
384+
><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
385+
</row>
386+
<row>
387+
<entry><filename>/usr/local/lib/systemd/system</filename></entry>
388+
<entry morerows="1">Units of installed packages</entry>
389+
</row>
353390
<row>
354391
<entry><filename>/usr/lib/systemd/system</filename></entry>
355-
<entry>Units of installed packages</entry>
392+
</row>
393+
<row>
394+
<entry><filename>/run/systemd/generator.late</filename></entry>
395+
<entry>Generated units with low priority (see <replaceable>late-dir</replaceable> in <citerefentry
396+
><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
356397
</row>
357398
</tbody>
358399
</tgroup>
@@ -374,12 +415,25 @@
374415
</thead>
375416
<tbody>
376417
<row>
377-
<entry><filename>$XDG_CONFIG_HOME/systemd/user</filename></entry>
378-
<entry>User configuration (only used when $XDG_CONFIG_HOME is set)</entry>
418+
<entry><filename>$XDG_CONFIG_HOME/systemd/user.control</filename> or <filename
419+
>~/.config/systemd/user.control</filename></entry>
420+
<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>
421+
</row>
422+
<row>
423+
<entry><filename>$XDG_RUNTIME_DIR/systemd/user.control</filename></entry>
424+
</row>
425+
<row>
426+
<entry><filename>/run/systemd/transient</filename></entry>
427+
<entry>Dynamic configuration for transient units</entry>
428+
</row>
429+
<row>
430+
<entry><filename>/run/systemd/generator.early</filename></entry>
431+
<entry>Generated units with high priority (see <replaceable>early-dir</replaceable> in <citerefentry
432+
><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
379433
</row>
380434
<row>
381-
<entry><filename>$HOME/.config/systemd/user</filename></entry>
382-
<entry>User configuration (only used when $XDG_CONFIG_HOME is not set)</entry>
435+
<entry><filename>$XDG_CONFIG_HOME/systemd/user</filename> or <filename>$HOME/.config/systemd/user</filename></entry>
436+
<entry>User configuration (<varname>$XDG_CONFIG_HOME</varname> is used if set, <filename>~/.config</filename> otherwise)</entry>
383437
</row>
384438
<row>
385439
<entry><filename>/etc/systemd/user</filename></entry>
@@ -394,27 +448,50 @@
394448
<entry>Runtime units</entry>
395449
</row>
396450
<row>
397-
<entry><filename>$XDG_DATA_HOME/systemd/user</filename></entry>
398-
<entry>Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is set)</entry>
451+
<entry><filename>$XDG_RUNTIME_DIR/systemd/generator</filename></entry>
452+
<entry>Generated units with medium priority (see <replaceable>normal-dir</replaceable> in <citerefentry
453+
><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
399454
</row>
400455
<row>
401-
<entry><filename>$HOME/.local/share/systemd/user</filename></entry>
402-
<entry>Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is not set)</entry>
456+
<entry><filename>$XDG_DATA_HOME/systemd/user</filename> or <filename>$HOME/.local/share/systemd/user</filename></entry>
457+
<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>
458+
</row>
459+
<row>
460+
<entry><filename>$dir/systemd/user</filename> for each <varname noindex='true'>$dir</varname> in <varname>$XDG_DATA_DIRS</varname></entry>
461+
<entry>Additional locations for installed user units, one for each entry in <varname>$XDG_DATA_DIRS</varname></entry>
462+
</row>
463+
<row>
464+
<entry><filename>/usr/local/lib/systemd/user</filename></entry>
465+
<entry morerows="1">Units of packages that have been installed system-wide</entry>
403466
</row>
404467
<row>
405468
<entry><filename>/usr/lib/systemd/user</filename></entry>
406-
<entry>Units of packages that have been installed system-wide</entry>
469+
</row>
470+
<row>
471+
<entry><filename>$XDG_RUNTIME_DIR/systemd/generator.late</filename></entry>
472+
<entry>Generated units with low priority (see <replaceable>late-dir</replaceable> in <citerefentry
473+
><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry>
407474
</row>
408475
</tbody>
409476
</tgroup>
410477
</table>
411478

412-
<para>Additional units might be loaded into systemd ("linked")
413-
from directories not on the unit load path. See the
414-
<command>link</command> command for
479+
<para>The set of load paths for the user manager instance may be augmented or
480+
changed using various environment variables. And environment variables may in
481+
turn be set using environment generators, see
482+
<citerefentry><refentrytitle>system.environment-generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
483+
In particular, <varname>$XDG_DATA_HOME</varname> and
484+
<varname>$XDG_DATA_DIRS</varname> may be easily set using
485+
<citerefentry><refentrytitle>systemd-environment-d-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
486+
Thus, directories listed here are just the defaults. To see the actual list that
487+
would be used based on compilation options and current environment use
488+
<programlisting>systemd-analyze --user unit-paths</programlisting>
489+
</para>
490+
491+
<para>Moreover, additional units might be loaded into systemd ("linked") from
492+
directories not on the unit load path. See the <command>link</command> command
493+
for
415494
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
416-
Also, some units are dynamically created via a
417-
<citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
418495
</para>
419496
</refsect1>
420497

0 commit comments

Comments
 (0)