👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

RedHat 9 (Linux i386) - man page for insmod (redhat section 8)

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

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)


All times are GMT -4. The time now is 11:24 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password