1.\" $NetBSD: module.7,v 1.7 2017/08/31 08:36:32 wiz Exp $ 2.\" 3.\" Copyright (c) 2010 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 16.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 17.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 18.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 19.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 20.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 21.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 22.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 23.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 24.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 25.\" POSSIBILITY OF SUCH DAMAGE. 26.\" 27.Dd August 31, 2017 28.Dt MODULE 7 29.Os 30.Sh NAME 31.Nm module 32.Nd Kernel Modules interface 33.Sh SYNOPSIS 34.Cd "options MODULAR" 35.Sh DESCRIPTION 36Kernel modules allow the system administrator to 37dynamically add and remove functionality from a running system. 38This also helps software developers add 39new parts of the kernel without constantly rebooting to 40test their changes. 41.Pp 42The kernel may automatically load software modules as 43needed to perform requested operations. 44For example, an 45.Dq xyzfs 46module can be loaded automatically when an 47attempt is made to mount an 48.Dq xyzfs 49file system. 50Modules can also depend on other modules, and dependent modules are 51automatically loaded. 52When a module is no longer needed, it can be automatically unloaded. 53.Pp 54An in-kernel linker resolves symbol references between the module 55and the rest of the kernel. 56.Pp 57The 58.Nm 59interface is accessed with the 60.Xr modctl 2 61system call. 62All common operations involving 63kernel modules are handled by the 64.Xr modload 8 , 65.Xr modunload 8 , 66and 67.Xr modstat 8 68programs. 69Users should never have to interact with 70.Xr modctl 2 71directly. 72.Sh MODULE CLASSES 73.Ss Virtual File System modules 74Virtual file systems may be added via the 75.Nm 76interface. 77.Ss Device Driver modules 78Many device drivers can be loaded as a kernel module. 79One potential problem specific to block and character device drivers 80is that the device nodes must exist for the devices to be accessed. 81These need to be created manually, after the driver module has been 82successfully loaded. 83Most device driver modules do not 84need any manual intervention to function properly. 85.Ss Execution Interpreters 86Execution Interpreters can be loaded to provide support for executing 87binaries not normally supported by the kernel. 88This also allows loading 89support for executing foreign system binaries. 90Execution Interpreters may require that an appropriate 91emulation module also be loaded. 92.Ss Miscellaneous modules 93Miscellaneous modules are modules for which there are not currently 94well-defined or well-used interfaces for extension. 95They are provided for extension, and the user-provided module 96initialization routine is expected to install the necessary "hooks" 97into the rest of the operating system. 98An example of a "miscellaneous module" might be a loader for 99card-specific VGA drivers or alternate terminal emulations in 100an appropriately layered console driver. 101.Ss Security-Model modules 102Alternate system security models also may be loaded using 103.Nm . 104.Sh EXAMPLES 105The common build tool of 106.Nx , 107.Dq build.sh , 108automatically compiles and installs most 109modules during a full system build and install. 110(The exceptions are some modules from external sources which, due to 111licensing concerns, can be built only as separately-loaded modules.) 112However, sometimes it is useful to update only modules. 113The following example demonstrates one way to do this. 114It is assumed that the source code is under 115.Pa /usr/src , 116while the object and toolchain directories are under 117.Pa /usr/obj 118and 119.Pa /usr/tools , 120respectively. 121.Bd -literal -offset indent 122cd /usr/src/sys/modules 123 124export OBJDIR=/usr/obj 125export TOOLDIR=/usr/tools 126 127make clean 128make 129make install 130.Ed 131.Pp 132Alternatively, the 133.Dq build.sh 134tool can be used to build only the modules. 135.Bd -literal -offset indent 136cd /usr/src 137\&./build.sh -O /usr/obj -T /usr/tools modules 138.Ed 139.Sh SEE ALSO 140.Xr modctl 2 , 141.Xr modload 8 , 142.Xr modstat 8 , 143.Xr modunload 8 , 144.Xr module 9 145.Sh HISTORY 146The 147.Nm 148facility was designed to be similar in functionality 149to the loadable kernel modules facility provided by 150SunOS 4.1.3. 151The old 152.Dv LKM 153interface was replaced by 154.Nm 155in 156.Nx 5.0 . 157.Sh AUTHORS 158The 159.Nm 160subsystem was implemented by 161.An Andrew Doran 162.Aq ad@netbsd.org . 163.Sh CAVEATS 164The 165.Nm 166framework is still under active development. 167At least two potential caveats can be mentioned. 168.Bl -enum -offset 2n 169.It 170Kernel modules are built to operate only with a specific version of the 171.Nx 172kernel. 173When the kernel is updated to a new version, the contents of the 174.Pa /stand/${ARCH}/${VERSION}/modules/ 175directory should be updated as well. 176(This location has been the subject of much discussion, and may change 177in future versions of 178.Nx . ) 179.It 180If an attempt is made to boot the operating system from a file system for 181which the module is not built into the kernel, the boot may fail 182with the message 183.Dq "Cannot mount root, error 79" . 184On certain architectures (currently, i386 and amd64), one may be able to 185recover from this error by using the 186.Dq "load xxxfs" 187command before trying to boot. 188This command is only available on newer bootloaders. 189.El 190.Pp 191The absence of required modules or the inability of the bootloader 192to load the modules are common reasons for failures to boot a 193.Cd MODULAR 194kernel. 195It may be a good practice to maintain a non-MODULAR kernel 196in the root file system for recovery purposes. 197.Sh SECURITY CONSIDERATIONS 198A module becomes part of the kernel once loaded. 199Unlike in userland programs, fatal errors in kernel modules 200may crash the operating system. 201There is no memory protection between modules and the rest of the kernel. 202Hence, a potential attacker with access to the 203.Xr modctl 2 204system call can acquire total control over the system. 205.Pp 206To avoid such security risks, new modules can only be loaded when 207.Pa securelevel 208is less than or equal to zero, or if the kernel was built with 209.Cd options INSECURE . 210Refer to 211.Xr secmodel_securelevel 9 212for additional details on the 213.Pa securelevel . 214Only use modules from trusted sources. 215