From b82f27e7a31d6fdc1738aa9e0f73e3b800f64cad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Thu, 8 Feb 2018 16:23:43 +0100 Subject: [PATCH] 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 this. This is necessary to keep everyting in one logical XML line so that docbook renders the table properly. Replaces #8050. --- man/systemd.generator.xml | 82 +++++++++++++++++---------- man/systemd.unit.xml | 115 +++++++++++++++++++++++++++++++------- 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 @@ Description - Generators are small executables that live in &systemgeneratordir;/ and other - directories listed above. - systemd1 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 - .d/ 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. + Generators are small executables that live in + &systemgeneratordir;/ and other directories listed above. + systemd1 + 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. + + 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 + .d/ 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 + systemd1, + allowing generated configuration to extend or override existing + definitions. + + Directory paths for generator output differ by priority: + …/generator.early has priority higher than the admin + configuration in /etc, while + …/generator has lower priority than + /etc but higher than vendor configuration in + /usr, and …/generator.late has priority + lower than all other configuration. See the next section and the discussion of + unit load paths and unit overriding in + systemd.unit5. + Generators are loaded from a set of paths determined during compilation, as listed above. System and user generators are loaded @@ -110,40 +129,45 @@ - Writing generators + Output directories - Generators are invoked with three arguments: paths to - runtime directories where generators can place their generated - unit files or symlinks. + 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 + systemd, but a generator may be called with different paths + for debugging purposes. normal-dir - argv[1] may be used to override unit files in - /usr, but not those in - /run or in /etc. - This means that unit files placed - in this directory take precedence over vendor unit - configuration but not over native user/administrator unit - configuration. + In normal use this is /run/systemd/generator in + case of the system generators and + $XDG_RUNTIME_DIR/generator 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. + early-dir - argv[2] may be used to override unit files in - /usr, in /run and in - /etc. This means that unit files placed - in this directory take precedence over all configuration, - both vendor and user/administrator. + In normal use this is /run/systemd/generator.early + in case of the system generators and + $XDG_RUNTIME_DIR/generator.early in case of the user + generators. Unit files placed in this directory override unit files in + /usr, /run and + /etc. This means that unit files placed in this + directory take precedence over all normal configuration, both vendor and + user/administrator. late-dir - 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. - + In normal use this is /run/systemd/generator.late + in case of the system generators and + $XDG_RUNTIME_DIR/generator.late 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. 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 @@ slice.slice, scope.scope - /etc/systemd/system/* + /etc/systemd/system.control/* +/run/systemd/system.control/* +/run/systemd/transient/* +/run/systemd/generator.early/* +/etc/systemd/system/* /run/systemd/system/* -/usr/lib/systemd/system/* +/run/systemd/generator/* … +/usr/lib/systemd/system/* +/run/systemd/generator.late/* - ~/.config/systemd/user/* + ~/.config/systemd/user.control/* +$XDG_RUNTIME_DIR/systemd/user.control/* +$XDG_RUNTIME_DIR/systemd/transient/* +$XDG_RUNTIME_DIR/systemd/generator.early/* +~/.config/systemd/user/* /etc/systemd/user/* $XDG_RUNTIME_DIR/systemd/user/* /run/systemd/user/* +$XDG_RUNTIME_DIR/systemd/generator/* ~/.local/share/systemd/user/* -/usr/lib/systemd/user/* … +/usr/lib/systemd/user/* +$XDG_RUNTIME_DIR/systemd/generator.late/* @@ -342,6 +354,22 @@ + + /etc/systemd/system.control + Persistent and transient configuration created using the dbus API + + + /run/systemd/system.control + + + /run/systemd/transient + Dynamic configuration for transient units + + + /run/systemd/generator.early + Generated units with high priority (see early-dir in system.generator7) + /etc/systemd/system Local configuration @@ -350,9 +378,22 @@ /run/systemd/system Runtime units + + /run/systemd/generator + Generated units with medium priority (see normal-dir in system.generator7) + + + /usr/local/lib/systemd/system + Units of installed packages + /usr/lib/systemd/system - Units of installed packages + + + /run/systemd/generator.late + Generated units with low priority (see late-dir in system.generator7) @@ -374,12 +415,25 @@ - $XDG_CONFIG_HOME/systemd/user - User configuration (only used when $XDG_CONFIG_HOME is set) + $XDG_CONFIG_HOME/systemd/user.control or ~/.config/systemd/user.control + Persistent and transient configuration created using the dbus API ($XDG_CONFIG_HOME is used if set, ~/.config otherwise) - $HOME/.config/systemd/user - User configuration (only used when $XDG_CONFIG_HOME is not set) + $XDG_RUNTIME_DIR/systemd/user.control + + + /run/systemd/transient + Dynamic configuration for transient units + + + /run/systemd/generator.early + Generated units with high priority (see early-dir in system.generator7) + + + $XDG_CONFIG_HOME/systemd/user or $HOME/.config/systemd/user + User configuration ($XDG_CONFIG_HOME is used if set, ~/.config otherwise) /etc/systemd/user @@ -394,27 +448,50 @@ Runtime units - $XDG_DATA_HOME/systemd/user - Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is set) + $XDG_RUNTIME_DIR/systemd/generator + Generated units with medium priority (see normal-dir in system.generator7) - $HOME/.local/share/systemd/user - Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is not set) + $XDG_DATA_HOME/systemd/user or $HOME/.local/share/systemd/user + Units of packages that have been installed in the home directory ($XDG_DATA_HOME is used if set, ~/.local/share otherwise) + + + $dir/systemd/user for each $dir in $XDG_DATA_DIRS + Additional locations for installed user units, one for each entry in $XDG_DATA_DIRS + + + /usr/local/lib/systemd/user + Units of packages that have been installed system-wide /usr/lib/systemd/user - Units of packages that have been installed system-wide + + + $XDG_RUNTIME_DIR/systemd/generator.late + Generated units with low priority (see late-dir in system.generator7) - Additional units might be loaded into systemd ("linked") - from directories not on the unit load path. See the - link command for + 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 + system.environment-generator7. + In particular, $XDG_DATA_HOME and + $XDG_DATA_DIRS may be easily set using + systemd-environment-d-generator8. + 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 + systemd-analyze --user unit-paths + + + Moreover, additional units might be loaded into systemd ("linked") from + directories not on the unit load path. See the link command + for systemctl1. - Also, some units are dynamically created via a - systemd.generator7.