INSMOD(8) Linux Module Support INSMOD(8) NNAAMMEE insmod - install loadable kernel module SSYYNNOOPPSSIISS iinnssmmoodd [-fhkLmnpqrsSvVxXyY] [-e persist_name] [-o module_name] [-O blob_name] [-P prefix] module [ symbol=value ... ] DDEESSCCRRIIPPTTIIOONN iinnssmmoodd installs a loadable module in the running kernel. iinnssmmoodd tries to link a module into the running kernel by resolving all symbols from the kernel's exported symbol table. If the module file name is given without directories or extension, iinnssmmoodd will search for the module in some common default directories. The environment variable MODPATH can be used to override this default. If a module configuration file such as /etc/modules.conf exists, it will override the paths defined in MODPATH. The environment variable MODULECONF can also be used to select a different configuration file from the default /etc/modules.conf (or /etc/conf.modules (deprecated)). This environment variable will override all the definitions above. OOPPTTIIOONNSS _-_f _-_-_f_o_r_c_e Attempt load the module even if the version of the running kernel and the version of the kernel for which the module was compiled do not match. This only overrides the kernel version check, it has no effect on symbol name checks. If the symbol names in the module do not match the kernel then there is no way to force _i_n_s_m_o_d to load the module. _-_h _-_-_h_e_l_p Print the help text. _-_k _-_-_a_u_t_o_c_l_e_a_n Set the auto-clean flag on the module. This flag will be used by kkeerrnneelldd(8) to remove modules that have not been used in some period of time -- usually one minute. _-_L _-_-_l_o_c_k Use fflloocckk(2) to prevent simultaneous loads of the same module. _-_m _-_-_m_a_p Output a load map on stdout, making it easier to debug the module in the event of a kernel panic. Linux November 10 2000 1 INSMOD(8) Linux Module Support INSMOD(8) _-_n _-_-_n_o_l_o_a_d Dummy run, do everything except load the module into the kernel. If requested by _-_m or _-_O, the run will produce a map or blob file. Since the module is not loaded, the real kernel load address is unknown so the map and blob file are based on an arbitrary load address of 0x12340000. _-_p _-_-_p_r_o_b_e Probe the module to see if it could be successfully loaded. This includes locating the object file in the module path, checking version numbers, and resolving symbols. It does not check the relocations nor does it produce a map or blob file. _-_q _-_-_q_u_i_e_t Do not print a list of any unresolved symbols. Do not complain about version mismatch. The problem will only be reflected in the exit status of _i_n_s_m_o_d. _-_r _-_-_r_o_o_t Some users compile modules under a non-root userid then install the modules as root. This process can leave the modules owned by the non-root userid, even though the modules directory is owned by root. If the non-root userid is compromised, an intruder can overwrite existing modules owned by that userid and use this exposure to bootstrap up to root access. By default, modutils will reject attempts to use a module that is not owned by root. Specifying -r will toggle the check and allow root to load modules that are not owned by root. NNoottee:: the default value for root check can be changed when modutils is configured. UUssee ooff _-_r ttoo ddiissaabbllee rroooott cchheecckkiinngg oorr sseettttiinngg tthhee ddeeffaauulltt ttoo ""nnoo rroooott cchheecckk"" aatt ccoonnffiigguurraattiioonn ttiimmee iiss aa mmaajjoorr sseeccuurriittyy eexxppoossuurree aanndd iiss nnoott rreeccoommmmeennddeedd.. _-_s _-_-_s_y_s_l_o_g Output everything to ssyysslloogg(3) instead of the terminal. _-_S _-_-_k_a_l_l_s_y_m_s Force the loaded module to have kallsyms data, even if the kernel does not support it. This option is for small systems where the kernel is loaded without kallsyms data but selected modules need kallsyms for debugging. Linux November 10 2000 2 INSMOD(8) Linux Module Support INSMOD(8) _-_v _-_-_v_e_r_b_o_s_e Be verbose. _-_X _-_-_e_x_p_o_r_t_, _-_x _-_-_n_o_e_x_p_o_r_t Do and do not export all of the module's external symbols, respectively. The default is for the symbols to be exported. This option is only effective if the module does not explicitly export its own controlled symbol table, and thus is deprecated. _-_Y _-_-_k_s_y_m_o_o_p_s_, _-_y _-_-_n_o_k_s_y_m_o_o_p_s Do and do not add ksymoops symbols to ksyms. These symbols are used by ksymoops to provide better debugging if there is an Oops in this module. The default is for the ksymoops symbols to be defined. This option is independent of the -X/-x options. ksymoops symbols add approximately 260 bytes per loaded module. Unless you are really short on kernel space and are trying to reduce ksyms to its minimum size, take the default and get more accurate Oops debugging. ksymoops symbols are required to save persistent module data. _-_o module_name _-_-_n_a_m_e=module_name Explicitly name the module, rather than deriving the name from the base name of the source object file. _-_O blob_name _-_-_b_l_o_b=blob_name Save the binary object in _b_l_o_b___n_a_m_e. The result is a binary blob (no ELF headers) showing exactly what is loaded into the kernel, after section manipulation and relocation. Option _-_m is recommended to get a map of the object. _-_P prefix _-_-_p_r_e_f_i_x=prefix This option can be used with versioned modules for an SMP or bigmem kernel, since such modules have an extra prefix added in their symbol names. If the kernel was built with symbol versions then _i_n_s_m_o_d will automatically extract the prefix from the definition of "get_module_symbol" or "inter_module_get", one of which must exist in any kernel that supports modules. If the kernel has no symbol versions but the module was built with symbol versions then the user must supply -P. _-_e persist_name _-_-_p_e_r_s_i_s_t=persist_name Specifies where any persistent data for the module is read from on load and written to when this instantiantion of the module is unloaded. This option is silently ignored if the module has no Linux November 10 2000 3 INSMOD(8) Linux Module Support INSMOD(8) persistent data. Persistent data is only read by _i_n_s_m_o_d if this option is present, by default _i_n_s_m_o_d does not process persistent data. As a shorthand form, _-_e "" (an empty string) is interpreted by _i_n_s_m_o_d as the value of _p_e_r_s_i_s_t_d_i_r (see mmoodduulleess..ccoonnff(5)) followed by the filename of the module, relative to the module search path it was found in, minus any trailing '.gz', '.o' and '.mod'. If you specify _p_e_r_s_i_s_t_d_i_r= (i.e. persistdir is an empty field) then this shorthand form is silently ignored. MMOODDUULLEE PPAARRAAMMEETTEERRSS Some modules accept load-time parameters to customize their operation. These parameters are often I/O port and IRQ numbers that vary from machine to machine and cannot be determined from the hardware. In modules built for 2.0 series kernels, any integer or character pointer symbol may be treated as a parameter and modified. Beginning in the 2.1 series kernels, symbols are explicitly marked as parameters so that only specific values may be changed. Furthermore type information is provided for checking the values provided at load time. In the case of integers, all values may be in decimal, octal or hexadecimal a la C: 17, 021 or 0x11. Array elements are specified sequence separated by commas; elements can be skipped by omitting the value. In 2.0 series modules, values that do not begin with a number are considered strings. Beginning in 2.1, the parameter's type information indicates whether to interpret the value as a string. If the value begins with double-quotes (_"), the string is interpreted as in C, escape sequences and all. Do note that from the shell prompt, the quotes themselves may need to be protected from shell interpretation. KKSSYYMMOOOOPPSS AASSSSIISSTTAANNCCEE To assist with debugging of kernel Oops when using modules, insmod defaults to adding some symbols to ksyms, see the --YY option. These symbols start with ____iinnssmmoodd___m_o_d_u_l_e_n_a_m_e__. The _m_o_d_u_l_e_n_a_m_e is required to make the symbols unique, it is legal to load the same object more than once under different module names. Currently defined symbols are __insmod__m_o_d_u_l_e_n_a_m_e_O_o_b_j_e_c_t_f_i_l_e_M_m_t_i_m_e_V_v_e_r_s_i_o_n _o_b_j_e_c_t_f_i_l_e is the name of the file that the object was loaded from. This ensures that ksymoops can match the code to the correct object. _m_t_i_m_e is the last modified timestamp on that file in hex, zero if stat failed. Linux November 10 2000 4 INSMOD(8) Linux Module Support INSMOD(8) _v_e_r_s_i_o_n is the kernel version that the module was compiled for, -1 if no version is available. The _O symbol has the same start address as the module header. __insmod__m_o_d_u_l_e_n_a_m_e_S_s_e_c_t_i_o_n_n_a_m_e_L_l_e_n_g_t_h This symbol appears at the start of selected ELF sections, currently .text, .rodata, .data and .bss. It only appears if the section has a non-zero size. _s_e_c_t_i_o_n_n_a_m_e is the name of the ELF section, _l_e_n_g_t_h is the length of the section in decimal. These symbols help ksymoops map addresses to sections when no symbols are available. __insmod__m_o_d_u_l_e_n_a_m_e_P_p_e_r_s_i_s_t_e_n_t___f_i_l_e_n_a_m_e Only created by insmod if the module has one or more parameters that are marked as persistent data and a filename to save persistent data (see _-_e above) is available. The other problem with debugging kernel Oops in modules is that the contents of /proc/ksyms and /proc/modules can change between the Oops and when you process the log file. To help overcome this problem, if directory /var/log/ksymoops exists then insmod and rmmod will automatically copy /proc/ksyms and /proc/modules to /var/log/ksymoops with a prefix of `date +%Y%m%d%H%M%S`. The system administrator can tell ksymoops which snapshot files to use when debugging an Oops. There is no switch to disable this automatic copy, if you do not want it to occur, do not create /var/log/ksymoops. If that directory exists, it should be owned by root and be mode 644 or 600 and you should run this script every day or so. The script below is installed as insmod_ksymoops_clean. #!/bin/sh # Delete saved ksyms and modules not accessed in 2 days if [ -d /var/log/ksymoops ] then set -e # Make sure there is always at least one version d=`date +%Y%m%d%H%M%S` cp -a /proc/ksyms /var/log/ksymoops/${d}.ksyms cp -a /proc/modules /var/log/ksymoops/${d}.modules find /var/log/ksymoops -type f -atime +2 -exec rm {} \; fi SSEEEE AALLSSOO rrmmmmoodd(8), mmooddpprroobbee(8), ddeeppmmoodd(8), llssmmoodd(8), kkssyymmss(8), mmoodduulleess(2), ggeennkkssyymmss(8), kkeerrnneelldd(8), kkssyymmooooppss(kernel). HHIISSTTOORRYY Module support was first conceived by Anonymous Initial Linux version by Bas Laarhoven Linux November 10 2000 5 INSMOD(8) Linux Module Support INSMOD(8) Version 0.99.14 by Jon Tombs Extended by Bjorn Ekwall Original ELF help from Eric Youngdale Rewritten for 2.1.17 by Richard Henderson Extended by Bjorn Ekwall for modutils-2.2.*, March 1999 Assistance for ksymoops by Keith Owens , May 1999 Maintainer: Keith Owens . Linux November 10 2000 6