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
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
-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.
-v, --verbose
Be verbose.
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
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
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 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.
__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
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>.
Man(1) output converted with
man2html