]>
Commit | Line | Data |
---|---|---|
e735f4d4 MP |
1 | <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>systemd.generator</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><style> |
2 | a.headerlink { | |
3 | color: #c60f0f; | |
4 | font-size: 0.8em; | |
5 | padding: 0 4px 0 4px; | |
6 | text-decoration: none; | |
7 | visibility: hidden; | |
8 | } | |
9 | ||
10 | a.headerlink:hover { | |
11 | background-color: #c60f0f; | |
12 | color: white; | |
13 | } | |
14 | ||
15 | h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink { | |
16 | visibility: visible; | |
17 | } | |
18 | </style><a href="index.html">Index </a>· | |
19 | <a href="systemd.directives.html">Directives </a>· | |
20 | <a href="../python-systemd/index.html">Python </a>· | |
21 | <a href="../libudev/index.html">libudev </a>· | |
e3bff60a | 22 | <a href="../libudev/index.html">gudev </a><span style="float:right">systemd 220</span><hr><div class="refentry"><a name="systemd.generator"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>systemd.generator — Systemd unit generators</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">/path/to/generator</code> <em class="replaceable"><code>normal-dir</code></em> <em class="replaceable"><code>early-dir</code></em> <em class="replaceable"><code>late-dir</code></em> </p></div><p> |
e735f4d4 MP |
23 | </p><div class="literallayout"><p><code class="filename">/run/systemd/system-generators/*</code><br> |
24 | <code class="filename">/etc/systemd/system-generators/*</code><br> | |
25 | <code class="filename">/usr/local/lib/systemd/system-generators/*</code><br> | |
26 | <code class="filename">/usr/lib/systemd/system-generators/*</code></p></div><p> | |
27 | </p><p> | |
28 | </p><div class="literallayout"><p><code class="filename">/run/systemd/user-generators/*</code><br> | |
29 | <code class="filename">/etc/systemd/user-generators/*</code><br> | |
30 | <code class="filename">/usr/local/lib/systemd/user-generators/*</code><br> | |
31 | <code class="filename">/usr/lib/systemd/user-generators/*</code></p></div><p> | |
e3bff60a | 32 | </p></div><div class="refsect1"><a name="idm139621018473376"></a><h2 id="Description">Description<a class="headerlink" title="Permalink to this headline" href="#Description">¶</a></h2><p>Generators are small binaries that live in |
e735f4d4 MP |
33 | <code class="filename">/usr/lib/systemd/user-generators/</code> and other directories |
34 | listed above. | |
35 | <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a> | |
36 | will execute those binaries very early at bootup and at | |
37 | configuration reload time — before unit files are loaded. | |
38 | Generators can dynamically generate unit files or create symbolic | |
39 | links to unit files to add additional dependencies, thus extending | |
40 | or overriding existing definitions. Their main purpose is to | |
41 | convert configuration files that are not native unit files | |
42 | dynamically into native unit files.</p><p>Generators are loaded from a set of paths determined during | |
43 | compilation, listed above. System and user generators are loaded | |
44 | from directories with names ending in | |
45 | <code class="filename">system-generators/</code> and | |
46 | <code class="filename">user-generators/</code>, respectively. Generators | |
47 | found in directories listed earlier override the ones with the | |
48 | same name in directories lower in the list. A symlink to | |
49 | <code class="filename">/dev/null</code> or an empty file can be used to | |
50 | mask a generator, thereby preventing it from running. Please note | |
51 | that the order of the two directories with the highest priority is | |
52 | reversed with respect to the unit load path and generators in | |
53 | <code class="filename">/run</code> overwrite those in | |
54 | <code class="filename">/etc</code>.</p><p>After installing new generators or updating the | |
55 | configuration, <span class="command"><strong>systemctl daemon-reload</strong></span> may be | |
56 | executed. This will delete the previous configuration created by | |
57 | generators, re-run all generators, and cause | |
58 | <span class="command"><strong>systemd</strong></span> to reload units from disk. See | |
59 | <a href="systemctl.html"><span class="citerefentry"><span class="refentrytitle">systemctl</span>(1)</span></a> | |
60 | for more information. | |
e3bff60a | 61 | </p></div><div class="refsect1"><a name="idm139621018462272"></a><h2 id="Writing generators">Writing generators<a class="headerlink" title="Permalink to this headline" href="#Writing%20generators">¶</a></h2><p>Generators are invoked with three arguments: paths to |
e735f4d4 MP |
62 | runtime directories where generators can place their generated |
63 | unit files or symlinks.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><em class="parameter"><code>normal-dir</code></em></p><p>argv[1] may be used to override unit files in | |
64 | <code class="filename">/usr</code>, but not those in | |
65 | <code class="filename">/etc</code>. This means that unit files placed | |
66 | in this directory take precedence over vendor unit | |
67 | configuration but not over native user/administrator unit | |
68 | configuration.</p></li><li class="listitem"><p><em class="parameter"><code>early-dir</code></em></p><p>argv[2] may be used to override unit files in | |
69 | <code class="filename">/usr</code> and in | |
70 | <code class="filename">/etc</code>. This means that unit files placed | |
71 | in this directory take precedence over all configuration, | |
72 | both vendor and user/administrator.</p></li><li class="listitem"><p><em class="parameter"><code>late-dir</code></em></p><p>argv[3] may be used to extend the unit file tree without | |
e3bff60a | 73 | overriding any other unit files. Any native configuration |
e735f4d4 MP |
74 | files supplied by the vendor or user/administrator take |
75 | precedence over the generated ones placed in this directory. | |
e3bff60a | 76 | </p></li></ol></div><div class="refsect2"><a name="idm139621018452528"></a><h3 id="Notes">Notes<a class="headerlink" title="Permalink to this headline" href="#Notes">¶</a></h3><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> |
e735f4d4 MP |
77 | All generators are executed in parallel. That means all |
78 | executables are started at the very same time and need to | |
79 | be able to cope with this parallelism. | |
80 | </p></li><li class="listitem"><p> | |
81 | Generators are run very early at boot and cannot rely on | |
82 | any external services. They may not talk to any other | |
83 | process. That includes simple things such as logging to | |
84 | <a href="http://man7.org/linux/man-pages/man3/syslog.3.html"><span class="citerefentry"><span class="refentrytitle">syslog</span>(3)</span></a>, | |
85 | or <span class="command"><strong>systemd</strong></span> itself (this means: no | |
86 | <a href="systemctl.html"><span class="citerefentry"><span class="refentrytitle">systemctl</span>(1)</span></a>!). They | |
87 | can however rely on the most basic kernel functionality to | |
88 | be available, including mounted <code class="filename">/sys</code>, | |
89 | <code class="filename">/proc</code>, <code class="filename">/dev</code>. | |
90 | </p></li><li class="listitem"><p> | |
91 | Units written by generators are removed when configuration | |
92 | is reloaded. That means the lifetime of the generated | |
93 | units is closely bound to the reload cycles of | |
94 | <span class="command"><strong>systemd</strong></span> itself. | |
95 | </p></li><li class="listitem"><p> | |
96 | Generators should only be used to generate unit files, not | |
97 | any other kind of configuration. Due to the lifecycle | |
98 | logic mentioned above generators are not a good fit to | |
99 | generate dynamic configuration for other services. If you | |
100 | need to generate dynamic configuration for other services | |
101 | do so in normal services you order before the service in | |
102 | question. | |
103 | </p></li><li class="listitem"><p> | |
104 | Since | |
105 | <a href="http://man7.org/linux/man-pages/man3/syslog.3.html"><span class="citerefentry"><span class="refentrytitle">syslog</span>(3)</span></a> | |
106 | is not available (see above) log messages have to be | |
107 | written to <code class="filename">/dev/kmsg</code> instead. | |
108 | </p></li><li class="listitem"><p> | |
109 | It is a good idea to use the | |
110 | <code class="varname">SourcePath=</code> directive in generated unit | |
111 | files to specify the source configuration file you are | |
112 | generating the unit from. This makes things more easily | |
113 | understood by the user and also has the benefit that | |
114 | systemd can warn the user about configuration files that | |
115 | changed on disk but have not been read yet by systemd. | |
116 | </p></li><li class="listitem"><p> | |
117 | Generators may write out dynamic unit files or just hook | |
118 | unit files into other units with the usual | |
119 | <code class="filename">.wants/</code> or | |
120 | <code class="filename">.requires/</code> symlinks. Often it is | |
121 | nicer to simply instantiate a template unit file from | |
122 | <code class="filename">/usr</code> with a generator instead of | |
123 | writing out entirely dynamic unit files. Of course this | |
124 | works only if a single parameter is to be used. | |
125 | </p></li><li class="listitem"><p> | |
126 | If you are careful you can implement generators in shell | |
127 | scripts. We do recommend C code however, since generators | |
128 | delay are executed synchronously and hence delay the | |
129 | entire boot if they are slow. | |
130 | </p></li><li class="listitem"><p>Regarding overriding semantics: there are two rules we | |
131 | try to follow when thinking about the overriding semantics: | |
132 | </p><div class="orderedlist"><ol class="orderedlist" type="i"><li class="listitem"><p>User configuration should override vendor | |
133 | configuration. This (mostly) means that stuff from | |
134 | <code class="filename">/etc</code> should override stuff from | |
135 | <code class="filename">/usr</code>.</p></li><li class="listitem"><p>Native configuration should override non-native | |
136 | configuration. This (mostly) means that stuff you | |
137 | generate should never override native unit files for the | |
138 | same purpose.</p></li></ol></div><p>Of these two rules the first rule is probably the more | |
139 | important one and breaks the second one sometimes. Hence, | |
140 | when deciding whether to user argv[1], argv[2], or argv[3], | |
141 | your default choice should probably be argv[1].</p></li><li class="listitem"><p> | |
142 | Instead of heading off now and writing all kind of | |
143 | generators for legacy configuration file formats, please | |
144 | think twice! It's often a better idea to just deprecate | |
145 | old stuff instead of keeping it artificially alive. | |
e3bff60a | 146 | </p></li></ul></div></div></div><div class="refsect1"><a name="idm139621018418304"></a><h2 id="Examples">Examples<a class="headerlink" title="Permalink to this headline" href="#Examples">¶</a></h2><div class="example"><a name="idm139621018417664"></a><p class="title"><b>Example 1. systemd-fstab-generator</b></p><div class="example-contents"><p><a href="systemd-fstab-generator.html"><span class="citerefentry"><span class="refentrytitle">systemd-fstab-generator</span>(8)</span></a> |
e735f4d4 MP |
147 | converts <code class="filename">/etc/fstab</code> into native mount |
148 | units. It uses argv[1] as location to place the generated unit | |
149 | files in order to allow the user to override | |
150 | <code class="filename">/etc/fstab</code> with her own native unit files, | |
151 | but also to ensure that <code class="filename">/etc/fstab</code> | |
152 | overrides any vendor default from <code class="filename">/usr</code>. | |
153 | </p><p>After editing <code class="filename">/etc/fstab</code>, the user | |
154 | should invoke <span class="command"><strong>systemctl daemon-reload</strong></span>. This | |
155 | will re-run all generators and cause <span class="command"><strong>systemd</strong></span> | |
156 | to reload units from disk. To actually mount new directories | |
157 | added to <code class="filename">fstab</code>, <span class="command"><strong>systemctl start | |
158 | <em class="replaceable"><code>/path/to/mountpoint</code></em></strong></span> or | |
159 | <span class="command"><strong>systemctl start local-fs.target</strong></span> may be used. | |
e3bff60a | 160 | </p></div></div><br class="example-break"><div class="example"><a name="idm139621018408832"></a><p class="title"><b>Example 2. systemd-system-update-generator</b></p><div class="example-contents"><p><a href="systemd-system-update-generator.html"><span class="citerefentry"><span class="refentrytitle">systemd-system-update-generator</span>(8)</span></a> |
e735f4d4 MP |
161 | temporarily redirects <code class="filename">default.target</code> to |
162 | <code class="filename">system-update.target</code> if a system update is | |
163 | scheduled. Since this needs to override the default user | |
164 | configuration for <code class="filename">default.target</code> it uses | |
165 | argv[2]. For details about this logic, see | |
166 | <a class="ulink" href="http://www.freedesktop.org/wiki/Software/systemd/SystemUpdates" target="_top">Implementing | |
e3bff60a | 167 | Offline System Updates</a>.</p></div></div><br class="example-break"><div class="example"><a name="idm139621018404416"></a><p class="title"><b>Example 3. Debuging a generator</b></p><div class="example-contents"><pre class="programlisting">dir=$(mktemp -d) |
e735f4d4 MP |
168 | SYSTEMD_LOG_LEVEL=debug /usr/lib/systemd/system-generators/systemd-fstab-generator \ |
169 | "$dir" "$dir" "$dir" | |
e3bff60a | 170 | find $dir</pre></div></div><br class="example-break"></div><div class="refsect1"><a name="idm139621018402736"></a><h2 id="See also">See also<a class="headerlink" title="Permalink to this headline" href="#See%20also">¶</a></h2><p> |
e735f4d4 MP |
171 | <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>, |
172 | <a href="systemd-cryptsetup-generator.html"><span class="citerefentry"><span class="refentrytitle">systemd-cryptsetup-generator</span>(8)</span></a>, | |
173 | <a href="systemd-debug-generator.html"><span class="citerefentry"><span class="refentrytitle">systemd-debug-generator</span>(8)</span></a>, | |
174 | <a href="systemd-efi-boot-generator.html"><span class="citerefentry"><span class="refentrytitle">systemd-efi-boot-generator</span>(8)</span></a>, | |
175 | <a href="systemd-fstab-generator.html"><span class="citerefentry"><span class="refentrytitle">systemd-fstab-generator</span>(8)</span></a>, | |
e3bff60a | 176 | <a href="http://man7.org/linux/man-pages/man5/fstab.5.html"><span class="citerefentry"><span class="refentrytitle">fstab</span>(5)</span></a>, |
e735f4d4 MP |
177 | <a href="systemd-getty-generator.html"><span class="citerefentry"><span class="refentrytitle">systemd-getty-generator</span>(8)</span></a>, |
178 | <a href="systemd-gpt-auto-generator.html"><span class="citerefentry"><span class="refentrytitle">systemd-gpt-auto-generator</span>(8)</span></a>, | |
179 | <a href="systemd-hibernate-resume-generator.html"><span class="citerefentry"><span class="refentrytitle">systemd-hibernate-resume-generator</span>(8)</span></a>, | |
180 | <a href="systemd-system-update-generator.html"><span class="citerefentry"><span class="refentrytitle">systemd-system-update-generator</span>(8)</span></a>, | |
181 | <a href="systemd-sysv-generator.html"><span class="citerefentry"><span class="refentrytitle">systemd-sysv-generator</span>(8)</span></a>, | |
182 | <a href="systemd.unit.html"><span class="citerefentry"><span class="refentrytitle">systemd.unit</span>(5)</span></a>, | |
183 | <a href="systemctl.html"><span class="citerefentry"><span class="refentrytitle">systemctl</span>(1)</span></a> | |
184 | </p></div></div></body></html> |