.\" Copyright (c) 1994, 1995 Jacques Gelinas (jacques@solucorp.qc.ca)
.\" Copyright (c) 1995, 1999 Bjorn Ekwall (bj0rn@blox.se)
.\" This program is distributed according to the Gnu General Public License.
.\" See the file COPYING in the base distribution directory
.\"
.TH MODPROBE 8 "February 12, 2003" Linux "Linux Module Support"
.SH NAME
modprobe \- high level handling of loadable modules
.SH SYNOPSIS
.hy 0
.B modprobe
[\-adnqv]\ [\-C\ \fIconfig\fR]\ module\ [symbol=value\ ...]
.br
.B modprobe
[\-adnqv] [\-C\ \fIconfig\fR] [\-t\ \fItype\fR] pattern
.br
.B modprobe
\-l [\-C\ \fIconfig\fR] [\-t\ \fItype\fR] pattern
.br
.B modprobe
\-c [\-C\ \fIconfig\fR]
.br
.B modprobe
\-r [\-dnv] [\-C\ \fIconfig\fR] [module ...]
.br
.B modprobe
-Vh
.SH OPTIONS
.TP
.BR \-a ", " \-\-all
Load \fBall\fR
matching modules instead of stopping after the first successful loading.
.TP
.BR \-c ", " \-\-showconfig
Show the currently used configuration.
.TP
\fB\-C\fR,\ \fB\-\-config\fR\ \fIconfig\fR
Use the file \fIconfig\fR instead of (the optional) \fI/etc/modules.conf\fR
to specify the configuration.
The environment variable \fBMODULECONF\fR can also be used to select (and
override) a different configuration file from the default /etc/modules.conf (or
\fI/etc/conf.modules\fR (deprecated)).
.PP
When environment variable
.B 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
.B 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.
.TP
.BR \-d ", " \-\-debug
Show information about the internal representation of the stack of modules.
.TP
.BR \-h ", " \-\-help
Display a summary of options and immediately exit.
.TP
.BR \-k ", " \-\-autoclean
Set 'autoclean' on loaded modules.  Used by the kernel when it calls on
.B modprobe
to satisfy a missing feature (supplied as a module).
The \fB\-q\fR option is implied by \fB\-k\fR.
These options will automatically be sent to \fBinsmod\fR.
.TP
.BR \-l ", " \-\-list
List modules matching given \fIpattern\fR.
.TP
.BR \-n ", " \-\-show
Don't actually perform the action, just show what would be done.
.TP
.BR \-q ", " \-\-quiet
Do not complain about \fBinsmod\fR failing to install a module.
Continue as normal, but silently, with other possibilities for modprobe to test.
This option will automatically be sent to \fBinsmod\fR.
.TP
.BR \-r ", " \-\-remove
Remove module (stacks) or do autoclean, depending on whether there are
any modules mentioned on the command line.
.TP
.BR \-s ", " \-\-syslog
Report via syslog instead of stderr.
This options will automatically be sent to \fBinsmod\fR.
.TP
\fB\-t\fR\ \fImoduletype\fR;\ \fB\-\-type\fR\ \fImoduletype\fR
Only consider modules of this type that match given \fIpattern\fR.  modprobe
will only look at modules whose directory path includes exactly
"\fI/moduletype/\fR".  \fImoduletype\fR can include more than one directory
name, e.g. "\fB\-t\fR\ \fIdrivers/net\fR" would list modules in
\fIxxx/drivers/net/\fR and its subdirectories.
.TP
.BR \-v ", " \-\-verbose
Print all commands as they are executed.
.TP
.BR "\-V, \-\-version"
Display the version of \fBmodprobe\fR.
.TP
.B Note:
Module names must not contain paths (no '/'), nor may they contain the
trailing '.o'.  For example, slip is a valid module name for
.BR modprobe ,
/lib/modules/2.2.19/net/slip and slip.o are invalid.  This applies to
entries in the config and the command line where \fImodule\fR is used.
Patterns are expected to have a trailing .o as found in the filename.
.SH DESCRIPTION
The \fBmodprobe\fR and \fBdepmod\fR utilities are intended
to make a Linux modular kernel more manageable for all users,
administrators and distribution maintainers.
.PP
\fBModprobe\fR uses a "Makefile"-like dependency file, created by
\fBdepmod\fR, to automatically load the relevant module(s) from the set of
modules available in predefined directory trees.
.PP
\fBModprobe\fR is used to load a single module,
a stack of dependent modules, or all modules that are marked with a specified
tag.
.PP
\fBModprobe\fR will automatically load all base modules needed in a module
stack, as described by the dependency file \fImodules.dep\fR.
If the loading of one of these modules fails, the whole current stack
of modules loaded in the current session will be unloaded automatically.
.PP
\fBModprobe\fR has two ways of loading modules. One way (the probe mode) will
try to load a module out of a list (defined by \fIpattern\fR).
\fBModprobe\fR stops loading as soon as one module loads successfully.
This could be used to autoload one Ethernet driver out of a list.
.br
The other way \fBmodprobe\fR can be used is to load \fBall\fR modules from a
list.  See \fBEXAMPLES\fR, below.
.PP
With the option \fB\-r\fR, modprobe will automatically unload a stack of
modules, similar to the way "\fBrmmod \-r\fR" does. Note that using just
"\fBmodprobe \-r\fR" will clean up unused autoloaded modules and also perform
the pre- and post-remove commands in the configuration file
\fI/etc/modules.conf\fR.
.PP
The combining the options \fB\-l\fR and \fB\-t\fR lists all available
modules of a certain type.
.PP
Option \fB\-c\fR will print the currently used configuration (default +
configuration file).
.SH CONFIGURATION
The behavior of \fBmodprobe\fR (and \fBdepmod\fR)
can be modified by the (optional) configuration file
\fI/etc/modules.conf\fR.
.br
For a more detailed description of what this file can contain,
as well as the default configuration used by \fBdepmod\fR and
\fBmodprobe\fR, see \fBmodules.conf\fR(5).
.PP
Note that the pre- and post-remove commands will \fBnot\fR be executed
if a module is "autocleaned" by kerneld!
Look for the up-coming support for persistent module storage instead.
.br
If you want to use the pre- and post-install features, you will have to
turn off autoclean for kerneld and instead put something like the following
line in your \fBcrontab\fR (this is used for kmod systems as well)
to do autoclean every 2 minutes:
.br
 */2 * * * * test \-f /proc/modules && /sbin/modprobe \-r
