shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2025-03-28 02:50:16 +03:00
Code

man: various improvements to systemd.generator(7)

Browse Source 
In particular, make clear the .d/*.conf unit file drop-ins are OK to
generate from generators.

Inspired by: https://lists.freedesktop.org/archives/systemd-devel/2021-February/046148.html
This commit is contained in:
Lennart Poettering 2021-02-23 14:07:46 +01:00 committed by Yu Watanabe
parent 774c0e433c
commit 3acf00a5a4
1 changed files with 27 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
man/systemd.generator.xml
View File

@ -47,12 +47,13 @@
<refsect1>
<title>Description</title>
<para>Generators are small executables that live in
<filename>&systemgeneratordir;/</filename> and other directories listed above.
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
will execute those binaries very early at bootup and at configuration reload time
— before unit files are loaded. Their main purpose is to convert configuration
that is not native into dynamically generated unit files.</para>
<para>Generators are small executables placed in <filename>&systemgeneratordir;/</filename> and other
directories listed above.
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> will execute
these binaries very early at bootup and at configuration reload time — before unit files are
loaded. Their main purpose is to convert configuration that is not native to the service manager into
dynamically generated unit files, symlinks or unit file drop-ins, so that they can extend the unit file
hierarchy the service manager subsequently loads and operates on.</para>
<para>Each generator is called with three directory paths that are to be used for
generator output. In these three directories, generators may dynamically generate
@ -155,17 +156,15 @@
</listitem>
<listitem>
<para>Generators are run very early at boot and cannot rely on any external
services. They may not talk to any other process. That includes simple things
such as logging to
<citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
or <command>systemd</command> itself (this means: no
<para>Generators are run very early at boot and cannot rely on any external services. They may not
talk to any other process. That includes simple things such as logging to <citerefentry
project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>, or
<command>systemd</command> itself (this means: no
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>)!
Non-essential file systems like <filename>/var/</filename> and
<filename>/home/</filename> are mounted after generators have run. Generators
can however rely on the most basic kernel functionality to be available,
including a mounted <filename>/sys/</filename>, <filename>/proc/</filename>,
<filename>/dev/</filename>, <filename>/usr/</filename>.
Non-essential file systems like <filename>/var/</filename> and <filename>/home/</filename> are
mounted after generators have run. Generators can however rely on the most basic kernel functionality
to be available, as well as mounted <filename>/sys/</filename>, <filename>/proc/</filename>,
<filename>/dev/</filename>, <filename>/usr/</filename> and <filename>/run/</filename> file systems.
</para>
</listitem>
@ -176,12 +175,18 @@
</listitem>
<listitem>
<para>Generators should only be used to generate unit files and symlinks to
them, not any other kind of configuration. Due to the lifecycle logic
mentioned above, generators are not a good fit to generate dynamic
configuration for other services. If you need to generate dynamic
configuration for other services, do so in normal services you order before
the service in question.</para>
<para>Generators should only be used to generate unit files, <filename>.d/*.conf</filename> drop-ins
for them and symlinks to them, not any other kind of non-unit related configuration. Due to the
lifecycle logic mentioned above, generators are not a good fit to generate dynamic configuration for
other services. If you need to generate dynamic configuration for other services, do so in normal
services you order before the service in question.</para>
<para>Note that using the <varname>StandardInputData=</varname>/<varname>StandardInputText=</varname>
settings of service unit files (see
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>), it
is possible to make arbitrary input data (including daemon-specific configuration) part of the unit
definitions, which often might be sufficient to embed data or configuration for other programs into
unit files in a native fashion.</para>
</listitem>
<listitem>