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