modules.conf - configuration file for loading kernel modules
The behavior of modprobe(8) (and depmod(8) ) can be modified by the
(optional) configuration file /etc/modules.conf.
The configuration file consists of a set of lines.
All empty lines, and all text on a line after a '#', will be ignored.
Lines may be continued by ending the line with a '\'.
The remaining lines should all conform to one of the following formats:
[add] above module module_list
alias alias_name result
[add] below module module_list
define VARIABLE WORD
depfile=A_PATH
else
elseif EXPRESSION
endif
if EXPRESSION
include PATH_TO_CONFIG_FILE
insmod_opt=GENERIC_OPTIONS_TO_INSMOD
install module command ...
keep
[add] options module MODULE_SPECIFIC_OPTIONS
path=A_PATH
path[TAG]=A_PATH
generic_stringfile=A_PATH
pcimapfile=A_PATH
isapnpmapfile=A_PATH
usbmapfile=A_PATH
parportmapfile=A_PATH
ieee1394mapfile=A_PATH
pnpbiosmapfile=A_PATH
[add] probe name module_list
[add] probeall name module_list
prune filename
post-install module command ...
post-remove module command ...
pre-install module command ...
pre-remove module command ...
remove module command ...
persistdir directory_name
All arguments to a directive will be processed to handle shell metacharacters,
which means that "shell tricks" like wild-cards and
commands enclosed in back-quotes can be used:
path[misc]=/lib/modules/1.1.5?/local
path[net]=/lib/modules/`uname -r`/net
DANGER: Applying shell expansion to user supplied input is a major
security risk. Modutils code only does meta expansion via shell
commands for trusted data. Basically this means only for data in the
config file. Even that assumes that the user cannot run modprobe as
root while supplying their own config file. Programs (including the
kernel) that invoke modutils programs as root with user supplied input
must pass exactly one user supplied parameter and must set safe mode or
risk creating local root exploits. See modprobe for details on safe
mode.
Directives may be repeated multiple times. Note that some directives
can have an optional prefix: add. When this prefix is used, the new
module_list will be added to the previous module_list instead of
replacing it.
A_PATH is the fully qualified path to the target. It is possible to
use shell meta-characters in A_PATH including command output, such as
`uname -r` and `kernelversion`.
These two commands are also understood internally in these utilities as
meaning the version number of the current kernel and the current kernel
version respectively (e.g.: 2.2.3 and 2.2).
WORD is a sequence if non-white characters. If ' " or ` is found in
the string, all characters up to the matching ' " or ` will also be
included, even whitespace. Every WORD will then be expanded w.r.t.
meta-characters. If the expanded result gives more than one word then
only the first word of the result will be used.
EXPRESSION below can be:
WORD compare_op WORD
where compare_op is one of ==, !=, <, <=, >= or >. The string
values of the WORDs are compared.
-n WORD compare_op WORD
where compare_op is one of ==, !=, <, <=, >= or >. The numeric
values of the WORDs are compared.
WORD If the expansion of WORD fails, or if the expansion is "0"
(zero), "false" or "" (empty) then the expansion has the value
FALSE. Otherwise the expansion has the value TRUE
-f FILENAME
Test if the file FILENAME exists.
-k Test if "autoclean" is enabled (i.e. called from the kernel).
! EXPRESSION
A negated expression is also an expression.
This is a description of the legal directives.
define VARIABLE WORD
Do a putenv("VARIABLE=WORD"). Variables can be created and
modified by this directive. The variables will be available in
the environment, which makes them usable for all commands
executed in the current session.
depfile=A_PATH
This is the path to the dependency file that will be created by
depmod and used by modprobe to find the modules and their
dependent modules. Normally the default value should be used,
see below.
if EXPRESSION
If the expression is evaluated to be TRUE then all directives up
to the matching else, elseif or endif are processed. Otherwise
they are ignored. if directives may be nested up to an internal
maximum of 20.
Note: please avoid having any path directives conditionally
processed. Since modprobe has enough built-in "smarts", a
conditionally processed path directive will gain you nothing but
confusion. Really.
else If the previous matching if or elseif directive evaluated its
expression to be FALSE then the directives enclosed by the
(optional) else directive and its matching endif directive will
be processed.
elseif EXPRESSION
If the previous matching if or elseif directives evaluated their
expression to be FALSE and if the expression for this directive
evaluates to TRUE then the directives up to the next matching
elseif, else or endif directive will be processed.
endif This directive ends the chain of matching if, elseif or else
directive(s) controlling the conditional processing of
configuration file directives.
if EXPRESSION
any config lines
elseif EXPRESSION
any config lines
else
any config lines
endif
The else and elseif directives are optional.
include PATH_TO_CONFIG_FILE
To handle different platforms or configurations with a single
configuration file can be quite complex. With the use of the
include directive, conditionally processed by if directives,
this is now easier to handle.
insmod_opt=GENERIC_OPTIONS_TO_INSMOD
If insmod should need some special options, not specified
elsewhere, this directive makes it possible to add such an
option, to be used for every invocation. The standard default
options to insmod does normally not have to be modified unless
some special situation needs to be handled.
keep If this word is found on a line before any lines that contain
the path descriptions, the default set of paths will be saved,
and thus added to. Otherwise the normal behavior is that the
default set will be replaced by the set of paths in the
configuration file.
path=A_PATH
path[TAG]=A_PATH
The A_PATH argument specifies an additional directory to search
for modules. The path directive can carry an optional tag.
This tells us a little more about the purpose of the modules in
this directory and allows some automated operations by modprobe.
The tag is appended to the "path" keyword enclosed in square
brackets. If the tag is missing, the tag "misc" is assumed.
One very useful tag is boot, which can be used to mark all
directories containing modules that should be loaded at boottime.
Note that you must specify the keep directive to prevent any
path directives from over-riding the default paths.
generic_stringfile=A_PATH
This is the path to the generic_string file that will be created
by depmod and used by install scripts that need string
information from modules. Normally the default value should be
used, see below. pcimapfile=A_PATH This is the path to the
pcimap file that will be created by depmod and used by install
scripts to find the module that supports a pci device. Normally
the default value should be used, see below.
isapnpmapfile=A_PATH
This is the path to the isapnpmap file that will be created by
depmod and used by install scripts to find the module that
supports an ISA PNP device. Normally the default value should
be used, see below.
usbmapfile=A_PATH
This is the path to the usbmap file that will be created by
depmod and used by install scripts to find the module that
supports an USB device. Normally the default value should be
used, see below.
parportmapfile=A_PATH
This is the path to the parportmap file that will be created by
depmod and used by install scripts to find the module that
supports an parport device. Normally the default value should
be used, see below.
ieee1394mapfile=A_PATH
This is the path to the ieee1394map file that will be created by
depmod and used by install scripts to find the module that
supports an ieee1394 device. Normally the default value should
be used, see below.
pnpbiosmapfile=A_PATH
This is the path to the pnpbiosmap file that will be created by
depmod and used by install scripts to find the module that
supports an pnpbios device. Normally the default value should
be used, see below.
alias alias_name result
The "alias" directive can be used to give alias names to
modules. A line in /etc/modules.conf that looks like this:
alias iso9660 isofs
makes it possible to write modprobe iso9660 although there is no
object file for such a module available.
Note that the line:
alias some_module off
will make modprobe ignore requests to load that module. Another
special alias is:
alias some_module null
which will make requests for some_module always succeed, but no
module will actually be installed. This can be used as a base
for stacks created via the above and below directives.
It is possible to have a large number of levels of alias
directives, since all aliases will be recursively expanded in
order to find the physical module actually referred to. There
is an arbitrary limit of 1000 on alias depth to detect loops
like:
alias a b
alias b a
If the final result of an alias mapping does not match the name
of any module then modprobe applies probe and probeall mappings
to the result. If those do not succeed then the module is not
found. This makes constructs like this give sensible results
(from devfs).
alias /dev/sg* /dev/sg
probeall /dev/sg scsi-hosts sg
It is legal for an alias to map module A to module B and for
module A to exist at the same time but this construct is
ambiguous and is not recommended. For historical reasons, the
kernel sound system has a module called sound.o but the sound
developers also want an alias from sound to the module for the
user's sound card, e.g. "alias sound sb". In an attempt to
support this requirement but still maintain the defined behavior
where options can be applied to aliases, modprobe bypasses alias
expansion when processing a module name if the name was obtained
via modules.dep, otherwise aliases are expanded. This is not
guaranteed to give the expected behavior on all combinations of
aliases and real modules, you should avoid using an alias with
the same name as a real module.
[add] probe name module_list
[add] probeall name module_list
These directives can only be used when name is the name of the
module requested on the command line of modprobe. The effect is
that when a request for name is made, the modules in module_list
will be tried, in the specified order. The difference between
the directives is that probe will continue until the first
successful module insertion, while probeall will continue until
the end of the list. The exit status reflects whether any
module has been successfully installed or not. The optional add
prefix adds the new list to the previous list instead of
replacing it.
prune filename
The top level module directory for a kernel install contains
files which are not modules. These include modules.dep,
modules.generic_string, modules.pcimap, modules.isapnpmap,
modules.usbmap, modules.parportmap, modules.ieee1394map,
modules.pnpbiosmap, the build symlink to the kernel source tree
and any other files that the install process wants to save from
a kernel build. To prevent depmod issuing warnings about "not
an ELF file", these non-module files should appear in the prune
list. depmod has a built in prune list which cannot be removed
because it lists files which will exist for any kernel build.
If you add your own files to the top level modules directory,
add a prune statement for each filename. Note: The prune list
is only used when scanning the top directory of a path, and only
if the directory contains at least one subdirectory from the
standard list of subdirectory names, i.e. it appears to be a top
level directory built from a kernel install. The prune list has
no effect on subdirectories of a path.
[add] options [-k] module [MODULE_SPECIFIC_OPTIONS]
All module names, including aliased names, can have their own
options directives. Options specified for an alias have higher
priority than the options specified for more "basic" names. This
rule is used to resolve conflicting options directives. Options
given on the command line have the highest priority. If there
is -k before the module name, then the module won't be
autocleaned even if modprobe has been invoked with the -k
autoclean option. The optional add prefix adds the new list to
the previous list instead of replacing it. If the result of an
alias is not a real module then any options that were
constructed from the alias chain are discarded before invoking
probe[all]. If any of the MODULE_SPECIFIC_OPTIONS contain
characters that are special to the shell (e.g. space, comma,
parentheses) then the option must be enclosed in '"..."'. The
'' delimit the option in modules.conf, the "" delimit the option
when it is passed to the shell. For example,
abc='"def,ghi jkl (xyz)"'
[add] above module module_list
This directive makes it possible for one module to "pull in"
another set of modules on top of itself in a module stack, as
seen in the output of the lsmod(8) command. The above directive
is useful for those circumstances when the dependencies are more
complex than what can be described in the modules.dep dependency
file. This is an optimized case of the post-install and pre-
remove directives. Note that failure of installing the module
will not influence the exit status of modprobe. The optional
add prefix adds the new list to the previous list instead of
replacing it.
[add] below module module_list
This directive makes it possible for one module to "push"
another set of modules below itself in a module stack, as seen
in the output of the lsmod(8) command. The below directive is
useful for those circumstances when the dependencies are more
complex than what can be described in the modules.dep dependency
file. This is an optimized case of the pre-install and post-
remove directives. Note that failure of installing the module
will not influence the exit status of modprobe. The optional
add prefix adds the new list to the previous list instead of
replacing it.
The following directives are useful for (optionally) executing specific
commands when loading and unloading a module. Note that even aliased
module names can have these directives, which will be executed in the
proper order together with any directives for the unaliased module
name.
pre-install module command
Execute command before installing the specified module. See the
below directive as well.
install module command
Execute command instead of the default insmod when installing
the specified module.
post-install module command
Execute command after installing the specified module. See the
above directive as well.
pre-remove module command
Execute command before removing the specified module. See the
above directive as well.
remove module command
Execute command instead of the default (built-in) rmmod when
removing the specified module.
post-remove module command
Execute command after removing the specified module. See the
below directive as well.
persistdir=directory_name
When rmmod removes a module that contains persistent module
parameters, it stores the (possibly) modified parameters
underneath directory_name. When modprobe loads a module that
contains persistent module parameters, it looks under
directory_name for any previous values for those parameters.
You must set persistdir to the name of a directory that is
readable when modules are loaded and is writable when modules
are unloaded, the default value is /var/lib/modules/persist.
Many Linux distributions load their modules before mounting
filesystems, this can cause problems for persistent data. If
/var is a separate partition and it is mounted after modules are
loaded then insmod has nowhere to read persistent data from.
You have two choices when /var is on a separate partition.
1) Specify persistdir pointing at a directory in the root
partition, say /lib/modules/persist. This assumes that the
root partition is writable when rmmod runs.
2) Load any filesystem related modules first, mount the /var
partition then load the rest of the modules. This assumes that
the filesystem modules have no persistent data.
DEFAULT CONFIGURATION [Toc] [Back] If the configuration file '/etc/modules.conf' is missing, or if any
directive is not overridden, the following defaults are assumed:
depfile=/lib/modules/`uname -r`/modules.dep
generic_stringfile=/lib/modules/`uname -r`/modules.generic_string
pcimapfile=/lib/modules/`uname -r`/modules.pcimap
isapnpmapfile=/lib/modules/`uname -r`/modules.isapnpmap
usbmapfile=/lib/modules/`uname -r`/modules.usbmap
parportmapfile=/lib/modules/`uname -r`/modules.parportmap
ieee1394mapfile=/lib/modules/`uname -r`/modules.ieee1394map
pnpbiosmapfile=/lib/modules/`uname -r`/modules.pnpbiosmap
path[boot]=/lib/modules/boot
path[toplevel]=/lib/modules/`uname -r`
path[toplevel]=/lib/modules/`kernelversion`
path[toplevel]=/lib/modules/default
path[toplevel]=/lib/modules
persistdir=/var/lib/modules/persist
There are also a set of default alias and options directives. Since
this set is continuously extended, no list will be given here. The
(current) default set can be viewed by using the modprobe -c command
with an empty /etc/modules.conf file.
All options directives specify the options needed for a module, as in:
modprobe de620 bnc=1
These options will be overridden by any options given in the
/etc/modules.conf file, and on the modprobe command line.
Remember that it is possible to have an options directive for aliased
module names as well as for the non-aliased name. This is useful for
e.g. the dummy module:
alias dummy0 dummy
options dummy0 -o dummy0
ALTERNATIVE CONFIGURATION FILE [Toc] [Back] For historical reasons, if /etc/modules.conf does not exist, modutils
will read /etc/conf.modules instead. However the use of this
historical name is deprecated and it should be replaced with
/etc/modules.conf. This version of modutils issues a warning message
if /etc/conf.modules exists, later versions will give an error message
and refuse to load modules.
depmod(8), modprobe(8), insmod(8)
Bjorn Ekwall <[email protected]>
Keith Owens <[email protected]>
4th Berkeley Distribution 07 December 1999 MODULES.CONF(5)
[ Back ] |
