d3fae78fe86f1dfcdb07fd613ccbb3adf547a617Josh Triplett<?xml version="1.0"?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
d3fae78fe86f1dfcdb07fd613ccbb3adf547a617Josh Triplett<!DOCTYPE refsection PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
d3fae78fe86f1dfcdb07fd613ccbb3adf547a617Josh Triplett <title>Configuration Directories and Precedence</title>
d3fae78fe86f1dfcdb07fd613ccbb3adf547a617Josh Triplett <para>Configuration files are read from directories in
d3fae78fe86f1dfcdb07fd613ccbb3adf547a617Josh Triplett <filename>/etc/</filename>, <filename>/run/</filename>, and
d3fae78fe86f1dfcdb07fd613ccbb3adf547a617Josh Triplett <filename>/usr/lib/</filename>, in order of precedence.
d3fae78fe86f1dfcdb07fd613ccbb3adf547a617Josh Triplett Each configuration file in these configuration directories shall be named in
d3fae78fe86f1dfcdb07fd613ccbb3adf547a617Josh Triplett the style of <filename><replaceable>filename</replaceable>.conf</filename>.
d3fae78fe86f1dfcdb07fd613ccbb3adf547a617Josh Triplett Files in <filename>/etc/</filename> override files with the same name in
d3fae78fe86f1dfcdb07fd613ccbb3adf547a617Josh Triplett <filename>/run/</filename> and <filename>/usr/lib/</filename>. Files in
d3fae78fe86f1dfcdb07fd613ccbb3adf547a617Josh Triplett <filename>/run/</filename> override files with the same name in
d3fae78fe86f1dfcdb07fd613ccbb3adf547a617Josh Triplett <para>Packages should install their configuration files in
d3fae78fe86f1dfcdb07fd613ccbb3adf547a617Josh Triplett <filename>/usr/lib/</filename>. Files in <filename>/etc/</filename> are
d3fae78fe86f1dfcdb07fd613ccbb3adf547a617Josh Triplett reserved for the local administrator, who may use this logic to override the
d3fae78fe86f1dfcdb07fd613ccbb3adf547a617Josh Triplett configuration files installed by vendor packages. All configuration files
d3fae78fe86f1dfcdb07fd613ccbb3adf547a617Josh Triplett are sorted by their filename in lexicographic order, regardless of which of
d3fae78fe86f1dfcdb07fd613ccbb3adf547a617Josh Triplett the directories they reside in. If multiple files specify the same option,
d3fae78fe86f1dfcdb07fd613ccbb3adf547a617Josh Triplett the entry in the file with the lexicographically latest name will take
d3fae78fe86f1dfcdb07fd613ccbb3adf547a617Josh Triplett precedence. It is recommended to prefix all filenames with a two-digit number
d3fae78fe86f1dfcdb07fd613ccbb3adf547a617Josh Triplett and a dash, to simplify the ordering of the files.</para>
d3fae78fe86f1dfcdb07fd613ccbb3adf547a617Josh Triplett <para>If the administrator wants to disable a configuration file supplied by
d3fae78fe86f1dfcdb07fd613ccbb3adf547a617Josh Triplett the vendor, the recommended way is to place a symlink to
d3fae78fe86f1dfcdb07fd613ccbb3adf547a617Josh Triplett <filename>/dev/null</filename> in the configuration directory in
d3fae78fe86f1dfcdb07fd613ccbb3adf547a617Josh Triplett <filename>/etc/</filename>, with the same filename as the vendor
2ef555d69a6a6c19897344dd11d7cd3a7c46af64Jan Synacek configuration file. If the vendor configuration file is included in
2ef555d69a6a6c19897344dd11d7cd3a7c46af64Jan Synacek the initrd image, the image has to be regenerated.</para>
d3fae78fe86f1dfcdb07fd613ccbb3adf547a617Josh Triplett </refsection>
e93549ef29c4123d9ee45acb5815048390201e49Zbigniew Jędrzejewski-Szmek <title>Configuration Directories and Precedence</title>
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt <para>The default configuration is defined during compilation, so a
e93549ef29c4123d9ee45acb5815048390201e49Zbigniew Jędrzejewski-Szmek configuration file is only needed when it is necessary to deviate
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt from those defaults. By default, the configuration file in
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen <filename>/etc/systemd/</filename> contains commented out entries
e93549ef29c4123d9ee45acb5815048390201e49Zbigniew Jędrzejewski-Szmek showing the defaults as a guide to the administrator. This file
e93549ef29c4123d9ee45acb5815048390201e49Zbigniew Jędrzejewski-Szmek can be edited to create local overrides.
e93549ef29c4123d9ee45acb5815048390201e49Zbigniew Jędrzejewski-Szmek <para>When packages need to customize the configuration, they can
e93549ef29c4123d9ee45acb5815048390201e49Zbigniew Jędrzejewski-Szmek install configuration snippets in
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen <filename>/usr/lib/systemd/*.conf.d/</filename>. Files in
e93549ef29c4123d9ee45acb5815048390201e49Zbigniew Jędrzejewski-Szmek <filename>/etc/</filename> are reserved for the local
e93549ef29c4123d9ee45acb5815048390201e49Zbigniew Jędrzejewski-Szmek administrator, who may use this logic to override the
e93549ef29c4123d9ee45acb5815048390201e49Zbigniew Jędrzejewski-Szmek configuration files installed by vendor packages. The main
e93549ef29c4123d9ee45acb5815048390201e49Zbigniew Jędrzejewski-Szmek configuration file is read before any of the configuration
e93549ef29c4123d9ee45acb5815048390201e49Zbigniew Jędrzejewski-Szmek directories, and has the lowest precedence; entries in a file in
e93549ef29c4123d9ee45acb5815048390201e49Zbigniew Jędrzejewski-Szmek any configuration directory override entries in the single
e93549ef29c4123d9ee45acb5815048390201e49Zbigniew Jędrzejewski-Szmek configuration file. Files in the
1d940aa32913c108e0282ebd359b2eb999ffeadfAlison Chaiken <filename>*.conf.d/</filename> configuration subdirectories
e93549ef29c4123d9ee45acb5815048390201e49Zbigniew Jędrzejewski-Szmek are sorted by their filename in lexicographic order, regardless of
e93549ef29c4123d9ee45acb5815048390201e49Zbigniew Jędrzejewski-Szmek which of the subdirectories they reside in. If multiple files
e93549ef29c4123d9ee45acb5815048390201e49Zbigniew Jędrzejewski-Szmek specify the same option, the entry in the file with the
e93549ef29c4123d9ee45acb5815048390201e49Zbigniew Jędrzejewski-Szmek lexicographically latest name takes precedence. It is recommended
e93549ef29c4123d9ee45acb5815048390201e49Zbigniew Jędrzejewski-Szmek to prefix all filenames in those subdirectories with a two-digit
e93549ef29c4123d9ee45acb5815048390201e49Zbigniew Jędrzejewski-Szmek number and a dash, to simplify the ordering of the files.</para>
e93549ef29c4123d9ee45acb5815048390201e49Zbigniew Jędrzejewski-Szmek <para>To disable a configuration file supplied by the vendor, the
e93549ef29c4123d9ee45acb5815048390201e49Zbigniew Jędrzejewski-Szmek recommended way is to place a symlink to
e93549ef29c4123d9ee45acb5815048390201e49Zbigniew Jędrzejewski-Szmek <filename>/dev/null</filename> in the configuration directory in
e93549ef29c4123d9ee45acb5815048390201e49Zbigniew Jędrzejewski-Szmek <filename>/etc/</filename>, with the same filename as the vendor
e93549ef29c4123d9ee45acb5815048390201e49Zbigniew Jędrzejewski-Szmek configuration file.</para>
d3fae78fe86f1dfcdb07fd613ccbb3adf547a617Josh Triplett </refsection>