summaryrefslogtreecommitdiffstats
path: root/man/standard-conf.xml
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--man/standard-conf.xml76
1 files changed, 54 insertions, 22 deletions
diff --git a/man/standard-conf.xml b/man/standard-conf.xml
index cc2b874..0ff71ec 100644
--- a/man/standard-conf.xml
+++ b/man/standard-conf.xml
@@ -1,5 +1,5 @@
<?xml version="1.0"?>
-<!DOCTYPE refsection PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<!--
@@ -7,8 +7,13 @@
Copyright ยฉ 2014 Josh Triplett
-->
-<refsection>
- <refsection id='confd'>
+<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
+ <refnamediv>
+ <refname/>
+ <refpurpose/>
+ </refnamediv>
+
+ <refsect1 id='confd'>
<title>Configuration Directories and Precedence</title>
<para>Configuration files are read from directories in <filename>/etc/</filename>,
@@ -27,29 +32,40 @@
that is ordered later).</para>
<para>Packages should install their configuration files in <filename>/usr/lib/</filename> (distribution
- packages) or <filename>/usr/local/lib/</filename> (local installs). 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. It is recommended to prefix all filenames with a two-digit number and a
- dash, to simplify the ordering of the files.</para>
+ packages) or <filename>/usr/local/lib/</filename> (local installs)
+ <xi:include xpointer="usr-local-footnote" />.
+ 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.</para>
+
+ <para>It is recommended to prefix all filenames with a two-digit number and a dash to simplify the
+ ordering. It is recommended to use the range 10-40 for configuration files in <filename>/usr/</filename>
+ and the range 60-90 for configuration files in <filename>/etc/</filename> and <filename>/run/</filename>,
+ to make sure that local and transient configuration files will always take priority over configuration
+ files shipped by the OS vendor.</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. If the vendor
configuration file is included in the initrd image, the image has to be regenerated.</para>
- </refsection>
+ </refsect1>
- <refsection id='main-conf'>
+ <refsect1 id='main-conf'>
<title>Configuration Directories and Precedence</title>
<para>The default configuration is set during compilation, so configuration is only needed when it is
- necessary to deviate from those defaults. The main configuration file is either in
- <filename>/usr/lib/systemd/</filename> or <filename>/etc/systemd/</filename> and contains commented out
- entries showing the defaults as a guide to the administrator. Local overrides can be created by creating
- drop-ins, as described below. The main configuration file can also be edited for this purpose (or a copy
- in <filename>/etc/</filename> if it's shipped in <filename>/usr/</filename>) however using drop-ins for
- local configuration is recommended over modifications to the main configuration file.</para>
-
- <para>In addition to the "main" configuration file, drop-in configuration snippets are read from
+ necessary to deviate from those defaults. The main configuration file is loaded from one of the
+ listed directories in order of priority, only the first file found is used:
+ <filename>/etc/systemd/</filename>,
+ <filename>/run/systemd/</filename>,
+ <filename>/usr/local/lib/systemd/</filename> <xi:include xpointer="usr-local-footnote" />,
+ <filename>/usr/lib/systemd/</filename>.
+ The vendor version of the file contains commented out entries showing the defaults as a guide to the
+ administrator. Local overrides can also be created by creating drop-ins, as described below. The main
+ configuration file can also be edited for this purpose (or a copy in <filename>/etc/</filename> if it's
+ shipped under <filename>/usr/</filename>), however using drop-ins for local configuration is recommended
+ over modifications to the main configuration file.</para>
+
+ <para>In addition to the main configuration file, drop-in configuration snippets are read from
<filename>/usr/lib/systemd/*.conf.d/</filename>, <filename>/usr/local/lib/systemd/*.conf.d/</filename>,
and <filename>/etc/systemd/*.conf.d/</filename>. Those drop-ins have higher precedence and override the
main configuration file. Files in the <filename>*.conf.d/</filename> configuration subdirectories are
@@ -63,12 +79,28 @@
who may use this logic to override the configuration files installed by vendor packages. Drop-ins have to
be used to override package drop-ins, since the main configuration file has lower 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. This also defined a concept of drop-in priority to allow
- distributions to ship drop-ins within a specific range lower than the range used by users. This should
- lower the risk of package drop-ins overriding accidentally drop-ins defined by users.</para>
+ simplify the ordering. This also defines a concept of drop-in priorities to allow OS vendors to ship
+ drop-ins within a specific range lower than the range used by users. This should lower the risk of
+ package drop-ins overriding accidentally drop-ins defined by users. It is recommended to use the range
+ 10-40 for drop-ins in <filename>/usr/</filename> and the range 60-90 for drop-ins in
+ <filename>/etc/</filename> and <filename>/run/</filename>, to make sure that local and transient drop-ins
+ take priority over drop-ins shipped by the OS vendor.</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>
+ </refsect1>
+
+ <refsect1>
+ <title>Extras</title>
+
+ <para><filename>/usr/local/lib/systemd</filename>
+ <footnote id='usr-local-footnote'>
+ <para>๐Ÿ’ฃ๐Ÿ’ฅ๐Ÿงจ๐Ÿ’ฅ๐Ÿ’ฅ๐Ÿ’ฃ Please note that those configuration files must be available at all times. If
+ <filename>/usr/local/</filename> is a separate partition, it may not be available during early boot,
+ and must not be used for configuration.</para>
+ </footnote>
+ </para>
+ </refsect1>
+
+</refentry>