mirror of
https://git.proxmox.com/git/systemd
synced 2025-11-04 07:40:42 +00:00
185 lines
16 KiB
HTML
185 lines
16 KiB
HTML
<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>
|
||
a.headerlink {
|
||
color: #c60f0f;
|
||
font-size: 0.8em;
|
||
padding: 0 4px 0 4px;
|
||
text-decoration: none;
|
||
visibility: hidden;
|
||
}
|
||
|
||
a.headerlink:hover {
|
||
background-color: #c60f0f;
|
||
color: white;
|
||
}
|
||
|
||
h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
|
||
visibility: visible;
|
||
}
|
||
</style><a href="index.html">Index </a>·
|
||
<a href="systemd.directives.html">Directives </a>·
|
||
<a href="../python-systemd/index.html">Python </a>·
|
||
<a href="../libudev/index.html">libudev </a>·
|
||
<a href="../libudev/index.html">gudev </a><span style="float:right">systemd 219</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>
|
||
</p><div class="literallayout"><p><code class="filename">/run/systemd/system-generators/*</code><br>
|
||
<code class="filename">/etc/systemd/system-generators/*</code><br>
|
||
<code class="filename">/usr/local/lib/systemd/system-generators/*</code><br>
|
||
<code class="filename">/usr/lib/systemd/system-generators/*</code></p></div><p>
|
||
</p><p>
|
||
</p><div class="literallayout"><p><code class="filename">/run/systemd/user-generators/*</code><br>
|
||
<code class="filename">/etc/systemd/user-generators/*</code><br>
|
||
<code class="filename">/usr/local/lib/systemd/user-generators/*</code><br>
|
||
<code class="filename">/usr/lib/systemd/user-generators/*</code></p></div><p>
|
||
</p></div><div class="refsect1"><a name="idm140270263216512"></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
|
||
<code class="filename">/usr/lib/systemd/user-generators/</code> and other directories
|
||
listed above.
|
||
<a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>
|
||
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.</p><p>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
|
||
<code class="filename">system-generators/</code> and
|
||
<code class="filename">user-generators/</code>, respectively. Generators
|
||
found in directories listed earlier override the ones with the
|
||
same name in directories lower in the list. A symlink to
|
||
<code class="filename">/dev/null</code> 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
|
||
<code class="filename">/run</code> overwrite those in
|
||
<code class="filename">/etc</code>.</p><p>After installing new generators or updating the
|
||
configuration, <span class="command"><strong>systemctl daemon-reload</strong></span> may be
|
||
executed. This will delete the previous configuration created by
|
||
generators, re-run all generators, and cause
|
||
<span class="command"><strong>systemd</strong></span> to reload units from disk. See
|
||
<a href="systemctl.html"><span class="citerefentry"><span class="refentrytitle">systemctl</span>(1)</span></a>
|
||
for more information.
|
||
</p></div><div class="refsect1"><a name="idm140270267147776"></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
|
||
runtime directories where generators can place their generated
|
||
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
|
||
<code class="filename">/usr</code>, but not those in
|
||
<code class="filename">/etc</code>. This means that unit files placed
|
||
in this directory take precedence over vendor unit
|
||
configuration but not over native user/administrator unit
|
||
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
|
||
<code class="filename">/usr</code> and in
|
||
<code class="filename">/etc</code>. This means that unit files placed
|
||
in this directory take precedence over all configuration,
|
||
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
|
||
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.
|
||
</p></li></ol></div><div class="refsect2"><a name="idm140270267099792"></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>
|
||
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.
|
||
</p></li><li class="listitem"><p>
|
||
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
|
||
<a href="http://man7.org/linux/man-pages/man3/syslog.3.html"><span class="citerefentry"><span class="refentrytitle">syslog</span>(3)</span></a>,
|
||
or <span class="command"><strong>systemd</strong></span> itself (this means: no
|
||
<a href="systemctl.html"><span class="citerefentry"><span class="refentrytitle">systemctl</span>(1)</span></a>!). They
|
||
can however rely on the most basic kernel functionality to
|
||
be available, including mounted <code class="filename">/sys</code>,
|
||
<code class="filename">/proc</code>, <code class="filename">/dev</code>.
|
||
</p></li><li class="listitem"><p>
|
||
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
|
||
<span class="command"><strong>systemd</strong></span> itself.
|
||
</p></li><li class="listitem"><p>
|
||
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.
|
||
</p></li><li class="listitem"><p>
|
||
Since
|
||
<a href="http://man7.org/linux/man-pages/man3/syslog.3.html"><span class="citerefentry"><span class="refentrytitle">syslog</span>(3)</span></a>
|
||
is not available (see above) log messages have to be
|
||
written to <code class="filename">/dev/kmsg</code> instead.
|
||
</p></li><li class="listitem"><p>
|
||
It is a good idea to use the
|
||
<code class="varname">SourcePath=</code> 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.
|
||
</p></li><li class="listitem"><p>
|
||
Generators may write out dynamic unit files or just hook
|
||
unit files into other units with the usual
|
||
<code class="filename">.wants/</code> or
|
||
<code class="filename">.requires/</code> symlinks. Often it is
|
||
nicer to simply instantiate a template unit file from
|
||
<code class="filename">/usr</code> with a generator instead of
|
||
writing out entirely dynamic unit files. Of course this
|
||
works only if a single parameter is to be used.
|
||
</p></li><li class="listitem"><p>
|
||
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.
|
||
</p></li><li class="listitem"><p>Regarding overriding semantics: there are two rules we
|
||
try to follow when thinking about the overriding semantics:
|
||
</p><div class="orderedlist"><ol class="orderedlist" type="i"><li class="listitem"><p>User configuration should override vendor
|
||
configuration. This (mostly) means that stuff from
|
||
<code class="filename">/etc</code> should override stuff from
|
||
<code class="filename">/usr</code>.</p></li><li class="listitem"><p>Native configuration should override non-native
|
||
configuration. This (mostly) means that stuff you
|
||
generate should never override native unit files for the
|
||
same purpose.</p></li></ol></div><p>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].</p></li><li class="listitem"><p>
|
||
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.
|
||
</p></li></ul></div></div></div><div class="refsect1"><a name="idm140270267080928"></a><h2 id="Examples">Examples<a class="headerlink" title="Permalink to this headline" href="#Examples">¶</a></h2><div class="example"><a name="idm140270267080256"></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>
|
||
converts <code class="filename">/etc/fstab</code> into native mount
|
||
units. It uses argv[1] as location to place the generated unit
|
||
files in order to allow the user to override
|
||
<code class="filename">/etc/fstab</code> with her own native unit files,
|
||
but also to ensure that <code class="filename">/etc/fstab</code>
|
||
overrides any vendor default from <code class="filename">/usr</code>.
|
||
</p><p>After editing <code class="filename">/etc/fstab</code>, the user
|
||
should invoke <span class="command"><strong>systemctl daemon-reload</strong></span>. This
|
||
will re-run all generators and cause <span class="command"><strong>systemd</strong></span>
|
||
to reload units from disk. To actually mount new directories
|
||
added to <code class="filename">fstab</code>, <span class="command"><strong>systemctl start
|
||
<em class="replaceable"><code>/path/to/mountpoint</code></em></strong></span> or
|
||
<span class="command"><strong>systemctl start local-fs.target</strong></span> may be used.
|
||
</p></div></div><br class="example-break"><div class="example"><a name="idm140270262127408"></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>
|
||
temporarily redirects <code class="filename">default.target</code> to
|
||
<code class="filename">system-update.target</code> if a system update is
|
||
scheduled. Since this needs to override the default user
|
||
configuration for <code class="filename">default.target</code> it uses
|
||
argv[2]. For details about this logic, see
|
||
<a class="ulink" href="http://www.freedesktop.org/wiki/Software/systemd/SystemUpdates" target="_top">Implementing
|
||
Offline System Updates</a>.</p></div></div><br class="example-break"><div class="example"><a name="idm140270262122992"></a><p class="title"><b>Example 3. Debuging a generator</b></p><div class="example-contents"><pre class="programlisting">dir=$(mktemp -d)
|
||
SYSTEMD_LOG_LEVEL=debug /usr/lib/systemd/system-generators/systemd-fstab-generator \
|
||
"$dir" "$dir" "$dir"
|
||
find $dir</pre></div></div><br class="example-break"></div><div class="refsect1"><a name="idm140270262121312"></a><h2 id="See also">See also<a class="headerlink" title="Permalink to this headline" href="#See%20also">¶</a></h2><p>
|
||
<a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
|
||
<a href="systemd-cryptsetup-generator.html"><span class="citerefentry"><span class="refentrytitle">systemd-cryptsetup-generator</span>(8)</span></a>,
|
||
<a href="systemd-debug-generator.html"><span class="citerefentry"><span class="refentrytitle">systemd-debug-generator</span>(8)</span></a>,
|
||
<a href="systemd-efi-boot-generator.html"><span class="citerefentry"><span class="refentrytitle">systemd-efi-boot-generator</span>(8)</span></a>,
|
||
<a href="systemd-fstab-generator.html"><span class="citerefentry"><span class="refentrytitle">systemd-fstab-generator</span>(8)</span></a>,
|
||
<a href="fstab.html"><span class="citerefentry"><span class="refentrytitle">fstab</span>(5)</span></a>,
|
||
<a href="systemd-getty-generator.html"><span class="citerefentry"><span class="refentrytitle">systemd-getty-generator</span>(8)</span></a>,
|
||
<a href="systemd-gpt-auto-generator.html"><span class="citerefentry"><span class="refentrytitle">systemd-gpt-auto-generator</span>(8)</span></a>,
|
||
<a href="systemd-hibernate-resume-generator.html"><span class="citerefentry"><span class="refentrytitle">systemd-hibernate-resume-generator</span>(8)</span></a>,
|
||
<a href="systemd-system-update-generator.html"><span class="citerefentry"><span class="refentrytitle">systemd-system-update-generator</span>(8)</span></a>,
|
||
<a href="systemd-sysv-generator.html"><span class="citerefentry"><span class="refentrytitle">systemd-sysv-generator</span>(8)</span></a>,
|
||
<a href="systemd.unit.html"><span class="citerefentry"><span class="refentrytitle">systemd.unit</span>(5)</span></a>,
|
||
<a href="systemctl.html"><span class="citerefentry"><span class="refentrytitle">systemctl</span>(1)</span></a>
|
||
</p></div></div></body></html>
|