Red Hat Training

A Red Hat training course is available for RHEL 8

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

  • modules.dep(5) manual page
  • 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

  • /usr/share/doc/kmod/README file
  • 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

  • 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. For information on how to load kernel modules to persist across system reboots, see Loading kernel modules automatically at system boot time.

Additional resources

  • 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 and Kernel module dependencies.

  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

  • modprobe(8) manual page

3.10. Unloading kernel modules at early stages of the boot process

In certain situations it is necessary to unload a kernel module very early in the booting process. For example, when the kernel module contains a code, which causes the system to become unresponsive, and the user is not able to reach the stage to permanently disable the rogue kernel module. In that case it is possible to temporarily block the loading of the kernel module using a bootloader.

Important

The changes described in this procedure will not persist after the next reboot. For information on how to add a kernel module to a denylist so that it will not be automatically loaded during the boot process, see Preventing kernel modules from being automatically loaded at system boot time.

Prerequisites

  • You have a loadable kernel module, which you want to prevent from loading for some reason.

Procedure

  • Edit the relevant bootloader entry to unload the desired kernel module before the booting sequence continues.

    • Use the cursor keys to highlight the relevant bootloader entry.
    • Press e key to edit the entry.

      Figure 3.1. Kernel boot menu

      kernel bootmenu
    • Use the cursor keys to navigate to the line that starts with linux.
    • Append modprobe.blacklist=module_name to the end of the line.

      Figure 3.2. Kernel boot entry

      kernel boot entry

      The serio_raw kernel module illustrates a rogue module to be unloaded early in the boot process.

    • Press CTRL+x keys to boot using the modified configuration.

Verification

  • Once the system fully boots, verify that the relevant kernel module is not loaded.

    # lsmod | grep serio_raw

Additional resources

3.11. 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

  • modules-load.d(5) manual page

3.12. 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

3.13. Compiling custom kernel modules

You can build a sampling kernel module as requested by various configurations at hardware and software level.

Prerequisites

  • You installed the kernel-devel, gcc, and elfutils-libelf-devel packages.
  • You have root permissions.
  • You created the /root/testmodule/ directory where you compile the custom kernel module.

Procedure

  1. Create the /root/testmodule/test.c file with the following content:

    #include <linux/module.h>
    
    #include <linux/kernel.h>
    
    int init_module(void)
        { printk("Hello World\n This is a test\n"); return 0; }
    
    void cleanup_module(void)
        { printk("Good Bye World"); }

    The test.c file is a source file that provides the main functionality to the kernel module. The file has been created in a dedicated /root/testmodule/ directory for organizational purposes. After the module compilation, the /root/testmodule/ directory will contain multiple files.

    The test.c file includes from the system libraries:

    • The linux/kernel.h header file is necessary for the printk() function in the example code.
    • The linux/module.h file contains function declarations and macro definitions to be shared between several source files written in C programming language.

      Next follow the init_module() and cleanup_module() functions to start and end the kernel logging function printk(), which prints text.

  2. Create the /root/testmodule/Makefile file with the following content:

    obj-m := test.o

    The Makefile contains instructions that the compiler has to produce an object file specifically named test.o. The obj-m directive specifies that the resulting test.ko file is going to be compiled as a loadable kernel module. Alternatively, the obj-y directive would instruct to build test.ko as a built-in kernel module.

  3. Compile the kernel module:

    # make -C /lib/modules/$(uname -r)/build M=/root/testmodule modules
    make: Entering directory '/usr/src/kernels/4.18.0-305.el8.x86_64'
      CC [M]  /root/testmodule/test.o
      Building modules, stage 2.
      MODPOST 1 modules
    WARNING: modpost: missing MODULE_LICENSE() in /root/testmodule/test.o
    see include/linux/module.h for more information
      CC      /root/testmodule/test.mod.o
      LD [M]  /root/testmodule/test.ko
    make: Leaving directory '/usr/src/kernels/4.18.0-305.el8.x86_64'

    The compiler creates an object file (test.o) for each source file (test.c) as an intermediate step before linking them together into the final kernel module (test.ko).

    After a successful compilation, /root/testmodule/ contains additional files that relate to the compiled custom kernel module. The compiled module itself is represented by the test.ko file.

Verification

  1. Optional: check the contents of the /root/testmodule/ directory:

    ls -l /root/testmodule/
    total 452
    -rw-r—​r--. 1 root root     16 Jul 12 10:16 Makefile
    -rw-r—​r--. 1 root root     32 Jul 12 10:16 modules.order
    -rw-r—​r--. 1 root root      0 Jul 12 10:16 Module.symvers
    -rw-r—​r--. 1 root root    197 Jul 12 10:15 test.c
    -rw-r—​r--. 1 root root 219736 Jul 12 10:16 test.ko
    -rw-r—​r--. 1 root root    826 Jul 12 10:16 test.mod.c
    -rw-r—​r--. 1 root root 113760 Jul 12 10:16 test.mod.o
    -rw-r—​r--. 1 root root 107424 Jul 12 10:16 test.o
  2. Copy the kernel module to the /lib/modules/$(uname -r)/ directory:

    # cp /root/testmodule/test.ko /lib/modules/$(uname -r)/
  3. Update the modular dependency list:

    # depmod -a
  4. Load the kernel module:

    # modprobe -v test
    insmod /lib/modules/4.18.0-305.el8.x86_64/test.ko
  5. Verify that the kernel module was successfully loaded:

    # lsmod | grep test
    test                   16384  0
  6. Read the latest messages from the kernel ring buffer:

    # dmesg
    …​
    [74422.545004] Hello World
                    This is a test