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 (expand / 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,14 +1,14 @@ @@ -1,14 +1,14 @@
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.\"
@@ -25,31 +25,31 @@ @@ -25,31 +25,31 @@
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.
@@ -70,55 +70,54 @@ Users should never have to interact with @@ -70,55 +70,54 @@ Users 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
@@ -177,28 +176,29 @@ recover from this error by using the @@ -177,28 +176,29 @@ recover 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.