man: unify titling, fix description of precedence in sysusers.d(5)

Fixes #6639.

(This behaviour of systemd-sysusers is long established, so it's better
to adjust the documentation rather than change the code. If there are any
situations out there where it matters, users must have adjusted to the
current behaviour.)

4 files changed, 34 insertions, 7 deletions

diff --git a/man/standard-conf.xml b/man/standard-conf.xml
index 6edbb7ff83..40764f525b 100644
--- a/man/standard-conf.xml
+++ b/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'>
diff --git a/man/systemd-sysusers.xml b/man/systemd-sysusers.xml
index 4892caad12..990b935cf2 100644
--- a/man/systemd-sysusers.xml
+++ b/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>
 
diff --git a/man/sysusers.d.xml b/man/sysusers.d.xml
index 2b87385d9c..c8f4c9cee7 100644
--- a/man/sysusers.d.xml
+++ b/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,6 +71,33 @@
     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>
 
@@ -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>
 
diff --git a/man/tmpfiles.d.xml b/man/tmpfiles.d.xml
index 29f8553196..a5c2b59e7e 100644
--- a/man/tmpfiles.d.xml
+++ b/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>