Merge pull request #6820 from keszybz/sysusers-doc-update

Assorted updates to man pages

man/standard-conf.xml

@@ -32,7 +32,6 @@
     <filename>/etc/</filename>, with the same filename as the vendor
     configuration file. If the vendor configuration file is included in
     the initrd image, the image has to be regenerated.</para>
-
   </refsection>
 
   <refsection id='main-conf'>

man/systemd-sysusers.xml

@@ -74,7 +74,7 @@
     specified in
     <citerefentry><refentrytitle>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
     are searched for a matching file. If the string
-    <filename>-</filename> is specified as filename, entries from the
+    <literal>-</literal> is specified instead of a filename, entries from the
     standard input of the process are read.</para>
   </refsect1>
 

man/systemd.link.xml

@@ -79,7 +79,7 @@
     how the device should be configured. The first (in lexical order)
     of the link files that matches a given device is applied. Note
     that a default file <filename>99-default.link</filename> is
-    shipped by the system, any user-supplied
+    shipped by the system. Any user-supplied
     <filename>.link</filename> should hence have a lexically earlier
     name to be considered at all.</para>
 
@@ -332,6 +332,16 @@
           <varname>NamePolicy=</varname> fail, or in case
           <varname>NamePolicy=</varname> is missing or
           disabled.</para>
+
+          <para>Note that specifying a name that the kernel might use for another
+          interface (for example <literal>eth0</literal>) is dangerous because the
+          name assignment done by udev will race with the assignment done by the
+          kernel, and only one interface may use the name. Depending on the order of
+          operations, either udev or the kernel will win, making the naming
+          unpredictable. It is best to use some different prefix, for example
+          <literal>internal0</literal>/<literal>external0</literal> or
+          <literal>lan0</literal>/<literal>lan1</literal>/<literal>lan3</literal>.
+          </para>
         </listitem>
       </varlistentry>
       <varlistentry>

man/sysusers.d.xml

@@ -63,7 +63,7 @@
   </refsect1>
 
   <refsect1>
-    <title>Configuration Format</title>
+    <title>Configuration Directories and Precedence</title>
 
     <para>Each configuration file shall be named in the style of
     <filename><replaceable>package</replaceable>.conf</filename> or
@@ -71,15 +71,42 @@
     The second variant should be used when it is desirable to make it
     easy to override just this part of configuration.</para>
 
+    <para>Files in <filename>/etc/sysusers.d</filename> override files
+    with the same name in <filename>/usr/lib/sysusers.d</filename> and
+    <filename>/run/sysusers.d</filename>. Files in
+    <filename>/run/sysusers.d</filename> override files with the same
+    name in <filename>/usr/lib/sysusers.d</filename>. Packages should
+    install their configuration files in
+    <filename>/usr/lib/sysusers.d</filename>. Files in
+    <filename>/etc/sysusers.d</filename> are reserved for the local
+    administrator, who may use this logic to override the
+    configuration files installed by vendor packages. All
+    configuration files are sorted by their filename in lexicographic
+    order, regardless of which of the directories they reside in. If
+    multiple files specify the same path, the entry in the file with
+    the lexicographically earliest name will be applied. All later
+    entries for the same user and group names will be logged as warnings.
+    </para>
+
+    <para>If the administrator wants to disable a configuration file
+    supplied by the vendor, the recommended way is to place a symlink
+    to <filename>/dev/null</filename> in
+    <filename>/etc/sysusers.d/</filename> bearing the same filename.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Configuration File Format</title>
+
     <para>The file format is one line per user or group containing
     name, ID, GECOS field description and home directory:</para>
 
-    <programlisting># Type Name ID GECOS
-u httpd 440 "HTTP User"
-u authd /usr/bin/authd "Authorization user"
-g input - -
-m authd input
-u root 0 "Superuser" /root</programlisting>
+    <programlisting>#Type  Name   ID              GECOS                 Home directory
+u      httpd  440             "HTTP User"
+u      authd  /usr/bin/authd  "Authorization user"
+g      input  -               -
+m      authd  input
+u      root   0               "Superuser"           /root</programlisting>
 
     <para>Empty lines and lines beginning with the <literal>#</literal> character are ignored, and may be used for
     commenting.</para>
@@ -198,11 +225,8 @@ u root 0 "Superuser" /root</programlisting>
       should otherwise be left unset, or be set to
       <literal>-</literal>.</para>
     </refsect2>
-
   </refsect1>
 
-  <xi:include href="standard-conf.xml" xpointer="confd" />
-
   <refsect1>
     <title>Idempotence</title>
 

man/tmpfiles.d.xml

@@ -76,7 +76,7 @@
   </refsect1>
 
   <refsect1>
-    <title>Configuration Format</title>
+    <title>Configuration Directories and Precedence</title>
 
     <para>Each configuration file shall be named in the style of
     <filename><replaceable>package</replaceable>.conf</filename> or
@@ -112,6 +112,10 @@
     to <filename>/dev/null</filename> in
     <filename>/etc/tmpfiles.d/</filename> bearing the same filename.
     </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Configuration File Format</title>
 
     <para>The configuration format is one line per path containing
     type, path, mode, ownership, age, and argument fields:</para>