MAN page from Old RedHat 7.X modutils-2.3.14-3.i386.rpm

INSMOD

Section: Linux Module Support (8)
Updated: October 12 1999
Index

NAME

insmod - install loadable kernel module

SYNOPSIS

insmod[-fkmpqrsxXvyY] [-P prefix] [-o module_name]object_file [ symbol=value ... ]

DESCRIPTION

Insmodinstalls a loadable module in the running kernel.

Insmodtries to link a module into the running kernel by resolving all symbolsfrom the kernel's exported symbol table.

If the object file name is given without extension,insmodwill 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 adifferent configuration file from the default /etc/modules.conf (or/etc/conf.modules (depreciated)).This environment variable will override all the definitions above.

OPTIONS

-f: Attempt load the module even if the version of the running kernel andthe version of the kernel for which the module was compiled do not match.
-k: Set the auto-clean flag on the module. This flag will be used bykerneld(8) to remove modules that have not been used in someperiod of time --- usually one minute.
-m: Output a load map, making it easier to debug the module in the eventof a kernel panic.
-o module_name: Explicitly name the module, rather than deriving the name from thebase name of the source object file.
-p: Probe the module to see if it could be successfully loaded. Thisincludes locating the object file in the module path, checkingversion numbers, and resolving symbols.
-q: 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: Some users compile modules under a non-root userid then install themodules as root. This process can leave the modules owned by thenon-root userid, even though the modules directory is owned by root.If the non-root userid is compromised, an intruder can overwriteexisting modules owned by that userid and use this exposure tobootstrap up to root access.
: By default, modutils will reject attempts to use a module that is notowned by root. Specifying -r will suppress the error and allow root toload modules that are not owned by root.
: Use of-ris a major security exposure and is not recommended.
-s: Output everything to syslog(3) instead of the terminal.
-v: Be verbose.
-X, -x: 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 onlyeffective if the module does not explicitly export its own controlledsymbol table, and thus is depreciated.
-Y, -y: Do and do not add ksymoops symbols to ksyms. These symbols are used byksymoops to provide better debugging if there is an Oops in thismodule. The default is for the ksymoops symbols to be defined. Thisoption is independent of the -X/-x options.
: ksymoops symbols add approximately 260 bytes per loaded module. Unlessyou are really short on kernel space and are trying to reduce ksyms toits minimum size, take the default and get more accurate Oopsdebugging.
-P prefix: This option can be used with versioned modules for an SMP or bigmemkernel, since such modules have an extra prefix added in their symbolnames.If the kernel was built with symbol versions then insmod willautomatically extract the prefix from the definition of"get_module_symbol" which must exist in any kernel that supportsmodules. If the kernel has no symbol versions but the module was builtwith symbol versions then the user must supply -P.

MODULE PARAMETERS

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

In modules built for 2.0 series kernels, any integer or character pointersymbol may be treated as a parameter and modified. Beginning in the2.1 series kernels, symbols are explicitly marked as parameters so thatonly specific values may be changed. Furthermore type information isprovided for checking the values provided at load time.

In the case of integers, all values may be in decimal, octal orhexadecimal a la C: 17, 021 or 0x11. Array elements are specifiedsequence separated by commas; elements can be skipped by omittingthe value.

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

KSYMOOPS ASSISTANCE

To assist with debugging of kernel Oops when using modules, insmoddefaults to adding some symbols to ksyms, see the -Y option.These symbols start with __insmod_modulename_. Themodulename is required to make the symbols unique, it is legal toload 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 loadedfrom. This ensures that ksymoops can match the code to the correctobject. mtime is the last modified timestamp on that file inhex, zero if stat failed. version is the kernel version thatthe 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 thesection has a non-zero size. sectionname is the name of the ELFsection, length is the length of the section in decimal. Thesesymbols help ksymoops map addresses to sections when no symbols areavailable.

The other problem with debugging kernel Oops in modules is that thecontents of /proc/ksyms and /proc/modules can change between the Oopsand when you process the log file. To help overcome this problem, ifdirectory /var/log/ksymoops exists then insmod and rmmod willautomatically copy /proc/ksyms and /proc/modules to /var/log/ksymoopswith a prefix of `date +%Y%m%d%H%M%S`.The system administrator can tell ksymoops which snapshot files to usewhen debugging an Oops. There is no switch to disable this automaticcopy, 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 or600 and you should run this script every day or so. The script belowis installed as insmod_clean_ksymoops.

  #!/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

HISTORY

Module support was first conceived by Anonymous
Initial Linux version by Bas Laarhoven <basAATTvimec.nl>
Version 0.99.14 by Jon Tombs <jonAATTgtex02.us.es>
Extended by Bjorn Ekwall <bj0rnAATTblox.se>
Original ELF help from Eric Youngdale <ericAATTaib.com>
Rewritten for 2.1.17 by Richard Henderson <rthAATTtamu.edu>
Extended by Bjorn Ekwall <bj0rnAATTblox.se> for modutils-2.2.*, March 1999
Assistance for ksymoops by Keith Owens <kaosAATTocs.com.au>, May 1999

Index

NAME

SYNOPSIS

DESCRIPTION

OPTIONS
MODULE PARAMETERS
KSYMOOPS ASSISTANCE

SEE ALSO

HISTORY

This document was created byman2html,using the manual pages.