Difference between revisions of "Kernel modules"

From ArchWiki
Jump to: navigation, search
m (Using files in /etc/modprobe.d/: fix wording)
(Automatic module handling: use man template)
 
(58 intermediate revisions by 24 users not shown)
Line 5: Line 5:
 
[[fr:Kernel modules]]
 
[[fr:Kernel modules]]
 
[[it:Kernel modules]]
 
[[it:Kernel modules]]
[[ja:Kernel modules]]
+
[[ja:カーネルモジュール]]
 +
[[ru:Kernel modules]]
 
[[zh-CN:Kernel modules]]
 
[[zh-CN:Kernel modules]]
{{Article summary start}}
+
{{Related articles start}}
{{Article summary text|This article covers the various methods for operating with kernel modules.}}
+
{{Related|Boot debugging}}
{{Article summary heading|Related}}
+
{{Related|Kernels}}
{{Article summary wiki|Boot Debugging}}
+
{{Related|Kernel parameters}}
{{Article summary wiki|Kernels}}
+
{{Related|Compile kernel module}}
{{Article summary wiki|Kernel parameters}}
+
{{Related articles end}}
{{Article summary heading|Resources}}
+
{{Article summary link|modprobe man page|http://linuxmanpages.com/man5/modprobe.conf.5.php}}
+
{{Article summary end}}
+
  
 
[[Wikipedia:Loadable_kernel_module|Kernel modules]] are pieces of code that can be loaded and unloaded into the kernel upon demand. They extend the functionality of the kernel without the need to reboot the system.  
 
[[Wikipedia:Loadable_kernel_module|Kernel modules]] are pieces of code that can be loaded and unloaded into the kernel upon demand. They extend the functionality of the kernel without the need to reboot the system.  
  
== Overview ==
+
To create a kernel module, you can read [http://tldp.org/LDP/lkmpg/2.6/html/index.html The Linux Kernel Module Programming Guide]. A module can be configured as built-in or loadable. To dynamically load or remove a module, it has to be configured as a loadable module in the kernel configuration (the line related to the module will therefore display the letter {{ic|M}}).
  
To create a kernel module, you can read [http://tldp.org/LDP/lkmpg/2.6/html/index.html this guide]. A module can be configured to be build-in or loadable. To dynamically load or remove a module, it has to be configured as a loadable module in the kernel configuration (the line related to the module will therefore display the letter {{ic|M}}).
+
== Obtaining information ==
  
 
Modules are stored in {{ic|/usr/lib/modules/''kernel_release''}}. You can use the command {{ic|uname -r}} to get your current kernel release version.
 
Modules are stored in {{ic|/usr/lib/modules/''kernel_release''}}. You can use the command {{ic|uname -r}} to get your current kernel release version.
  
{{Note|Module names often use underscores ({{ic|_}}) or dashes ({{ic|-}}), however those symbols are interchangeable both when using the {{ic|modprobe}} command and in configuration files in {{ic|/etc/modprobe.d/}}.}}
+
{{Note|Module names often use underscores ({{ic|_}}) or dashes ({{ic|-}}); however, those symbols are interchangeable, both when using the {{ic|modprobe}} command and in configuration files in {{ic|/etc/modprobe.d/}}.}}
 
+
== Obtaining information ==
+
  
 
To show what kernel modules are currently loaded:
 
To show what kernel modules are currently loaded:
Line 53: Line 49:
 
  $ modprobe --show-depends ''module_name''
 
  $ modprobe --show-depends ''module_name''
  
== Loading ==
+
== Automatic module handling ==
  
The {{ic|/sbin/modprobe}} command handles the addition and removal of modules from the Linux kernel.
+
Today, all necessary modules loading is handled automatically by [[udev]], so if you do not need to use any out-of-tree kernel modules, there is no need to put modules that should be loaded at boot in any configuration file. However, there are cases where you might want to load an extra module during the boot process, or blacklist another one for your computer to function properly.
To manually load (or add) a module, run:
+
  
# modprobe ''module_name''
+
Kernel modules can be explicitly loaded during boot and are configured as a static list in files under {{ic|/etc/modules-load.d/}}. Each configuration file is named in the style of {{ic|/etc/modules-load.d/<program>.conf}}. Configuration files simply contain a list of kernel modules names to load, separated by newlines. Empty lines and lines whose first non-whitespace character is {{ic|#}} or {{ic|;}} are ignored.
 
+
Most modules should be loaded on-demand. Modules to be unconditionally loaded at boot can be specified in {{ic|/etc/modules-load.d/}}, for example:
+
  
 
{{hc|/etc/modules-load.d/virtio-net.conf|
 
{{hc|/etc/modules-load.d/virtio-net.conf|
#Load 'virtio-net.ko' at boot.
+
# Load virtio-net.ko at boot
 
+
 
virtio-net}}
 
virtio-net}}
  
== Removal ==
+
See {{man|5|modules-load.d}} for more details.
 +
 
 +
== Manual module handling ==
 +
 
 +
Kernel modules are handled by tools provided by {{Pkg|kmod}} package. You can use these tools manually.
 +
 
 +
{{Note|If you have upgraded your kernel but have not yet rebooted, ''modprobe'' will fail with no error message and exit with code 1, because the path {{ic|/lib/modules/$(uname -r)/}} no longer exists. Check manually if this path exists when ''modprobe'' failed to determine if this is the case.}}
 +
 
 +
To load a module:
 +
 
 +
# modprobe ''module_name''
 +
 
 +
To load a module by filename (i.e. one that is not installed in {{ic|/lib/modules/$(uname -r)/}}):
 +
 
 +
# insmod filename [args]
  
Occasionally you could need to remove (or unload) a module; in this case use the following command:
+
To unload a module:
  
 
  # modprobe -r ''module_name''
 
  # modprobe -r ''module_name''
Line 77: Line 83:
 
  # rmmod ''module_name''
 
  # rmmod ''module_name''
  
== Configuration ==
+
== Setting module options ==
  
To pass a parameter to a kernel module you can use a modprobe conf file or use the kernel command line. See also [[Systemd#Kernel_modules]].
+
To pass a parameter to a kernel module, you can pass them manually with modprobe or assure certain parameters are always applied using a modprobe configuration file or by using the kernel command line.
 +
 
 +
=== Manually at load time using modprobe ===
 +
 
 +
The basic way to pass parameters to a module is using the modprobe command. Parameters are specified on command line using simple {{ic|1=''key=value''}} assignments:
 +
 
 +
# modprobe ''module_name parameter_name=parameter_value''
  
 
=== Using files in /etc/modprobe.d/ ===
 
=== Using files in /etc/modprobe.d/ ===
  
The {{ic|/etc/modprobe.d/}} directory can be used to pass module settings to [[udev]], which will use {{ic|modprobe}} to manage the loading of the modules during system boot. You can use configuration files with any name in the directory, given that they end with the {{ic|.conf}} extension. The syntax is:
+
Files in {{ic|/etc/modprobe.d/}} directory can be used to pass module settings to [[udev]], which will use {{ic|modprobe}} to manage the loading of the modules during system boot. Configuration files in this directory can have any name, given that they end with the {{ic|.conf}} extension. The syntax is:
 +
 
 
{{hc|/etc/modprobe.d/myfilename.conf|2=
 
{{hc|/etc/modprobe.d/myfilename.conf|2=
options modname parametername=parametercontents}}
+
options ''module_name parameter_name=parameter_value''}}
  
 
For example:
 
For example:
  
 
{{hc|/etc/modprobe.d/thinkfan.conf|2=
 
{{hc|/etc/modprobe.d/thinkfan.conf|2=
#On Thinkpads, this lets the 'thinkfan' daemon control fan speed.
+
# On ThinkPads, this lets the 'thinkfan' daemon control fan speed
 
+
 
options thinkpad_acpi fan_control=1}}
 
options thinkpad_acpi fan_control=1}}
  
{{Note|If any of the modules affected are loaded while booting (from the init ramdisk) then you will need to add the appropriate {{ic|.conf}}-file to FILES in [[mkinitcpio.conf]].}}
+
{{Note|If any of the affected modules is loaded from the initramfs, then you will need to add the appropriate {{ic|.conf}} file to {{ic|FILES}} in [[mkinitcpio.conf]] or use the {{ic|modconf}} [[Mkinitcpio.conf#HOOKS|hook]], so that it will be included in the initramfs. To see the contents of the default initramfs use {{ic|lsinitcpio /boot/initramfs-linux.img}}.}}
  
 
=== Using kernel command line ===
 
=== Using kernel command line ===
  
If the module is built into the kernel you can also pass options to the module using the kernel command line. For all common Bootloaders the following syntax is correct:
+
If the module is built into the kernel, you can also pass options to the module using the kernel command line. For all common bootloaders, the following syntax is correct:
  
  modname.parametername=parametercontents
+
  ''module_name.parameter_name=parameter_value''
  
for example:
+
For example:
  
 
  thinkpad_acpi.fan_control=1
 
  thinkpad_acpi.fan_control=1
  
Simply add this to your bootloaders kernel-line as described in [[Kernel_parameters#When_starting_the_kernel|Kernel Parameters]].
+
Simply add this to your bootloader's kernel-line, as described in [[Kernel parameters|Kernel Parameters]].
  
 
== Aliasing ==
 
== Aliasing ==
  
Aliases are alternate names for a module. For example: "alias my-mod really_long_modulename" means you can use "modprobe my-mod" instead of "modprobe really_long_modulename". You can also use shell-style wildcards, so "alias my-mod* really_long_modulename" means that "modprobe my-mod-something" has the same effect. Create an alias:
+
Aliases are alternate names for a module. For example: {{ic|alias my-mod really_long_modulename}} means you can use {{ic|modprobe my-mod}} instead of {{ic|modprobe really_long_modulename}}. You can also use shell-style wildcards, so {{ic|alias my-mod* really_long_modulename}} means that {{ic|modprobe my-mod-something}} has the same effect. Create an alias:
  
 
{{hc|/etc/modprobe.d/myalias.conf|
 
{{hc|/etc/modprobe.d/myalias.conf|
alias mymod ''really_long_module_name''}}
+
alias mymod really_long_module_name}}
  
Some modules have aliases which are used to autoload them when they are needed by an application. Disabling these aliases can prevent auto-loading, but will still allow the modules to be manually loaded.
+
Some modules have aliases which are used to automatically load them when they are needed by an application. Disabling these aliases can prevent automatic loading but will still allow the modules to be manually loaded.
  
 
{{hc|/etc/modprobe.d/modprobe.conf|
 
{{hc|/etc/modprobe.d/modprobe.conf|
#Prevent Bluetooth autoload.
+
# Prevent Bluetooth autoload
 
+
 
alias net-pf-31 off}}
 
alias net-pf-31 off}}
  
Line 126: Line 137:
 
Blacklisting, in the context of kernel modules, is a mechanism to prevent the kernel module from loading. This could be useful if, for example, the associated hardware is not needed, or if loading that module causes problems: for instance there may be two kernel modules that try to control the same piece of hardware, and loading them together would result in a conflict.
 
Blacklisting, in the context of kernel modules, is a mechanism to prevent the kernel module from loading. This could be useful if, for example, the associated hardware is not needed, or if loading that module causes problems: for instance there may be two kernel modules that try to control the same piece of hardware, and loading them together would result in a conflict.
  
Some modules are loaded as part of the [[initramfs]]. {{ic|mkinitcpio -M}} will print out all autodetected modules: to prevent the initramfs from loading some of those modules, blacklist them in {{ic|/etc/modprobe.d/modprobe.conf}}. Running {{ic|mkinitcpio -v}} will list all modules pulled in by the various hooks (e.g. filesystem hook, SCSI hook, etc.). Remember to add that {{ic|.conf}} file to the FILES section in {{ic|/etc/mkinitcpio.conf}} (if you have not done so already) and rebuild the initramfs once you have blacklisted the modules, and to reboot afterwards.
+
Some modules are loaded as part of the [[initramfs]]. {{ic|mkinitcpio -M}} will print out all automatically detected modules: to prevent the initramfs from loading some of those modules, blacklist them in {{ic|/etc/modprobe.d/modprobe.conf}}. Running {{ic|mkinitcpio -v}} will list all modules pulled in by the various hooks (e.g. {{ic|filesystems}} hook, {{ic|block}} hook, etc.). Remember to add that {{ic|.conf}} file to the {{ic|FILES}} section in {{ic|/etc/mkinitcpio.conf}}, if you have not done so already, and rebuild the initramfs once you have blacklisted the modules, and reboot afterwards.
  
 
=== Using files in /etc/modprobe.d/ ===
 
=== Using files in /etc/modprobe.d/ ===
Line 133: Line 144:
  
 
{{hc|/etc/modprobe.d/nobeep.conf|
 
{{hc|/etc/modprobe.d/nobeep.conf|
#Do not load the 'pcspkr' module on boot.
+
# Do not load the 'pcspkr' module on boot.
 
+
 
blacklist pcspkr}}
 
blacklist pcspkr}}
  
Line 154: Line 164:
 
You can also blacklist modules from the bootloader.
 
You can also blacklist modules from the bootloader.
  
Simply add {{ic|1=modprobe.blacklist=modname1,modname2,modname3}} to your bootloader's kernel line, as described in [[Kernel_parameters#When_starting_the_kernel|Kernel Parameters]].
+
Simply add {{ic|1=modprobe.blacklist=modname1,modname2,modname3}} to your bootloader's kernel line, as described in [[Kernel parameters]].
  
 
{{Note|When you are blacklisting more than one module, note that they are separated by commas only. Spaces or anything else might presumably break the syntax.}}
 
{{Note|When you are blacklisting more than one module, note that they are separated by commas only. Spaces or anything else might presumably break the syntax.}}
  
== Tips and tricks ==
+
== Troubleshooting ==
 
+
=== Bash function to list module parameters ===
+
 
+
Here is a nice bash function to be run as root that will show a list of all the currently loaded modules and all of their parameters, including the current value of the parameter.  It uses {{ic|/proc/modules}} to retrieve the current list of loaded modules, then access the module file directly with modinfo to grab a description of the module and descriptions for each param (if available), finally it accesses the sysfs filesystem to grab the actual parameter names and currently loaded values.
+
 
+
{{bc|<nowiki>
+
function aa_mod_parameters ()
+
{
+
    N=/dev/null;
+
    C=`tput op` O=$(echo -en "\n`tput setaf 2`>>> `tput op`");
+
    for mod in $(cat /proc/modules|cut -d" " -f1);
+
    do
+
        md=/sys/module/$mod/parameters;
+
        [[ ! -d $md ]] && continue;
+
        m=$mod;
+
        d=`modinfo -d $m 2>$N | tr "\n" "\t"`;
+
        echo -en "$O$m$C";
+
        [[ ${#d} -gt 0 ]] && echo -n " - $d";
+
        echo;
+
        for mc in $(cd $md; echo *);
+
        do
+
            de=`modinfo -p $mod 2>$N | grep ^$mc 2>$N|sed "s/^$mc=//" 2>$N`;
+
            echo -en "\t$mc=`cat $md/$mc 2>$N`";
+
            [[ ${#de} -gt 1 ]] && echo -en " - $de";
+
            echo;
+
        done;
+
    done
+
}</nowiki>}}
+
 
+
Here is some sample output:
+
  
{{hc|# aa_mod_parameters|2=
+
=== Modules do not load ===
>>> ehci_hcd - USB 2.0 'Enhanced' Host Controller (EHCI) Driver
+
        hird=0 - hird:host initiated resume duration, +1 for each 75us (int)
+
        ignore_oc=N - ignore_oc:ignore bogus hardware overcurrent indications (bool)
+
        log2_irq_thresh=0 - log2_irq_thresh:log2 IRQ latency, 1-64 microframes (int)
+
        park=0 - park:park setting; 1-3 back-to-back async packets (uint)
+
  
>>> processor - ACPI Processor Driver
+
In case a specific module does not load and the boot log (accessible with {{ic|journalctl -b}}) says that the module is blacklisted, but the directory {{ic|/etc/modprobe.d/}} does not show a corresponding entry, check another modprobe source folder at {{ic|/usr/lib/modprobe.d/}} for blacklisting entries.
        ignore_ppc=-1 - ignore_ppc:If the frequency of your machine gets wronglylimited by BIOS, this should help (int)
+
        ignore_tpc=0 - ignore_tpc:Disable broken BIOS _TPC throttling support (int)
+
        latency_factor=2 - latency_factor: (uint)
+
  
>>> usb_storage - USB Mass Storage driver for Linux
+
A module will not be loaded if the "vermagic" string contained within the kernel module does not match the value of the currently running kernel. If it is known that the module is compatible with the current running kernel the "vermagic" check can be ignored with {{ic|modprobe --force-vermagic}}.
        delay_use=1 - delay_use:seconds to delay before using a new device (uint)
+
        option_zero_cd=1 - option_zero_cd:ZeroCD mode (1=Force Modem (default), 2=Allow CD-Rom (uint)
+
        quirks= - quirks:supplemental list of device IDs and their quirks (string)
+
        swi_tru_install=1 - swi_tru_install:TRU-Install mode (1=Full Logic (def), 2=Force CD-Rom, 3=Force Modem) (uint)
+
  
>>> video - ACPI Video Driver
+
{{warning|Ignoring the version checks for a kernel module can cause a kernel to crash or a system to exhibit undefined behavior due to incompatibility. Use {{ic|--force-vermagic}} only with the utmost caution.}}
        allow_duplicates=N - allow_duplicates: (bool)
+
        brightness_switch_enabled=Y - brightness_switch_enabled: (bool)
+
        use_bios_initial_backlight=Y - use_bios_initial_backlight: (bool)}}
+
  
 
== See also ==
 
== See also ==
  
*[[Disable PC Speaker Beep]]
+
* [[Disable PC speaker beep]]
 +
* [https://lwn.net/Articles/391230/ Writing a WMI driver] - an LWM introduction

Latest revision as of 11:23, 8 August 2016

Kernel modules are pieces of code that can be loaded and unloaded into the kernel upon demand. They extend the functionality of the kernel without the need to reboot the system.

To create a kernel module, you can read The Linux Kernel Module Programming Guide. A module can be configured as built-in or loadable. To dynamically load or remove a module, it has to be configured as a loadable module in the kernel configuration (the line related to the module will therefore display the letter M).

Obtaining information

Modules are stored in /usr/lib/modules/kernel_release. You can use the command uname -r to get your current kernel release version.

Note: Module names often use underscores (_) or dashes (-); however, those symbols are interchangeable, both when using the modprobe command and in configuration files in /etc/modprobe.d/.

To show what kernel modules are currently loaded:

$ lsmod

To show information about a module:

$ modinfo module_name

To list the options that are set for a loaded module:

$ systool -v -m module_name

To display the comprehensive configuration of all the modules:

$ modprobe -c | less

To display the configuration of a particular module:

$ modprobe -c | grep module_name

List the dependencies of a module (or alias), including the module itself:

$ modprobe --show-depends module_name

Automatic module handling

Today, all necessary modules loading is handled automatically by udev, so if you do not need to use any out-of-tree kernel modules, there is no need to put modules that should be loaded at boot in any configuration file. However, there are cases where you might want to load an extra module during the boot process, or blacklist another one for your computer to function properly.

Kernel modules can be explicitly loaded during boot and are configured as a static list in files under /etc/modules-load.d/. Each configuration file is named in the style of /etc/modules-load.d/<program>.conf. Configuration files simply contain a list of kernel modules names to load, separated by newlines. Empty lines and lines whose first non-whitespace character is # or ; are ignored.

/etc/modules-load.d/virtio-net.conf
# Load virtio-net.ko at boot
virtio-net

See modules-load.d(5) for more details.

Manual module handling

Kernel modules are handled by tools provided by kmod package. You can use these tools manually.

Note: If you have upgraded your kernel but have not yet rebooted, modprobe will fail with no error message and exit with code 1, because the path /lib/modules/$(uname -r)/ no longer exists. Check manually if this path exists when modprobe failed to determine if this is the case.

To load a module:

# modprobe module_name

To load a module by filename (i.e. one that is not installed in /lib/modules/$(uname -r)/):

# insmod filename [args]

To unload a module:

# modprobe -r module_name

Or, alternatively:

# rmmod module_name

Setting module options

To pass a parameter to a kernel module, you can pass them manually with modprobe or assure certain parameters are always applied using a modprobe configuration file or by using the kernel command line.

Manually at load time using modprobe

The basic way to pass parameters to a module is using the modprobe command. Parameters are specified on command line using simple key=value assignments:

# modprobe module_name parameter_name=parameter_value

Using files in /etc/modprobe.d/

Files in /etc/modprobe.d/ directory can be used to pass module settings to udev, which will use modprobe to manage the loading of the modules during system boot. Configuration files in this directory can have any name, given that they end with the .conf extension. The syntax is:

/etc/modprobe.d/myfilename.conf
options module_name parameter_name=parameter_value

For example:

/etc/modprobe.d/thinkfan.conf
# On ThinkPads, this lets the 'thinkfan' daemon control fan speed
options thinkpad_acpi fan_control=1
Note: If any of the affected modules is loaded from the initramfs, then you will need to add the appropriate .conf file to FILES in mkinitcpio.conf or use the modconf hook, so that it will be included in the initramfs. To see the contents of the default initramfs use lsinitcpio /boot/initramfs-linux.img.

Using kernel command line

If the module is built into the kernel, you can also pass options to the module using the kernel command line. For all common bootloaders, the following syntax is correct:

module_name.parameter_name=parameter_value

For example:

thinkpad_acpi.fan_control=1

Simply add this to your bootloader's kernel-line, as described in Kernel Parameters.

Aliasing

Aliases are alternate names for a module. For example: alias my-mod really_long_modulename means you can use modprobe my-mod instead of modprobe really_long_modulename. You can also use shell-style wildcards, so alias my-mod* really_long_modulename means that modprobe my-mod-something has the same effect. Create an alias:

/etc/modprobe.d/myalias.conf
alias mymod really_long_module_name

Some modules have aliases which are used to automatically load them when they are needed by an application. Disabling these aliases can prevent automatic loading but will still allow the modules to be manually loaded.

/etc/modprobe.d/modprobe.conf
# Prevent Bluetooth autoload
alias net-pf-31 off

Blacklisting

Blacklisting, in the context of kernel modules, is a mechanism to prevent the kernel module from loading. This could be useful if, for example, the associated hardware is not needed, or if loading that module causes problems: for instance there may be two kernel modules that try to control the same piece of hardware, and loading them together would result in a conflict.

Some modules are loaded as part of the initramfs. mkinitcpio -M will print out all automatically detected modules: to prevent the initramfs from loading some of those modules, blacklist them in /etc/modprobe.d/modprobe.conf. Running mkinitcpio -v will list all modules pulled in by the various hooks (e.g. filesystems hook, block hook, etc.). Remember to add that .conf file to the FILES section in /etc/mkinitcpio.conf, if you have not done so already, and rebuild the initramfs once you have blacklisted the modules, and reboot afterwards.

Using files in /etc/modprobe.d/

Create a .conf file inside /etc/modprobe.d/ and append a line for each module you want to blacklist, using the blacklist keyword. If for example you want to prevent the pcspkr module from loading:

/etc/modprobe.d/nobeep.conf
# Do not load the 'pcspkr' module on boot.
blacklist pcspkr
Note: The blacklist command will blacklist a module so that it will not be loaded automatically, but the module may be loaded if another non-blacklisted module depends on it or if it is loaded manually.

However, there is a workaround for this behaviour; the install command instructs modprobe to run a custom command instead of inserting the module in the kernel as normal, so you can force the module to always fail loading with:

/etc/modprobe.d/blacklist.conf
...
install module_name /bin/false
...
This will effectively blacklist that module and any other that depends on it.

Using kernel command line

Tip: This can be very useful if a broken module makes it impossible to boot your system.

You can also blacklist modules from the bootloader.

Simply add modprobe.blacklist=modname1,modname2,modname3 to your bootloader's kernel line, as described in Kernel parameters.

Note: When you are blacklisting more than one module, note that they are separated by commas only. Spaces or anything else might presumably break the syntax.

Troubleshooting

Modules do not load

In case a specific module does not load and the boot log (accessible with journalctl -b) says that the module is blacklisted, but the directory /etc/modprobe.d/ does not show a corresponding entry, check another modprobe source folder at /usr/lib/modprobe.d/ for blacklisting entries.

A module will not be loaded if the "vermagic" string contained within the kernel module does not match the value of the currently running kernel. If it is known that the module is compatible with the current running kernel the "vermagic" check can be ignored with modprobe --force-vermagic.

Warning: Ignoring the version checks for a kernel module can cause a kernel to crash or a system to exhibit undefined behavior due to incompatibility. Use --force-vermagic only with the utmost caution.

See also