diff --git a/man/systemd.generator.xml b/man/systemd.generator.xml index a41e43df0f..60ca0cecad 100644 --- a/man/systemd.generator.xml +++ b/man/systemd.generator.xml @@ -170,135 +170,112 @@ the vendor or user/administrator take precedence. + - - Notes + + Notes about writing generators - - - - 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. + + - - - 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. - - + + 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. - - + + 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. - - + + 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. - - + + Since + syslog3 - - - 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. - - + is not available (see above), log messages have to be written to + /dev/kmsg instead. + - - - 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. - - + + 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. + - - - 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. - - + + 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. + - - Regarding overriding semantics: there are two rules we - try to follow when thinking about the overriding semantics: - + + 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. + - - - User configuration should override vendor - configuration. This (mostly) means that stuff from - /etc should override stuff from - /usr. - + + Regarding overriding semantics: there are two rules we try to follow + when thinking about the overriding semantics: - - Native configuration should override non-native - configuration. This (mostly) means that stuff you - generate should never override native unit files for the - same purpose. - - + + + User configuration should override vendor configuration. This + (mostly) means that stuff from /etc should override + stuff from /usr. + - 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]. - + + Native configuration should override non-native configuration. This + (mostly) means that stuff you generate should never override native unit + files for the same purpose. + + - - - 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. - - - - + 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. + + + @@ -307,22 +284,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. - + 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. - + 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. @@ -331,9 +304,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.