2015-02-11 04:17:59 +00:00
|
|
|
<?xml version='1.0'?> <!--*-nxml-*-->
|
2019-03-14 13:40:58 +00:00
|
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
2015-02-11 04:17:59 +00:00
|
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
|
|
|
<!ENTITY % entities SYSTEM "custom-entities.ent" >
|
|
|
|
%entities;
|
|
|
|
]>
|
2019-03-14 13:29:37 +00:00
|
|
|
<!-- SPDX-License-Identifier: LGPL-2.1+ -->
|
2015-02-11 04:17:59 +00:00
|
|
|
|
|
|
|
<refentry id="systemd.generator">
|
|
|
|
<refentryinfo>
|
|
|
|
<title>systemd.generator</title>
|
|
|
|
<productname>systemd</productname>
|
|
|
|
</refentryinfo>
|
|
|
|
|
|
|
|
<refmeta>
|
|
|
|
<refentrytitle>systemd.generator</refentrytitle>
|
|
|
|
<manvolnum>7</manvolnum>
|
|
|
|
</refmeta>
|
|
|
|
|
|
|
|
<refnamediv>
|
|
|
|
<refname>systemd.generator</refname>
|
2017-12-13 16:42:04 +00:00
|
|
|
<refpurpose>systemd unit generators</refpurpose>
|
2015-02-11 04:17:59 +00:00
|
|
|
</refnamediv>
|
|
|
|
|
|
|
|
<refsynopsisdiv>
|
|
|
|
<cmdsynopsis>
|
|
|
|
<command>/path/to/generator</command>
|
|
|
|
<arg choice="plain"><replaceable>normal-dir</replaceable></arg>
|
|
|
|
<arg choice="plain"><replaceable>early-dir</replaceable></arg>
|
|
|
|
<arg choice="plain"><replaceable>late-dir</replaceable></arg>
|
|
|
|
</cmdsynopsis>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
<literallayout><filename>/run/systemd/system-generators/*</filename>
|
2015-06-18 17:47:44 +00:00
|
|
|
<filename>/etc/systemd/system-generators/*</filename>
|
2015-02-11 04:17:59 +00:00
|
|
|
<filename>/usr/local/lib/systemd/system-generators/*</filename>
|
|
|
|
<filename>&systemgeneratordir;/*</filename></literallayout>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
<literallayout><filename>/run/systemd/user-generators/*</filename>
|
2015-06-18 17:47:44 +00:00
|
|
|
<filename>/etc/systemd/user-generators/*</filename>
|
2015-02-11 04:17:59 +00:00
|
|
|
<filename>/usr/local/lib/systemd/user-generators/*</filename>
|
|
|
|
<filename>&usergeneratordir;/*</filename></literallayout>
|
|
|
|
</para>
|
|
|
|
</refsynopsisdiv>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Description</title>
|
2018-02-08 15:23:43 +00:00
|
|
|
<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. Their main purpose is to convert configuration
|
|
|
|
that is not native into dynamically generated unit files.</para>
|
|
|
|
|
|
|
|
<para>Each generator is called with three directory paths that are to be used for
|
|
|
|
generator output. In these three directories, generators may dynamically generate
|
|
|
|
unit files (regular ones, instances, as well as templates), unit file
|
|
|
|
<filename>.d/</filename> drop-ins, and create symbolic links to unit files to add
|
|
|
|
additional dependencies, create aliases, or instantiate existing templates. Those
|
|
|
|
directories are included in the unit load path of
|
|
|
|
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
|
|
|
allowing generated configuration to extend or override existing
|
|
|
|
definitions.</para>
|
|
|
|
|
|
|
|
<para>Directory paths for generator output differ by priority:
|
|
|
|
<filename>…/generator.early</filename> has priority higher than the admin
|
|
|
|
configuration in <filename>/etc</filename>, while
|
|
|
|
<filename>…/generator</filename> has lower priority than
|
|
|
|
<filename>/etc</filename> but higher than vendor configuration in
|
|
|
|
<filename>/usr</filename>, and <filename>…/generator.late</filename> has priority
|
|
|
|
lower than all other configuration. See the next section and the discussion of
|
|
|
|
unit load paths and unit overriding in
|
|
|
|
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
|
|
|
|
</para>
|
2015-02-11 04:17:59 +00:00
|
|
|
|
|
|
|
<para>Generators are loaded from a set of paths determined during
|
2014-08-03 05:11:37 +00:00
|
|
|
compilation, as listed above. System and user generators are loaded
|
2015-02-11 04:17:59 +00:00
|
|
|
from directories with names ending in
|
|
|
|
<filename>system-generators/</filename> and
|
|
|
|
<filename>user-generators/</filename>, respectively. Generators
|
|
|
|
found in directories listed earlier override the ones with the
|
|
|
|
same name in directories lower in the list. A symlink to
|
|
|
|
<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
|
2014-08-03 05:11:12 +00:00
|
|
|
reversed with respect to the unit load path, and generators in
|
2015-02-11 04:17:59 +00:00
|
|
|
<filename>/run</filename> overwrite those in
|
|
|
|
<filename>/etc</filename>.</para>
|
|
|
|
|
|
|
|
<para>After installing new generators or updating the
|
2015-02-11 16:22:55 +00:00
|
|
|
configuration, <command>systemctl daemon-reload</command> may be
|
2015-02-11 04:17:59 +00:00
|
|
|
executed. This will delete the previous configuration created by
|
|
|
|
generators, re-run all generators, and cause
|
|
|
|
<command>systemd</command> to reload units from disk. See
|
|
|
|
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
|
|
|
for more information.
|
|
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
2018-02-08 15:23:43 +00:00
|
|
|
<title>Output directories</title>
|
2015-02-11 04:17:59 +00:00
|
|
|
|
2018-02-08 15:23:43 +00:00
|
|
|
<para>Generators are invoked with three arguments: paths to directories where
|
|
|
|
generators can place their generated unit files or symlinks. By default those
|
|
|
|
paths are runtime directories that are included in the search path of
|
|
|
|
<command>systemd</command>, but a generator may be called with different paths
|
|
|
|
for debugging purposes.</para>
|
2015-02-11 04:17:59 +00:00
|
|
|
|
|
|
|
<orderedlist>
|
|
|
|
<listitem>
|
|
|
|
<para><parameter>normal-dir</parameter></para>
|
2018-02-08 15:23:43 +00:00
|
|
|
<para>In normal use this is <filename>/run/systemd/generator</filename> in
|
|
|
|
case of the system generators and
|
|
|
|
<filename>$XDG_RUNTIME_DIR/generator</filename> in case of the user
|
|
|
|
generators. Unit files placed in this directory take precedence over vendor
|
|
|
|
unit configuration but not over native user/administrator unit configuration.
|
|
|
|
</para>
|
2015-02-11 04:17:59 +00:00
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para><parameter>early-dir</parameter></para>
|
2018-02-08 15:23:43 +00:00
|
|
|
<para>In normal use this is <filename>/run/systemd/generator.early</filename>
|
|
|
|
in case of the system generators and
|
|
|
|
<filename>$XDG_RUNTIME_DIR/generator.early</filename> in case of the user
|
|
|
|
generators. Unit files placed in this directory override unit files in
|
|
|
|
<filename>/usr</filename>, <filename>/run</filename> and
|
|
|
|
<filename>/etc</filename>. This means that unit files placed in this
|
|
|
|
directory take precedence over all normal configuration, both vendor and
|
|
|
|
user/administrator.</para>
|
2015-02-11 04:17:59 +00:00
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para><parameter>late-dir</parameter></para>
|
2018-02-08 15:23:43 +00:00
|
|
|
<para>In normal use this is <filename>/run/systemd/generator.late</filename>
|
|
|
|
in case of the system generators and
|
|
|
|
<filename>$XDG_RUNTIME_DIR/generator.late</filename> in case of the user
|
|
|
|
generators. This directory may be used to extend the unit file tree without
|
|
|
|
overriding any other unit files. Any native configuration files supplied by
|
|
|
|
the vendor or user/administrator take precedence.</para>
|
2015-02-11 04:17:59 +00:00
|
|
|
</listitem>
|
|
|
|
</orderedlist>
|
2018-02-08 15:33:28 +00:00
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Notes about writing generators</title>
|
|
|
|
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem>
|
|
|
|
<para>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.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<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>,
|
|
|
|
or <command>systemd</command> itself (this means: no
|
|
|
|
<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 the configuration is
|
|
|
|
reloaded. That means the lifetime of the generated units is closely bound to
|
|
|
|
the reload cycles of <command>systemd</command> itself.</para>
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>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>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>Since
|
|
|
|
<citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
|
|
|
|
|
|
|
is not available (see above), log messages have to be written to
|
|
|
|
<filename>/dev/kmsg</filename> instead.</para>
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
2019-03-15 07:19:07 +00:00
|
|
|
<para>The generator should always include its own name in a comment at the top of the generated file,
|
|
|
|
so that the user can easily figure out which component created or amended a particular unit.</para>
|
|
|
|
|
|
|
|
<para>The <varname>SourcePath=</varname> directive should be used in generated files to specify the
|
|
|
|
source configuration file they are generated 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. The <varname>SourcePath=</varname> value does not have
|
|
|
|
to be a file in a physical filesystem. For example, in the common case of the generator looking at
|
|
|
|
the kernel command line, <option>SourcePath=/proc/cmdline</option> should be used.</para>
|
2018-02-08 15:33:28 +00:00
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>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 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
|
|
|
|
works only if a single parameter is to be used.</para>
|
|
|
|
</listitem>
|
2015-02-11 04:17:59 +00:00
|
|
|
|
2018-02-08 15:33:28 +00:00
|
|
|
<listitem>
|
|
|
|
<para>If you are careful, you can implement generators in shell scripts. We
|
|
|
|
do recommend C code however, since generators are executed synchronously and
|
|
|
|
hence delay the entire boot if they are slow.</para>
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>Regarding overriding semantics: there are two rules we try to follow
|
|
|
|
when thinking about the overriding semantics:</para>
|
|
|
|
|
|
|
|
<orderedlist numeration="lowerroman">
|
|
|
|
<listitem>
|
|
|
|
<para>User configuration should override vendor configuration. This
|
|
|
|
(mostly) means that stuff from <filename>/etc</filename> should override
|
|
|
|
stuff from <filename>/usr</filename>.</para>
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>Native configuration should override non-native configuration. This
|
|
|
|
(mostly) means that stuff you generate should never override native unit
|
|
|
|
files for the same purpose.</para>
|
|
|
|
</listitem>
|
|
|
|
</orderedlist>
|
|
|
|
|
|
|
|
<para>Of these two rules the first rule is probably the more important one
|
|
|
|
and breaks the second one sometimes. Hence, when deciding whether to use
|
|
|
|
argv[1], argv[2], or argv[3], your default choice should probably be
|
|
|
|
argv[1].</para>
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>Instead of heading off now and writing all kind of generators for
|
|
|
|
legacy configuration file formats, please think twice! It is often a better
|
|
|
|
idea to just deprecate old stuff instead of keeping it artificially alive.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
2015-02-11 04:17:59 +00:00
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Examples</title>
|
|
|
|
<example>
|
|
|
|
<title>systemd-fstab-generator</title>
|
|
|
|
|
|
|
|
<para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
2018-02-08 15:33:28 +00:00
|
|
|
converts <filename>/etc/fstab</filename> into native mount units. It uses
|
|
|
|
argv[1] as location to place the generated unit files in order to allow the
|
2018-08-23 14:57:30 +00:00
|
|
|
user to override <filename>/etc/fstab</filename> with their own native unit
|
2018-02-08 15:33:28 +00:00
|
|
|
files, but also to ensure that <filename>/etc/fstab</filename> overrides any
|
|
|
|
vendor default from <filename>/usr</filename>.</para>
|
|
|
|
|
|
|
|
<para>After editing <filename>/etc/fstab</filename>, the user should invoke
|
|
|
|
<command>systemctl daemon-reload</command>. This will re-run all generators and
|
|
|
|
cause <command>systemd</command> to reload units from disk. To actually mount
|
|
|
|
new directories added to <filename>fstab</filename>, <command>systemctl start
|
|
|
|
<replaceable>/path/to/mountpoint</replaceable></command> or <command>systemctl
|
|
|
|
start local-fs.target</command> may be used.</para>
|
2015-02-11 04:17:59 +00:00
|
|
|
</example>
|
|
|
|
|
|
|
|
<example>
|
|
|
|
<title>systemd-system-update-generator</title>
|
|
|
|
|
|
|
|
<para><citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
|
|
|
temporarily redirects <filename>default.target</filename> to
|
2016-05-28 20:43:22 +00:00
|
|
|
<filename>system-update.target</filename>, if a system update is
|
2018-02-08 15:33:28 +00:00
|
|
|
scheduled. Since this needs to override the default user configuration for
|
|
|
|
<filename>default.target</filename>, it uses argv[2]. For details about this
|
|
|
|
logic, see
|
2016-05-28 20:49:43 +00:00
|
|
|
<citerefentry><refentrytitle>systemd.offline-updates</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
|
|
|
|
</para>
|
2015-02-11 04:17:59 +00:00
|
|
|
</example>
|
|
|
|
|
|
|
|
<example>
|
2016-01-15 11:46:08 +00:00
|
|
|
<title>Debugging a generator</title>
|
2015-02-11 04:17:59 +00:00
|
|
|
|
|
|
|
<programlisting>dir=$(mktemp -d)
|
|
|
|
SYSTEMD_LOG_LEVEL=debug &systemgeneratordir;/systemd-fstab-generator \
|
|
|
|
"$dir" "$dir" "$dir"
|
|
|
|
find $dir</programlisting>
|
|
|
|
</example>
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>See also</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
|
|
|
<citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
|
|
|
|
<citerefentry><refentrytitle>systemd-debug-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
|
|
|
|
<citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
|
2015-03-14 02:22:39 +00:00
|
|
|
<citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
2015-02-11 04:17:59 +00:00
|
|
|
<citerefentry><refentrytitle>systemd-getty-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
|
|
|
|
<citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
|
|
|
|
<citerefentry><refentrytitle>systemd-hibernate-resume-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
|
2017-12-24 15:50:19 +00:00
|
|
|
<citerefentry><refentrytitle>systemd-rc-local-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
|
2015-02-11 04:17:59 +00:00
|
|
|
<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>,
|
2017-01-23 06:11:45 +00:00
|
|
|
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
|
|
|
<citerefentry><refentrytitle>systemd.environment-generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>
|
2015-02-11 04:17:59 +00:00
|
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
</refentry>
|