diff options
Diffstat (limited to 'man/systemd.generator.xml')
| -rw-r--r-- | man/systemd.generator.xml | 348 |
1 files changed, 0 insertions, 348 deletions
diff --git a/man/systemd.generator.xml b/man/systemd.generator.xml deleted file mode 100644 index 4b80dab108..0000000000 --- a/man/systemd.generator.xml +++ /dev/null @@ -1,348 +0,0 @@ -<?xml version='1.0'?> <!--*-nxml-*--> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ -<!ENTITY % entities SYSTEM "custom-entities.ent" > -%entities; -]> - -<!-- - This file is part of systemd. - - Copyright 2015 Zbigniew Jędrzejewski-Szmek - - systemd is free software; you can redistribute it and/or modify it - under the terms of the GNU Lesser General Public License as published by - the Free Software Foundation; either version 2.1 of the License, or - (at your option) any later version. - - systemd is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public License - along with systemd; If not, see <http://www.gnu.org/licenses/>. ---> - -<refentry id="systemd.generator"> - <refentryinfo> - <title>systemd.generator</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd.generator</refentrytitle> - <manvolnum>7</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd.generator</refname> - <refpurpose>Systemd unit generators</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>/path/to/generator</command> - <arg choice="plain"><replaceable>normal-dir</replaceable></arg> - <arg choice="plain"><replaceable>early-dir</replaceable></arg> - <arg choice="plain"><replaceable>late-dir</replaceable></arg> - </cmdsynopsis> - - <para> - <literallayout><filename>/run/systemd/system-generators/*</filename> -<filename>/etc/systemd/system-generators/*</filename> -<filename>/usr/local/lib/systemd/system-generators/*</filename> -<filename>&systemgeneratordir;/*</filename></literallayout> - </para> - - <para> - <literallayout><filename>/run/systemd/user-generators/*</filename> -<filename>/etc/systemd/user-generators/*</filename> -<filename>/usr/local/lib/systemd/user-generators/*</filename> -<filename>&usergeneratordir;/*</filename></literallayout> - </para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - <para>Generators are small binaries that live in - <filename>&usergeneratordir;/</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. - Generators can dynamically generate unit files or create symbolic - links to unit files to add additional dependencies, thus extending - or overriding existing definitions. Their main purpose is to - convert configuration files that are not native unit files - dynamically into native unit files.</para> - - <para>Generators are loaded from a set of paths determined during - compilation, as listed above. System and user generators are loaded - from directories with names ending in - <filename>system-generators/</filename> and - <filename>user-generators/</filename>, respectively. Generators - found in directories listed earlier override the ones with the - same name in directories lower in the list. A symlink to - <filename>/dev/null</filename> or an empty file can be used to - mask a generator, thereby preventing it from running. Please note - that the order of the two directories with the highest priority is - reversed with respect to the unit load path, and generators in - <filename>/run</filename> overwrite those in - <filename>/etc</filename>.</para> - - <para>After installing new generators or updating the - configuration, <command>systemctl daemon-reload</command> may be - executed. This will delete the previous configuration created by - generators, re-run all generators, and cause - <command>systemd</command> to reload units from disk. See - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - for more information. - </para> - </refsect1> - - <refsect1> - <title>Writing generators</title> - - <para>Generators are invoked with three arguments: paths to - runtime directories where generators can place their generated - unit files or symlinks.</para> - - <orderedlist> - <listitem> - <para><parameter>normal-dir</parameter></para> - <para>argv[1] may be used to override unit files in - <filename>/usr</filename>, but not those in - <filename>/etc</filename>. This means that unit files placed - in this directory take precedence over vendor unit - configuration but not over native user/administrator unit - configuration.</para> - </listitem> - - <listitem> - <para><parameter>early-dir</parameter></para> - <para>argv[2] may be used to override unit files in - <filename>/usr</filename> and in - <filename>/etc</filename>. This means that unit files placed - in this directory take precedence over all configuration, - both vendor and user/administrator.</para> - </listitem> - - <listitem> - <para><parameter>late-dir</parameter></para> - <para>argv[3] may be used to extend the unit file tree without - overriding any other unit files. Any native configuration - files supplied by the vendor or user/administrator take - precedence over the generated ones placed in this directory. - </para> - </listitem> - </orderedlist> - - <refsect2> - <title>Notes</title> - - <itemizedlist> - <listitem> - <para> - All generators are executed in parallel. That means all - executables are started at the very same time and need to - be able to cope with this parallelism. - </para> - </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 - <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>. - </para> - </listitem> - - <listitem> - <para> - Units written by generators are removed when the configuration - is reloaded. That means the lifetime of the generated - units is closely bound to the reload cycles of - <command>systemd</command> itself. - </para> - </listitem> - - <listitem> - <para> - Generators should only be used to generate unit files, 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> - </listitem> - - <listitem> - <para> - Since - <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> - is not available (see above), log messages have to be - written to <filename>/dev/kmsg</filename> instead. - </para> - </listitem> - - <listitem> - <para> - It is a good idea to use the - <varname>SourcePath=</varname> directive in generated unit - files to specify the source configuration file you are - generating the unit from. This makes things more easily - understood by the user and also has the benefit that - systemd can warn the user about configuration files that - changed on disk but have not been read yet by systemd. - </para> - </listitem> - - <listitem> - <para> - Generators may write out dynamic unit files or just hook - unit files into other units with the usual - <filename>.wants/</filename> or - <filename>.requires/</filename> symlinks. Often, it is - nicer to simply instantiate a template unit file from - <filename>/usr</filename> with a generator instead of - writing out entirely dynamic unit files. Of course, this - works only if a single parameter is to be used. - </para> - </listitem> - - <listitem> - <para> - If you are careful, you can implement generators in shell - scripts. We do recommend C code however, since generators - are executed synchronously and hence delay the - entire boot if they are slow. - </para> - </listitem> - - <listitem> - <para>Regarding overriding semantics: there are two rules we - try to follow when thinking about the overriding semantics: - </para> - - <orderedlist numeration="lowerroman"> - <listitem> - <para>User configuration should override vendor - configuration. This (mostly) means that stuff from - <filename>/etc</filename> should override stuff from - <filename>/usr</filename>.</para> - </listitem> - - <listitem> - <para>Native configuration should override non-native - configuration. This (mostly) means that stuff you - generate should never override native unit files for the - same purpose.</para> - </listitem> - </orderedlist> - - <para>Of these two rules the first rule is probably the more - important one and breaks the second one sometimes. Hence, - when deciding whether to user argv[1], argv[2], or argv[3], - your default choice should probably be argv[1].</para> - </listitem> - - <listitem> - <para> - Instead of heading off now and writing all kind of - generators for legacy configuration file formats, please - think twice! It is often a better idea to just deprecate - old stuff instead of keeping it artificially alive. - </para> - </listitem> - </itemizedlist> - </refsect2> - </refsect1> - - <refsect1> - <title>Examples</title> - <example> - <title>systemd-fstab-generator</title> - - <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> - converts <filename>/etc/fstab</filename> into native mount - units. It uses argv[1] as location to place the generated unit - files in order to allow the user to override - <filename>/etc/fstab</filename> with her own native unit files, - but also to ensure that <filename>/etc/fstab</filename> - overrides any vendor default from <filename>/usr</filename>. - </para> - - <para>After editing <filename>/etc/fstab</filename>, the user - should invoke <command>systemctl daemon-reload</command>. This - will re-run all generators and cause <command>systemd</command> - to reload units from disk. To actually mount new directories - added to <filename>fstab</filename>, <command>systemctl start - <replaceable>/path/to/mountpoint</replaceable></command> or - <command>systemctl start local-fs.target</command> may be used. - </para> - </example> - - <example> - <title>systemd-system-update-generator</title> - - <para><citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> - temporarily redirects <filename>default.target</filename> to - <filename>system-update.target</filename> if a system update is - scheduled. Since this needs to override the default user - configuration for <filename>default.target</filename>, it uses - argv[2]. For details about this logic, see - <ulink url="http://www.freedesktop.org/wiki/Software/systemd/SystemUpdates">Implementing - Offline System Updates</ulink>.</para> - </example> - - <example> - <title>Debugging a generator</title> - - <programlisting>dir=$(mktemp -d) -SYSTEMD_LOG_LEVEL=debug &systemgeneratordir;/systemd-fstab-generator \ - "$dir" "$dir" "$dir" -find $dir</programlisting> - </example> - </refsect1> - - <refsect1> - <title>See also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-debug-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-getty-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-hibernate-resume-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-sysv-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> -</refentry> |