.SH STRATEGY
The idea is that \fBmodprobe\fR will look first in the directory containing
modules compiled for the current release of the kernel.  If the module is not
found there, \fBmodprobe\fR will look in the directory common to the kernel
version (e.g. 2.0, 2.2).  If the module is still found, \fBmodprobe\fR
will look in the directory containing modules for a default release,
and so on.
.PP
When you install a new linux, the modules should be moved to a directory
related to the release (and version) of the kernel you are installing.
Then you should do a symlink from this directory to the "default" directory.
.PP
Each time you compile a new kernel, the command "\fBmake modules_install\fR"
will create a new directory, but won't change the "default" link.
.PP
When you get a module unrelated to the kernel distribution
you should place it in one of the version-independent directories
under \fI/lib/modules\fR.
.PP
This is the default strategy, which can be overridden in
\fI/etc/modules.conf\fR.
.SH EXAMPLES
.TP
.B modprobe \-t net
Load one of the modules that are stored in the directory tagged "net".
Each module are tried until one succeeds.
.TP
.B modprobe \-a \-t boot
All modules that are stored in directories tagged "boot" will be loaded.
.TP
.B modprobe slip
This will attempt to load the module slhc.o if it was not previously loaded,
since the slip module needs the functionality in the slhc module.
This dependency will be described in the file \fImodules.dep\fR that was
created automatically by \fBdepmod\fR.
.TP
.B modprobe \-r slip
This will unload the slip module.
It will also unload the slhc module automatically,
unless it is used by some other module as well (e.g. ppp).
.SH FILES
.nf
.IR /etc/modules.conf\  "(alternatively but deprecated\ " /etc/conf.modules )
.IR /lib/modules/*/modules.dep ,
.I  /lib/modules/*
.fi
.SH SEE ALSO
.BR depmod "(8), " lsmod "(8), " kerneld "(8), " ksyms "(8), " rmmod "(8)."
.SH SAFE MODE
If the effective uid is not equal to the real uid then \fBmodprobe\fR treats
its input with extreme suspicion.  The last parameter is always treated
as a module name, even if it starts with '-'.  There can only be one
module name and options of the form "variable=value" are forbidden.
The module name is always treated as a string, no meta expansion is
performed in safe mode.  However meta expansion is still applied to
data read from the config file.
.PP
euid may not be equal to uid when modprobe is invoked from the kernel,
this is true for kernels >= 2.4.0-test11.  In an ideal world, \fBmodprobe\fR
could trust the kernel to only pass valid parameters to modprobe.
However at least one local root exploit has occurred because high level
kernel code passed unverified parameters direct from the user to
modprobe.  So modprobe no longer trusts kernel input.
.PP
.ne 8
\fBmodprobe\fR automatically sets safe mode when the environment consists
only of these strings
.nf
 HOME=/
 TERM=linux
 PATH=/sbin:/usr/sbin:/bin:/usr/bin
.fi
This detects modprobe execution from the kernel on kernels 2.2 though
2.4.0-test11, even if uid == euid, which it does on the earlier
kernels.
.SH "LOGGING COMMANDS"
If directory \fI/var/log/ksymoops\fR exists and \fBmodprobe\fR is run with an
option that could load or a delete a module then modprobe will log its
command and return status in \fI/var/log/ksymoops/`date\ +%Y%m%d.log`\fR.
There is no switch to disable this automatic logging, if you do not
want it to occur, do not create \fI/var/log/ksymoops\fR.  If that directory
exists, it should be owned by root and be mode 644 or 600 and you
should run script \fBinsmod_ksymoops_clean\fR every day or so.
.SH REQUIRED UTILITIES
.BR depmod "(8), " insmod "(8)."
.SH NOTES
Patterns supplied to \fBmodprobe\fR will often need to be escaped to ensure
that it is evaluated in the proper context.
.SH BUGS
\fBmodprobe\fR\ [ \fB\-V\fR\ |\ \fB\-\-version\fR ] should exit immediately.
Instead, it prints the version information and behaves as if no options were
given.
.P
Although the fix for this bug is trivial, it changes the behaviour of
modutils.
Given the large number of distributions and scripts that run modutils
and expect the current behaviour, any change of behaviour is
unacceptable in 2.4.
Don't bother sending patches for this bug, it will not be fixed in 2.4,
it should be fixed in 2.5.
.SH AUTHOR
Jacques Gelinas (jack@solucorp.qc.ca)
.br
Bjorn Ekwall (bj0rn@blox.se)