diff --git a/man/systemd.generator.xml b/man/systemd.generator.xml index fb521726e3..287d4a8f4b 100644 --- a/man/systemd.generator.xml +++ b/man/systemd.generator.xml @@ -51,95 +51,79 @@ directories listed above. systemd1 will execute these 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 to the service manager into - dynamically generated unit files, symlinks or unit file drop-ins, so that they can extend the unit file - hierarchy the service manager subsequently loads and operates on. + loaded. Their main purpose is to convert configuration and execution context parameters that are not + native to the service manager into dynamically generated unit files, symlinks or unit file drop-ins, so + that they can extend the unit file hierarchy the service manager subsequently loads and operates + on. - 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. + 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 + 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 - from directories with names ending in - system-generators/ and - user-generators/, respectively. Generators - found in directories listed earlier override the ones with the - same name in directories lower in the list. A symlink to - /dev/null or an empty file can be used to - mask a generator, thereby preventing it from running. Please note - that the order of the two directories with the highest priority is - reversed with respect to the unit load path, and generators in - /run/ overwrite those in - /etc/. + Generators are loaded from a set of paths determined during compilation, as listed above. System + and user generators are loaded from directories with names ending in + system-generators/ and user-generators/, + respectively. Generators found in directories listed earlier override the ones with the same name in + directories lower in the list. A symlink to /dev/null or an empty file can be used + to mask a generator, thereby preventing it from running. Please note that the order of the two + directories with the highest priority is reversed with respect to the unit load path, and generators in + /run/ overwrite those in /etc/. - After installing new generators or updating the - configuration, systemctl daemon-reload may be - executed. This will delete the previous configuration created by - generators, re-run all generators, and cause - systemd to reload units from disk. See - systemctl1 - for more information. + After installing new generators or updating the configuration, systemctl + daemon-reload may be executed. This will delete the previous configuration created by + generators, re-run all generators, and cause systemd to reload units from disk. See + systemctl1 for more + information. Output directories - 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. + 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 - 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. + 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 - 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. + 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 - 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. + 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. @@ -149,9 +133,8 @@ - All generators are executed in parallel. That means all executables are - started at the very same time and need to be able to cope with this - parallelism. + All generators are executed in parallel. That means all executables are started at the very + same time and need to be able to cope with this parallelism. @@ -169,9 +152,9 @@ - Units written by generators are removed when the configuration is - reloaded. That means the lifetime of the generated units is closely bound to - the reload cycles of systemd itself. + Units written by generators are removed when the configuration is reloaded. That means the + lifetime of the generated units is closely bound to the reload cycles of systemd + itself. @@ -193,8 +176,8 @@ Since syslog3 - is not available (see above), log messages have to be written to - /dev/kmsg instead. + is not available (see above), log messages have to be written to /dev/kmsg + instead. @@ -210,48 +193,44 @@ - Generators may write out dynamic unit files or just hook unit files - into other units with the usual .wants/ or - .requires/ symlinks. Often, it is nicer to simply - instantiate a template unit file from /usr/ with a - generator instead of writing out entirely dynamic unit files. Of course, this - works only if a single parameter is to be used. + Generators may write out dynamic unit files or just hook unit files into other units with the + usual .wants/ or .requires/ symlinks. Often, it is nicer to + simply instantiate a template unit file from /usr/ with a generator instead of + writing out entirely dynamic unit files. Of course, this works only if a single parameter is to be + used. - If you are careful, you can implement generators in shell scripts. We - do recommend C code however, since generators are executed synchronously and - hence delay the entire boot if they are slow. + If you are careful, you can implement generators in shell scripts. We do recommend C code + however, since generators are executed synchronously and hence delay the entire boot if they are + slow. - Regarding overriding semantics: there are two rules we try to follow - when thinking about the overriding semantics: + Regarding overriding semantics: there are two rules we try to follow when thinking about the + overriding semantics: - User configuration should override vendor configuration. This - (mostly) means that stuff from /etc/ should override - stuff from /usr/. + User configuration should override vendor configuration. This (mostly) means that stuff + from /etc/ should override stuff from /usr/. - Native configuration should override non-native configuration. This - (mostly) means that stuff you generate should never override native unit - files for the same purpose. + Native configuration should override non-native configuration. This (mostly) means that + stuff you generate should never override native unit files for the same purpose. - Of these two rules the first rule is probably the more important one - and breaks the second one sometimes. Hence, when deciding whether to use - argv[1], argv[2], or argv[3], your default choice should probably be - argv[1]. + Of these two rules the first rule is probably the more important one and breaks the second one + sometimes. Hence, when deciding whether to use argv[1], argv[2], or argv[3], your default choice + should probably be argv[1]. - Instead of heading off now and writing all kind of generators for - legacy configuration file formats, please think twice! It is often a better - idea to just deprecate old stuff instead of keeping it artificially alive. + Instead of heading off now and writing all kind of generators for legacy configuration file + formats, please think twice! It is often a better idea to just deprecate old stuff instead of keeping + it artificially alive. @@ -263,17 +242,15 @@ systemd-fstab-generator systemd-fstab-generator8 - converts /etc/fstab into native mount units. It uses - argv[1] as location to place the generated unit files in order to allow the - user to override /etc/fstab with their own native unit - files, but also to ensure that /etc/fstab overrides any + converts /etc/fstab into native mount units. It uses argv[1] as location to place + the generated unit files in order to allow the user to override /etc/fstab with + their own native unit files, but also to ensure that /etc/fstab overrides any vendor default from /usr/. - After editing /etc/fstab, the user should invoke - systemctl daemon-reload. This will re-run all generators and - cause systemd to reload units from disk. To actually mount - new directories added to fstab, systemctl start - /path/to/mountpoint or systemctl + After editing /etc/fstab, the user should invoke systemctl + daemon-reload. This will re-run all generators and cause systemd to reload + units from disk. To actually mount new directories added to fstab, + systemctl start /path/to/mountpoint or systemctl start local-fs.target may be used. @@ -281,11 +258,9 @@ systemd-system-update-generator systemd-system-update-generator8 - temporarily redirects default.target to - system-update.target, if a system update is - scheduled. Since this needs to override the default user configuration for - default.target, it uses argv[2]. For details about this - logic, see + temporarily redirects default.target to system-update.target, + if a system update is scheduled. Since this needs to override the default user configuration for + default.target, it uses argv[2]. For details about this logic, see systemd.offline-updates7.