215 lines
6.8 KiB
Groff
215 lines
6.8 KiB
Groff
.\" $NetBSD: module.7,v 1.7 2017/08/31 08:36:32 wiz 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 August 31, 2017
|
|
.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 only the modules.
|
|
.Bd -literal -offset indent
|
|
cd /usr/src
|
|
\&./build.sh -O /usr/obj -T /usr/tools modules
|
|
.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.
|