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

       -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:

       -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. This option is the default
              on Red Hat Linux.

       -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.
              This option is only effective if the module does not  explicitly
              export  its own controlled symbol table, and thus is deprecated.

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


HISTORY

       Module support was first conceived by Anonymous
       Initial Linux version by Bas Laarhoven <bas@vimec.nl>
       Version 0.99.14 by Jon Tombs <jon@gtex02.us.es>
       Extended by Bjorn Ekwall <bj0rn@blox.se>
       Original ELF help from Eric Youngdale <eric@aib.com>
       Rewritten for 2.1.17 by Richard Henderson <rth@tamu.edu>
       Extended by Bjorn Ekwall <bj0rn@blox.se> for modutils-2.2.*, March 1999
       Assistance for ksymoops by Keith Owens <kaos@ocs.com.au>, May 1999
       Maintainer: Keith Owens <kaos@ocs.com.au>.

Linux                          January 30, 2002                      insmod(8)