MODULE(7) BSD Miscellaneous Information Manual MODULE(7)NAME
module — Kernel Modules interface
SYNOPSIS
options MODULAR
DESCRIPTION
Kernel modules allow the system administrator to dynamically add and
remove functionality from a running system. This ability also helps
software developers to develop new parts of the kernel without constantly
rebooting to test their changes.
Additionally, the kernel may automatically load software modules as
needed to perform requested operations. For example, an “xyzfs” module
can be loaded automatically when an attempt is made to mount an “xyzfs”
file system. Modules can also depend on other modules, and dependent
modules are automatically loaded. When a module is no longer needed, it
can be automatically unloaded.
An in-kernel linker resolves symbol references between the module and the
rest of the kernel.
The module interface is accessed with the modctl(2) system call. All
common operations involving kernel modules are handled by the modload(8),
modunload(8), and modstat(8) programs. Users should never have to inter‐
act with modctl(2) directly.
MODULE CLASSES
Virtual File System modules
Virtual file systems may be added via the module interface.
Device Driver modules
Many device drivers can be loaded as a kernel module. One potential
problem specific to block and character device drivers is that the device
nodes must exist for the devices to be accessed. These need to be cre‐
ated manually, after the driver module has been successfully loaded. The
majority of the device driver modules however does not need any manual
intervention to function properly.
Execution Interpreters
Execution Interpreters can be loaded to provide support for executing
binaries not normally supported by kernel. This also allows loading sup‐
port for executing foreign system binaries. Execution Interpreters may
require that an appropriate emulation module also be loaded.
Miscellaneous modules
Miscellaneous modules are modules for which there are not currently well-
defined or well-used interfaces for extension. They are provided for
extension, and the user-provided module initialization routine is
expected to install the necessary "hooks" into the rest of the operating
system. An example of a "miscellaneous module" might be a loader for
card-specific VGA drivers or alternate terminal emulations in an appro‐
priately layered console driver.
Security-Model modules
Alternate system security models may loaded using the module facility.
EXAMPLES
The common build tool of NetBSD, “build.sh”, automatically compiles and
installs all modules during a full system build and install. Sometimes
it is however useful to update only modules. The following example
demonstrates one way to do this. It is assumed that the source code is
under /usr/src, while the object and toolchain directories are under
/usr/obj and /usr/tools, respectively.
cd /usr/src/sys/modules
export OBJDIR=/usr/obj
export TOOLDIR=/usr/tools
make clean
make
make install
SEE ALSOmodctl(2), modload(8), modstat(8), modunload(8), module(9)HISTORY
The module facility was designed to be similar in functionality to the
loadable kernel modules facility provided by SunOS 4.1.3. The old LKM
interface was replaced by module in NetBSD 5.0.
AUTHORS
The module subsystem was implemented by Andrew Doran ⟨ad@netbsd.org⟩.
CAVEATS
The module framework is still under active development. At least two
potential caveats can be mentioned.
1. Kernel modules are built to operate only with a specific version
of the NetBSD kernel. When the kernel is updated to a new ver‐
sion, the contents of the /stand/${ARCH}/${VERSION}/modules/
directory should be updated as well. (This location has been the
subject of much discussion, and may change in future versions of
NetBSD.)
2. If an attempt is made to boot the operating system from a file
system for which the module is not built into the kernel, the boot
may fail with the message “Cannot mount root, error 79”. On cer‐
tain architectures (currently, i386 and amd64), one may be able to
recover from this error by using the “load xxxfs” command before
trying to boot. This command is only available on newer bootload‐
ers.
The absence of required modules or the inability of the bootloader to
load the modules are common reasons for failures to boot a MODULAR ker‐
nel. It may be a good practice to maintain a non-MODULAR kernel in the
root file system for recovery purposes.
SECURITY CONSIDERATIONS
A module becomes part of the kernel once loaded. Compared to userland
programs, all errors in the code can be fatal. There is no memory pro‐
tection between modules and the rest of the kernel. Hence, a potential
attacker with access to the modctl(2) system call can acquire complete
and total control over the system.
To avoid associated security risks, new modules can only be loaded when
securelevel is less than or equal to zero, or if the kernel was built
with options INSECURE. Refer to secmodel_securelevel(9) for additional
details on the securelevel. Only use modules from trusted sources.
BSD December 14, 2010 BSD
