table of contents
SYSTEMD.GENERATOR(7) | systemd.generator | SYSTEMD.GENERATOR(7) |
NAME¶
systemd.generator - Systemd unit generators
SYNOPSIS¶
/path/to/generator normal-dir early-dir late-dir
/run/systemd/system-generators/* /etc/systemd/system-generators/* /usr/local/lib/systemd/system-generators/* /usr/lib/systemd/system-generators/*
/run/systemd/user-generators/* /etc/systemd/user-generators/* /usr/local/lib/systemd/user-generators/* /usr/lib/systemd/user-generators/*
DESCRIPTION¶
Generators are small binaries that live in /usr/lib/systemd/user-generators/ and other directories listed above. systemd(1) 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-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 systemctl(1) 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.
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.
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.
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¶
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].
EXAMPLES¶
Example 1. systemd-fstab-generator
systemd-fstab-generator(8) 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.
Example 2. systemd-system-update-generator
systemd-system-update-generator(8) 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[1].
Example 3. Debuging a generator
dir=$(mktemp -d) SYSTEMD_LOG_LEVEL=debug /usr/lib/systemd/system-generators/systemd-fstab-generator \
"$dir" "$dir" "$dir" find $dir
SEE ALSO¶
systemd(1), systemd-cryptsetup-generator(8), systemd-debug-generator(8), systemd-efi-boot-generator(8), systemd-fstab-generator(8), fstab(5), systemd-getty-generator(8), systemd-gpt-auto-generator(8), systemd-hibernate-resume-generator(8), systemd-system-update-generator(8), systemd-sysv-generator(8), systemd.unit(5), systemctl(1)
NOTES¶
- 1.
- Implementing Offline System Updates
systemd 219 |