Chapter 3. Managing kernel modules

The following sections explain what kernel modules are, how to display their information, and how to perform basic administrative tasks with kernel modules.

3.1. Introduction to kernel modules

The Red Hat Enterprise Linux kernel can be extended with optional, additional pieces of functionality, called kernel modules, without having to reboot the system. On Red Hat Enterprise Linux 8, kernel modules are extra kernel code which is built into compressed <KERNEL_MODULE_NAME>.ko.xz object files.

The most common functionality enabled by kernel modules are:

  • Device driver which adds support for new hardware
  • Support for a file system such as GFS2 or NFS
  • System calls

On modern systems, kernel modules are automatically loaded when needed. However, in some cases it is necessary to load or unload modules manually.

Like the kernel itself, the modules can take parameters that customize their behavior if needed.

Tooling is provided to inspect which modules are currently running, which modules are available to load into the kernel and which parameters a module accepts. The tooling also provides a mechanism to load and unload kernel modules into the running kernel.

3.2. Introduction to bootloader specification

The BootLoader Specification (BLS) defines a scheme and the file format to manage the bootloader configuration for each boot option in the drop-in directory without the need to manipulate the bootloader configuration files. Unlike earlier approaches, each boot entry is now represented by a separate configuration file in the drop-in directory. The drop-in directory extends its configuration without having the need to edit or regenerate the configuration files. The BLS extends this concept for the boot menu entries.

Using BLS, you can manage the bootloader menu options by adding, removing, or editing individual boot entry files in a directory. This makes the kernel installation process significantly simpler and consistent across the different architectures.

The grubby tool is a thin wrapper script around the BLS and it supports the same grubby arguments and options. It runs the dracut to create an initial ramdisk image. With this setup, the core bootloader configuration files are static and are not modified after kernel installation.

This premise is particularly relevant in Red Hat Enterprise Linux 8 because the same bootloader is not used in all architectures. GRUB2 is used in most of them such as the 64-bit ARM, but little-endian variants of IBM Power Systems with Open Power Abstraction Layer (OPAL) uses Petitboot and the IBM Z architecture uses zipl.

Additional Resources

3.3. Kernel module dependencies

Certain kernel modules sometimes depend on one or more other kernel modules. The /lib/modules/<KERNEL_VERSION>/modules.dep file contains a complete list of kernel module dependencies for the respective kernel version.

The dependency file is generated by the depmod program, which is a part of the kmod package. Many of the utilities provided by kmod take module dependencies into account when performing operations so that manual dependency-tracking is rarely necessary.

Warning

The code of kernel modules is executed in kernel-space in the unrestricted mode. Because of this, you should be mindful of what modules you are loading.

Additional resources

  • For more information about /lib/modules/<KERNEL_VERSION>/modules.dep, refer to the modules.dep(5) manual page.
  • For further details including the synopsis and options of depmod, see the depmod(8) manual page.

3.4. Listing currently loaded kernel modules

The following procedure describes how to view the currently loaded kernel modules.

Prerequisites

  • The kmod package is installed.

Procedure

  • To list all currently loaded kernel modules, execute:

    $ lsmod
    
    Module                  Size  Used by
    fuse                  126976  3
    uinput                 20480  1
    xt_CHECKSUM            16384  1
    ipt_MASQUERADE         16384  1
    xt_conntrack           16384  1
    ipt_REJECT             16384  1
    nft_counter            16384  16
    nf_nat_tftp            16384  0
    nf_conntrack_tftp      16384  1 nf_nat_tftp
    tun                    49152  1
    bridge                192512  0
    stp                    16384  1 bridge
    llc                    16384  2 bridge,stp
    nf_tables_set          32768  5
    nft_fib_inet           16384  1
    …​

    In the example above:

    • The first column provides the names of currently loaded modules.
    • The second column displays the amount of memory per module in kilobytes.
    • The last column shows the number, and optionally the names of modules that are dependent on a particular module.

Additional resources

  • For more information about kmod, refer to the /usr/share/doc/kmod/README file or the lsmod(8) manual page.

3.5. Listing all installed kernels

The following procedure describes how to use the command line tool grubby to list the GRUB2 boot entries.

Procedure

To list the boot entries of the kernel:

  • To list the boot entries of the kernel, execute:

    # grubby --info=ALL | grep title

    The command displays the boot entries of the kernel. The kernel field shows the kernel path.

    The following procedure describes how to use grubby utility to list all installed kernels in their systems using the kernel command line.

As an example, consider listing grubby-8.40-17, from the Grub2 menu on both the BLS and non-BLS installs.

Procedure

