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

man: document unit load paths

Browse source 
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> <refsect1>
<title>Description</title> <title>Description</title>
<para>Generators are small executables that live in <filename>&systemgeneratordir;/</filename> and other <para>Generators are small executables that live in
directories listed above. <filename>&systemgeneratordir;/</filename> and other directories listed above.
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> will execute those <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
binaries very early at bootup and at configuration reload time — before unit files are loaded. Generators may will execute those binaries very early at bootup and at configuration reload time
dynamically generate unit files (regular ones, instances as well as templates) and unit file — before unit files are loaded. Their main purpose is to convert configuration
<filename>.d/</filename> drop-ins, or create symbolic links to unit files to add additional dependencies or that is not native into dynamically generated unit files.</para>
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>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 <para>Generators are loaded from a set of paths determined during
compilation, as listed above. System and user generators are loaded compilation, as listed above. System and user generators are loaded
@ -110,40 +129,45 @@
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>Writing generators</title> <title>Output directories</title>
<para>Generators are invoked with three arguments: paths to <para>Generators are invoked with three arguments: paths to directories where
runtime directories where generators can place their generated generators can place their generated unit files or symlinks. By default those
unit files or symlinks.</para> 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> <orderedlist>
<listitem> <listitem>
<para><parameter>normal-dir</parameter></para> <para><parameter>normal-dir</parameter></para>
<para>argv[1] may be used to override unit files in <para>In normal use this is <filename>/run/systemd/generator</filename> in
<filename>/usr</filename>, but not those in case of the system generators and
<filename>/run</filename> or in <filename>/etc</filename>. <filename>$XDG_RUNTIME_DIR/generator</filename> in case of the user
This means that unit files placed generators. Unit files placed in this directory take precedence over vendor
in this directory take precedence over vendor unit unit configuration but not over native user/administrator unit configuration.
configuration but not over native user/administrator unit </para>
configuration.</para>
</listitem> </listitem>
<listitem> <listitem>
<para><parameter>early-dir</parameter></para> <para><parameter>early-dir</parameter></para>
<para>argv[2] may be used to override unit files in <para>In normal use this is <filename>/run/systemd/generator.early</filename>
<filename>/usr</filename>, in <filename>/run</filename> and in in case of the system generators and
<filename>/etc</filename>. This means that unit files placed <filename>$XDG_RUNTIME_DIR/generator.early</filename> in case of the user
in this directory take precedence over all configuration, generators. Unit files placed in this directory override unit files in
both vendor and user/administrator.</para> <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>
<listitem> <listitem>
<para><parameter>late-dir</parameter></para> <para><parameter>late-dir</parameter></para>
<para>argv[3] may be used to extend the unit file tree without <para>In normal use this is <filename>/run/systemd/generator.late</filename>
overriding any other unit files. Any native configuration in case of the system generators and
files supplied by the vendor or user/administrator take <filename>$XDG_RUNTIME_DIR/generator.late</filename> in case of the user
precedence over the generated ones placed in this directory. generators. This directory may be used to extend the unit file tree without
</para> overriding any other unit files. Any native configuration files supplied by
the vendor or user/administrator take precedence.</para>
</listitem> </listitem>
</orderedlist> </orderedlist>

115
man/systemd.unit.xml
View file

@ -65,19 +65,31 @@
<filename><replaceable>slice</replaceable>.slice</filename>, <filename><replaceable>slice</replaceable>.slice</filename>,
<filename><replaceable>scope</replaceable>.scope</filename></para> <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>/run/systemd/system/*</filename>
<filename>/usr/lib/systemd/system/*</filename> <filename>/run/systemd/generator/*</filename>
<filename>…</filename> <filename>…</filename>
<filename>/usr/lib/systemd/system/*</filename>
<filename>/run/systemd/generator.late/*</filename>
</literallayout></para> </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>/etc/systemd/user/*</filename>
<filename>$XDG_RUNTIME_DIR/systemd/user/*</filename> <filename>$XDG_RUNTIME_DIR/systemd/user/*</filename>
<filename>/run/systemd/user/*</filename> <filename>/run/systemd/user/*</filename>
<filename>$XDG_RUNTIME_DIR/systemd/generator/*</filename>
<filename>~/.local/share/systemd/user/*</filename> <filename>~/.local/share/systemd/user/*</filename>
<filename>/usr/lib/systemd/user/*</filename>
<filename>…</filename> <filename>…</filename>
<filename>/usr/lib/systemd/user/*</filename>
<filename>$XDG_RUNTIME_DIR/systemd/generator.late/*</filename>
</literallayout></para> </literallayout></para>
</refsynopsisdiv> </refsynopsisdiv>
@ -342,6 +354,22 @@
</row> </row>
</thead> </thead>
<tbody> <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> <row>
<entry><filename>/etc/systemd/system</filename></entry> <entry><filename>/etc/systemd/system</filename></entry>
<entry>Local configuration</entry> <entry>Local configuration</entry>
@ -350,9 +378,22 @@
<entry><filename>/run/systemd/system</filename></entry> <entry><filename>/run/systemd/system</filename></entry>
<entry>Runtime units</entry> <entry>Runtime units</entry>
</row> </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> <row>
<entry><filename>/usr/lib/systemd/system</filename></entry> <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> </row>
</tbody> </tbody>
</tgroup> </tgroup>
@ -374,12 +415,25 @@
</thead> </thead>
<tbody> <tbody>
<row> <row>
<entry><filename>$XDG_CONFIG_HOME/systemd/user</filename></entry> <entry><filename>$XDG_CONFIG_HOME/systemd/user.control</filename> or <filename
<entry>User configuration (only used when $XDG_CONFIG_HOME is set)</entry> >~/.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>
<row> <row>
<entry><filename>$HOME/.config/systemd/user</filename></entry> <entry><filename>$XDG_RUNTIME_DIR/systemd/user.control</filename></entry>
<entry>User configuration (only used when $XDG_CONFIG_HOME is not set)</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>
<row> <row>
<entry><filename>/etc/systemd/user</filename></entry> <entry><filename>/etc/systemd/user</filename></entry>
@ -394,27 +448,50 @@
<entry>Runtime units</entry> <entry>Runtime units</entry>
</row> </row>
<row> <row>
<entry><filename>$XDG_DATA_HOME/systemd/user</filename></entry> <entry><filename>$XDG_RUNTIME_DIR/systemd/generator</filename></entry>
<entry>Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is set)</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>
<row> <row>
<entry><filename>$HOME/.local/share/systemd/user</filename></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 (only used when $XDG_DATA_HOME is not set)</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>
<row> <row>
<entry><filename>/usr/lib/systemd/user</filename></entry> <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> </row>
</tbody> </tbody>
</tgroup> </tgroup>
</table> </table>
<para>Additional units might be loaded into systemd ("linked") <para>The set of load paths for the user manager instance may be augmented or
from directories not on the unit load path. See the changed using various environment variables. And environment variables may in
<command>link</command> command for 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>. <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> </para>
</refsect1> </refsect1>