<?xml version='1.0'?> <!--*-nxml-*-->

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [

<!ENTITY % entities SYSTEM "custom-entities.ent" >

%entities;

]>

<refentry id="systemd.generator">

<refentryinfo>

<title>systemd.generator</title>

<productname>systemd</productname>

<authorgroup>

<author>

<contrib>Developer</contrib>

<firstname>Lennart</firstname>

<surname>Poettering</surname>

<email>lennart@poettering.net</email>

</author>

</authorgroup>

</refentryinfo>

<refmeta>

<refentrytitle>systemd.generator</refentrytitle>

<manvolnum>7</manvolnum>

</refmeta>

<refnamediv>

<refname>systemd.generator</refname>

<refpurpose>Systemd unit generators</refpurpose>

</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>

<filename>/etc/systemd/system-generators/*</filename>

<filename>/usr/local/lib/systemd/system-generators/*</filename>

<filename>&systemgeneratordir;/*</filename></literallayout>

</para>

<para>

<literallayout><filename>/run/systemd/user-generators/*</filename>

<filename>/etc/systemd/user-generators/*</filename>

<filename>/usr/local/lib/systemd/user-generators/*</filename>

<filename>&usergeneratordir;/*</filename></literallayout>

</para>

</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 loaded from a set of paths determined during

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

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

reversed with respect to the unit load path, and generators in

<filename>/run</filename> overwrite those in

<filename>/etc</filename>.</para>

<para>After installing new generators or updating the

configuration, <command>systemctl daemon-reload</command> may be

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>

<title>Writing generators</title>

<para>Generators are invoked with three arguments: paths to

runtime directories where generators can place their generated

unit files or symlinks.</para>

<orderedlist>

<listitem>

<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

in this directory take precedence over vendor unit

configuration but not over native user/administrator unit

configuration.</para>

</listitem>

<listitem>

<para><parameter>early-dir</parameter></para>

<para>argv[2] may be used to override unit files in

<filename>/usr</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>

</listitem>

<listitem>

<para><parameter>late-dir</parameter></para>

<para>argv[3] 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 over the generated ones placed in this directory.

</para>

</listitem>

</orderedlist>

<refsect2>

<title>Notes</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>!). They

can however rely on the most basic kernel functionality to

be available, including a mounted <filename>/sys</filename>,

<filename>/proc</filename>, <filename>/dev</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, 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>

<para>

It is a good idea to use the

<varname>SourcePath=</varname> 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.

</para>

</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>

<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 user 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's often a better idea to just deprecate

old stuff instead of keeping it artificially alive.

</para>

</listitem>

</itemizedlist>

</refsect2>

</refsect1>

<refsect1>

<title>Examples</title>

<example>

<title>systemd-fstab-generator</title>

<para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>

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 user to override

<filename>/etc/fstab</filename> with her own native unit 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>

</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

<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

argv[2]. For details about this logic, see

<ulink url="http://www.freedesktop.org/wiki/Software/systemd/SystemUpdates">Implementing

Offline System Updates</ulink>.</para>

</example>

<example>

<title>Debuging a generator</title>

<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>,

<citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

<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>,

<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>

</para>

</refsect1>

</refentry>