MODULE(7)

💖 NAME 💖

okay bestie, welcome to module(7) — the Kernel Modules interface from the Miscellaneous Information Manual.

module — Kernel Modules interface

---

🌸 SYNOPSIS 🌸

options MODULAR

---

💅 DESCRIPTION 💅

Kernel modules let the system administrator dynamically add and remove functionality from a running system. Iconic, honestly. This also helps software developers add new parts of the kernel without constantly rebooting to test their changes. No cap.

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. Slay.

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.

---

xoxo, source/version Debian, date July 13, 2020, page module(7) — bye bestie 💖🎀