Section 8: insmod
This page was been converted automatically, from Debian GNU/Linux
man pages.
INSMOD(8) Linux Module Support INSMOD(8)
NAME
insmod - install loadable kernel module
SYNOPSIS
insmod [-fkmpqrsxXvyY] [-P prefix] [-o module_name]
object_file [ 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 object file name is given without extension, insmod
will search for the module in some common default directo-
ries. 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 (depreciated)).
This environment variable will override all the defini-
tions above.
OPTIONS
-f 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.
-k 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 -- usu-
ally one minute.
-m Output a load map, making it easier to debug the
module in the event of a kernel panic.
-o module_name
Explicitly name the module, rather than deriving
the name from the base name of the source object
file.
-p 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.
-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 ins-
mod.
Linux October 12 1999 1
INSMOD(8) Linux Module Support INSMOD(8)
-r 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 suppress the error and allow root to load mod-
ules that are not owned by root.
Use of -r is a major security exposure and is not
recommended.
-s Output everything to syslog(3) instead of the ter-
minal.
-v Be verbose.
-X, -x Do and do not export all of the module's external
symbols, respectively. The default is for the sym-
bols to be exported. This option is only effective
if the module does not explicitly export its own
controlled symbol table, and thus is depreciated.
-Y, -y 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 ker-
nel space and are trying to reduce ksyms to its
minimum size, take the default and get more accu-
rate Oops debugging.
-P 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 def-
inition of "get_module_symbol" 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.
MODULE PARAMETERS
Some modules accept load-time parameters to customize
their operation. These parameters are often I/O port and
Linux October 12 1999 2
INSMOD(8) Linux Module Support INSMOD(8)
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 ele-
ments 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 inter-
pret the value as a string. If the value begins with dou-
ble-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.
KSYMOOPS ASSISTANCE
To assist with debugging of kernel Oops when using mod-
ules, insmod defaults to adding some symbols to ksyms, see
the -Y option. These symbols start with __insmod_module-
name_. 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. ver-
sion 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 sec-
tion in decimal. These symbols help ksymoops map
addresses to sections when no symbols are available.
The other problem with debugging kernel Oops in modules is
that the contents of /proc/ksyms and /proc/modules can
Linux October 12 1999 3
INSMOD(8) Linux Module Support INSMOD(8)
change between the Oops and when you process the log file.
To help overcome this problem, if directory /var/log/ksy-
moops exists then insmod and rmmod will automatically copy
/proc/ksyms and /proc/modules to /var/log/ksymoops with a
prefix of `date +`. The system administrator
can tell ksymoops which snapshot files to use when debug-
ging an Oops. There is no switch to disable this auto-
matic 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_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 +`
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), mod-
ules(2), genksyms(8), kerneld(8), ksymoops(kernel).
HISTORY
Module support was first conceived by Anonymous
Initial Linux version by Bas Laarhoven
Version 0.99.14 by Jon Tombs
Extended by Bjorn Ekwall
Original ELF help from Eric Youngdale
Rewritten for 2.1.17 by Richard Henderson
Extended by Bjorn Ekwall for modu-
tils-2.2.*, March 1999
Assistance for ksymoops by Keith Owens ,
May 1999
Linux October 12 1999 4