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 executables that live in <filename>&systemgeneratordir;/</filename> and other
  78     directories listed above.
  79     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> will execute those
  80     binaries very early at bootup and at configuration reload time — before unit files are loaded.  Generators may
  81     dynamically generate unit files (regular ones, instances as well as templates) and unit file
  82     <filename>.d/</filename> drop-ins, or create symbolic links to unit files to add additional dependencies or
  83     instantiate existing templates, thus extending or overriding existing definitions. Their main purpose is to convert
  84     configuration files that are not native unit files dynamically into native unit files.</para>
  85
  86     <para>Generators are loaded from a set of paths determined during
  87     compilation, as listed above. System and user generators are loaded
  88     from directories with names ending in
  89     <filename>system-generators/</filename> and
  90     <filename>user-generators/</filename>, respectively. Generators
  91     found in directories listed earlier override the ones with the
  92     same name in directories lower in the list. A symlink to
  93     <filename>/dev/null</filename> or an empty file can be used to
  94     mask a generator, thereby preventing it from running. Please note
  95     that the order of the two directories with the highest priority is
  96     reversed with respect to the unit load path, and generators in
  97     <filename>/run</filename> overwrite those in
  98     <filename>/etc</filename>.</para>
  99
 100     <para>After installing new generators or updating the
 101     configuration, <command>systemctl daemon-reload</command> may be
 102     executed. This will delete the previous configuration created by
 103     generators, re-run all generators, and cause
 104     <command>systemd</command> to reload units from disk. See
 105     <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 106     for more information.
 107     </para>
 108   </refsect1>
 109
 110   <refsect1>
 111     <title>Writing generators</title>
 112
 113     <para>Generators are invoked with three arguments: paths to
 114     runtime directories where generators can place their generated
 115     unit files or symlinks.</para>
 116
 117     <orderedlist>
 118       <listitem>
 119         <para><parameter>normal-dir</parameter></para>
 120         <para>argv[1] may be used to override unit files in
 121         <filename>/usr</filename>, but not those in
 122         <filename>/run</filename> or in <filename>/etc</filename>.
 123         This means that unit files placed
 124         in this directory take precedence over vendor unit
 125         configuration but not over native user/administrator unit
 126         configuration.</para>
 127       </listitem>
 128
 129       <listitem>
 130         <para><parameter>early-dir</parameter></para>
 131         <para>argv[2] may be used to override unit files in
 132         <filename>/usr</filename>, in <filename>/run</filename> and in
 133         <filename>/etc</filename>. This means that unit files placed
 134         in this directory take precedence over all configuration,
 135         both vendor and user/administrator.</para>
 136       </listitem>
 137
 138       <listitem>
 139         <para><parameter>late-dir</parameter></para>
 140         <para>argv[3] may be used to extend the unit file tree without
 141         overriding any other unit files. Any native configuration
 142         files supplied by the vendor or user/administrator take
 143         precedence over the generated ones placed in this directory.
 144         </para>
 145       </listitem>
 146     </orderedlist>
 147
 148     <refsect2>
 149       <title>Notes</title>
 150
 151       <itemizedlist>
 152         <listitem>
 153           <para>
 154             All generators are executed in parallel. That means all
 155             executables are started at the very same time and need to
 156             be able to cope with this parallelism.
 157           </para>
 158         </listitem>
 159
 160         <listitem>
 161           <para>
 162             Generators are run very early at boot and cannot rely on
 163             any external services. They may not talk to any other
 164             process. That includes simple things such as logging to
 165             <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 166             or <command>systemd</command> itself (this means: no
 167             <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>)!
 168             Non-essential file systems like
 169             <filename>/var</filename> and <filename>/home</filename>
 170             are mounted after generators have run. Generators
 171             can however rely on the most basic kernel functionality to be
 172             available, including a mounted <filename>/sys</filename>,
 173             <filename>/proc</filename>, <filename>/dev</filename>,
 174             <filename>/usr</filename>.
 175           </para>
 176         </listitem>
 177
 178         <listitem>
 179           <para>
 180             Units written by generators are removed when the configuration
 181             is reloaded. That means the lifetime of the generated
 182             units is closely bound to the reload cycles of
 183             <command>systemd</command> itself.
 184           </para>
 185         </listitem>
 186
 187         <listitem>
 188           <para>
 189             Generators should only be used to generate unit files and symlinks to them, not any other kind of
 190             configuration. Due to the lifecycle logic mentioned above, generators are not a good fit to generate
 191             dynamic configuration for other services. If you need to generate dynamic configuration for other services,
 192             do so in normal services you order before the service in question.
 193           </para>
 194         </listitem>
 195
 196         <listitem>
 197           <para>
 198             Since
 199             <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 200             is not available (see above), log messages have to be
 201             written to <filename>/dev/kmsg</filename> instead.
 202           </para>
 203         </listitem>
 204
 205         <listitem>
 206           <para>
 207             It is a good idea to use the
 208             <varname>SourcePath=</varname> directive in generated unit
 209             files to specify the source configuration file you are
 210             generating the unit from. This makes things more easily
 211             understood by the user and also has the benefit that
 212             systemd can warn the user about configuration files that
 213             changed on disk but have not been read yet by systemd.
 214           </para>
 215         </listitem>
 216
 217         <listitem>
 218           <para>
 219             Generators may write out dynamic unit files or just hook
 220             unit files into other units with the usual
 221             <filename>.wants/</filename> or
 222             <filename>.requires/</filename> symlinks. Often, it is
 223             nicer to simply instantiate a template unit file from
 224             <filename>/usr</filename> with a generator instead of
 225             writing out entirely dynamic unit files. Of course, this
 226             works only if a single parameter is to be used.
 227           </para>
 228         </listitem>
 229
 230         <listitem>
 231           <para>
 232             If you are careful, you can implement generators in shell
 233             scripts. We do recommend C code however, since generators
 234             are executed synchronously and hence delay the
 235             entire boot if they are slow.
 236           </para>
 237         </listitem>
 238
 239         <listitem>
 240           <para>Regarding overriding semantics: there are two rules we
 241           try to follow when thinking about the overriding semantics:
 242           </para>
 243
 244           <orderedlist numeration="lowerroman">
 245             <listitem>
 246               <para>User configuration should override vendor
 247               configuration. This (mostly) means that stuff from
 248               <filename>/etc</filename> should override stuff from
 249               <filename>/usr</filename>.</para>
 250             </listitem>
 251
 252             <listitem>
 253               <para>Native configuration should override non-native
 254               configuration. This (mostly) means that stuff you
 255               generate should never override native unit files for the
 256               same purpose.</para>
 257             </listitem>
 258           </orderedlist>
 259
 260           <para>Of these two rules the first rule is probably the more
 261           important one and breaks the second one sometimes. Hence,
 262           when deciding whether to user argv[1], argv[2], or argv[3],
 263           your default choice should probably be argv[1].</para>
 264         </listitem>
 265
 266         <listitem>
 267           <para>
 268             Instead of heading off now and writing all kind of
 269             generators for legacy configuration file formats, please
 270             think twice! It is often a better idea to just deprecate
 271             old stuff instead of keeping it artificially alive.
 272           </para>
 273         </listitem>
 274       </itemizedlist>
 275     </refsect2>
 276   </refsect1>
 277
 278   <refsect1>
 279     <title>Examples</title>
 280     <example>
 281       <title>systemd-fstab-generator</title>
 282
 283       <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 284       converts <filename>/etc/fstab</filename> into native mount
 285       units. It uses argv[1] as location to place the generated unit
 286       files in order to allow the user to override
 287       <filename>/etc/fstab</filename> with her own native unit files,
 288       but also to ensure that <filename>/etc/fstab</filename>
 289       overrides any vendor default from <filename>/usr</filename>.
 290       </para>
 291
 292       <para>After editing <filename>/etc/fstab</filename>, the user
 293       should invoke <command>systemctl daemon-reload</command>. This
 294       will re-run all generators and cause <command>systemd</command>
 295       to reload units from disk. To actually mount new directories
 296       added to <filename>fstab</filename>, <command>systemctl start
 297       <replaceable>/path/to/mountpoint</replaceable></command> or
 298       <command>systemctl start local-fs.target</command> may be used.
 299       </para>
 300     </example>
 301
 302     <example>
 303       <title>systemd-system-update-generator</title>
 304
 305       <para><citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 306       temporarily redirects <filename>default.target</filename> to
 307       <filename>system-update.target</filename>, if a system update is
 308       scheduled. Since this needs to override the default user
 309       configuration for <filename>default.target</filename>, it uses
 310       argv[2]. For details about this logic, see
 311       <citerefentry><refentrytitle>systemd.offline-updates</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
 312       </para>
 313     </example>
 314
 315     <example>
 316       <title>Debugging a generator</title>
 317
 318       <programlisting>dir=$(mktemp -d)
 319 SYSTEMD_LOG_LEVEL=debug &systemgeneratordir;/systemd-fstab-generator \
 320         "$dir" "$dir" "$dir"
 321 find $dir</programlisting>
 322     </example>
 323   </refsect1>
 324
 325   <refsect1>
 326     <title>See also</title>
 327
 328     <para>
 329       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 330       <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 331       <citerefentry><refentrytitle>systemd-debug-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 332       <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 333       <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 334       <citerefentry><refentrytitle>systemd-getty-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 335       <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 336       <citerefentry><refentrytitle>systemd-hibernate-resume-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>