Provided by: modutils_2.4.27.0-3ubuntu1_i386 bug

NAME

       modules.conf - configuration file for loading kernel modules

DESCRIPTION

       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 meta-
       characters,  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.

       All commands (in post-install,  post-remove,  pre-install,  pre-remove,
       and  remove)  are executed using the system() call. Commands need to be
       posixly correct, as they will be processed by /bin/sh.

       Notice  that  in  systems  running  Debian  GNU/Linux,  this  file   is
       automatically  generated  by  the  script  update-modules  based on the
       contents in /etc/modutils/. If you want to manage this file by yourself
       make  sure  you  remove  the  first  header line which indicates to the
       script that it can regenerate it. If you don’t, your local changes will
       be  lost  on package upgrade. Instead of modifying this file you should
       modify the content of files under the /etc/modutils/ directory.

SEMANTICS

       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.

SYNTAX

       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 boot-
              time.
              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

       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

       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.

SEE ALSO

       depmod(8), modprobe(8), insmod(8), update-modules(8)

AUTHOR

       Bjorn Ekwall <bj0rn@blox.se>
       Keith Owens <kaos@ocs.com.au>