diff options
Diffstat (limited to 'man/standard-conf.xml')
| -rw-r--r-- | man/standard-conf.xml | 76 |
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> |