Tue Sep 22 00:10:12 2015 UTC ()
Tweaks from Michael McConville - thanks!


(pgoyette)
diff -r1.3 -r1.4 src/share/man/man7/module.7
cvs diff -r1.3 -r1.4 src/share/man/man7/module.7 (switch to unified diff)

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