X-Git-Url: http://git.ipfire.org/?a=blobdiff_plain;f=man%2Fsystemd.generator.xml;h=55bb2b4a901c03cd6c3c4a40ff8453a5c6b787d0;hb=a1b2c92d8290c76a29ccd0887a92ac064e1bb5a1;hp=b36aab32598ad2e1edbbaef299f1cc34bc6ad94e;hpb=7ca4155737730ece73ae4b4ac80571005cb99b69;p=thirdparty%2Fsystemd.git

diff --git a/man/systemd.generator.xml b/man/systemd.generator.xml
index b36aab32598..55bb2b4a901 100644
--- a/man/systemd.generator.xml
+++ b/man/systemd.generator.xml
@@ -6,6 +6,8 @@
 ]>
 
 <!--
+  SPDX-License-Identifier: LGPL-2.1+
+
   This file is part of systemd.
 
   Copyright 2015 Zbigniew Jędrzejewski-Szmek
@@ -46,7 +48,7 @@
 
   <refnamediv>
     <refname>systemd.generator</refname>
-    <refpurpose>Systemd unit generators</refpurpose>
+    <refpurpose>systemd unit generators</refpurpose>
   </refnamediv>
 
   <refsynopsisdiv>
@@ -74,17 +76,14 @@
 
   <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 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.  Generators may
+    dynamically generate unit files (regular ones, instances as well as templates) and unit file
+    <filename>.d/</filename> drop-ins, or create symbolic links to unit files to add additional dependencies or
+    instantiate existing templates, 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
@@ -122,7 +121,8 @@
         <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
+        <filename>/run</filename> or 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>
@@ -131,7 +131,7 @@
       <listitem>
         <para><parameter>early-dir</parameter></para>
         <para>argv[2] may be used to override unit files in
-        <filename>/usr</filename> and in
+        <filename>/usr</filename>, in <filename>/run</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>
@@ -164,13 +164,16 @@
             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>,
+            <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>!). They
-            can however rely on the most basic kernel functionality to
-            be available, including a mounted <filename>/sys</filename>,
-            <filename>/proc</filename>, <filename>/dev</filename>.
+            <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>
 
@@ -185,13 +188,10 @@
 
         <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.
+            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>
         </listitem>
 
@@ -306,16 +306,16 @@
 
       <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
+      <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>
+      <citerefentry><refentrytitle>systemd.offline-updates</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+      </para>
     </example>
 
     <example>
-      <title>Debuging a generator</title>
+      <title>Debugging a generator</title>
 
       <programlisting>dir=$(mktemp -d)
 SYSTEMD_LOG_LEVEL=debug &systemgeneratordir;/systemd-fstab-generator \
@@ -339,7 +339,8 @@ find $dir</programlisting>
       <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>
+      <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd.environment-generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>
     </para>
   </refsect1>
 </refentry>