unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-3.1)
Page:
Section:
Apropos / Subsearch:
optional field

INSMOD(8)                    Linux Module Support                    INSMOD(8)



NAME
       insmod - install loadable kernel module

SYNOPSIS
       insmod    [-fhkLmnpqrsSvVxXyYN]    [-e persist_name]   [-o module_name]
       [-O blob_name] [-P prefix] module [ symbol=value ... ]

DESCRIPTION
       insmod installs a loadable module in the running kernel.

       insmod tries to link a module into the running kernel by resolving  all
       symbols from the kernel's exported symbol table.

       If  the  module  file  name  is given without directories or extension,
       insmod will search for the module in some common  default  directories.
       The  environment variable MODPATH can be used to override this default.
       If a module configuration file such  as  /etc/modules.conf  exists,  it
       will override the paths defined in MODPATH.

       The  environment  variable  MODULECONF  can  also  be  used to select a
       different configuration file from  the  default  /etc/modules.conf  (or
       /etc/conf.modules   (deprecated)).    This  environment  variable  will
       override all the definitions above.

       When environment variable UNAME_MACHINE is set, modutils will  use  its
       value  instead  of the machine field from the uname() syscall.  This is
       mainly of use when you are compiling 64 bit  modules  in  32  bit  user
       space  or  vice  versa,  set  UNAME_MACHINE to the type of the modules.
       Current modutils does not support full cross build mode for modules, it
       is  limited  to  choosing  between  32  and 64 bit versions of the host
       architecture.

   OPTIONS
       -e persist_name, --persist=persist_name
              Specifies where any persistent data for the module is read  from
              on load and written to when this instantiantion of the module is
              unloaded.  This option is silently ignored if the module has  no
              persistent data.  Persistent data is only read by insmod if this
              option is present, by default insmod does not process persistent
              data.

              As  a  shorthand form, -e "" (an empty string) is interpreted by
              insmod as the value of persistdir as  defined  in  modules.conf,
              followed  by  the  filename of the module relative to the module
              search path it was found in, minus any trailing ".gz",  ".o"  or
              ".mod".    If   modules.conf   specifies   "persistdir ="  (i.e.
              persistdir is an  empty  field)  then  this  shorthand  form  is
              silently ignored.  (See modules.conf (5).)

       -f, --force
              Attempt  load  the  module  even  if  the version of the running
              kernel and the version of the kernel for which  the  module  was
              compiled  do  not match.  This only overrides the kernel version
              check, it has no effect on symbol name checks.   If  the  symbol
              names in the module do not match the kernel then there is no way
              to force insmod to load the module.

       -h, --help
              Display a summary of options and immediately exit.

       -k, --autoclean
              Set the auto-clean flag on the module.  This flag will  be  used
              by  kerneld(8) to remove modules that have not been used in some
              period of time -- usually one minute.

       -L, --lock
              Use flock(2) to prevent simultaneous loads of the same module.

       -m, --map
              Output a load map on stdout,  making  it  easier  to  debug  the
              module in the event of a kernel panic.

       -n, --noload
              Dummy run, do everything except load the module into the kernel.
              If requested by an -m or -O, the run will produce a map or  blob
              file.   Since  the  module  is  not loaded, the real kernel load
              address is unknown so the map and blob  file  are  based  on  an
              arbitrary load address of 0x12340000.

       -o module_name, --name=module_name
              Explicitly  name  the module, rather than deriving the name from
              the base name of the source object file.

       -O blob_name, --blob=blob_name
              Save the binary object in blob_name.  The  result  is  a  binary
              blob  (no  ELF  headers) showing exactly what is loaded into the
              kernel after section manipulation and relocation.  Option -m  is
              recommended to get a map of the object.

       -p, --probe
              Probe  the  module  to  see  if it could be successfully loaded.
              This includes locating the  object  file  in  the  module  path,
              checking  version  numbers,  and resolving symbols.  It does not
              check the relocations nor does it produce a map or blob file.

       -P prefix, --prefix=prefix
              This option can be used with versioned modules  for  an  SMP  or
              bigmem  kernel, since such modules have an extra prefix added in
              their symbol  names.   If  the  kernel  was  built  with  symbol
              versions  then insmod will automatically extract the prefix from
              the definition of "get_module_symbol" or "inter_module_get", one
              of which must exist in any kernel that supports modules.  If the
              kernel has no symbol versions but  the  module  was  built  with
              symbol versions then the user must supply -P.

       -q, --quiet
              Do  not print a list of any unresolved symbols.  Do not complain
              about version mismatch.  The problem will only be  reflected  in
              the exit status of insmod.

       -r, --root
              Some  users compile modules under a non-root userid then install
              the modules as root.  This process can leave the  modules  owned
              by  the  non-root  userid,  even though the modules directory is
              owned by root.   If  the  non-root  userid  is  compromised,  an
              intruder can overwrite existing modules owned by that userid and
              use this exposure to bootstrap up to root access.

              By default, modutils will reject attempts to use a  module  that
              is  not  owned by root.  Specifying -r will toggle the check and
              allow root to load modules that are not owned  by  root.   Note:
              the default value for root check can be changed when modutils is
              configured.

              Use of -r to disable root checking or setting the default to "no
              root  check"  at configuration time is a major security exposure
              and is not recommended.

       -s, --syslog
              Output everything to syslog(3) instead of the terminal.

       -S, --kallsyms
              Force the loaded module to  have  kallsyms  data,  even  if  the
              kernel  does  not  support it.  This option is for small systems
              where the kernel is loaded without kallsyms  data  but  selected
              modules need kallsyms for debugging.

       -v, --verbose
              Be verbose.

       -V, --version
              Display the version of insmod.

       -X, --export; -x, --noexport
              Do  and  do  not  export  all  of the module's external symbols,
              respectively.  The default is for the symbols  to  be  exported,
              unless  the  architecture has function descriptors.  This option
              is only effective if the module does not explicitly  export  its
              own  controlled  symbol  table,  and  thus is deprecated.  It is
              unsafe on architectures with function descriptors and  has  been
              disabled for such architectures.

       -Y, --ksymoops; -y, --noksymoops
              Do  and do not add ksymoops symbols to ksyms.  These symbols are
              used by ksymoops to provide better debugging if there is an Oops
              in  this  module.  The default is for the ksymoops symbols to be
              defined.  This option is independent of the -X/-x options.

              ksymoops symbols add approximately 260 bytes per loaded  module.
              Unless  you  are  really short on kernel space and are trying to
              reduce ksyms to its minimum size, take the default and get  more
              accurate  Oops debugging.  ksymoops symbols are required to save
              persistent module data.

       -N, --numeric-only
              Only check the numeric part of the module  version  against  the
              kernel  version,  i.e.  ignore  EXTRAVERSION  when deciding if a
              module belongs to a kernel.  This flag is automatically set  for
              kernel 2.5 onwards, it is optional for earlier kernels.

   MODULE PARAMETERS
       Some  modules accept load-time parameters to customize their operation.
       These parameters are often I/O port and  IRQ  numbers  that  vary  from
       machine to machine and cannot be determined from the hardware.

       In  modules  built  for  2.0  series  kernels, any integer or character
       pointer symbol may be treated as a parameter and  modified.   Beginning
       in  the 2.1 series kernels, symbols are explicitly marked as parameters
       so  that  only  specific  values  may  be  changed.   Furthermore  type
       information is provided for checking the values provided at load time.

       In  the  case  of  integers,  all  values  may  be in decimal, octal or
       hexadecimal a la C: 17, 021 or  0x11.   Array  elements  are  specified
       sequence  separated by commas.  Elements can be skipped by omitting the
       value.

       In 2.0 series modules, values that do  not  begin  with  a  number  are
       considered strings.  Beginning in 2.1, the parameter's type information
       indicates whether to interpret the value as a  string.   If  the  value
       begins  with  double-quotes  ("),  the  string  is interpreted as in C,
       escape sequences and all.  Do note that  from  the  shell  prompt,  the
       quotes themselves may need to be protected from shell interpretation.

   GPL LICENSED MODULES AND SYMBOLS
       Starting  with  kernel  2.4.10,  modules  should have a license string,
       defined using MODULE_LICENSE().   Several  strings  are  recognised  as
       being  GPL  compatible;  any  other license string or no license at all
       means   that   the   module   is   treated   as    proprietary.     See
       include/linux/module.h for a list of GPL compatible license strings.

       If  the  kernel  supports the /proc/sys/kernel/tainted flag then insmod
       will OR the tainted flag with '1' when loading a module without  a  GPL
       license.   A  warning  is  issued if the kernel supports tainting and a
       module is loaded without a license.  A warning  is  always  issued  for
       modules  which have a MODULE_LICENSE() that is not GPL compatible, even
       on older kernels that do not support tainting.  This minimizes warnings
       when a new modutils is used on older kernels.

       insmod -f  (force)  mode  will  OR the tainted flag with '2' on kernels
       that support tainting.  It always issues a warning.

       Some kernel developers require that symbols exported by their code must
       only  be  used by modules with a GPL compatible license.  These symbols
       are exported by EXPORT_SYMBOL_GPL instead of the normal  EXPORT_SYMBOL.
       GPL-only  symbols  exported by the kernel and by other modules are only
       visible to modules with a GPL-compatible license, these symbols  appear
       in  /proc/ksyms  with  a  prefix  of  'GPLONLY_'.   insmod  ignores the
       GPLONLY_ prefix on symbols while loading a GPL licensed module  so  the
       module  just refers to the normal symbol name, without the prefix.  GPL
       only symbols are not made available to modules without a GPL compatible
       license, this includes  modules with no license at all.

   KSYMOOPS ASSISTANCE
       To  assist  with  debugging  of  kernel Oops when using modules, insmod
       defaults to adding some symbols to ksyms, see  the  -Y  option.   These
       symbols start with __insmod_modulename_.  The modulename is required to
       make the symbols unique.  It is legal to load the same object more than
       once under different module names.  Currently defined symbols are:

       __insmod_modulename_Oobjectfile_Mmtime_Vversion
              objectfile  is  the  name of the file that the object was loaded
              from.  This ensures that ksymoops can  match  the  code  to  the
              correct  object.   mtime  is the last modified timestamp on that
              file in hex, zero if stat failed.  version is the kernel version
              that the module was compiled for, -1 if no version is available.
              The _O symbol has the same start address as the module header.

       __insmod_modulename_Ssectionname_Llength
              This symbol appears at  the  start  of  selected  ELF  sections,
              currently  .text,  .rodata,  .data,  .bss  and  .sbss.   It only
              appears if the section has a non-zero size.  sectionname is  the
              name  of the ELF section, length is the length of the section in
              decimal.  These symbols help ksymoops map addresses to  sections
              when no symbols are available.

       __insmod_modulename_Ppersistent_filename
              Only  created by insmod if the module has one or more parameters
              that are marked as  persistent  data  and  a  filename  to  save
              persistent data (see -e, above) is available.

       The  other  problem  with  debugging kernel Oops in modules is that the
       contents of /proc/ksyms and /proc/modules can change between  the  Oops
       and  when  you process the log file.  To help overcome this problem, if
       the directory /var/log/ksymoops  exists  then  insmod  and  rmmod  will
       automatically  copy  /proc/ksyms and /proc/modules to /var/log/ksymoops
       with a prefix of `date +%Y%m%d%H%M%S`.  The  system  administrator  can
       tell  ksymoops  which  snapshot  files  to  use when debugging an Oops.
       There is no switch to disable this automatic copy.  If you do not  want
       it  to  occur,  do  not  create  /var/log/ksymoops.   If that directory
       exists, it should be owned by root and be  mode  644  or  600  and  you
       should  run this script every day or so.  The script below is installed
       as insmod_ksymoops_clean.

         #!/bin/sh
         # Delete saved ksyms and modules not accessed in 2 days
         if [ -d /var/log/ksymoops ]
         then
              set -e
              # Make sure there is always at least one version
              d=`date +%Y%m%d%H%M%S`
              cp -a /proc/ksyms /var/log/ksymoops/${d}.ksyms
              cp -a /proc/modules /var/log/ksymoops/${d}.modules
              find /var/log/ksymoops -type f -atime +2 -exec rm {} \;
         fi

SEE ALSO
       rmmod(8),  modprobe(8),  depmod(8),  lsmod(8),  ksyms(8),   modules(2),
       genksyms(8), kerneld(8), ksymoops(kernel).

BUGS
       insmod  [-V | --version]  should  display  version information and then
       exit immediately.  Instead,  it  prints  the  version  information  and
       behaves as if no options were given.

       Although  the  fix for this bug is trivial, it changes the behaviour of
       modutils.  Given the large number of distributions and scripts that run
       modutils  and  expect the current behaviour, any change of behaviour is
       unacceptable in 2.4.  Don't bother sending patches  for  this  bug,  it
       will not be fixed in 2.4, it should be fixed in 2.5.

HISTORY
       Module support was first conceived by Anonymous
       Initial Linux version by Bas Laarhoven <basATvimec.nl>
       Version 0.99.14 by Jon Tombs <jonATgtex02.es>
       Extended by Bjorn Ekwall <bj0rnATblox.se>
       Original ELF help from Eric Youngdale <ericATaib.com>
       Rewritten for 2.1.17 by Richard Henderson <rthATtamu.edu>
       Extended by Bjorn Ekwall <bj0rnATblox.se> for modutils-2.2.*, March 1999
       Assistance for ksymoops by Keith Owens <kaosATocs.au>, May 1999
       Maintainer: Keith Owens <kaosATocs.au>.



Linux                           March 23, 2003                       INSMOD(8)