From 4160043a0fac8b812905b7502ce34adf3af538f1 Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Tue, 6 Sep 2016 02:27:18 -0400 Subject: move man pages to appropriate directories --- man/systemd.generator.xml | 348 ---------------------------------------------- 1 file changed, 348 deletions(-) delete mode 100644 man/systemd.generator.xml (limited to 'man/systemd.generator.xml') diff --git a/man/systemd.generator.xml b/man/systemd.generator.xml deleted file mode 100644 index 4b80dab108..0000000000 --- a/man/systemd.generator.xml +++ /dev/null @@ -1,348 +0,0 @@ - - -%entities; -]> - - - - - - systemd.generator - systemd - - - - Developer - Lennart - Poettering - lennart@poettering.net - - - - - - systemd.generator - 7 - - - - systemd.generator - Systemd unit generators - - - - - /path/to/generator - normal-dir - early-dir - late-dir - - - - /run/systemd/system-generators/* -/etc/systemd/system-generators/* -/usr/local/lib/systemd/system-generators/* -&systemgeneratordir;/* - - - - /run/systemd/user-generators/* -/etc/systemd/user-generators/* -/usr/local/lib/systemd/user-generators/* -&usergeneratordir;/* - - - - - Description - Generators are small binaries that live in - &usergeneratordir;/ 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 can dynamically generate unit files or create symbolic - links to unit files to add additional dependencies, 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 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. - - - - - Writing generators - - Generators are invoked with three arguments: paths to - runtime directories where generators can place their generated - unit files or symlinks. - - - - normal-dir - argv[1] may be used to override unit files in - /usr, but not those 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. - - - - early-dir - argv[2] may be used to override unit files in - /usr and in - /etc. This means that unit files placed - in this directory take precedence over all 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. - - - - - - 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, 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. - - - - - - - - Examples - - 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. - - - - - 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 - Implementing - Offline System Updates. - - - - Debugging a generator - - dir=$(mktemp -d) -SYSTEMD_LOG_LEVEL=debug &systemgeneratordir;/systemd-fstab-generator \ - "$dir" "$dir" "$dir" -find $dir - - - - - See also - - - systemd1, - systemd-cryptsetup-generator8, - systemd-debug-generator8, - systemd-fstab-generator8, - fstab5, - systemd-getty-generator8, - systemd-gpt-auto-generator8, - systemd-hibernate-resume-generator8, - systemd-system-update-generator8, - systemd-sysv-generator8, - systemd.unit5, - systemctl1 - - - -- cgit v1.2.3-54-g00ecf