diff --git a/Makefile-man.am b/Makefile-man.am
index 7503abb8b6..d0fb9aa1ae 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 1c738cede6..ee6127c0b5 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 0000000000..519da15910
--- /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
+
+
+