Penguin
Recent Changes
Annotated edit history of insmod(8) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 INSMOD
2 !!!INSMOD
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 SEE ALSO
7 BUGS
8 HISTORY
9 ----
10 !!NAME
11
12
13 insmod - install loadable kernel module
14 !!SYNOPSIS
15
16
17 __insmod__ [[-fhkLmnpqrsSvVxXyY] [[-e ''persist_name'']
18 [[-o ''module_name''] [[-O ''blob_name''] [[-P
19 ''prefix''] ''module'' [[ __symbol__=''value''
20 ... ]
21 !!DESCRIPTION
22
23
24 __insmod__ installs a loadable module in the running
25 kernel.
26
27
28 __insmod__ tries to link a module into the running kernel
29 by resolving all symbols from the kernel's exported symbol
30 table.
31
32
33 If the module file name is given without directories or
34 extension, __insmod__ will search for the module in some
35 common default directories. The environment variable
36 __MODPATH__ can be used to override this default. If a
37 module configuration file such as ''/etc/modules.conf''
38 exists, it will override the paths defined in
39 __MODPATH__.
40
41
42 The environment variable __MODULECONF__ can also be used
43 to select a different configuration file from the default
44 ''/etc/modules.conf'' (or ''/etc/conf.modules''
45 (deprecated)). This environment variable will override all
46 the definitions above.
47
48
49 __OPTIONS__
50
51
52 __-e__ ''persist_name'',
53 __--persist__=''persist_name''
54
55
56 Specifies where any persistent data for the module is read
57 from on load and written to when this instantiantion of the
58 module is unloaded. This option is silently ignored if the
59 module has no persistent data. Persistent data is only read
60 by __insmod__ if this option is present, by default
61 __insmod__ does not process persistent data.
62
63
64 As a shorthand form, __-e __ (an empty
65 string) is interpreted by __insmod__ as the value of
66 __persistdir__ as defined in ''modules.conf'',
67 followed by the filename of the module relative to the
68 module search path it was found in, minus any trailing
69 ''modules.conf__ specifies __persistdir
70 =____persistdir__ is an empty field) then
71 this shorthand form is silently ignored. (See
72 __modules.conf__ (5).)
73
74
75 __-f__, __--force__
76
77
78 Attempt load the module even if the version of the running
79 kernel and the version of the kernel for which the module
80 was compiled do not match. This only overrides the kernel
81 version check, it has no effect on symbol name checks. If
82 the symbol names in the module do not match the kernel then
83 there is no way to force __insmod__ to load the
84 module.
85
86
87 __-h__, __--help__
88
89
90 Display a summary of options and immediately
91 exit.
92
93
94 __-k__, __--autoclean__
95
96
97 Set the auto-clean flag on the module. This flag will be
98 used by kerneld(8) to remove modules that have not
99 been used in some period of time -- usually one
100 minute.
101
102
103 __-L__, __--lock__
104
105
106 Use flock(2) to prevent simultaneous loads of the
107 same module.
108
109
110 __-m__, __--map__
111
112
113 Output a load map on stdout, making it easier to debug the
114 module in the event of a kernel panic.
115
116
117 __-n__, __--noload__
118
119
120 Dummy run, do everything except load the module into the
121 kernel. If requested by an __-m__ or __-O__, the run
122 will produce a map or blob file. Since the module is not
123 loaded, the real kernel load address is unknown so the map
124 and blob file are based on an arbitrary load address of
125 0x12340000.
126
127
128 __-o__ ''module_name'',
129 __--name__=''module_name''
130
131
132 Explicitly name the module, rather than deriving the name
133 from the base name of the source object file.
134
135
136 __-O__ ''blob_name'',
137 __--blob__=''blob_name''
138
139
140 Save the binary object in ''blob_name''. The result is a
141 binary blob (no ELF headers) showing exactly what is loaded
142 into the kernel after section manipulation and relocation.
143 Option __-m__ is recommended to get a map of the
144 object.
145
146
147 __-p__, __--probe__
148
149
150 Probe the module to see if it could be successfully loaded.
151 This includes locating the object file in the module path,
152 checking version numbers, and resolving symbols. It does not
153 check the relocations nor does it produce a map or blob
154 file.
155
156
157 __-P__ ''prefix'',
158 __--prefix__=''prefix''
159
160
161 This option can be used with versioned modules for an SMP or
162 bigmem kernel, since such modules have an extra prefix added
163 in their symbol names. If the kernel was built with symbol
164 versions then __insmod__ will automatically extract the
165 prefix from the definition of
166 __-P__.
167
168
169 __-q__, __--quiet__
170
171
172 Do not print a list of any unresolved symbols. Do not
173 complain about version mismatch. The problem will only be
174 reflected in the exit status of __insmod__.
175
176
177 __-r__, __--root__
178
179
180 Some users compile modules under a non-root userid then
181 install the modules as root. This process can leave the
182 modules owned by the non-root userid, even though the
183 modules directory is owned by root. If the non-root userid
184 is compromised, an intruder can overwrite existing modules
185 owned by that userid and use this exposure to bootstrap up
186 to root access.
187
188
189 By default, modutils will reject attempts to use a module
190 that is not owned by root. Specifying -r will toggle the
191 check and allow root to load modules that are not owned by
192 root. __Note:__ the default value for root check can be
193 changed when modutils is configured.
194
195
196 __Use of -r to disable root checking or setting the default
197 to
198 __
199
200
201 __-s__, __--syslog__
202
203
204 Output everything to syslog(3) instead of the
205 terminal.
206
207
208 __-S__, __--kallsyms__
209
210
211 Force the loaded module to have __kallsyms__ data, even
212 if the kernel does not support it. This option is for small
213 systems where the kernel is loaded without __kallsyms__
214 data but selected modules need __kallsyms__ for
215 debugging.
216
217
218 __-v__, __--verbose__
219
220
221 Be verbose.
222
223
224 __-V__, __--version__
225
226
227 Display the version of __insmod__.
228
229
230 __-X__, __--export__; __-x__,
231 __--noexport__
232
233
234 Do and do not export all of the module's external symbols,
235 respectively. The default is for the symbols to be exported.
236 This option is only effective if the module does not
237 explicitly export its own controlled symbol table, and thus
238 is deprecated.
239
240
241 __-Y__, __--ksymoops__; __-y__,
242 __--noksymoops__
243
244
245 Do and do not add __ksymoops__ symbols to ksyms. These
246 symbols are used by __ksymoops__ to provide better
247 debugging if there is an Oops in this module. The default is
248 for the __ksymoops__ symbols to be defined. This option
249 is independent of the __-X__/__-x__
250 options.
251
252
253 __ksymoops__ symbols add approximately 260 bytes per
254 loaded module. Unless you are really short on kernel space
255 and are trying to reduce ksyms to its minimum size, take the
256 default and get more accurate Oops debugging.
257 __ksymoops__ symbols are required to save persistent
258 module data.
259
260
261 __MODULE PARAMETERS__
262
263
264 Some modules accept load-time parameters to customize their
265 operation. These parameters are often I/O port and IRQ
266 numbers that vary from machine to machine and cannot be
267 determined from the hardware.
268
269
270 In modules built for 2.0 series kernels, any integer or
271 character pointer symbol may be treated as a parameter and
272 modified. Beginning in the 2.1 series kernels, symbols are
273 explicitly marked as parameters so that only specific values
274 may be changed. Furthermore type information is provided for
275 checking the values provided at load time.
276
277
278 In the case of integers, all values may be in decimal, octal
279 or hexadecimal a la C: 17, 021 or 0x11. Array elements are
280 specified sequence separated by commas. Elements can be
281 skipped by omitting the value.
282
283
284 In 2.0 series modules, values that do not begin with a
285 number are considered strings. Beginning in 2.1, the
286 parameter's type information indicates whether to interpret
287 the value as a string. If the value begins with
288 double-quotes (____), the string is interpreted as
289 in C, escape sequences and all. Do note that from the shell
290 prompt, the quotes themselves may need to be protected from
291 shell interpretation.
292
293
294 __GPL LICENSED MODULES AND SYMBOLS__
295
296
297 Starting with kernel 2.4.10, modules should have a license
298 string, defined using __MODULE_LICENSE()__. Several
299 strings are recognised as being GPL compatible; any other
300 license string or no license at all means that the module is
301 treated as proprietary. See ''include/linux/module.h''
302 for a list of GPL compatible license strings.
303
304
305 If the kernel supports the ''/proc/sys/kernel/tainted''
306 flag then __insmod__ will OR the tainted flag with '1'
307 when loading a module without a GPL license. A warning is
308 issued if the kernel supports tainting and a module is
309 loaded without a license. A warning is always issued for
310 modules which have a __MODULE_LICENSE()__ that is not GPL
311 compatible, even on older kernels that do not support
312 tainting. This minimizes warnings when a new modutils is
313 used on older kernels.
314
315
316 __insmod -f__ (force) mode will OR the tainted flag with
317 '2' on kernels that support tainting. It always issues a
318 warning.
319
320
321 Some kernel developers require that symbols exported by
322 their code must only be used by modules with a GPL
323 compatible license. These symbols are exported by
324 __EXPORT_SYMBOL_GPL__ instead of the normal
325 __EXPORT_SYMBOL__. GPL-only symbols exported by the
326 kernel and by other modules are only visible to modules with
327 a GPL-compatible license, these symbols appear in
328 ''/proc/ksyms'' with a prefix of '__GPLONLY___'.
329 __insmod__ ignores the __GPLONLY___ prefix on symbols
330 while loading a GPL licensed module so the module just
331 refers to the normal symbol name, without the prefix. GPL
332 only symbols are not made available to modules without a GPL
333 compatible license, this includes modules with no license at
334 all.
335
336
337 __KSYMOOPS ASSISTANCE__
338
339
340 To assist with debugging of kernel Oops when using modules,
341 __insmod__ defaults to adding some symbols to ksyms, see
342 the __-Y__ option. These symbols start with
343 ____insmod_modulename___. The ''modulename'' is
344 required to make the symbols unique. It is legal to load the
345 same object more than once under different module names.
346 Currently defined symbols are:
347
348
349 ____insmod_modulename_Oobjectfile_Mmtime_Vversion__
350
351
352 ''objectfile'' is the name of the file that the object
353 was loaded from. This ensures that ksymoops can match the
354 code to the correct object. ''mtime'' is the last
355 modified timestamp on that file in hex, zero if stat failed.
356 ''version'' is the kernel version that the module was
357 compiled for, -1 if no version is available. The ___O__
358 symbol has the same start address as the module
359 header.
360
361
362 ____insmod_modulename_Ssectionname_Llength__
363
364
365 This symbol appears at the start of selected ELF sections,
366 currently .text, .rodata, .data and .bss. It only appears if
367 the section has a non-zero size. ''sectionname'' is the
368 name of the ELF section, ''length'' is the length of the
369 section in decimal. These symbols help ksymoops map
370 addresses to sections when no symbols are
371 available.
372
373
374 ____insmod_modulename_Ppersistent_filename__
375
376
377 Only created by __insmod__ if the module has one or more
378 parameters that are marked as persistent data and a filename
379 to save persistent data (see __-e__, above) is
380 available.
381
382
383 The other problem with debugging kernel Oops in modules is
384 that the contents of ''/proc/ksyms'' and
385 ''/proc/modules'' can change between the Oops and when
386 you process the log file. To help overcome this problem, if
387 the directory ''/var/log/ksymoops'' exists then
388 __insmod__ and __rmmod__ will automatically copy
389 ''/proc/ksyms'' and ''/proc/modules'' to
390 ''/var/log/ksymoops'' with a prefix of `date
391 +%Y%m%d%H%M%S`. The system administrator can tell
392 __ksymoops__ which snapshot files to use when debugging
393 an Oops. There is no switch to disable this automatic copy.
394 If you do not want it to occur, do not create
395 ''/var/log/ksymoops''. If that directory exists, it
396 should be owned by root and be mode 644 or 600 and you
397 should run this script every day or so. The script below is
398 installed as __insmod_ksymoops_clean__.
399
400
401 #!/bin/sh
402 # Delete saved ksyms and modules not accessed in 2 days
403 if [[ -d /var/log/ksymoops ]
404 then
405 set -e
406 # Make sure there is always at least one version
407 d=`date +%Y%m%d%H%M%S`
408 cp -a /proc/ksyms /var/log/ksymoops/${d}.ksyms
409 cp -a /proc/modules /var/log/ksymoops/${d}.modules
410 find /var/log/ksymoops -type f -atime +2 -exec rm {} ;
411 fi
412 !!SEE ALSO
413
414
415 rmmod(8), modprobe(8), depmod(8),
416 lsmod(8), ksyms(8), modules(2),
417 genksyms(8), kerneld(8),
418 __ksymoops__(kernel).
419 !!BUGS
420
421
422 __insmod__ [[__-V__ | __--version__] should display
423 version information and then exit immediately. Instead, it
424 prints the version information and behaves as if no options
425 were given.
426 !!HISTORY
427
428
429 Module support was first conceived by Anonymous
430 Initial Linux version by Bas Laarhoven
431 Version 0.99.14 by Jon Tombs
432 Extended by Bjorn Ekwall
433 Original ELF help from Eric Youngdale
434 Rewritten for 2.1.17 by Richard Henderson
435 Extended by Bjorn Ekwall
436 Assistance for ksymoops by Keith Owens
437 Maintainer: Keith Owens
438 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.