]>
<!--
+ SPDX-License-Identifier: LGPL-2.1+
+
This file is part of systemd.
Copyright 2015 Zbigniew Jędrzejewski-Szmek
<refnamediv>
<refname>systemd.generator</refname>
- <refpurpose>Systemd unit generators</refpurpose>
+ <refpurpose>systemd unit generators</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsect1>
<title>Description</title>
- <para>Generators are small binaries that live in
- <filename>&usergeneratordir;/</filename> and other directories
- listed above.
- <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- 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.</para>
+ <para>Generators are small executables that live in <filename>&systemgeneratordir;/</filename> and other
+ directories listed above.
+ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> will execute those
+ binaries very early at bootup and at configuration reload time — before unit files are loaded. Generators may
+ dynamically generate unit files (regular ones, instances as well as templates) and unit file
+ <filename>.d/</filename> drop-ins, or create symbolic links to unit files to add additional dependencies or
+ instantiate existing templates, 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.</para>
<para>Generators are loaded from a set of paths determined during
- compilation, listed above. System and user generators are loaded
+ compilation, as listed above. System and user generators are loaded
from directories with names ending in
<filename>system-generators/</filename> and
<filename>user-generators/</filename>, respectively. Generators
<filename>/dev/null</filename> 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
+ reversed with respect to the unit load path, and generators in
<filename>/run</filename> overwrite those in
<filename>/etc</filename>.</para>
<para><parameter>normal-dir</parameter></para>
<para>argv[1] may be used to override unit files in
<filename>/usr</filename>, but not those in
- <filename>/etc</filename>. This means that unit files placed
+ <filename>/run</filename> or in <filename>/etc</filename>.
+ This means that unit files placed
in this directory take precedence over vendor unit
configuration but not over native user/administrator unit
configuration.</para>
<listitem>
<para><parameter>early-dir</parameter></para>
<para>argv[2] may be used to override unit files in
- <filename>/usr</filename> and in
+ <filename>/usr</filename>, in <filename>/run</filename> and in
<filename>/etc</filename>. This means that unit files placed
in this directory take precedence over all configuration,
both vendor and user/administrator.</para>
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
- <citerefentry
- project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
or <command>systemd</command> itself (this means: no
- <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>!). They
- can however rely on the most basic kernel functionality to
- be available, including mounted <filename>/sys</filename>,
- <filename>/proc</filename>, <filename>/dev</filename>.
+ <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>)!
+ Non-essential file systems like
+ <filename>/var</filename> and <filename>/home</filename>
+ are mounted after generators have run. Generators
+ can however rely on the most basic kernel functionality to be
+ available, including a mounted <filename>/sys</filename>,
+ <filename>/proc</filename>, <filename>/dev</filename>,
+ <filename>/usr</filename>.
</para>
</listitem>
<listitem>
<para>
- Units written by generators are removed when configuration
+ Units written by generators are removed when the configuration
is reloaded. That means the lifetime of the generated
units is closely bound to the reload cycles of
<command>systemd</command> itself.
<listitem>
<para>
- 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.
+ Generators should only be used to generate unit files and symlinks to them, 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.
</para>
</listitem>
<para>
Since
<citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
- is not available (see above) log messages have to be
+ is not available (see above), log messages have to be
written to <filename>/dev/kmsg</filename> instead.
</para>
</listitem>
Generators may write out dynamic unit files or just hook
unit files into other units with the usual
<filename>.wants/</filename> or
- <filename>.requires/</filename> symlinks. Often it is
+ <filename>.requires/</filename> symlinks. Often, it is
nicer to simply instantiate a template unit file from
<filename>/usr</filename> with a generator instead of
- writing out entirely dynamic unit files. Of course this
+ writing out entirely dynamic unit files. Of course, this
works only if a single parameter is to be used.
</para>
</listitem>
<listitem>
<para>
- If you are careful you can implement generators in shell
+ 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
+ are executed synchronously and hence delay the
entire boot if they are slow.
</para>
</listitem>
<para>
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
+ think twice! It is often a better idea to just deprecate
old stuff instead of keeping it artificially alive.
</para>
</listitem>
<para><citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
temporarily redirects <filename>default.target</filename> to
- <filename>system-update.target</filename> if a system update is
+ <filename>system-update.target</filename>, if a system update is
scheduled. Since this needs to override the default user
- configuration for <filename>default.target</filename> it uses
+ configuration for <filename>default.target</filename>, it uses
argv[2]. For details about this logic, see
- <ulink url="http://www.freedesktop.org/wiki/Software/systemd/SystemUpdates">Implementing
- Offline System Updates</ulink>.</para>
+ <citerefentry><refentrytitle>systemd.offline-updates</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+ </para>
</example>
<example>
- <title>Debuging a generator</title>
+ <title>Debugging a generator</title>
<programlisting>dir=$(mktemp -d)
SYSTEMD_LOG_LEVEL=debug &systemgeneratordir;/systemd-fstab-generator \
<citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-sysv-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.environment-generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>
projects / thirdparty / systemd.git / blobdiff