[systemd-devel] [PATCH 02/10] man: Factor out a common snippet for .d directories and precedence
Josh Triplett
josh at joshtriplett.org
Sat Nov 29 01:05:43 PST 2014
Several manpages contain duplicate text describing a standard set of .d
configuration directories, with the usual sorting, precedence,
overrides, and so on. Factor this common text out using XInclude before
proliferating it even further.
---
Makefile-man.am | 1 +
man/binfmt.d.xml | 30 ++++--------------------------
man/logind.conf.xml | 27 +++++----------------------
man/modules-load.d.xml | 26 ++++----------------------
man/standard-conf.xml | 45 +++++++++++++++++++++++++++++++++++++++++++++
man/sysctl.d.xml | 33 ++++-----------------------------
man/sysusers.d.xml | 27 ++++++---------------------
7 files changed, 69 insertions(+), 120 deletions(-)
create mode 100644 man/standard-conf.xml
diff --git a/Makefile-man.am b/Makefile-man.am
index 906a968..c24606a 100644
--- a/Makefile-man.am
+++ b/Makefile-man.am
@@ -1638,6 +1638,7 @@ EXTRA_DIST += \
man/sd_uid_get_state.xml \
man/sd_watchdog_enabled.xml \
man/shutdown.xml \
+ man/standard-conf.xml \
man/standard-options.xml \
man/sysctl.d.xml \
man/systemctl.xml \
diff --git a/man/binfmt.d.xml b/man/binfmt.d.xml
index 2270166..55a3df0 100644
--- a/man/binfmt.d.xml
+++ b/man/binfmt.d.xml
@@ -19,7 +19,8 @@
You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
-<refentry id="binfmt.d" conditional='ENABLE_BINFMT'>
+<refentry id="binfmt.d" conditional='ENABLE_BINFMT'
+ xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>binfmt.d</title>
@@ -74,33 +75,10 @@
<para>Empty lines and lines beginning with ; and # are
ignored. Note that this means you may not use ; and #
as delimiter in binary format rules.</para>
-
- <para>Each configuration file shall be named in the
- style of <filename><replaceable>program</replaceable>.conf</filename>.
- Files in <filename>/etc/</filename> override files
- with the same name in <filename>/usr/lib/</filename>
- and <filename>/run/</filename>. Files in
- <filename>/run/</filename> override files with the
- same name in <filename>/usr/lib/</filename>. Packages
- should install their configuration files in
- <filename>/usr/lib/</filename>, files in
- <filename>/etc/</filename> are reserved for the local
- administrator, who may use this logic to override the
- configuration files installed from vendor
- packages. All files are sorted by their filename in
- lexicographic order, regardless of which of the
- directories they reside in. If multiple files specify
- the same binary type name, the entry in the file with
- the lexicographically latest name will be applied.</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/binfmt.d/</filename> bearing the
- same filename.</para>
</refsect1>
+ <xi:include href="standard-conf.xml" xpointer="confd" />
+
<refsect1>
<title>Example</title>
<example>
diff --git a/man/logind.conf.xml b/man/logind.conf.xml
index ca7525f..e927cf4 100644
--- a/man/logind.conf.xml
+++ b/man/logind.conf.xml
@@ -22,7 +22,8 @@
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
-<refentry id="logind.conf" conditional='ENABLE_LOGIND'>
+<refentry id="logind.conf" conditional='ENABLE_LOGIND'
+ xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>logind.conf</title>
<productname>systemd</productname>
@@ -59,29 +60,11 @@
<title>Description</title>
<para>These files configure various parameters of the systemd login manager, <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
-
- <para>Each configuration file shall be named in the style of
- <filename><replaceable>filename</replaceable>.conf</filename>.
- Files in <filename>/etc/</filename> override files with the
- same name in <filename>/usr/lib/</filename> and
- <filename>/run/</filename>. Files in
- <filename>/run/</filename> override files with the same name in
- <filename>/usr/lib/</filename>. Packages should install their
- configuration files in <filename>/usr/lib/</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. 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 option, the
- entry in the file with the lexicographically latest name will
- be applied; entries in any <filename>logind.conf.d</filename>
- file override entries in
- <filename>/etc/systemd/logind.conf</filename>. It is
- recommended to prefix all filenames with a two-digit number and
- a dash, to simplify the ordering of the files.</para>
</refsect1>
+ <xi:include href="standard-conf.xml" xpointer="confd" />
+ <xi:include href="standard-conf.xml" xpointer="conf" />
+
<refsect1>
<title>Options</title>
diff --git a/man/modules-load.d.xml b/man/modules-load.d.xml
index 33c466f..4b578d7 100644
--- a/man/modules-load.d.xml
+++ b/man/modules-load.d.xml
@@ -19,7 +19,8 @@
You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
-<refentry id="modules-load.d" conditional='HAVE_KMOD'>
+<refentry id="modules-load.d" conditional='HAVE_KMOD'
+ xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>modules-load.d</title>
@@ -74,29 +75,10 @@
list of kernel module names to load, separated by
newlines. Empty lines and lines whose first
non-whitespace character is # or ; are ignored.</para>
-
- <para>Each configuration file shall be named in the
- style of <filename><replaceable>program</replaceable>.conf</filename>.
- Files in <filename>/etc/</filename> override files
- with the same name in <filename>/usr/lib/</filename>
- and <filename>/run/</filename>. Files in
- <filename>/run/</filename> override files with the
- same name in <filename>/usr/lib/</filename>. Packages
- should install their configuration files in
- <filename>/usr/lib/</filename>, files in
- <filename>/etc/</filename> are reserved for the local
- administrator, who may use this logic to override the
- configuration files installed from vendor
- packages.</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/modules-load.d/</filename> bearing the
- same filename.</para>
</refsect1>
+ <xi:include href="standard-conf.xml" xpointer="confd" />
+
<refsect1>
<title>Example</title>
<example>
diff --git a/man/standard-conf.xml b/man/standard-conf.xml
new file mode 100644
index 0000000..b87d7e9
--- /dev/null
+++ b/man/standard-conf.xml
@@ -0,0 +1,45 @@
+<?xml version="1.0"?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
+<!DOCTYPE refsection PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<refsection>
+ <refsection id='confd'>
+ <title>Configuration Directories and Precedence</title>
+
+ <para>Configuration files are read from directories in
+ <filename>/etc/</filename>, <filename>/run/</filename>, and
+ <filename>/usr/lib/</filename>, in order of precedence.
+ Each configuration file in these configuration directories shall be named in
+ the style of <filename><replaceable>filename</replaceable>.conf</filename>.
+ Files in <filename>/etc/</filename> override files with the same name in
+ <filename>/run/</filename> and <filename>/usr/lib/</filename>. Files in
+ <filename>/run/</filename> override files with the same name in
+ <filename>/usr/lib/</filename>.</para>
+
+ <para>Packages should install their configuration files in
+ <filename>/usr/lib/</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. 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 option,
+ the entry in the file with the lexicographically latest name will take
+ precedence. It is recommended to prefix all filenames with a two-digit number
+ and a dash, to simplify the ordering of the files.</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 the configuration directory in
+ <filename>/etc/</filename>, with the same filename as the vendor
+ 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>
+</refsection>
diff --git a/man/sysctl.d.xml b/man/sysctl.d.xml
index 922b5c4..c67a199 100644
--- a/man/sysctl.d.xml
+++ b/man/sysctl.d.xml
@@ -18,7 +18,8 @@
You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
-<refentry id="sysctl.d">
+<refentry id="sysctl.d"
+ xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sysctl.d</title>
@@ -70,27 +71,6 @@
is <literal>#</literal> or <literal>;</literal> are
ignored.</para>
- <para>Each configuration file shall be named in the
- style of <filename><replaceable>program</replaceable>.conf</filename>.
- Files in <filename>/etc/</filename> override files
- with the same name in <filename>/usr/lib/</filename>
- and <filename>/run/</filename>. Files in
- <filename>/run/</filename> override files with the same
- name in <filename>/usr/lib/</filename>. Packages
- should install their configuration files in
- <filename>/usr/lib/</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. 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 variable name, the entry in the file with the
- lexicographically latest name will be applied. It is
- recommended to prefix all filenames with a two-digit
- number and a dash, to simplify the ordering of the
- files.</para>
-
<para>Note that either <literal>/</literal> or
<literal>.</literal> may be used as separators within
sysctl variable names. If the first separator is a
@@ -109,13 +89,6 @@
<filename>/proc/sys/net/ipv4/conf/enp3s0.200/forwarding</filename>.
</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/sysctl.d/</filename> bearing the
- same filename.</para>
-
<para>The settings configured with
<filename>sysctl.d</filename> files will be applied
early on boot. The network interface-specific options
@@ -142,6 +115,8 @@
example below).</para>
</refsect1>
+ <xi:include href="standard-conf.xml" xpointer="confd" />
+
<refsect1>
<title>Examples</title>
<example>
diff --git a/man/sysusers.d.xml b/man/sysusers.d.xml
index 18c71db..ac2db98 100644
--- a/man/sysusers.d.xml
+++ b/man/sysusers.d.xml
@@ -19,7 +19,8 @@
You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
-<refentry id="sysusers.d">
+<refentry id="sysusers.d"
+ xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sysusers.d</title>
@@ -239,8 +240,10 @@ u root 0 "Superuser" /root</programlisting>
</refsect1>
+ <xi:include href="standard-conf.xml" xpointer="confd" />
+
<refsect1>
- <title>Overriding vendor configuration</title>
+ <title>Idempotence</title>
<para>Note that <command>systemd-sysusers</command>
will do nothing if the specified users or groups
@@ -248,31 +251,13 @@ u root 0 "Superuser" /root</programlisting>
<filename>sysusers.d</filename> vendor configuration,
except to block certain users or groups from being
created.</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>. The scheme is the same as for
- <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- except for the directory name.</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>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd-sysusers</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ <citerefentry><refentrytitle>systemd-sysusers</refentrytitle><manvolnum>8</manvolnum></citerefentry>
</para>
</refsect1>
--
2.1.3
More information about the systemd-devel
mailing list