[kmod,15/20] man: modprobe.d: document the config file order handling

Commit Message

Emil Velikov via B4 Relay June 11, 2024, 3:05 p.m. UTC

From: Emil Velikov <[e-mail]>

The modprobe.d configuration order/handling aligns with existing tools
such as sysctl.d, even though there is no mention in the manual.

Reorder the list in SYNOPSIS and add a bit of verbiage describing things.

Section is copied^Winspired by sysctl.d(5) ;-)

Signed-off-by: Emil Velikov <[e-mail]>
---
The documentation says ".conf", yet the code in libkmod-config.c also
permits for .alias files. I haven't dug through history - is that
intentional? Should we document why - in-code or manual page?
---
 man/modprobe.d.5.scd | 31 ++++++++++++++++++++++---------
 1 file changed, 22 insertions(+), 9 deletions(-)

Comments

Lucas De Marchi June 28, 2024, 10:55 p.m. UTC | #1

On Tue, Jun 11, 2024 at 04:05:15PM GMT, Emil Velikov via B4 Relay wrote:
>From: Emil Velikov <[e-mail]>
>
>The modprobe.d configuration order/handling aligns with existing tools
>such as sysctl.d, even though there is no mention in the manual.
>
>Reorder the list in SYNOPSIS and add a bit of verbiage describing things.
>
>Section is copied^Winspired by sysctl.d(5) ;-)
>
>Signed-off-by: Emil Velikov <[e-mail]>
>---
>The documentation says ".conf", yet the code in libkmod-config.c also
>permits for .alias files. I haven't dug through history - is that
>intentional? Should we document why - in-code or manual page?

to retain compatibility with the previous project used for loading
modules in Linux, module-init-tools:

                                 if (len < 6 ||
                                     (strcmp(&i->d_name[len-5], ".conf") != 0 &&
                                      strcmp(&i->d_name[len-6], ".alias") != 0))
                                         warn("All config files need .conf: %s/%s, "
                                              "it will be ignored in a future release.\n"
                                              filename, i->d_name);

And by "All config files need .conf" I imagine module-init-tools was
doing that to retain compatibility with distros using .alias or because
it was also using the same logic to parse modules.alias from the kernel.
Not sure.

The oldest commit I found referencing this in module-init-tools is:

	commit 50f21358cf9937906f42be1352ba2b588375a344
	Author: Kay Sievers <[e-mail]>
	Date:   Mon Mar 2 13:59:29 2009 +0100

Before that, module-init-tools wouldn't enforce any suffix, but filtered
out the known-bad ones.

I think we can leave that undocumented and maybe 15 years is more than
enough to finally do what the warning said :)

Lucas De Marchi

Patch

diff --git a/man/modprobe.d.5.scd b/man/modprobe.d.5.scd
index 2907175..2f78dd7 100644
--- a/man/modprobe.d.5.scd
+++ b/man/modprobe.d.5.scd
@@ -6,25 +6,24 @@  modprobe.d - Configuration directory for modprobe
 
 # SYNOPSIS
 
-/lib/modprobe.d/\*.conf
+@SYSCONFDIR@/modprobe.d/\*.conf
 
-@DISTCONFDIR@/modprobe.d/\*.conf
+/run/modprobe.d/\*.conf
 
 /usr/local/lib/modprobe.d/\*.conf
 
-/run/modprobe.d/\*.conf
+@DISTCONFDIR@/modprobe.d/\*.conf
 
-/etc/modprobe.d/\*.conf
+/lib/modprobe.d/\*.conf
 
 # DESCRIPTION
 
 Because the *modprobe* command can add or remove more than one module, due to
 modules having dependencies, we need a method of specifying what options are to
-be used with those modules. All files underneath the /etc/modprobe.d directory
-which end with the .conf extension specify those options as required. They can
-also be used to create convenient aliases: alternate names for a module, or they
-can override the normal *modprobe* behavior altogether for those with special
-requirements (such as inserting more than one module).
+be used with those modules. One can also use them to create convenient aliases:
+alternate names for a module, or they can override the normal *modprobe*
+behavior altogether for those with special requirements (such as inserting more
+than one module).
 
 Note that module and alias names (like other module names) can have - or \_ in
 them: both are interchangeable throughout all the module commands as underscore
@@ -35,6 +34,20 @@  lines and lines starting with '#' ignored (useful for adding comments). A '\\'
 at the end of a line causes it to continue on the next line, which makes the
 file a bit neater.
 
+# CONFIGURATION DIRECTORIES AND PRECEDENCE
+
+Configuration files are read from directories in @SYSCONFDIR@/, /run/,
+/usr/local/lib/, @DISTCONFDIR@/, and /lib/ in order of precedence, as listed in
+the SYNOPSIS section above. Files must have the ".conf" extension. Files in
+@SYSCONFDIR@/ override files with the same name in /run/, /usr/local/lib/,
+@DISTCONFDIR@/, and /lib/. Files in /run/ override files with the same name
+under /usr/, @DISTCONFDIR@/ and /lib/.
+
+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.
+
 # COMMANDS
 
 alias _wildcard_ _modulename_