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