1SYSTEMD.GENERATOR(7)           systemd.generator          SYSTEMD.GENERATOR(7)
2
3
4

NAME

6       systemd.generator - systemd unit generators
7

SYNOPSIS

9       /path/to/generator normal-dir early-dir late-dir
10
11       /run/systemd/system-generators/*
12       /etc/systemd/system-generators/*
13       /usr/local/lib/systemd/system-generators/*
14       /usr/lib/systemd/system-generators/*
15
16       /run/systemd/user-generators/*
17       /etc/systemd/user-generators/*
18       /usr/local/lib/systemd/user-generators/*
19       /usr/lib/systemd/user-generators/*
20
21

DESCRIPTION

23       Generators are small executables that live in
24       /usr/lib/systemd/system-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. Their main
27       purpose is to convert configuration that is not native into dynamically
28       generated unit files.
29
30       Each generator is called with three directory paths that are to be used
31       for generator output. In these three directories, generators may
32       dynamically generate unit files (regular ones, instances, as well as
33       templates), unit file .d/ drop-ins, and create symbolic links to unit
34       files to add additional dependencies, create aliases, or instantiate
35       existing templates. Those directories are included in the unit load
36       path of systemd(1), allowing generated configuration to extend or
37       override existing definitions.
38
39       Directory paths for generator output differ by priority:
40       .../generator.early has priority higher than the admin configuration in
41       /etc, while .../generator has lower priority than /etc but higher than
42       vendor configuration in /usr, and .../generator.late has priority lower
43       than all other configuration. See the next section and the discussion
44       of unit load paths and unit overriding in systemd.unit(5).
45
46       Generators are loaded from a set of paths determined during
47       compilation, as listed above. System and user generators are loaded
48       from directories with names ending in system-generators/ and
49       user-generators/, respectively. Generators found in directories listed
50       earlier override the ones with the same name in directories lower in
51       the list. A symlink to /dev/null or an empty file can be used to mask a
52       generator, thereby preventing it from running. Please note that the
53       order of the two directories with the highest priority is reversed with
54       respect to the unit load path, and generators in /run overwrite those
55       in /etc.
56
57       After installing new generators or updating the configuration,
58       systemctl daemon-reload may be executed. This will delete the previous
59       configuration created by generators, re-run all generators, and cause
60       systemd to reload units from disk. See systemctl(1) for more
61       information.
62

OUTPUT DIRECTORIES

64       Generators are invoked with three arguments: paths to directories where
65       generators can place their generated unit files or symlinks. By default
66       those paths are runtime directories that are included in the search
67       path of systemd, but a generator may be called with different paths for
68       debugging purposes.
69
70        1. normal-dir
71
72           In normal use this is /run/systemd/generator in case of the system
73           generators and $XDG_RUNTIME_DIR/generator in case of the user
74           generators. Unit files placed in this directory take precedence
75           over vendor unit configuration but not over native
76           user/administrator unit configuration.
77
78        2. early-dir
79
80           In normal use this is /run/systemd/generator.early in case of the
81           system generators and $XDG_RUNTIME_DIR/generator.early in case of
82           the user generators. Unit files placed in this directory override
83           unit files in /usr, /run and /etc. This means that unit files
84           placed in this directory take precedence over all normal
85           configuration, both vendor and user/administrator.
86
87        3. late-dir
88
89           In normal use this is /run/systemd/generator.late in case of the
90           system generators and $XDG_RUNTIME_DIR/generator.late in case of
91           the user generators. This directory may be used to extend the unit
92           file tree without overriding any other unit files. Any native
93           configuration files supplied by the vendor or user/administrator
94           take precedence.
95

NOTES ABOUT WRITING GENERATORS

97       ·   All generators are executed in parallel. That means all executables
98           are started at the very same time and need to be able to cope with
99           this parallelism.
100
101       ·   Generators are run very early at boot and cannot rely on any
102           external services. They may not talk to any other process. That
103           includes simple things such as logging to syslog(3), or systemd
104           itself (this means: no systemctl(1))! Non-essential file systems
105           like /var and /home are mounted after generators have run.
106           Generators can however rely on the most basic kernel functionality
107           to be available, including a mounted /sys, /proc, /dev, /usr.
108
109       ·   Units written by generators are removed when the configuration is
110           reloaded. That means the lifetime of the generated units is closely
111           bound to the reload cycles of systemd itself.
112
113       ·   Generators should only be used to generate unit files and symlinks
114           to them, not any other kind of configuration. Due to the lifecycle
115           logic mentioned above, generators are not a good fit to generate
116           dynamic configuration for other services. If you need to generate
117           dynamic configuration for other services, do so in normal services
118           you order before the service in question.
119
120       ·   Since syslog(3) is not available (see above), log messages have to
121           be written to /dev/kmsg instead.
122
123       ·   The generator should always include its own name in a comment at
124           the top of the generated file, so that the user can easily figure
125           out which component created or amended a particular unit.
126
127           The SourcePath= directive should be used in generated files to
128           specify the source configuration file they are generated from. This
129           makes things more easily understood by the user and also has the
130           benefit that systemd can warn the user about configuration files
131           that changed on disk but have not been read yet by systemd. The
132           SourcePath= value does not have to be a file in a physical
133           filesystem. For example, in the common case of the generator
134           looking at the kernel command line, SourcePath=/proc/cmdline should
135           be used.
136
137       ·   Generators may write out dynamic unit files or just hook unit files
138           into other units with the usual .wants/ or .requires/ symlinks.
139           Often, it is nicer to simply instantiate a template unit file from
140           /usr with a generator instead of writing out entirely dynamic unit
141           files. Of course, this works only if a single parameter is to be
142           used.
143
144       ·   If you are careful, you can implement generators in shell scripts.
145           We do recommend C code however, since generators are executed
146           synchronously and hence delay the entire boot if they are slow.
147
148       ·   Regarding overriding semantics: there are two rules we try to
149           follow when thinking about the overriding semantics:
150
151            1. User configuration should override vendor configuration. This
152               (mostly) means that stuff from /etc should override stuff from
153               /usr.
154
155            2. Native configuration should override non-native configuration.
156               This (mostly) means that stuff you generate should never
157               override native unit files for the same purpose.
158
159           Of these two rules the first rule is probably the more important
160           one and breaks the second one sometimes. Hence, when deciding
161           whether to use argv[1], argv[2], or argv[3], your default choice
162           should probably be argv[1].
163
164       ·   Instead of heading off now and writing all kind of generators for
165           legacy configuration file formats, please think twice! It is often
166           a better idea to just deprecate old stuff instead of keeping it
167           artificially alive.
168

EXAMPLES

170       Example 1. systemd-fstab-generator
171
172       systemd-fstab-generator(8) converts /etc/fstab into native mount units.
173       It uses argv[1] as location to place the generated unit files in order
174       to allow the user to override /etc/fstab with their own native unit
175       files, but also to ensure that /etc/fstab overrides any vendor default
176       from /usr.
177
178       After editing /etc/fstab, the user should invoke systemctl
179       daemon-reload. This will re-run all generators and cause systemd to
180       reload units from disk. To actually mount new directories added to
181       fstab, systemctl start /path/to/mountpoint or systemctl start
182       local-fs.target may be used.
183
184       Example 2. systemd-system-update-generator
185
186       systemd-system-update-generator(8) temporarily redirects default.target
187       to system-update.target, if a system update is scheduled. Since this
188       needs to override the default user configuration for default.target, it
189       uses argv[2]. For details about this logic, see systemd.offline-
190       updates(7).
191
192       Example 3. Debugging a generator
193
194           dir=$(mktemp -d)
195           SYSTEMD_LOG_LEVEL=debug /usr/lib/systemd/system-generators/systemd-fstab-generator \
196                   "$dir" "$dir" "$dir"
197           find $dir
198

SEE ALSO

200       systemd(1), systemd-cryptsetup-generator(8), systemd-debug-
201       generator(8), systemd-fstab-generator(8), fstab(5), systemd-getty-
202       generator(8), systemd-gpt-auto-generator(8), systemd-hibernate-resume-
203       generator(8), systemd-rc-local-generator(8), systemd-system-update-
204       generator(8), systemd-sysv-generator(8), systemd.unit(5), systemctl(1),
205       systemd.environment-generator(7)
206
207
208
209systemd 243                                               SYSTEMD.GENERATOR(7)
Impressum