1SYSTEMD.GENERATOR(7) systemd.generator SYSTEMD.GENERATOR(7)
2
6 systemd.generator - Systemd unit generators
7
9 /path/to/generator normal-dir early-dir late-dir
10 /run/systemd/system-generators/*
12 /etc/systemd/system-generators/*
13 /usr/local/lib/systemd/system-generators/*
14 /usr/lib/systemd/system-generators/*
15 /run/systemd/user-generators/*
17 /etc/systemd/user-generators/*
18 /usr/local/lib/systemd/user-generators/*
19 /usr/lib/systemd/user-generators/*
20
23 Generators are small binaries that live in
24 /usr/lib/systemd/user-generators/ and other directories listed above.
25 systemd(1) will execute those binaries very early at bootup and at
26 configuration reload time — before unit files are loaded. Generators
27 can dynamically generate unit files or create symbolic links to unit
28 files to add additional dependencies, thus extending or overriding
29 existing definitions. Their main purpose is to convert configuration
30 files that are not native unit files dynamically into native unit
31 files.
32 Generators are loaded from a set of paths determined during
34 compilation, listed above. System and user generators are loaded from
35 directories with names ending in system-generators/ and
36 user-generators/, respectively. Generators found in directories listed
37 earlier override the ones with the same name in directories lower in
38 the list. A symlink to /dev/null or an empty file can be used to mask a
39 generator, thereby preventing it from running. Please note that the
40 order of the two directories with the highest priority is reversed with
41 respect to the unit load path and generators in /run overwrite those in
42 /etc.
43 After installing new generators or updating the configuration,
45 systemctl daemon-reload may be executed. This will delete the previous
46 configuration created by generators, re-run all generators, and cause
47 systemd to reload units from disk. See systemctl(1) for more
48 information.
49
51 Generators are invoked with three arguments: paths to runtime
52 directories where generators can place their generated unit files or
53 symlinks.
54 1. normal-dir
56 argv[1] may be used to override unit files in /usr, but not those
58 in /etc. This means that unit files placed in this directory take
59 precedence over vendor unit configuration but not over native
60 user/administrator unit configuration.
61 2. early-dir
63 argv[2] may be used to override unit files in /usr and in /etc.
65 This means that unit files placed in this directory take precedence
66 over all configuration, both vendor and user/administrator.
67 3. late-dir
69 argv[3] may be used to extend the unit file tree without
71 overridding any other unit files. Any native configuration files
72 supplied by the vendor or user/administrator take precedence over
73 the generated ones placed in this directory.
74 Notes
76 · All generators are executed in parallel. That means all executables
77 are started at the very same time and need to be able to cope with
78 this parallelism.
79 · Generators are run very early at boot and cannot rely on any
81 external services. They may not talk to any other process. That
82 includes simple things such as logging to syslog(3), or systemd
83 itself (this means: no systemctl(1)!). They can however rely on the
84 most basic kernel functionality to be available, including mounted
85 /sys, /proc, /dev.
86 · Units written by generators are removed when configuration is
88 reloaded. That means the lifetime of the generated units is closely
89 bound to the reload cycles of systemd itself.
90 · Generators should only be used to generate unit files, not any
92 other kind of configuration. Due to the lifecycle logic mentioned
93 above generators are not a good fit to generate dynamic
94 configuration for other services. If you need to generate dynamic
95 configuration for other services do so in normal services you order
96 before the service in question.
97 · Since syslog(3) is not available (see above) log messages have to
99 be written to /dev/kmsg instead.
100 · It is a good idea to use the SourcePath= directive in generated
102 unit files to specify the source configuration file you are
103 generating the unit from. This makes things more easily understood
104 by the user and also has the benefit that systemd can warn the user
105 about configuration files that changed on disk but have not been
106 read yet by systemd.
107 · Generators may write out dynamic unit files or just hook unit files
109 into other units with the usual .wants/ or .requires/ symlinks.
110 Often it is nicer to simply instantiate a template unit file from
111 /usr with a generator instead of writing out entirely dynamic unit
112 files. Of course this works only if a single parameter is to be
113 used.
114 · If you are careful you can implement generators in shell scripts.
116 We do recommend C code however, since generators delay are executed
117 synchronously and hence delay the entire boot if they are slow.
118 · Regarding overriding semantics: there are two rules we try to
120 follow when thinking about the overriding semantics:
121 1. User configuration should override vendor configuration. This
123 (mostly) means that stuff from /etc should override stuff from
124 /usr.
125 2. Native configuration should override non-native configuration.
127 This (mostly) means that stuff you generate should never
128 override native unit files for the same purpose.
129 Of these two rules the first rule is probably the more important
131 one and breaks the second one sometimes. Hence, when deciding
132 whether to user argv[1], argv[2], or argv[3], your default choice
133 should probably be argv[1].
134 · Instead of heading off now and writing all kind of generators for
136 legacy configuration file formats, please think twice! It's often a
137 better idea to just deprecate old stuff instead of keeping it
138 artificially alive.
139
141 Example 1. systemd-fstab-generator
142 systemd-fstab-generator(8) converts /etc/fstab into native mount units.
144 It uses argv[1] as location to place the generated unit files in order
145 to allow the user to override /etc/fstab with her own native unit
146 files, but also to ensure that /etc/fstab overrides any vendor default
147 from /usr.
148 After editing /etc/fstab, the user should invoke systemctl
150 daemon-reload. This will re-run all generators and cause systemd to
151 reload units from disk. To actually mount new directories added to
152 fstab, systemctl start /path/to/mountpoint or systemctl start
153 local-fs.target may be used.
154 Example 2. systemd-system-update-generator
156 systemd-system-update-generator(8) temporarily redirects default.target
158 to system-update.target if a system update is scheduled. Since this
159 needs to override the default user configuration for default.target it
160 uses argv[2]. For details about this logic, see Implementing Offline
161 System Updates[1].
162 Example 3. Debuging a generator
164 dir=$(mktemp -d)
166 SYSTEMD_LOG_LEVEL=debug /usr/lib/systemd/system-generators/systemd-fstab-generator \
167 "$dir" "$dir" "$dir"
168 find $dir
169
171 systemd(1), systemd-cryptsetup-generator(8), systemd-debug-
172 generator(8), systemd-efi-boot-generator(8), systemd-fstab-
173 generator(8), fstab(5), systemd-getty-generator(8), systemd-gpt-auto-
174 generator(8), systemd-hibernate-resume-generator(8), systemd-system-
175 update-generator(8), systemd-sysv-generator(8), systemd.unit(5),
176 systemctl(1)
177
179 1. Implementing Offline System Updates
180 http://www.freedesktop.org/wiki/Software/systemd/SystemUpdates
181systemd 219 SYSTEMD.GENERATOR(7)