man/systemd.generator.html

   1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>systemd.generator</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><style>
   2     a.headerlink {
   3       color: #c60f0f;
   4       font-size: 0.8em;
   5       padding: 0 4px 0 4px;
   6       text-decoration: none;
   7       visibility: hidden;
   8     }
   9
  10     a.headerlink:hover {
  11       background-color: #c60f0f;
  12       color: white;
  13     }
  14
  15     h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
  16       visibility: visible;
  17     }
  18   </style><a href="index.html">Index </a>·
  19   <a href="systemd.directives.html">Directives </a>·
  20   <a href="../python-systemd/index.html">Python </a>·
  21   <a href="../libudev/index.html">libudev </a>·
  22   <a href="../libudev/index.html">gudev </a><span style="float:right">systemd 220</span><hr><div class="refentry"><a name="systemd.generator"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>systemd.generator — Systemd unit generators</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">/path/to/generator</code>   <em class="replaceable"><code>normal-dir</code></em>   <em class="replaceable"><code>early-dir</code></em>   <em class="replaceable"><code>late-dir</code></em> </p></div><p>
  23       </p><div class="literallayout"><p><code class="filename">/run/systemd/system-generators/*</code><br>
  24 <code class="filename">/etc/systemd/system-generators/*</code><br>
  25 <code class="filename">/usr/local/lib/systemd/system-generators/*</code><br>
  26 <code class="filename">/usr/lib/systemd/system-generators/*</code></p></div><p>
  27     </p><p>
  28       </p><div class="literallayout"><p><code class="filename">/run/systemd/user-generators/*</code><br>
  29 <code class="filename">/etc/systemd/user-generators/*</code><br>
  30 <code class="filename">/usr/local/lib/systemd/user-generators/*</code><br>
  31 <code class="filename">/usr/lib/systemd/user-generators/*</code></p></div><p>
  32     </p></div><div class="refsect1"><a name="idm139621018473376"></a><h2 id="Description">Description<a class="headerlink" title="Permalink to this headline" href="#Description">¶</a></h2><p>Generators are small binaries that live in
  33     <code class="filename">/usr/lib/systemd/user-generators/</code> and other directories
  34     listed above.
  35     <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>
  36     will execute those binaries very early at bootup and at
  37     configuration reload time — before unit files are loaded.
  38     Generators can dynamically generate unit files or create symbolic
  39     links to unit files to add additional dependencies, thus extending
  40     or overriding existing definitions. Their main purpose is to
  41     convert configuration files that are not native unit files
  42     dynamically into native unit files.</p><p>Generators are loaded from a set of paths determined during
  43     compilation, listed above. System and user generators are loaded
  44     from directories with names ending in
  45     <code class="filename">system-generators/</code> and
  46     <code class="filename">user-generators/</code>, respectively. Generators
  47     found in directories listed earlier override the ones with the
  48     same name in directories lower in the list. A symlink to
  49     <code class="filename">/dev/null</code> or an empty file can be used to
  50     mask a generator, thereby preventing it from running. Please note
  51     that the order of the two directories with the highest priority is
  52     reversed with respect to the unit load path and generators in
  53     <code class="filename">/run</code> overwrite those in
  54     <code class="filename">/etc</code>.</p><p>After installing new generators or updating the
  55     configuration, <span class="command"><strong>systemctl daemon-reload</strong></span> may be
  56     executed. This will delete the previous configuration created by
  57     generators, re-run all generators, and cause
  58     <span class="command"><strong>systemd</strong></span> to reload units from disk. See
  59     <a href="systemctl.html"><span class="citerefentry"><span class="refentrytitle">systemctl</span>(1)</span></a>
  60     for more information.
  61     </p></div><div class="refsect1"><a name="idm139621018462272"></a><h2 id="Writing generators">Writing generators<a class="headerlink" title="Permalink to this headline" href="#Writing%20generators">¶</a></h2><p>Generators are invoked with three arguments: paths to
  62     runtime directories where generators can place their generated
  63     unit files or symlinks.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><em class="parameter"><code>normal-dir</code></em></p><p>argv[1] may be used to override unit files in
  64         <code class="filename">/usr</code>, but not those in
  65         <code class="filename">/etc</code>. This means that unit files placed
  66         in this directory take precedence over vendor unit
  67         configuration but not over native user/administrator unit
  68         configuration.</p></li><li class="listitem"><p><em class="parameter"><code>early-dir</code></em></p><p>argv[2] may be used to override unit files in
  69         <code class="filename">/usr</code> and in
  70         <code class="filename">/etc</code>. This means that unit files placed
  71         in this directory take precedence over all configuration,
  72         both vendor and user/administrator.</p></li><li class="listitem"><p><em class="parameter"><code>late-dir</code></em></p><p>argv[3] may be used to extend the unit file tree without
  73         overriding any other unit files. Any native configuration
  74         files supplied by the vendor or user/administrator take
  75         precedence over the generated ones placed in this directory.
  76         </p></li></ol></div><div class="refsect2"><a name="idm139621018452528"></a><h3 id="Notes">Notes<a class="headerlink" title="Permalink to this headline" href="#Notes">¶</a></h3><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
  77             All generators are executed in parallel. That means all
  78             executables are started at the very same time and need to
  79             be able to cope with this parallelism.
  80           </p></li><li class="listitem"><p>
  81             Generators are run very early at boot and cannot rely on
  82             any external services. They may not talk to any other
  83             process. That includes simple things such as logging to
  84             <a href="http://man7.org/linux/man-pages/man3/syslog.3.html"><span class="citerefentry"><span class="refentrytitle">syslog</span>(3)</span></a>,
  85             or <span class="command"><strong>systemd</strong></span> itself (this means: no
  86             <a href="systemctl.html"><span class="citerefentry"><span class="refentrytitle">systemctl</span>(1)</span></a>!). They
  87             can however rely on the most basic kernel functionality to
  88             be available, including mounted <code class="filename">/sys</code>,
  89             <code class="filename">/proc</code>, <code class="filename">/dev</code>.
  90           </p></li><li class="listitem"><p>
  91             Units written by generators are removed when configuration
  92             is reloaded. That means the lifetime of the generated
  93             units is closely bound to the reload cycles of
  94             <span class="command"><strong>systemd</strong></span> itself.
  95           </p></li><li class="listitem"><p>
  96             Generators should only be used to generate unit files, not
  97             any other kind of configuration. Due to the lifecycle
  98             logic mentioned above generators are not a good fit to
  99             generate dynamic configuration for other services. If you
 100             need to generate dynamic configuration for other services
 101             do so in normal services you order before the service in
 102             question.
 103           </p></li><li class="listitem"><p>
 104             Since
 105             <a href="http://man7.org/linux/man-pages/man3/syslog.3.html"><span class="citerefentry"><span class="refentrytitle">syslog</span>(3)</span></a>
 106             is not available (see above) log messages have to be
 107             written to <code class="filename">/dev/kmsg</code> instead.
 108           </p></li><li class="listitem"><p>
 109             It is a good idea to use the
 110             <code class="varname">SourcePath=</code> directive in generated unit
 111             files to specify the source configuration file you are
 112             generating the unit from. This makes things more easily
 113             understood by the user and also has the benefit that
 114             systemd can warn the user about configuration files that
 115             changed on disk but have not been read yet by systemd.
 116           </p></li><li class="listitem"><p>
 117             Generators may write out dynamic unit files or just hook
 118             unit files into other units with the usual
 119             <code class="filename">.wants/</code> or
 120             <code class="filename">.requires/</code> symlinks. Often it is
 121             nicer to simply instantiate a template unit file from
 122             <code class="filename">/usr</code> with a generator instead of
 123             writing out entirely dynamic unit files. Of course this
 124             works only if a single parameter is to be used.
 125           </p></li><li class="listitem"><p>
 126             If you are careful you can implement generators in shell
 127             scripts. We do recommend C code however, since generators
 128             delay are executed synchronously and hence delay the
 129             entire boot if they are slow.
 130           </p></li><li class="listitem"><p>Regarding overriding semantics: there are two rules we
 131           try to follow when thinking about the overriding semantics:
 132           </p><div class="orderedlist"><ol class="orderedlist" type="i"><li class="listitem"><p>User configuration should override vendor
 133               configuration. This (mostly) means that stuff from
 134               <code class="filename">/etc</code> should override stuff from
 135               <code class="filename">/usr</code>.</p></li><li class="listitem"><p>Native configuration should override non-native
 136               configuration. This (mostly) means that stuff you
 137               generate should never override native unit files for the
 138               same purpose.</p></li></ol></div><p>Of these two rules the first rule is probably the more
 139           important one and breaks the second one sometimes. Hence,
 140           when deciding whether to user argv[1], argv[2], or argv[3],
 141           your default choice should probably be argv[1].</p></li><li class="listitem"><p>
 142             Instead of heading off now and writing all kind of
 143             generators for legacy configuration file formats, please
 144             think twice! It's often a better idea to just deprecate
 145             old stuff instead of keeping it artificially alive.
 146           </p></li></ul></div></div></div><div class="refsect1"><a name="idm139621018418304"></a><h2 id="Examples">Examples<a class="headerlink" title="Permalink to this headline" href="#Examples">¶</a></h2><div class="example"><a name="idm139621018417664"></a><p class="title"><b>Example 1. systemd-fstab-generator</b></p><div class="example-contents"><p><a href="systemd-fstab-generator.html"><span class="citerefentry"><span class="refentrytitle">systemd-fstab-generator</span>(8)</span></a>
 147       converts <code class="filename">/etc/fstab</code> into native mount
 148       units. It uses argv[1] as location to place the generated unit
 149       files in order to allow the user to override
 150       <code class="filename">/etc/fstab</code> with her own native unit files,
 151       but also to ensure that <code class="filename">/etc/fstab</code>
 152       overrides any vendor default from <code class="filename">/usr</code>.
 153       </p><p>After editing <code class="filename">/etc/fstab</code>, the user
 154       should invoke <span class="command"><strong>systemctl daemon-reload</strong></span>. This
 155       will re-run all generators and cause <span class="command"><strong>systemd</strong></span>
 156       to reload units from disk. To actually mount new directories
 157       added to <code class="filename">fstab</code>, <span class="command"><strong>systemctl start
 158       <em class="replaceable"><code>/path/to/mountpoint</code></em></strong></span> or
 159       <span class="command"><strong>systemctl start local-fs.target</strong></span> may be used.
 160       </p></div></div><br class="example-break"><div class="example"><a name="idm139621018408832"></a><p class="title"><b>Example 2. systemd-system-update-generator</b></p><div class="example-contents"><p><a href="systemd-system-update-generator.html"><span class="citerefentry"><span class="refentrytitle">systemd-system-update-generator</span>(8)</span></a>
 161       temporarily redirects <code class="filename">default.target</code> to
 162       <code class="filename">system-update.target</code> if a system update is
 163       scheduled. Since this needs to override the default user
 164       configuration for <code class="filename">default.target</code> it uses
 165       argv[2]. For details about this logic, see
 166       <a class="ulink" href="http://www.freedesktop.org/wiki/Software/systemd/SystemUpdates" target="_top">Implementing
 167       Offline System Updates</a>.</p></div></div><br class="example-break"><div class="example"><a name="idm139621018404416"></a><p class="title"><b>Example 3. Debuging a generator</b></p><div class="example-contents"><pre class="programlisting">dir=$(mktemp -d)
 168 SYSTEMD_LOG_LEVEL=debug /usr/lib/systemd/system-generators/systemd-fstab-generator \
 169         "$dir" "$dir" "$dir"
 170 find $dir</pre></div></div><br class="example-break"></div><div class="refsect1"><a name="idm139621018402736"></a><h2 id="See also">See also<a class="headerlink" title="Permalink to this headline" href="#See%20also">¶</a></h2><p>
 171       <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
 172       <a href="systemd-cryptsetup-generator.html"><span class="citerefentry"><span class="refentrytitle">systemd-cryptsetup-generator</span>(8)</span></a>,
 173       <a href="systemd-debug-generator.html"><span class="citerefentry"><span class="refentrytitle">systemd-debug-generator</span>(8)</span></a>,
 174       <a href="systemd-efi-boot-generator.html"><span class="citerefentry"><span class="refentrytitle">systemd-efi-boot-generator</span>(8)</span></a>,
 175       <a href="systemd-fstab-generator.html"><span class="citerefentry"><span class="refentrytitle">systemd-fstab-generator</span>(8)</span></a>,
 176       <a href="http://man7.org/linux/man-pages/man5/fstab.5.html"><span class="citerefentry"><span class="refentrytitle">fstab</span>(5)</span></a>,
 177       <a href="systemd-getty-generator.html"><span class="citerefentry"><span class="refentrytitle">systemd-getty-generator</span>(8)</span></a>,
 178       <a href="systemd-gpt-auto-generator.html"><span class="citerefentry"><span class="refentrytitle">systemd-gpt-auto-generator</span>(8)</span></a>,
 179       <a href="systemd-hibernate-resume-generator.html"><span class="citerefentry"><span class="refentrytitle">systemd-hibernate-resume-generator</span>(8)</span></a>,
 180       <a href="systemd-system-update-generator.html"><span class="citerefentry"><span class="refentrytitle">systemd-system-update-generator</span>(8)</span></a>,
 181       <a href="systemd-sysv-generator.html"><span class="citerefentry"><span class="refentrytitle">systemd-sysv-generator</span>(8)</span></a>,
 182       <a href="systemd.unit.html"><span class="citerefentry"><span class="refentrytitle">systemd.unit</span>(5)</span></a>,
 183       <a href="systemctl.html"><span class="citerefentry"><span class="refentrytitle">systemctl</span>(1)</span></a>
 184     </p></div></div></body></html>