X-Git-Url: http://git.ipfire.org/?a=blobdiff_plain;f=man%2Fsystemd.generator.xml;h=c77afda0f2193e16113b7baf79ca987da558cef6;hb=5057d73ba1bb016c9325d0a7fdb84519d3443622;hp=5e25bb776d25976bb1e64b366ee4d9d63b89c731;hpb=3529295d2b9113ae6f41797fe11121181fa01cbd;p=thirdparty%2Fsystemd.git diff --git a/man/systemd.generator.xml b/man/systemd.generator.xml index 5e25bb776d2..c77afda0f21 100644 --- a/man/systemd.generator.xml +++ b/man/systemd.generator.xml @@ -1,44 +1,15 @@ - %entities; ]> - - + systemd.generator systemd - - - - Developer - Lennart - Poettering - lennart@poettering.net - - @@ -76,14 +47,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,171 +100,156 @@ - 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. + + + + Notes about writing generators - - Notes - - - - - 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. - - - - - - Generators are run very early at boot and cannot rely on - any external services. They may not talk to any other - process. That includes simple things such as logging to - syslog3, - or systemd itself (this means: no - systemctl1)! - Non-essential file systems like - /var and /home - are mounted after generators have run. Generators - can however rely on the most basic kernel functionality to be - available, including a mounted /sys, - /proc, /dev, - /usr. - - - - - - 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. - - - - - - Generators should only be used to generate unit files and symlinks to them, not any other kind of - configuration. Due to the lifecycle logic mentioned above, generators are not a good fit to generate - dynamic configuration for other services. If you need to generate dynamic configuration for other services, - do so in normal services you order before the service in question. - - - - - - Since - syslog3 - is not available (see above), log messages have to be - written to /dev/kmsg instead. - - - - - - It is a good idea to use the - SourcePath= directive in generated unit - files to specify the source configuration file you are - generating the unit from. This makes things more easily - understood by the user and also has the benefit that - systemd can warn the user about configuration files that - changed on disk but have not been read yet by systemd. - - - - - - 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. - - - - - 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. - - - - 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 user 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. - - - - + + + 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. + + + + + Generators are run very early at boot and cannot rely on any external + services. They may not talk to any other process. That includes simple things + such as logging to + syslog3, + or systemd itself (this means: no + systemctl1)! + Non-essential file systems like /var and + /home are mounted after generators have run. Generators + can however rely on the most basic kernel functionality to be available, + including a mounted /sys, /proc, + /dev, /usr. + + + + + 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. + + + + Generators should only be used to generate unit files and symlinks to + them, not any other kind of configuration. Due to the lifecycle logic + mentioned above, generators are not a good fit to generate dynamic + configuration for other services. If you need to generate dynamic + configuration for other services, do so in normal services you order before + the service in question. + + + + Since + syslog3 + + is not available (see above), log messages have to be written to + /dev/kmsg instead. + + + + The generator should always include its own name in a comment at the top of the generated file, + so that the user can easily figure out which component created or amended a particular unit. + + The SourcePath= directive should be used in generated files to specify the + source configuration file they are generated from. This makes things more easily understood by the + user and also has the benefit that systemd can warn the user about configuration files that changed + on disk but have not been read yet by systemd. The SourcePath= value does not have + to be a file in a physical filesystem. For example, in the common case of the generator looking at + the kernel command line, should 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. + + + + 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. + + + + 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]. + + + + 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. + + + @@ -283,22 +258,18 @@ 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 her 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 start local-fs.target may be used. - + 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 + start local-fs.target may be used. @@ -307,9 +278,9 @@ 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 + 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.