From 432d59656bd480b32a1fa6cf1c74662bfcafaf28 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Tue, 10 Feb 2015 23:17:59 -0500 Subject: [PATCH] man: add systemd.generator(7) This is largely based on http://www.freedesktop.org/wiki/Software/systemd/Generators/, and obsoletes that page. It seems that we do a much better job of keeping man pages up-to-date compared to wiki pages. Man pages are also easier to find for users. https://bugs.freedesktop.org/show_bug.cgi?id=89048 --- Makefile-man.am | 2 + man/systemctl.xml | 17 +- man/systemd.generator.xml | 346 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 359 insertions(+), 6 deletions(-) create mode 100644 man/systemd.generator.xml diff --git a/Makefile-man.am b/Makefile-man.am index 7503abb8b..d0fb9aa1a 100644 --- a/Makefile-man.am +++ b/Makefile-man.am @@ -99,6 +99,7 @@ MANPAGES += \ man/systemd.automount.5 \ man/systemd.device.5 \ man/systemd.exec.5 \ + man/systemd.generator.7 \ man/systemd.journal-fields.7 \ man/systemd.kill.5 \ man/systemd.link.5 \ @@ -1791,6 +1792,7 @@ EXTRA_DIST += \ man/systemd.device.xml \ man/systemd.directives.xml \ man/systemd.exec.xml \ + man/systemd.generator.xml \ man/systemd.index.xml \ man/systemd.journal-fields.xml \ man/systemd.kill.xml \ diff --git a/man/systemctl.xml b/man/systemctl.xml index 1c738cede..ee6127c0b 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -1367,12 +1367,16 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service daemon-reload - Reload systemd manager configuration. This will reload - all unit files and recreate the entire dependency - tree. While the daemon is being reloaded, all sockets systemd - listens on behalf of user configuration will stay - accessible. This command should not be confused - with the reload command. + Reload systemd manager configuration. This will + rerun all generators (see + systemd.generator7), + reload all unit files, and recreate the entire dependency + tree. While the daemon is being reloaded, all sockets + systemd listens on behalf of user configuration will stay + accessible. + + This command should not be confused with the + reload command. @@ -1721,6 +1725,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service systemd.special7, wall1, systemd.preset5, + systemd.generator7, glob7 diff --git a/man/systemd.generator.xml b/man/systemd.generator.xml new file mode 100644 index 000000000..519da1591 --- /dev/null +++ b/man/systemd.generator.xml @@ -0,0 +1,346 @@ + + +%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, 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-reloead 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 + overridding 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!). They + can however rely on the most basic kernel functionality to + be available, including mounted /sys, + /proc, /dev. + + + + + + Units written by generators are removed when 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 + delay 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's 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. + + + + Debuging 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-efi-boot-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 + + + -- 2.30.2