mirror of
https://github.com/systemd/systemd.git
synced 2025-01-03 05:18:09 +03:00
man: document that separate /usr/local/ must not be used for config
Since we document /usr/local/lib/systemd/ and other paths for various things,
add notes that this is not supported if /usr/local is a separate partition. In
systemd.unit, I tried to add the footnote in the table where
/usr/local/lib/systemd/ is listed, but that get's rendered as '[sup]a[/sup]'
with a mangled footnote at the bottom of the table :( .
Also, split paragraphs in one place where the subject changes without any
transition.
Follow-up for 02f35b1c90.
Replaces https://github.com/systemd/systemd/pull/33231.
This commit is contained in:
Zbigniew Jędrzejewski-Szmek
Luca Boccassi
parent
835fbe5f75
commit
7b529bfc47
@ -7,7 +7,7 @@
|
||||
Copyright © 2014 Josh Triplett
|
||||
-->
|
||||
|
||||
<refentry>
|
||||
<refentry xmlns:xi="http://www.w3.org/2001/XInclude">
|
||||
<refnamediv>
|
||||
<refname/>
|
||||
<refpurpose/>
|
||||
@ -32,13 +32,16 @@
|
||||
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. 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>
|
||||
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
|
||||
@ -54,7 +57,7 @@
|
||||
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>,
|
||||
<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
|
||||
@ -76,10 +79,10 @@
|
||||
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 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
|
||||
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>
|
||||
|
||||
@ -87,4 +90,17 @@
|
||||
to <filename>/dev/null</filename> in the configuration directory in <filename>/etc/</filename>, with the
|
||||
same filename as the vendor configuration file.</para>
|
||||
</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>
|
||||
|
||||
@ -61,11 +61,12 @@
|
||||
above. System and user environment generators are loaded from directories with names ending in
|
||||
<filename>system-environment-generators/</filename> and
|
||||
<filename>user-environment-generators/</filename>, respectively. Generators found in directories
|
||||
listed earlier override the ones with the same name in directories lower in the list. A symlink
|
||||
to <filename>/dev/null</filename> or an empty file can be used to mask a generator, thereby
|
||||
preventing it from running. Please note that the order of the two directories with the highest
|
||||
priority is reversed with respect to the unit load path, and generators in
|
||||
<filename>/run/</filename> overwrite those in <filename>/etc/</filename>.</para>
|
||||
listed earlier override the ones with the same name in directories lower in the list
|
||||
<xi:include href="standard-conf.xml" xpointer="usr-local-footnote" />.
|
||||
A symlink to <filename>/dev/null</filename> or an empty file can be used to mask a generator,
|
||||
thereby preventing it from running. Please note that the order of the two directories with the highest
|
||||
priority is reversed with respect to the unit load path, and generators in <filename>/run/</filename>
|
||||
overwrite those in <filename>/etc/</filename>.</para>
|
||||
|
||||
<para>After installing new generators or updating the configuration, <command>systemctl
|
||||
daemon-reload</command> may be executed. This will re-run all generators, updating environment
|
||||
|
||||
@ -77,10 +77,11 @@
|
||||
and user generators are loaded from directories with names ending in
|
||||
<filename>system-generators/</filename> and <filename>user-generators/</filename>,
|
||||
respectively. Generators found in directories listed earlier override the ones with the same name in
|
||||
directories lower in the list. A symlink to <filename>/dev/null</filename> or an empty file can be used
|
||||
to mask a generator, thereby preventing it from running. Please note that the order of the two
|
||||
directories with the highest priority is reversed with respect to the unit load path, and generators in
|
||||
<filename>/run/</filename> overwrite those in <filename>/etc/</filename>.</para>
|
||||
directories lower in the list <xi:include href="standard-conf.xml" xpointer="usr-local-footnote" />.
|
||||
A symlink to <filename>/dev/null</filename> or an empty file can be used to mask a generator, thereby
|
||||
preventing it from running. Please note that the order of the two directories with the highest priority
|
||||
is reversed with respect to the unit load path, and generators in <filename>/run/</filename> overwrite
|
||||
those in <filename>/etc/</filename>.</para>
|
||||
|
||||
<para>After installing new generators or updating the configuration, <command>systemctl
|
||||
daemon-reload</command> may be executed. This will delete the previous configuration created by
|
||||
|
||||
@ -35,7 +35,9 @@
|
||||
|
||||
<para>The <filename>.link</filename> files are read from the files located in the system network
|
||||
directory <filename>/usr/lib/systemd/network</filename> and
|
||||
<filename>/usr/local/lib/systemd/network</filename>, the volatile runtime network directory
|
||||
<filename>/usr/local/lib/systemd/network</filename>
|
||||
<xi:include href="standard-conf.xml" xpointer="usr-local-footnote" />,
|
||||
the volatile runtime network directory
|
||||
<filename>/run/systemd/network</filename>, and the local administration network directory
|
||||
<filename>/etc/systemd/network</filename>. All configuration files are collectively sorted and
|
||||
processed in alphanumeric order, regardless of the directories in which they live. However, files
|
||||
|
||||
@ -39,13 +39,14 @@
|
||||
|
||||
<para>The <filename>.network</filename> files are read from the files located in the system network
|
||||
directories <filename>/usr/lib/systemd/network</filename> and
|
||||
<filename>/usr/local/lib/systemd/network</filename>, the volatile runtime network directory
|
||||
<filename>/run/systemd/network</filename> and the local administration network directory
|
||||
<filename>/etc/systemd/network</filename>. All configuration files are collectively sorted and
|
||||
processed in alphanumeric order, regardless of the directories in which they live. However, files
|
||||
with identical filenames replace each other. It is recommended that each filename is prefixed with
|
||||
a number smaller than <literal>70</literal> (e.g. <filename>10-eth0.network</filename>). Otherwise, the
|
||||
default <filename>.network</filename> files or those generated by
|
||||
<filename>/usr/local/lib/systemd/network</filename>
|
||||
<xi:include href="standard-conf.xml" xpointer="usr-local-footnote" />,
|
||||
the volatile runtime network directory <filename>/run/systemd/network</filename> and the local
|
||||
administration network directory <filename>/etc/systemd/network</filename>. All configuration files are
|
||||
collectively sorted and processed in alphanumeric order, regardless of the directories in which they
|
||||
live. However, files with identical filenames replace each other. It is recommended that each filename is
|
||||
prefixed with a number smaller than <literal>70</literal> (e.g. <filename>10-eth0.network</filename>).
|
||||
Otherwise, the default <filename>.network</filename> files or those generated by
|
||||
<citerefentry><refentrytitle>systemd-network-generator.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
||||
may take precedence over user configured files. Files in <filename>/etc/</filename> have the highest
|
||||
priority, files in <filename>/run/</filename> take precedence over files with the same name under
|
||||
|
||||
@ -353,7 +353,9 @@
|
||||
<para>Unit files are loaded from a set of paths determined during
|
||||
compilation, described in the two tables below. Unit files found
|
||||
in directories listed earlier override files with the same name in
|
||||
directories lower in the list.</para>
|
||||
directories lower in the list
|
||||
<xi:include href="standard-conf.xml" xpointer="usr-local-footnote" />.
|
||||
</para>
|
||||
|
||||
<para>When the variable <varname>$SYSTEMD_UNIT_PATH</varname> is set,
|
||||
the contents of this variable overrides the unit load path. If
|
||||
@ -407,7 +409,7 @@
|
||||
</row>
|
||||
<row>
|
||||
<entry><filename>/usr/local/lib/systemd/system</filename></entry>
|
||||
<entry>System units installed by the administrator </entry>
|
||||
<entry>System units installed by the administrator</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><filename>/usr/lib/systemd/system</filename></entry>
|
||||
@ -2687,5 +2689,4 @@ OnFailure=failure-handler@%N.service
|
||||
<member><citerefentry project='man-pages'><refentrytitle>uname</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
|
||||
</simplelist></para>
|
||||
</refsect1>
|
||||
|
||||
</refentry>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user