final v236 update (#7649)

[thirdparty/systemd.git] / man / systemd.generator.xml

diff --git a/man/systemd.generator.xml b/man/systemd.generator.xml
index 919c8f8080d36deb41567e5da3b6848e9cc57f0a..55bb2b4a901c03cd6c3c4a40ff8453a5c6b787d0 100644 (file)
--- 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>
@@ -188,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>
 
@@ -313,8 +310,8 @@
       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>
@@ -342,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>