To list all installed kernel modules:

  • Execute the following command:

    # grubby --info=ALL | grep title

    The list of all installed kernels is displayed as follows:

    title=Red Hat Enterprise Linux (4.18.0-20.el8.x86_64) 8.0 (Ootpa)
    title=Red Hat Enterprise Linux (4.18.0-19.el8.x86_64) 8.0 (Ootpa)
    title=Red Hat Enterprise Linux (4.18.0-12.el8.x86_64) 8.0 (Ootpa)
    title=Red Hat Enterprise Linux (4.18.0) 8.0 (Ootpa)
    title=Red Hat Enterprise Linux (0-rescue-2fb13ddde2e24fde9e6a246a942caed1) 8.0 (Ootpa)

The above output displays the list of all installed kernels for grubby-8.40-17, using the Grub2 menu.

3.6. Setting a kernel as default

The following procedure describes how to set a specific kernel as default using the grubby command-line tool and GRUB2.

Procedure

Setting the kernel as default, using the grubby tool
  • Execute the following command to set the kernel as default using the grubby tool:

# grubby --set-default $kernel_path

The command uses a machine ID without the .conf suffix as an argument.

Note

The machine ID is located in the /boot/loader/entries/ directory.

Setting the kernel as default, using the id argument
  • List the boot entries using the id argument and then set an intended kernel as default:
# grubby --info ALL | grep id
# grubby --set-default /boot/vmlinuz-<version>.<architecture>
Note

To list the boot entries using the title argument, execute the # grubby --info=ALL | grep title command.

Setting the default kernel for only the next boot
  • Execute the following command to set the default kernel for only the next reboot using the grub2-reboot command:
# grub2-reboot <index|title|id>
Warning

Set the default kernel for only the next boot with care. Installing new kernel RPM’s, self-built kernels, and manually adding the entries to the /boot/loader/entries/ directory may change the index values.

3.7. Displaying information about kernel modules

When working with a kernel module, you may want to see further information about that module. This procedure describes how to display extra information about kernel modules.

Prerequisites

  • The kmod package is installed.

Procedure

  • To display information about any kernel module, execute:

    $ modinfo <KERNEL_MODULE_NAME>
    
    For example:
    $ modinfo virtio_net
    
    filename:       /lib/modules/4.18.0-94.el8.x86_64/kernel/drivers/net/virtio_net.ko.xz
    license:        GPL
    description:    Virtio network driver
    rhelversion:    8.1
    srcversion:     2E9345B281A898A91319773
    alias:          virtio:d00000001v*
    depends:        net_failover
    intree:         Y
    name:           virtio_net
    vermagic:       4.18.0-94.el8.x86_64 SMP mod_unload modversions
    …​
    parm:           napi_weight:int
    parm:           csum:bool
    parm:           gso:bool
    parm:           napi_tx:bool

    The modinfo command displays some detailed information about the specified kernel module. You can query information about all available modules, regardless of whether they are loaded or not. The parm entries show parameters the user is able to set for the module, and what type of value they expect.

    Note

    When entering the name of a kernel module, do not append the .ko.xz extension to the end of the name. Kernel module names do not have extensions; their corresponding files do.

Additional resources

  • For more information about the modinfo, refer to the modinfo(8) manual page.

3.8. Loading kernel modules at system runtime

The optimal way to expand the functionality of the Linux kernel is by loading kernel modules. The following procedure describes how to use the modprobe command to find and load a kernel module into the currently running kernel.

Prerequisites

  • Root permissions
  • The kmod package is installed.
  • The respective kernel module is not loaded. To ensure this is the case, list the loaded kernel modules.

Procedure

  1. Select a kernel module you want to load.

    The modules are located in the /lib/modules/$(uname -r)/kernel/<SUBSYSTEM>/ directory.

  2. Load the relevant kernel module:

    # modprobe <MODULE_NAME>
    Note

    When entering the name of a kernel module, do not append the .ko.xz extension to the end of the name. Kernel module names do not have extensions; their corresponding files do.

  3. Optionally, verify the relevant module was loaded:

    $ lsmod | grep <MODULE_NAME>

    If the module was loaded correctly, this command displays the relevant kernel module. For example:

    $ lsmod | grep serio_raw
    serio_raw              16384  0
Important

The changes described in this procedure will not persist after rebooting the system.

Additional resources

  • For further details about modprobe, see the modprobe(8) manual page.

3.9. Unloading kernel modules at system runtime

At times, you find that you need to unload certain kernel modules from the running kernel. The following procedure describes how to use the modprobe command to find and unload a kernel module at system runtime from the currently loaded kernel.

Prerequisites

  • Root permissions
  • The kmod package is installed.

Procedure

  1. Execute the lsmod command and select a kernel module you want to unload.

    If a kernel module has dependencies, unload those prior to unloading the kernel module. For details on identifying modules with dependencies, see Listing currently loaded kernel modules.

  2. Unload the relevant kernel module:

    # modprobe -r <MODULE_NAME>

    When entering the name of a kernel module, do not append the .ko.xz extension to the end of the name. Kernel module names do not have extensions; their corresponding files do.

    Warning

    Do not unload kernel modules when they are used by the running system. Doing so can lead to an unstable or non-operational system.

  3. Optionally, verify the relevant module was unloaded:

    $ lsmod | grep <MODULE_NAME>

    If the module was unloaded successfully, this command does not display any output.

