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
 174     <refsect2>
 175       <title>Notes</title>
 176
 177       <itemizedlist>
 178         <listitem>
 179           <para>
 180             All generators are executed in parallel. That means all
 181             executables are started at the very same time and need to
 182             be able to cope with this parallelism.
 183           </para>
 184         </listitem>
 185
 186         <listitem>
 187           <para>
 188             Generators are run very early at boot and cannot rely on
 189             any external services. They may not talk to any other
 190             process. That includes simple things such as logging to
 191             <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 192             or <command>systemd</command> itself (this means: no
 193             <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>)!
 194             Non-essential file systems like
 195             <filename>/var</filename> and <filename>/home</filename>
 196             are mounted after generators have run. Generators
 197             can however rely on the most basic kernel functionality to be
 198             available, including a mounted <filename>/sys</filename>,
 199             <filename>/proc</filename>, <filename>/dev</filename>,
 200             <filename>/usr</filename>.
 201           </para>
 202         </listitem>
 203
 204         <listitem>
 205           <para>
 206             Units written by generators are removed when the configuration
 207             is reloaded. That means the lifetime of the generated
 208             units is closely bound to the reload cycles of
 209             <command>systemd</command> itself.
 210           </para>
 211         </listitem>
 212
 213         <listitem>
 214           <para>
 215             Generators should only be used to generate unit files and symlinks to them, not any other kind of
 216             configuration. Due to the lifecycle logic mentioned above, generators are not a good fit to generate
 217             dynamic configuration for other services. If you need to generate dynamic configuration for other services,
 218             do so in normal services you order before the service in question.
 219           </para>
 220         </listitem>
 221
 222         <listitem>
 223           <para>
 224             Since
 225             <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 226             is not available (see above), log messages have to be
 227             written to <filename>/dev/kmsg</filename> instead.
 228           </para>
 229         </listitem>
 230
 231         <listitem>
 232           <para>
 233             It is a good idea to use the
 234             <varname>SourcePath=</varname> directive in generated unit
 235             files to specify the source configuration file you are
 236             generating the unit from. This makes things more easily
 237             understood by the user and also has the benefit that
 238             systemd can warn the user about configuration files that
 239             changed on disk but have not been read yet by systemd.
 240           </para>
 241         </listitem>
 242
 243         <listitem>
 244           <para>
 245             Generators may write out dynamic unit files or just hook
 246             unit files into other units with the usual
 247             <filename>.wants/</filename> or
 248             <filename>.requires/</filename> symlinks. Often, it is
 249             nicer to simply instantiate a template unit file from
 250             <filename>/usr</filename> with a generator instead of
 251             writing out entirely dynamic unit files. Of course, this
 252             works only if a single parameter is to be used.
 253           </para>
 254         </listitem>
 255
 256         <listitem>
 257           <para>
 258             If you are careful, you can implement generators in shell
 259             scripts. We do recommend C code however, since generators
 260             are executed synchronously and hence delay the
 261             entire boot if they are slow.
 262           </para>
 263         </listitem>
 264
 265         <listitem>
 266           <para>Regarding overriding semantics: there are two rules we
 267           try to follow when thinking about the overriding semantics:
 268           </para>
 269
 270           <orderedlist numeration="lowerroman">
 271             <listitem>
 272               <para>User configuration should override vendor
 273               configuration. This (mostly) means that stuff from
 274               <filename>/etc</filename> should override stuff from
 275               <filename>/usr</filename>.</para>
 276             </listitem>
 277
 278             <listitem>
 279               <para>Native configuration should override non-native
 280               configuration. This (mostly) means that stuff you
 281               generate should never override native unit files for the
 282               same purpose.</para>
 283             </listitem>
 284           </orderedlist>
 285
 286           <para>Of these two rules the first rule is probably the more
 287           important one and breaks the second one sometimes. Hence,
 288           when deciding whether to use argv[1], argv[2], or argv[3],
 289           your default choice should probably be argv[1].</para>
 290         </listitem>
 291
 292         <listitem>
 293           <para>
 294             Instead of heading off now and writing all kind of
 295             generators for legacy configuration file formats, please
 296             think twice! It is often a better idea to just deprecate
 297             old stuff instead of keeping it artificially alive.
 298           </para>
 299         </listitem>
 300       </itemizedlist>
 301     </refsect2>
 302   </refsect1>
 303
 304   <refsect1>
 305     <title>Examples</title>
 306     <example>
 307       <title>systemd-fstab-generator</title>
 308
 309       <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 310       converts <filename>/etc/fstab</filename> into native mount
 311       units. It uses argv[1] as location to place the generated unit
 312       files in order to allow the user to override
 313       <filename>/etc/fstab</filename> with her own native unit files,
 314       but also to ensure that <filename>/etc/fstab</filename>
 315       overrides any vendor default from <filename>/usr</filename>.
 316       </para>
 317
 318       <para>After editing <filename>/etc/fstab</filename>, the user
 319       should invoke <command>systemctl daemon-reload</command>. This
 320       will re-run all generators and cause <command>systemd</command>
 321       to reload units from disk. To actually mount new directories
 322       added to <filename>fstab</filename>, <command>systemctl start
 323       <replaceable>/path/to/mountpoint</replaceable></command> or
 324       <command>systemctl start local-fs.target</command> may be used.
 325       </para>
 326     </example>
 327
 328     <example>
 329       <title>systemd-system-update-generator</title>
 330
 331       <para><citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 332       temporarily redirects <filename>default.target</filename> to
 333       <filename>system-update.target</filename>, if a system update is
 334       scheduled. Since this needs to override the default user
 335       configuration for <filename>default.target</filename>, it uses
 336       argv[2]. For details about this logic, see
 337       <citerefentry><refentrytitle>systemd.offline-updates</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
 338       </para>
 339     </example>
 340
 341     <example>
 342       <title>Debugging a generator</title>
 343
 344       <programlisting>dir=$(mktemp -d)
 345 SYSTEMD_LOG_LEVEL=debug &systemgeneratordir;/systemd-fstab-generator \
 346         "$dir" "$dir" "$dir"
 347 find $dir</programlisting>
 348     </example>
 349   </refsect1>
 350
 351   <refsect1>
 352     <title>See also</title>
 353
 354     <para>
 355       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 356       <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 357       <citerefentry><refentrytitle>systemd-debug-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 358       <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 359       <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 360       <citerefentry><refentrytitle>systemd-getty-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 361       <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 362       <citerefentry><refentrytitle>systemd-hibernate-resume-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 363       <citerefentry><refentrytitle>systemd-rc-local-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 364       <citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 365       <citerefentry><refentrytitle>systemd-sysv-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 366       <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 367       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 368       <citerefentry><refentrytitle>systemd.environment-generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 369     </para>
 370   </refsect1>
 371 </refentry>