picnoir
/
Systemd
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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.
This commit is contained in:
Zbigniew Jędrzejewski-Szmek 2018-02-08 16:23:43 +01:00
parent 0d6671b2ef
commit b82f27e7a3
2 changed files with 149 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

82
man/systemd.generator.xml
View File

@ -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>

115
man/systemd.unit.xml
View File

@ -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>
@ -342,6 +354,22 @@
</row>
</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>
@ -350,9 +378,22 @@
<entry><filename>/run/systemd/system</filename></entry>
<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>$HOME/.config/systemd/user</filename></entry>
<entry>User configuration (only used when $XDG_CONFIG_HOME is not set)</entry>
<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>$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>