Do not advertise .d snippets over main config file

For daemons which have a main configuration file, there's
little reason for the administrator to use configuration snippets.
They are useful for packagers which need to override settings, but
we shouldn't advertise that as the main way of configuring those
services.

https://bugs.freedesktop.org/show_bug.cgi?id=89397

1 files changed, 34 insertions, 8 deletions

diff --git a/man/standard-conf.xml b/man/standard-conf.xml
index b87d7e955..36af45927 100644
--- a/man/standard-conf.xml
+++ b/man/standard-conf.xml
@@ -33,13 +33,39 @@
     configuration file.</para>
   </refsection>
 
-  <refsection id='conf'>
-    <title>Configuration File</title>
-
-    <para>Configuration is also read from a single configuration file in
-    <filename>/etc/</filename>. This file is read before any of the
-    configuration directories, and has the lowest precedence; entries in a file
-    in any configuration directory override entries in the single configuration
-    file.</para>
+  <refsection id='main-conf'>
+    <title>Configuration Directories and Precedence</title>
+
+    <para>Default configuration is defined during compilation, so a
+    configuration file is only needed when it is necessary to deviate
+    from those defaults. By default the configuration file in
+    <filename>/etc/systemd/</filename> contains commented out entries
+    showing the defaults as a guide to the administrator. This file
+    can be edited to create local overrides.
+    </para>
+
+    <para>When packages need to customize the configuration, they can
+    install configuration snippets in
+    <filename>/usr/lib/systemd/*.conf.d/</filename>. Files in
+    <filename>/etc/</filename> are reserved for the local
+    administrator, who may use this logic to override the
+    configuration files installed by vendor packages. The main
+    configuration file is read before any of the configuration
+    directories, and has the lowest precedence; entries in a file in
+    any configuration directory override entries in the single
+    configuration file. Files in the
+    <filename>logind.conf.d/</filename> configuration subdirectories
+    are sorted by their filename in lexicographic order, regardless of
+    which of the subdirectories they reside in. If multiple files
+    specify the same option, the entry in the file with the
+    lexicographically latest name takes precedence.  It is recommended
+    to prefix all filenames in those subdirectories with a two-digit
+    number and a dash, to simplify the ordering of the files.</para>
+
+    <para>To disable a configuration file supplied by the vendor, the
+    recommended way is to place a symlink to
+    <filename>/dev/null</filename> in the configuration directory in
+    <filename>/etc/</filename>, with the same filename as the vendor
+    configuration file.</para>
   </refsection>
 </refsection>