From d3fae78fe86f1dfcdb07fd613ccbb3adf547a617 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Sat, 29 Nov 2014 01:05:43 -0800 Subject: [PATCH] man: Factor out a common snippet for .d directories and precedence 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 906a96895..c24606a9c 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 227016616..55a3df0b7 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 . --> - + binfmt.d @@ -74,33 +75,10 @@ Empty lines and lines beginning with ; and # are ignored. Note that this means you may not use ; and # as delimiter in binary format rules. - - Each configuration file shall be named in the - style of program.conf. - Files in /etc/ override files - with the same name in /usr/lib/ - and /run/. Files in - /run/ override files with the - same name in /usr/lib/. Packages - should install their configuration files in - /usr/lib/, files in - /etc/ 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. - - If the administrator wants to disable a - configuration file supplied by the vendor, the - recommended way is to place a symlink to - /dev/null in - /etc/binfmt.d/ bearing the - same filename. + + Example diff --git a/man/logind.conf.xml b/man/logind.conf.xml index ca7525f31..e927cf445 100644 --- a/man/logind.conf.xml +++ b/man/logind.conf.xml @@ -22,7 +22,8 @@ along with systemd; If not, see . --> - + logind.conf systemd @@ -59,29 +60,11 @@ Description These files configure various parameters of the systemd login manager, systemd-logind.service8. - - Each configuration file shall be named in the style of - filename.conf. - Files in /etc/ override files with the - same name in /usr/lib/ and - /run/. Files in - /run/ override files with the same name in - /usr/lib/. Packages should install their - configuration files in /usr/lib/. Files in - /etc/ 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 logind.conf.d - file override entries in - /etc/systemd/logind.conf. It is - recommended to prefix all filenames with a two-digit number and - a dash, to simplify the ordering of the files. + + + Options diff --git a/man/modules-load.d.xml b/man/modules-load.d.xml index 33c466f92..4b578d714 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 . --> - + modules-load.d @@ -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. - - Each configuration file shall be named in the - style of program.conf. - Files in /etc/ override files - with the same name in /usr/lib/ - and /run/. Files in - /run/ override files with the - same name in /usr/lib/. Packages - should install their configuration files in - /usr/lib/, files in - /etc/ are reserved for the local - administrator, who may use this logic to override the - configuration files installed from vendor - packages. - - If the administrator wants to disable a - configuration file supplied by the vendor, the - recommended way is to place a symlink to - /dev/null in - /etc/modules-load.d/ bearing the - same filename. + + Example diff --git a/man/standard-conf.xml b/man/standard-conf.xml new file mode 100644 index 000000000..b87d7e955 --- /dev/null +++ b/man/standard-conf.xml @@ -0,0 +1,45 @@ + + + + + + Configuration Directories and Precedence + + Configuration files are read from directories in + /etc/, /run/, and + /usr/lib/, in order of precedence. + Each configuration file in these configuration directories shall be named in + the style of filename.conf. + Files in /etc/ override files with the same name in + /run/ and /usr/lib/. Files in + /run/ override files with the same name in + /usr/lib/. + + Packages should install their configuration files in + /usr/lib/. Files in /etc/ 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. + + If the administrator wants to disable a configuration file supplied by + the vendor, the recommended way is to place a symlink to + /dev/null in the configuration directory in + /etc/, with the same filename as the vendor + configuration file. + + + + Configuration File + + Configuration is also read from a single configuration file in + /etc/. 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. + + diff --git a/man/sysctl.d.xml b/man/sysctl.d.xml index 922b5c4ea..c67a199fb 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 . --> - + sysctl.d @@ -70,27 +71,6 @@ is # or ; are ignored. - Each configuration file shall be named in the - style of program.conf. - Files in /etc/ override files - with the same name in /usr/lib/ - and /run/. Files in - /run/ override files with the same - name in /usr/lib/. Packages - should install their configuration files in - /usr/lib/. Files in - /etc/ 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. - Note that either / or . may be used as separators within sysctl variable names. If the first separator is a @@ -109,13 +89,6 @@ /proc/sys/net/ipv4/conf/enp3s0.200/forwarding. - If the administrator wants to disable a - configuration file supplied by the vendor, the - recommended way is to place a symlink to - /dev/null in - /etc/sysctl.d/ bearing the - same filename. - The settings configured with sysctl.d files will be applied early on boot. The network interface-specific options @@ -142,6 +115,8 @@ example below). + + Examples diff --git a/man/sysusers.d.xml b/man/sysusers.d.xml index 18c71db63..ac2db9885 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 . --> - + sysusers.d @@ -239,8 +240,10 @@ u root 0 "Superuser" /root + + - Overriding vendor configuration + Idempotence Note that systemd-sysusers will do nothing if the specified users or groups @@ -248,31 +251,13 @@ u root 0 "Superuser" /root sysusers.d vendor configuration, except to block certain users or groups from being created. - - Files in /etc/sysusers.d - override files with the same name in - /usr/lib/sysusers.d and - /run/sysusers.d. Files in - /run/sysusers.d override files - with the same name in - /usr/lib/sysusers.d. The scheme is the same as for - tmpfiles.d5, - except for the directory name. - - If the administrator wants to disable a - configuration file supplied by the vendor, the - recommended way is to place a symlink to - /dev/null in - /etc/sysusers.d/ bearing the - same filename. See Also systemd1, - systemd-sysusers8, - tmpfiles.d5 + systemd-sysusers8 -- 2.30.2