man/systemd.generator.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
   4 <!ENTITY % entities SYSTEM "custom-entities.ent" >
   5 %entities;
   6 ]>
   7
   8 <!--
   9   SPDX-License-Identifier: LGPL-2.1+
  10
  11   Copyright © 2015 Zbigniew Jędrzejewski-Szmek
  12 -->
  13
  14 <refentry id="systemd.generator">
  15   <refentryinfo>
  16     <title>systemd.generator</title>
  17     <productname>systemd</productname>
  18
  19     <authorgroup>
  20       <author>
  21         <contrib>Developer</contrib>
  22         <firstname>Lennart</firstname>
  23         <surname>Poettering</surname>
  24         <email>lennart@poettering.net</email>
  25       </author>
  26     </authorgroup>
  27   </refentryinfo>
  28
  29   <refmeta>
  30     <refentrytitle>systemd.generator</refentrytitle>
  31     <manvolnum>7</manvolnum>
  32   </refmeta>
  33
  34   <refnamediv>
  35     <refname>systemd.generator</refname>
  36     <refpurpose>systemd unit generators</refpurpose>
  37   </refnamediv>
  38
  39   <refsynopsisdiv>
  40     <cmdsynopsis>
  41       <command>/path/to/generator</command>
  42       <arg choice="plain"><replaceable>normal-dir</replaceable></arg>
  43       <arg choice="plain"><replaceable>early-dir</replaceable></arg>
  44       <arg choice="plain"><replaceable>late-dir</replaceable></arg>
  45     </cmdsynopsis>
  46
  47     <para>
  48       <literallayout><filename>/run/systemd/system-generators/*</filename>
  49 <filename>/etc/systemd/system-generators/*</filename>
  50 <filename>/usr/local/lib/systemd/system-generators/*</filename>
  51 <filename>&systemgeneratordir;/*</filename></literallayout>
  52     </para>
  53
  54     <para>
  55       <literallayout><filename>/run/systemd/user-generators/*</filename>
  56 <filename>/etc/systemd/user-generators/*</filename>
  57 <filename>/usr/local/lib/systemd/user-generators/*</filename>
  58 <filename>&usergeneratordir;/*</filename></literallayout>
  59     </para>
  60   </refsynopsisdiv>
  61
  62   <refsect1>
  63     <title>Description</title>
  64     <para>Generators are small executables that live in
  65     <filename>&systemgeneratordir;/</filename> and other directories listed above.
  66     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  67     will execute those binaries very early at bootup and at configuration reload time
  68     — before unit files are loaded. Their main purpose is to convert configuration
  69     that is not native into dynamically generated unit files.</para>
  70
  71     <para>Each generator is called with three directory paths that are to be used for
  72     generator output. In these three directories, generators may dynamically generate
  73     unit files (regular ones, instances, as well as templates), unit file
  74     <filename>.d/</filename> drop-ins, and create symbolic links to unit files to add
  75     additional dependencies, create aliases, or instantiate existing templates. Those
  76     directories are included in the unit load path of
  77     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
  78     allowing generated configuration to extend or override existing
  79     definitions.</para>
  80
  81     <para>Directory paths for generator output differ by priority:
  82     <filename>…/generator.early</filename> has priority higher than the admin
  83     configuration in <filename>/etc</filename>, while
  84     <filename>…/generator</filename> has lower priority than
  85     <filename>/etc</filename> but higher than vendor configuration in
  86     <filename>/usr</filename>, and <filename>…/generator.late</filename> has priority
  87     lower than all other configuration. See the next section and the discussion of
  88     unit load paths and unit overriding in
  89     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
  90     </para>
  91
  92     <para>Generators are loaded from a set of paths determined during
  93     compilation, as listed above. System and user generators are loaded
  94     from directories with names ending in
  95     <filename>system-generators/</filename> and
  96     <filename>user-generators/</filename>, respectively. Generators
  97     found in directories listed earlier override the ones with the
  98     same name in directories lower in the list. A symlink to
  99     <filename>/dev/null</filename> or an empty file can be used to
 100     mask a generator, thereby preventing it from running. Please note
 101     that the order of the two directories with the highest priority is
 102     reversed with respect to the unit load path, and generators in
 103     <filename>/run</filename> overwrite those in
 104     <filename>/etc</filename>.</para>
 105
 106     <para>After installing new generators or updating the
 107     configuration, <command>systemctl daemon-reload</command> may be
 108     executed. This will delete the previous configuration created by
 109     generators, re-run all generators, and cause
 110     <command>systemd</command> to reload units from disk. See
 111     <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 112     for more information.
 113     </para>
 114   </refsect1>
 115
 116   <refsect1>
 117     <title>Output directories</title>
 118
 119     <para>Generators are invoked with three arguments: paths to directories where
 120     generators can place their generated unit files or symlinks. By default those
 121     paths are runtime directories that are included in the search path of
 122     <command>systemd</command>, but a generator may be called with different paths
 123     for debugging purposes.</para>
 124
 125     <orderedlist>
 126       <listitem>
 127         <para><parameter>normal-dir</parameter></para>
 128         <para>In normal use this is <filename>/run/systemd/generator</filename> in
 129         case of the system generators and
 130         <filename>$XDG_RUNTIME_DIR/generator</filename> in case of the user
 131         generators. Unit files placed in this directory take precedence over vendor
 132         unit configuration but not over native user/administrator unit configuration.
 133         </para>
 134       </listitem>
 135
 136       <listitem>
 137         <para><parameter>early-dir</parameter></para>
 138         <para>In normal use this is <filename>/run/systemd/generator.early</filename>
 139         in case of the system generators and
 140         <filename>$XDG_RUNTIME_DIR/generator.early</filename> in case of the user
 141         generators. Unit files placed in this directory override unit files in
 142         <filename>/usr</filename>, <filename>/run</filename> and
 143         <filename>/etc</filename>. This means that unit files placed in this
 144         directory take precedence over all normal configuration, both vendor and
 145         user/administrator.</para>
 146       </listitem>
 147
 148       <listitem>
 149         <para><parameter>late-dir</parameter></para>
 150         <para>In normal use this is <filename>/run/systemd/generator.late</filename>
 151         in case of the system generators and
 152         <filename>$XDG_RUNTIME_DIR/generator.late</filename> in case of the user
 153         generators. This directory may be used to extend the unit file tree without
 154         overriding any other unit files. Any native configuration files supplied by
 155         the vendor or user/administrator take precedence.</para>
 156       </listitem>
 157     </orderedlist>
 158   </refsect1>
 159
 160   <refsect1>
 161     <title>Notes about writing generators</title>
 162
 163     <itemizedlist>
 164       <listitem>
 165         <para>All generators are executed in parallel. That means all executables are
 166         started at the very same time and need to be able to cope with this
 167         parallelism.
 168         </para>
 169       </listitem>
 170
 171       <listitem>
 172         <para>Generators are run very early at boot and cannot rely on any external
 173         services. They may not talk to any other process. That includes simple things
 174         such as logging to
 175         <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 176         or <command>systemd</command> itself (this means: no
 177         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>)!
 178         Non-essential file systems like <filename>/var</filename> and
 179         <filename>/home</filename> are mounted after generators have run. Generators
 180         can however rely on the most basic kernel functionality to be available,
 181         including a mounted <filename>/sys</filename>, <filename>/proc</filename>,
 182         <filename>/dev</filename>, <filename>/usr</filename>.
 183         </para>
 184       </listitem>
 185
 186       <listitem>
 187         <para>Units written by generators are removed when the configuration is
 188         reloaded. That means the lifetime of the generated units is closely bound to
 189         the reload cycles of <command>systemd</command> itself.</para>
 190       </listitem>
 191
 192       <listitem>
 193         <para>Generators should only be used to generate unit files and symlinks to
 194         them, not any other kind of configuration. Due to the lifecycle logic
 195         mentioned above, generators are not a good fit to generate dynamic
 196         configuration for other services. If you need to generate dynamic
 197         configuration for other services, do so in normal services you order before
 198         the service in question.</para>
 199       </listitem>
 200
 201       <listitem>
 202         <para>Since
 203         <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 204
 205         is not available (see above), log messages have to be written to
 206         <filename>/dev/kmsg</filename> instead.</para>
 207       </listitem>
 208
 209       <listitem>
 210         <para>It is a good idea to use the <varname>SourcePath=</varname> directive
 211         in generated unit files to specify the source configuration file you are
 212         generating the unit from. This makes things more easily understood by the
 213         user and also has the benefit that systemd can warn the user about
 214         configuration files that changed on disk but have not been read yet by
 215         systemd.</para>
 216       </listitem>
 217
 218       <listitem>
 219         <para>Generators may write out dynamic unit files or just hook unit files
 220         into other units with the usual <filename>.wants/</filename> or
 221         <filename>.requires/</filename> symlinks. Often, it is nicer to simply
 222         instantiate a template unit file from <filename>/usr</filename> with a
 223         generator instead of writing out entirely dynamic unit files. Of course, this
 224         works only if a single parameter is to be used.</para>
 225       </listitem>
 226
 227       <listitem>
 228         <para>If you are careful, you can implement generators in shell scripts. We
 229         do recommend C code however, since generators are executed synchronously and
 230         hence delay the entire boot if they are slow.</para>
 231       </listitem>
 232
 233       <listitem>
 234         <para>Regarding overriding semantics: there are two rules we try to follow
 235         when thinking about the overriding semantics:</para>
 236
 237         <orderedlist numeration="lowerroman">
 238           <listitem>
 239             <para>User configuration should override vendor configuration. This
 240             (mostly) means that stuff from <filename>/etc</filename> should override
 241             stuff from <filename>/usr</filename>.</para>
 242           </listitem>
 243
 244           <listitem>
 245             <para>Native configuration should override non-native configuration. This
 246             (mostly) means that stuff you generate should never override native unit
 247             files for the same purpose.</para>
 248           </listitem>
 249         </orderedlist>
 250
 251         <para>Of these two rules the first rule is probably the more important one
 252         and breaks the second one sometimes. Hence, when deciding whether to use
 253         argv[1], argv[2], or argv[3], your default choice should probably be
 254         argv[1].</para>
 255       </listitem>
 256
 257       <listitem>
 258         <para>Instead of heading off now and writing all kind of generators for
 259         legacy configuration file formats, please think twice! It is often a better
 260         idea to just deprecate old stuff instead of keeping it artificially alive.
 261         </para>
 262       </listitem>
 263     </itemizedlist>
 264   </refsect1>
 265
 266   <refsect1>
 267     <title>Examples</title>
 268     <example>
 269       <title>systemd-fstab-generator</title>
 270
 271       <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 272       converts <filename>/etc/fstab</filename> into native mount units. It uses
 273       argv[1] as location to place the generated unit files in order to allow the
 274       user to override <filename>/etc/fstab</filename> with her own native unit
 275       files, but also to ensure that <filename>/etc/fstab</filename> overrides any
 276       vendor default from <filename>/usr</filename>.</para>
 277
 278       <para>After editing <filename>/etc/fstab</filename>, the user should invoke
 279       <command>systemctl daemon-reload</command>. This will re-run all generators and
 280       cause <command>systemd</command> to reload units from disk. To actually mount
 281       new directories added to <filename>fstab</filename>, <command>systemctl start
 282       <replaceable>/path/to/mountpoint</replaceable></command> or <command>systemctl
 283       start local-fs.target</command> may be used.</para>
 284     </example>
 285
 286     <example>
 287       <title>systemd-system-update-generator</title>
 288
 289       <para><citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 290       temporarily redirects <filename>default.target</filename> to
 291       <filename>system-update.target</filename>, if a system update is
 292       scheduled. Since this needs to override the default user configuration for
 293       <filename>default.target</filename>, it uses argv[2]. For details about this
 294       logic, see
 295       <citerefentry><refentrytitle>systemd.offline-updates</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
 296       </para>
 297     </example>
 298
 299     <example>
 300       <title>Debugging a generator</title>
 301
 302       <programlisting>dir=$(mktemp -d)
 303 SYSTEMD_LOG_LEVEL=debug &systemgeneratordir;/systemd-fstab-generator \
 304         "$dir" "$dir" "$dir"
 305 find $dir</programlisting>
 306     </example>
 307   </refsect1>
 308
 309   <refsect1>
 310     <title>See also</title>
 311
 312     <para>
 313       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 314       <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 315       <citerefentry><refentrytitle>systemd-debug-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 316       <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 317       <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 318       <citerefentry><refentrytitle>systemd-getty-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 319       <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 320       <citerefentry><refentrytitle>systemd-hibernate-resume-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 321       <citerefentry><refentrytitle>systemd-rc-local-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 322       <citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 323       <citerefentry><refentrytitle>systemd-sysv-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 324       <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 325       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 326       <citerefentry><refentrytitle>systemd.environment-generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 327     </para>
 328   </refsect1>
 329 </refentry>