From 8165be2edf635535fc742cb77edc7e66f173f231 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@in.waw.pl>
Date: Thu, 14 Sep 2017 11:55:00 +0200
Subject: [PATCH] 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.)
---
 man/standard-conf.xml    |  1 -
 man/systemd-sysusers.xml |  2 +-
 man/sysusers.d.xml       | 32 ++++++++++++++++++++++++++++----
 man/tmpfiles.d.xml       |  6 +++++-
 4 files changed, 34 insertions(+), 7 deletions(-)

diff --git a/man/standard-conf.xml b/man/standard-conf.xml
index 6edbb7ff83a..40764f525b2 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 4892caad129..990b935cf21 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 2b87385d9c3..c8f4c9cee7e 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 29f85531967..a5c2b59e7e1 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>
-- 
2.39.2