Important

After finishing this procedure, the kernel modules that are defined to be automatically loaded on boot, will not stay unloaded after rebooting the system. For information on how to counter this outcome, see Preventing kernel modules from being automatically loaded at system boot time.

Additional resources

  • For further details about modprobe, see the modprobe(8) manual page.

3.10. Loading kernel modules automatically at system boot time

The following procedure describes how to configure a kernel module so that it is loaded automatically during the boot process.

Prerequisites

  • Root permissions
  • The kmod package is installed.

Procedure

  1. Select a kernel module you want to load during the boot process.

    The modules are located in the /lib/modules/$(uname -r)/kernel/<SUBSYSTEM>/ directory.

  2. Create a configuration file for the module:

    # echo <MODULE_NAME> > /etc/modules-load.d/<MODULE_NAME>.conf
    Note

    When entering the name of a kernel module, do not append the .ko.xz extension to the end of the name. Kernel module names do not have extensions; their corresponding files do.

  3. Optionally, after reboot, verify the relevant module was loaded:

    $ lsmod | grep <MODULE_NAME>

    The example command above should succeed and display the relevant kernel module.

Important

The changes described in this procedure will persist after rebooting the system.

Additional resources

  • For further details about loading kernel modules during the boot process, see the modules-load.d(5) manual page.

3.11. Preventing kernel modules from being automatically loaded at system boot time

The following procedure describes how to add a kernel module to a denylist so that it will not be automatically loaded during the boot process.

Prerequisites

  • Root permissions
  • The kmod package is installed.
  • Ensure that a kernel module in a denylist is not vital for your current system configuration.

Procedure

  1. Select a kernel module that you want to put in a denylist:

    $ lsmod
    
    Module                  Size  Used by
    fuse                  126976  3
    xt_CHECKSUM            16384  1
    ipt_MASQUERADE         16384  1
    uinput                 20480  1
    xt_conntrack           16384  1
    …​

    The lsmod command displays a list of modules loaded to the currently running kernel.

    • Alternatively, identify an unloaded kernel module you want to prevent from potentially loading.

      All kernel modules are located in the /lib/modules/<KERNEL_VERSION>/kernel/<SUBSYSTEM>/ directory.

  2. Create a configuration file for a denylist:

    # vim /etc/modprobe.d/blacklist.conf
    
    	# Blacklists <KERNEL_MODULE_1>
    	blacklist <MODULE_NAME_1>
    	install <MODULE_NAME_1> /bin/false
    
    	# Blacklists <KERNEL_MODULE_2>
    	blacklist <MODULE_NAME_2>
    	install <MODULE_NAME_2> /bin/false
    
    	# Blacklists <KERNEL_MODULE_n>
    	blacklist <MODULE_NAME_n>
    	install <MODULE_NAME_n> /bin/false
    	…​

    The example shows the contents of the blacklist.conf file, edited by the vim editor. The blacklist line ensures that the relevant kernel module will not be automatically loaded during the boot process. The blacklist command, however, does not prevent the module from being loaded as a dependency for another kernel module that is not in a denylist. Therefore the install line causes the /bin/false to run instead of installing a module.

    The lines starting with a hash sign are comments to make the file more readable.

    Note

    When entering the name of a kernel module, do not append the .ko.xz extension to the end of the name. Kernel module names do not have extensions; their corresponding files do.

  3. Create a backup copy of the current initial ramdisk image before rebuilding:

    # cp /boot/initramfs-$(uname -r).img /boot/initramfs-$(uname -r).bak.$(date +%m-%d-%H%M%S).img

    The command above creates a backup initramfs image in case the new version has an unexpected problem.

    • Alternatively, create a backup copy of other initial ramdisk image which corresponds to the kernel version for which you want to put kernel modules in a denylist:

      # cp /boot/initramfs-<SOME_VERSION>.img /boot/initramfs-<SOME_VERSION>.img.bak.$(date +%m-%d-%H%M%S)
  4. Generate a new initial ramdisk image to reflect the changes:

    # dracut -f -v
    • If you are building an initial ramdisk image for a different kernel version than you are currently booted into, specify both target initramfs and kernel version:

      # dracut -f -v /boot/initramfs-<TARGET_VERSION>.img <CORRESPONDING_TARGET_KERNEL_VERSION>
  5. Reboot the system:

    $ reboot
Important

The changes described in this procedure will take effect and persist after rebooting the system. If you improperly put a key kernel module in a denylist, you can face an unstable or non-operational system.

Additional resources

  • For further details concerning the dracut utility, refer to the dracut(8) manual page.