.\" $NetBSD: module.7,v 1.9 2020/07/13 13:42:51 pgoyette Exp $
.\"
.\" Copyright (c) 2010 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd July 13, 2020
.Dt MODULE 7
.Os
.Sh NAME
.Nm module
.Nd Kernel Modules interface
.Sh SYNOPSIS
.Cd "options MODULAR"
.Sh DESCRIPTION
Kernel modules allow the system administrator to
dynamically add and remove functionality from a running system.
This also helps software developers add
new parts of the kernel without constantly rebooting to
test their changes.
.Pp
The kernel may automatically load software modules as
needed to perform requested operations.
For example, an
.Dq xyzfs
module can be loaded automatically when an
attempt is made to mount an
.Dq 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.
.Pp
An in-kernel linker resolves symbol references between the module
and the rest of the kernel.
.Pp
The
.Nm
interface is accessed with the
.Xr modctl 2
system call.
All common operations involving
kernel modules are handled by the
.Xr modload 8 ,
.Xr modunload 8 ,
and
.Xr modstat 8
programs.
Users should never have to interact with
.Xr modctl 2
directly.
.Sh MODULE CLASSES
.Ss Virtual File System modules
Virtual file systems may be added via the
.Nm
interface.
.Ss 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 created manually, after the driver module has been
successfully loaded.
Most device driver modules do not
need any manual intervention to function properly.
.Ss Execution Interpreters
Execution Interpreters can be loaded to provide support for executing
binaries not normally supported by the kernel.
This also allows loading
support for executing foreign system binaries.
Execution Interpreters may require that an appropriate
emulation module also be loaded.
.Ss 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 appropriately layered console driver.
.Ss Security-Model modules
Alternate system security models also may be loaded using
.Nm .
.Sh EXAMPLES
The common build tool of
.Nx ,
.Dq build.sh ,
automatically compiles and installs most
modules during a full system build and install.
(The exceptions are some modules from external sources which, due to
licensing concerns, can be built only as separately-loaded modules.)
However, sometimes it is useful to update only modules.
The following example demonstrates one way to do this.
It is assumed that the source code is under
.Pa /usr/src ,
while the object and toolchain directories are under
.Pa /usr/obj
and
.Pa /usr/tools ,
respectively.
.Bd -literal -offset indent
cd /usr/src/sys/modules

export OBJDIR=/usr/obj
export TOOLDIR=/usr/tools

make clean
make
make install
.Ed
.Pp
Alternatively, the
.Dq build.sh
tool can be used to build and install only the modules:
.Bd -literal -offset indent
cd /usr/src
\&./build.sh -O /usr/obj -T /usr/tools modules
\&./build.sh -O /usr/obj -T /usr/tools installmodules=/
.Ed
.Sh SEE ALSO
.Xr modctl 2 ,
.Xr modload 8 ,
.Xr modstat 8 ,
.Xr modunload 8 ,
.Xr module 9
.Sh HISTORY
The
.Nm
facility was designed to be similar in functionality
to the loadable kernel modules facility provided by
SunOS 4.1.3.
The old
.Dv LKM
interface was replaced by
.Nm
in
.Nx 5.0 .
.Sh AUTHORS
The
.Nm
subsystem was implemented by
.An Andrew Doran
.Aq ad@netbsd.org .
.Sh CAVEATS
The
.Nm
framework is still under active development.
At least two potential caveats can be mentioned.
.Bl -enum -offset 2n
.It
Kernel modules are built to operate only with a specific version of the
.Nx
kernel.
When the kernel is updated to a new version, the contents of the
.Pa /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
.Nx . )
.It
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
.Dq "Cannot mount root, error 79" .
On certain architectures (currently, i386 and amd64), one may be able to
recover from this error by using the
.Dq "load xxxfs"
command before trying to boot.
This command is only available on newer bootloaders.
.El
.Pp
The absence of required modules or the inability of the bootloader
to load the modules are common reasons for failures to boot a
.Cd MODULAR
kernel.
It may be a good practice to maintain a non-MODULAR kernel
in the root file system for recovery purposes.
.Sh SECURITY CONSIDERATIONS
A module becomes part of the kernel once loaded.
Unlike in userland programs, fatal errors in kernel modules
may crash the operating system.
There is no memory protection between modules and the rest of the kernel.
Hence, a potential attacker with access to the
.Xr modctl 2
system call can acquire total control over the system.
.Pp
To avoid such security risks, new modules can only be loaded when
.Pa securelevel
is less than or equal to zero, or if the kernel was built with
.Cd options INSECURE .
Refer to
.Xr secmodel_securelevel 9
for additional details on the
.Pa securelevel .
Only use modules from trusted sources.