*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Linux man pages -> insmod (8)              



NAME    [Toc]    [Back]

       insmod - install loadable kernel module

SYNOPSIS    [Toc]    [Back]

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

DESCRIPTION    [Toc]    [Back]

       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.

   OPTIONS    [Toc]    [Back]
       -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

	      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

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

   MODULE PARAMETERS    [Toc]    [Back]
       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

       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.

       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    [Toc]    [Back]
       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:

	      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.

	      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.

	      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.

	 # Delete saved ksyms and modules not accessed in 2 days
	 if [ -d /var/log/ksymoops ]
	      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 {} \;

SEE ALSO    [Toc]    [Back]

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

BUGS    [Toc]    [Back]

       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    [Toc]    [Back]

       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)
[ Back ]
 Similar pages
Name OS Title
init_module Linux initialize a loadable module entry
create_module Linux create a loadable module entry
delete_module Linux delete a loadable module entry
snmpmod FreeBSD SNMP daemon loadable module interface
mload IRIX dynamically loadable kernel modules
lkm OpenBSD Loadable Kernel Modules interface
depmod Linux handle dependency descriptions for loadable kernel modules
modpath HP-UX change global search path for dynamically loadable kernel modules
installkernel Linux install a new kernel image
MODULE_DEPEND FreeBSD set kernel module dependencies
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service