Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.


MODULE(7)              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 also helps software
     developers add new parts of the kernel without constantly rebooting to
     test their changes.

     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
     interact 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
     created manually, after the driver module has been successfully loaded.
     Most device driver modules do 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 the kernel.  This also allows loading
     support 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
     appropriately layered console driver.

   Security-Model modules
     Alternate system security models also may be loaded using module.

EXAMPLES
     The common build tool of NetBSD, "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 /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

     Alternatively, the "build.sh" tool can be used to build and install only
     the modules:

           cd /usr/src
           ./build.sh -O /usr/obj -T /usr/tools modules
           ./build.sh -O /usr/obj -T /usr/tools installmodules=/

SEE ALSO
     modctl(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
            version, 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
            certain 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
            bootloaders.

     The absence of required modules or the inability of the bootloader to
     load the modules are common reasons for failures to boot a MODULAR
     kernel.  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.  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 modctl(2) system call can
     acquire total control over the system.

     To avoid such 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.

NetBSD 10.99                     July 13, 2020                    NetBSD 10.99