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

              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


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

              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 begins with

       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

              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 and .bss.
              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

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


Man(1) output converted with man2html