modules.conf  - configuration file for loading kernel mod­
       ules


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[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.


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


       ! 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

                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

              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


                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

              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)"'

              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.

              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/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)


AUTHOR

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


Man(1) output converted with man2html