MAN page from PLD modutils-2.4.6-2.i386.rpm

MODULES.CONF

Section: File Formats (5)
Updated: 07 December 1999
Index

NAME

modules.conf - configuration file for loading kernel modules

DESCRIPTION

The behavior ofmodprobe(8)(anddepmod(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  [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 handleshell meta-characters,which means that "shell tricks" like wild-cardsand 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 securityrisk. Modutils code only does meta expansion via shell commands fortrusted data. Basically this means only for data in the config file.Even that assumes that the user cannot run modprobe as root whilesupplying their own config file. Programs (including the kernel) thatinvoke modutils programs as root with user supplied input must passexactly one user supplied parameter and must set safe mode or riskcreating local root exploits. Seemodprobefor 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 beaddedto the previous module_list instead of replacing it.

SEMANTICS

A_PATHis the fully qualified path to the target.It is possible to use shell meta-characters inA_PATHincluding command output, such as`uname -r`and`kernelversion`.
These two commands are also understood internally in these utilitiesas meaning the version number of the current kernel and the currentkernel version respectively (e.g.: 2.2.3 and 2.2).

WORDis a sequence if non-white characters.If ' " or ` is found in the string, all characters up to thematching ' " or ` will also be included, even whitespace.EveryWORDwill then be expanded w.r.t. meta-characters.If the expanded result gives more than one word then onlythe 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 theexpansion 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.

SYNTAX

This is a description of the legal directives.

define VARIABLE WORD

Do aputenv(VARIABLE=WORD).Variables can be created and modified by this directive.The variables will be available in the environment, which makes themusable for all commands executed in the current session.

depfile=A_PATH

This is the path to the dependency file that will be created bydepmodand used bymodprobeto find the modules and their dependent modules.Normally the default value should be used, see below.

if EXPRESSION

If the expression is evaluated to beTRUEthen all directives up to the matchingelse, elseiforendifare processed. Otherwise they are ignored.ifdirectives may be nested up to an internal maximum of 20.
Note: please avoid having anypathdirectives conditionally processed.Sincemodprobehas enough built-in "smarts", a conditionally processedpathdirective will gain you nothing but confusion. Really.

else

If the previous matchingiforelseifdirective evaluated its expression to beFALSEthen the directives enclosed by the (optional)elsedirective and its matchingendifdirective will be processed.

elseif EXPRESSION

If the previous matchingiforelseifdirectives evaluated their expression to beFALSEand if the expression for this directive evaluates toTRUEthen the directives up to the next matchingelseif, elseorendifdirective will be processed.

endif

This directive ends the chain of matchingif, elseiforelsedirective(s) controlling the conditional processing of configurationfile directives.

  if EXPRESSION      any config lines  elseif EXPRESSION      any config lines  else      any config lines  endif

Theelseandelseifdirectives are optional.

include PATH_TO_CONFIG_FILE

To handle different platforms or configurations with asingle configuration file can be quite complex.With the use of theincludedirective, conditionally processed byifdirectives, 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 tobe modified unless some special situation needs to be handled.

keep

If this word is found on a linebeforeany lines that contain thepathdescriptions, the default set of paths will be saved, and thus added to.Otherwise the normal behavior is that the default set will bereplacedby the set of paths in the configuration file.

path=A_PATH

path[TAG]=A_PATH

TheA_PATHargument specifies an additional directory to search for modules.Thepathdirective can carry an optional tag.This tells us a little more about the purpose of the modules inthis directory and allows some automated operations bymodprobe.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 isboot,which can be used to mark all directories containing modulesthat should be loaded at boot-time.
Note that you must specify thekeepdirective to prevent anypathdirectives from over-riding the default paths.

generic_stringfile=A_PATH

This is the path to the generic_string file that will be created bydepmodand used by install scripts that need string information from modules.Normally the default value should be used, see below.pcimapfile=A_PATHThis is the path to the pcimap file that will be created bydepmodand 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 bydepmodand 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 bydepmodand 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 bydepmodand used by install scripts to find the module that supports an parport 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 writemodprobe iso9660although 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 nomodule will actually be installed.This can be used as a base for stacks created via theaboveandbelowdirectives.

It is possible to have a large number of levels ofaliasdirectives, since all aliases will be recursively expandedin order to find the physical module actually referred to. There is anarbitrary limit of 1000 on alias depth to detect loops like:

  alias a b  alias b a

If the final result of analiasmapping does not match the name of any module then modprobe appliesprobe and probeall mappings to the result. If those do not succeedthen the module is not found. This makes constructs like this givesensible 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 moduleA to exist at the same time but this construct is ambiguous and isnotrecommended. For historical reasons, the kernel sound system has amodule called sound.o but the sound developers also want an alias fromsound to the module for the user's sound card, e.g. "alias sound sb".In an attempt to support this requirement but still maintain thedefined behavior where options can be applied to aliases, modprobebypasses alias expansion when processing a module name if the name wasobtained via modules.dep, otherwise aliases are expanded. This is notguaranteed to give the expected behavior on all combinations ofaliases and real modules, you should avoid using an alias with the samename as a real module.

[add] probe name module_list

[add] probeall name module_list

These directives can only be used whennameis the name of the module requested on the command line ofmodprobe.The effect is that when a request fornameis made, the modules in module_list will be tried, in the specified order.The difference between the directives is thatprobewill continue until the first successful module insertion, whileprobeallwill continue until the end of the list.The exit status reflects whether any module has been successfullyinstalled or not.The optionaladdprefix adds the new list to the previous list instead of replacing it.

prune filename

The top level module directory for a kernel install contains fileswhich are not modules. These include modules.dep,modules.generic_string, modules.pcimap, modules.isapnpmap,modules.usbmap, modules.parportmap, the build symlink to the kernelsource tree and any other files that the install process wants to savefrom a kernel build. To preventdepmodissuing warnings about "not an ELF file", these non-module files shouldappear in the prune list.depmodhas a built in prune list which cannot be removed because it listsfiles which will exist for any kernel build. If you add your own filesto the top level modules directory, add aprunestatement for eachfilename.Note:The prune list is only used when scanning the top directory of apath,and only if the directory contains at least one subdirectory from thestandard list of subdirectory names, i.e. it appears to be a top leveldirectory built from a kernel install. Theprunelist has no effect on subdirectories of apath.

[add] options [-k] module [MODULE_SPECIFIC_OPTIONS]

All module names, including aliased names, can have their ownoptionsdirectives.Options specified for an alias have higher priority than the optionsspecified for more "basic" names. This rule is used to resolveconflictingoptionsdirectives.Options given on the command line have the highest priority.If there is-kbefore the module name, then the module won't be autocleaned even ifmodprobehas been invoked with the-kautoclean option.The optionaladdprefix adds the new list to the previous list instead of replacing it.If the result of analiasis not a real module then anyoptionsthat were constructed from thealiaschain are discarded before invoking probe[all].If any of theMODULE_SPECIFIC_OPTIONScontain 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 optionwhen 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 thelsmod(8)command.Theabovedirective is useful for those circumstances when the dependenciesare more complex than what can be described in themodules.depdependency file.This is an optimized case of thepost-installandpre-removedirectives.Note that failure of installing the module will not influence theexit status ofmodprobe.The optionaladdprefix 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 thelsmod(8)command.Thebelowdirective is useful for those circumstances when the dependenciesare more complex than what can be described in themodules.depdependency file.This is an optimized case of thepre-installandpost-removedirectives.Note that failure of installing the module will not influence theexit status ofmodprobe.The optionaladdprefix adds the new list to the previous list instead of replacing it.

The following directives are useful for (optionally) executing specificcommands when loading and unloading a module. Note that even aliasedmodule names can have these directives,which will be executed in the proper order together with anydirectives for the unaliased module name.

pre-install module command: Executecommandbefore installing the specified module.See thebelowdirective as well.
install module command: Executecommandinstead of the defaultinsmodwhen installing the specified module.
post-install module command: Executecommandafter installing the specified module.See theabovedirective as well.
pre-remove module command: Executecommandbefore removing the specified module.See theabovedirective as well.
remove module command: Executecommandinstead of the default (built-in)rmmodwhen removing the specified module.
post-remove module command: Executecommandafter removing the specified module.See thebelowdirective as well.
persistdir=directory_name: Whenrmmodremoves a module that contains persistent module parameters, it storesthe (possibly) modified parameters underneathdirectory_name.Whenmodprobeloads a module that contains persistent module parameters, it looksunderdirectory_namefor any previous values for those parameters.You must setpersistdirto the name of a directory that is readable when modules are loaded andis writable when modules are unloaded, the default value is/var/lib/modules/persist.Many Linux distributions load their modules before mountingfilesystems, this can cause problems for persistent data.If /var is a separate partition and it is mounted after modules areloaded theninsmodhas nowhere to read persistent data from.You have two choices when /var is on a separate partition.
: 1) Specifypersistdirpointing at a directory in the root partition, say/lib/modules/persist. This assumes that the root partition is writablewhenrmmodruns.
: 2) Load any filesystem related modules first, mount the /var partitionthen load the rest of the modules. This assumes that the filesystemmodules have no persistent data.

DEFAULT CONFIGURATION

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

  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 defaultaliasandoptionsdirectives.Since this set is continuously extended, no list will be given here.The (current) default set can be viewed by using themodprobe -ccommand with an empty/etc/modules.conffile.

Alloptionsdirectives specify the options needed fora module, as in:

  modprobe de620 bnc=1

These options will be overridden by any options givenin the/etc/modules.conffile, and on themodprobecommand line.

Remember that it is possible to have anoptionsdirective for aliased module names as wellas for the non-aliased name.This is useful for e.g. the dummy module:

  alias dummy0 dummy  options dummy0 -o dummy0

ALTERNATIVE CONFIGURATION FILE

For historical reasons, if /etc/modules.conf does not exist, modutilswill read /etc/conf.modules instead.However the use of this historical name is deprecated and it should bereplaced with /etc/modules.conf.This version of modutils issues a warning message if /etc/conf.modulesexists, later versions will give an error message and refuse to loadmodules.

AUTHOR

Bjorn Ekwall <bj0rnAATTblox.se>Keith Owens <kaosAATTocs.com.au>

This document was created byman2html,using the manual pages.