insmod
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)
