a device driver which adds support for new hardware; or, support for a file system such as btrfs or NFS.
Like the kernel itself, modules can take parameters that customize their behavior, though the default parameters work well in most cases. User-space tools can list the modules currently loaded into a running kernel; query all available modules for available parameters and module-specific information; and load or unload (remove) modules dynamically into or from a running kernel. Many of these utilities, which are provided by the kmod package, take module dependencies into account when performing operations so that manual dependency-tracking is rarely necessary.
On modern systems, kernel modules are automatically loaded by various mechanisms when the conditions call for it. However, there are occasions when it is necessary to load or unload modules manually, such as when one module is preferred over another although either could provide basic functionality, or when a module is misbehaving.
This chapter explains how to:
You can list all kernel modules that are currently loaded into the kernel by running the lsmod command, for example:
~]$ lsmod Module Size Used by tcp_lp 12663 0 bnep 19704 2 bluetooth 372662 7 bnep rfkill 26536 3 bluetooth fuse 87661 3 ip6t_rpfilter 12546 1 ip6t_REJECT 12939 2 ipt_REJECT 12541 2 xt_conntrack 12760 7 ebtable_nat 12807 0 ebtable_broute 12731 0 bridge 110196 1 ebtable_broute stp 12976 1 bridge llc 14552 2 stp,bridge ebtable_filter 12827 0 ebtables 30913 3 ebtable_broute,ebtable_nat,ebtable_filter ip6table_nat 13015 1 nf_conntrack_ipv6 18738 5 nf_defrag_ipv6 34651 1 nf_conntrack_ipv6 nf_nat_ipv6 13279 1 ip6table_nat ip6table_mangle 12700 1 ip6table_security 12710 1 ip6table_raw 12683 1 ip6table_filter 12815 1 ip6_tables 27025 5 ip6table_filter,ip6table_mangle,ip6table_security,ip6table_nat,ip6table_raw iptable_nat 13011 1 nf_conntrack_ipv4 14862 4 nf_defrag_ipv4 12729 1 nf_conntrack_ipv4 nf_nat_ipv4 13263 1 iptable_nat nf_nat 21798 4 nf_nat_ipv4,nf_nat_ipv6,ip6table_nat,iptable_nat [output truncated]
Each row of lsmod output specifies:
Finally, note that lsmod output is less verbose and considerably easier to read than the content of the /proc/modules pseudo-file.
You can display detailed information about a kernel module by running the modinfo module_name command.
Here are descriptions of a few of the fields in modinfo output: filename The absolute path to the .ko kernel object file. You can use modinfo -n as a shortcut command for printing only the filename field. descriptionA short description of the module. You can use modinfo -d as a shortcut command for printing only the description field. aliasThe alias field appears as many times as there are aliases for a module, or is omitted entirely if there are none. dependsThis field contains a comma-separated list of all the modules this module depends on.
Each parm field presents one module parameter in the form `parameter_name:description`, where:
To load a kernel module, run modprobe module_name as root. For example, to load the wacom module, run:
By default, modprobe attempts to load the module from /lib/modules/kernel_version/kernel/drivers/. In this directory, each type of module has its own subdirectory, such as net/ and scsi/, for network and SCSI interface drivers respectively.
Some modules have dependencies, which are other kernel modules that must be loaded before the module in question can be loaded. The modprobe command always takes dependencies into account when performing operations. When you ask modprobe to load a specific kernel module, it first examines the dependencies of that module, if there are any, and loads them if they are not already loaded into the kernel. modprobe resolves dependencies recursively: it will load all dependencies of dependencies, and so on, if necessary, thus ensuring that all dependencies are always met.
You can use the -v (or --verbose) option to cause modprobe to display detailed information about what it is doing, which can include loading module dependencies.
Example 3. modprobe -v shows module dependencies as they are loaded
You can load the Fibre Channel over Ethernet module verbosely by typing the following at a shell prompt:
~]# modprobe -v fcoe insmod /lib/modules/3.17.4-302.fc21.x86_64/kernel/drivers/scsi/scsi_transport_fc.ko.xz insmod /lib/modules/3.17.4-302.fc21.x86_64/kernel/drivers/scsi/libfc/libfc.ko.xz insmod /lib/modules/3.17.4-302.fc21.x86_64/kernel/drivers/scsi/fcoe/libfcoe.ko.xz insmod /lib/modules/3.17.4-302.fc21.x86_64/kernel/drivers/scsi/fcoe/fcoe.ko.xz
In this example, you can see that modprobe loaded the scsi_tgt, scsi_transport_fc, libfc and libfcoe modules as dependencies before finally loading fcoe. Also note that modprobe used the more primitive insmod command to insert the modules into the running kernel.
You can unload a kernel module by running modprobe -r module_name as root. For example, assuming that the wacom module is already loaded into the kernel, you can unload it by running:
However, this command will fail if a process is using:
See Listing Currently-Loaded Modules for more information about using lsmod to obtain the names of the modules which are preventing you from unloading a certain module.
Example 4. Unloading a kernel module
For example, if you want to unload the firewire_ohci module, your terminal session might look similar to this:
~]# modinfo -F depends firewire_ohci firewire-core ~]# modinfo -F depends firewire_core crc-itu-t ~]# modinfo -F depends crc-itu-t
You have figured out the dependency tree (which does not branch in this example) for the loaded Firewire modules: firewire_ohci depends on firewire_core, which itself depends on crc-itu-t.
You can unload firewire_ohci using the modprobe -v -r module_name command, where -r is short for --remove and -v for --verbose:
~]# modprobe -r -v firewire_ohci rmmod firewire_ohci rmmod firewire_core rmmod crc_itu_t
The output shows that modules are unloaded in the reverse order that they are loaded, given that no processes depend on any of the modules being unloaded.
Like the kernel itself, modules can also take parameters that change their behavior. Most of the time, the default ones work well, but occasionally it is necessary or desirable to set custom parameters for a module. Because parameters cannot be dynamically set for a module that is already loaded into a running kernel, there are two different methods for setting them.
Example 5. Supplying optional parameters when loading a kernel module
You can use modprobe to load a kernel module with custom parameters using the following command line format:
~]# modprobe module_name parameter=value
When loading a module with custom parameters on the command line, be aware of the following:
Here are the recommended steps for setting custom parameters and then loading a kernel module. This procedure illustrates the steps using the e1000e module, which is the network driver for Intel PRO/1000 network adapters, as an example:
Loading a Kernel Module with Custom Parameters
As shown in Listing information about a kernel module with lsmod, many kernel modules are loaded automatically at boot time. You can specify additional modules to be loaded by the systemd-modules-load.service daemon by creating a program.conf file in the /etc/modules-load.d/ directory, where program is any descriptive name of your choice. The files in /etc/modules-load.d/ are text files that list the modules to be loaded, one per line.
Example 6. A Text File to Load a Module
To create a file to load the virtio-net.ko module, create a file /etc/modules-load.d/virtio-net.conf with the following content:
# Load virtio-net.ko at boot virtio-net
See the modules-load.d(5) and systemd-modules-load.service(8) man pages for more information.
Fedora includes support for the UEFI Secure Boot feature, which means that Fedora can be installed and run on systems where UEFI Secure Boot is enabled. When Secure Boot is enabled, the EFI operating system boot loaders, the Fedora kernel, and all kernel modules must be signed with a private key and authenticated with the corresponding public key. The Fedora distribution includes signed boot loaders, signed kernels, and signed kernel modules. In addition, the signed first-stage boot loader and the signed kernel include embedded Fedora public keys. These signed executable binaries and embedded keys enable Fedora to install, boot, and run with the Microsoft UEFI Secure Boot CA keys that are provided by the UEFI firmware on systems that support UEFI Secure Boot.
The information provided in the following sections describes steps necessary to enable you to self-sign privately built kernel modules for use with Fedora on UEFI-based systems where Secure Boot is enabled. These sections also provide an overview of available options for getting your public key onto the target system where you want to deploy your kernel module.
In order to enable signing of externally built modules, the tools listed in the following table are required to be installed on the system.
In Fedora, when a kernel module is loaded, the module’s signature is checked using the public X.509 keys on the kernel’s system key ring, excluding those keys that are on the kernel’s system black list key ring.
During boot, the kernel loads X.509 keys into the system key ring or the system black list key ring from a set of persistent key stores as shown in Sources For System Key Rings
Note that if the system is not UEFI-based or if UEFI Secure Boot is not enabled, then only the keys that are embedded in the kernel are loaded onto the system key ring and you have no ability to augment that set of keys without rebuilding the kernel. The system black list key ring is a list of X.509 keys which have been revoked. If your module is signed by a key on the black list then it will fail authentication even if your public key is in the system key ring.
To confirm if Secure Boot is enabled, enter a command as follows:
~]$ mokutil --sb-state SecureBoot enabled
If Secure Boot is not enabled then the message Failed to read SecureBoot is displayed.
You can display information about the keys on the system key rings using the keyctl utility. The following is abbreviated example output from a Fedora system where UEFI Secure Boot is not enabled.
~]# keyctl list %:.builtin_trusted_keys 1 key in keyring: 265061799: ---lswrv 0 0 asymmetric: Fedora kernel signing key: ba8e2919f98f3f8e2e27541cde0d1f...
The following is abbreviated example output from a Fedora system where UEFI Secure Boot is enabled.
~]# keyctl list %:.builtin_trusted_keys 5 keys in keyring: ...asymmetric: Microsoft Windows Production PCA 2011: a92902398e16c497... ...asymmetric: Fedora kernel signing key: ba8e2919f98f3f8e2e27541cde0d... ...asymmetric: Fedora Secure Boot CA: fde32599c2d61db1bf5807335d7b20e4... ...asymmetric: Red Hat Test Certifying CA: 08a0ef5800cb02fb587c12b4032... ...asymmetric: Microsoft Corporation UEFI CA 2011: 13adbf4309bd82709c8...
The above output shows the addition of two keys from the UEFI Secure Boot “db” keys plus the Fedora Secure Boot CA which is embedded in the shim.efi boot loader.
If UEFI Secure Boot is enabled or if the module.sig_enforce kernel parameter has been specified, then only signed kernel modules that are authenticated using a key on the system key ring can be successfully loaded. If UEFI Secure Boot is disabled and if the module.sig_enforce kernel parameter has not been specified, then unsigned kernel modules and signed kernel modules without a public key can be successfully loaded. This is summarized in Kernel Module Authentication Requirements for Loading.
Subsequent sections will describe how to generate a public and private X.509 key pair, how to use the private key to sign a kernel module, and how to enroll the public key into a source for the system key ring.
You need to generate a public and private X.509 key pair that will be used to sign a kernel module after it has been built. The corresponding public key will be used to authenticate the kernel module when it is loaded.
When Fedora boots on a UEFI-based system with Secure Boot enabled, all keys that are in the Secure Boot db key database, but not in the dbx database of revoked keys, are loaded onto the system keyring by the kernel. The system keyring is used to authenticate kernel modules.
To facilitate authentication of your kernel module on your systems, consider requesting your system vendor to incorporate your public key into the UEFI Secure Boot key database in their factory firmware image.
It is possible to add a key to an existing populated and active Secure Boot key database. This can be done by writing and providing an EFI executable enrollment image. Such an enrollment image contains a properly formed request to append a key to the Secure Boot key database. This request must include data that is properly signed by the private key that corresponds to a public key that is already in the system’s Secure Boot Key Exchange Key (KEK) database. Additionally, this EFI image must be signed by a private key that corresponds to a public key that is already in the key database.
It is also possible to write an enrollment image that runs under Fedora. However, the Fedora image must be properly signed by a private key that corresponds to a public key that is already in the KEK database.
The construction of either type of key enrollment images requires assistance from the platform vendor.
The Machine Owner Key (MOK) facility is a feature that is supported by Fedora and can be used to augment the UEFI Secure Boot key database. When Fedora boots on a UEFI-enabled system with Secure Boot enabled, the keys on the MOK list are also added to the system keyring in addition to the keys from the key database. The MOK list keys are also stored persistently and securely in the same fashion as the Secure Boot key database keys, but these are two separate facilities. The MOK facility is supported by shim.efi, MokManager.efi, grubx64.efi, and the Fedora mokutil utility.
The major capability provided by the MOK facility is the ability to add public keys to the MOK list without needing to have the key chain back to another key that is already in the KEK database. However, enrolling a MOK key requires manual interaction by a physically present user at the UEFI system console on each target system. Nevertheless, the MOK facility provides an excellent method for testing newly generated key pairs and testing kernel modules signed with them.
Follow these steps to add your public key to the MOK list:
Once a key is on the MOK list, it will be automatically propagated to the system key ring on this and subsequent boots when UEFI Secure Boot is enabled.
There are no extra steps required to prepare your kernel module for signing. You build your kernel module normally. Assuming an appropriate Makefile and corresponding sources, follow these steps to build your module and sign it:
Your kernel module is in ELF image format and this application computes and appends the signature directly to the ELF image in your my_module.ko file. The modinfo utility can be used to display information about the kernel module’s signature, if it is present. For information on using the utility, see Displaying Information About a Module.
Note that this appended signature is not contained in an ELF image section and is not a formal part of the ELF image. Therefore, tools such as readelf will not be able to display the signature on your kernel module.
Your kernel module is now ready for loading. Note that your signed kernel module is also loadable on systems where UEFI Secure Boot is disabled or on a non-UEFI system. That means you do not need to provide both a signed and unsigned version of your kernel module.
Once your public key is enrolled and is in the system keyring, the normal kernel module loading mechanisms will work transparently. In the following example, you will use mokutil to add your public key to the MOK list and you will manually load your kernel module with modprobe.
For more information on kernel modules and their utilities, see the following resources.
Manual Page Documentation
Installable and External Documentation
Want to help? Learn how to contribute to Fedora Docs. |