Chapter 3. Managing kernel modules

Learn about kernel modules, 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 9, 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. 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.

depmod

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.

weak-modules

In addition to depmod, Red Hat Enterprise Linux provides the weak-modules script shipped also with the kmod package. weak-modules determines which modules are kABI-compatible with installed kernels. While checking modules kernel compatibility, weak-modules processes modules symbol dependencies from higher to lower release of kernel for which they were built. This means that weak-modules processes each module independently of kernel release they were built against.

3.3. Listing installed kernel modules

The grubby --info=ALL command displays an indexed list of installed kernels on !BLS and BLS installs.

Procedure

  • List the installed kernels using the following command:

    # grubby --info=ALL | grep title

    The list of all installed kernels is displayed as follows:

    title="Red Hat Enterprise Linux (5.14.0-1.el9.x86_64) 9.0 (Plow)"
    title="Red Hat Enterprise Linux (0-rescue-0d772916a9724907a5d1350bcd39ac92) 9.0 (Plow)"

The above example displays the installed kernels list of grubby-8.40-17, from the GRUB menu.

3.4. Listing currently loaded kernel modules

View the currently loaded kernel modules.

Prerequisites

  • The kmod package is installed.

Procedure

  • To list all currently loaded kernel modules, enter:

    $ 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:

    1. The Module column provides the names of currently loaded modules.
    2. The Size column displays the amount of memory per module in kilobytes.
    3. The Used by column shows the number, and optionally the names of modules that are dependent on a particular module.

Additional resources

  • The /usr/share/doc/kmod/README file
  • The lsmod(8) manual page

3.5. Displaying information about kernel modules

Use the modinfo command to display some detailed information about the specified kernel module.

Prerequisites

  • The kmod package is installed.

Procedure

  • To display information about any kernel module, enter:

    $ modinfo <KERNEL_MODULE_NAME>

    For example:

    $ modinfo virtio_net
    
    filename:       /lib/modules/5.14.0-1.el9.x86_64/kernel/drivers/net/virtio_net.ko.xz
    license:        GPL
    description:    Virtio network driver
    rhelversion:    9.0
    srcversion:     8809CDDBE7202A1B00B9F1C
    alias:          virtio:d00000001v*
    depends:        net_failover
    retpoline:      Y
    intree:         Y
    name:           virtio_net
    vermagic:       5.14.0-1.el9.x86_64 SMP mod_unload modversions
    …​
    parm:           napi_weight:int
    parm:           csum:bool
    parm:           gso:bool
    parm:           napi_tx:bool

    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

  • The modinfo(8) manual page

3.6. Loading kernel modules at system runtime

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

Important

The changes described in this procedure will not persist after rebooting the system. For information about how to load kernel modules to persist across system reboots, see Loading kernel modules automatically at system boot time.

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.

Verification

  • 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

Additional resources

  • The modprobe(8) manual page

3.7. Unloading kernel modules at system runtime

At times, you find that you need to unload certain kernel modules from the running kernel. Use the modprobe command to find and unload a kernel module at system runtime from the currently loaded kernel.

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.

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 about how to counter this outcome, see Preventing kernel modules from being automatically loaded at system boot time.

Prerequisites

  • Root permissions
  • The kmod package is installed.

Procedure

  1. List all loaded kernel modules:

    # lsmod
  2. Select the 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.

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

Verification

  • Optionally, verify the relevant module was unloaded:

    $ lsmod | grep <MODULE_NAME>

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

Additional resources

  • modprobe(8) manual page

3.8. 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 boot loader.

You can edit the relevant boot loader entry to unload the desired kernel module before the booting sequence continues.

Important

The changes described in this procedure will not persist after the next reboot. For information about 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 that you want to prevent from loading for some reason.

Procedure

  1. Boot the system into the boot loader.
  2. Use the cursor keys to highlight the relevant boot loader entry.
  3. Press the e key to edit the entry.

    Figure 3.1. Kernel boot menu

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

    Figure 3.2. Kernel boot entry

    kernel boot entry rhel9

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

  6. Press Ctrl+X 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.9. Loading kernel modules automatically at system boot time

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.10. Preventing kernel modules from being automatically loaded at system boot time

You can prevent the system from loading a kernel module automatically during the boot process by listing the module in modprobe configuration file with a corresponding command.

Prerequisites

  • The commands in this procedure require root privileges. Either use su - to switch to the root user or preface the commands with sudo.
  • The kmod package is installed.
  • Ensure that your current system configuration does not require a kernel module you plan to deny.

Procedure

  1. List modules loaded to the currently running kernel by using the lsmod command:

    $ lsmod
    Module                  Size  Used by
    tls                   131072  0
    uinput                 20480  1
    snd_seq_dummy          16384  0
    snd_hrtimer            16384  1
    …

    In the output, identify the module you want to prevent from being loaded.

    • Alternatively, identify an unloaded kernel module you want to prevent from potentially loading in the /lib/modules/<KERNEL-VERSION>/kernel/<SUBSYSTEM>/ directory, for example:

      $ ls /lib/modules/4.18.0-477.20.1.el8_8.x86_64/kernel/crypto/
      ansi_cprng.ko.xz        chacha20poly1305.ko.xz  md4.ko.xz               serpent_generic.ko.xz
      anubis.ko.xz            cmac.ko.xz…
  2. Create a configuration file serving as a denylist:

    # touch /etc/modprobe.d/denylist.conf
  3. In a text editor of your choice, combine the names of modules you want to exclude from automatic loading to the kernel with the blacklist configuration command, for example:

    # Prevents <KERNEL-MODULE-1> from being loaded
    blacklist <MODULE-NAME-1>
    install <MODULE-NAME-1> /bin/false
    
    # Prevents <KERNEL-MODULE-2> from being loaded
    blacklist <MODULE-NAME-2>
    install <MODULE-NAME-2> /bin/false
    …

    Because the blacklist command does not prevent the module from being loaded as a dependency for another kernel module that is not in a denylist, you must also define the install line. In this case, the system runs /bin/false instead of installing the module. The lines starting with a hash sign are comments you can use 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.

  4. Create a backup copy of the current initial RAM disk image before rebuilding:

    # cp /boot/initramfs-$(uname -r).img /boot/initramfs-$(uname -r).bak.$(date +%m-%d-%H%M%S).img
    • Alternatively, create a backup copy of an initial RAM disk image which corresponds to the kernel version for which you want to prevent kernel modules from automatic loading:

      # cp /boot/initramfs-<VERSION>.img /boot/initramfs-<VERSION>.img.bak.$(date +%m-%d-%H%M%S)
  5. Generate a new initial RAM disk image to apply the changes:

    # dracut -f -v
    • If you build an initial RAM disk image for a different kernel version than your system currently uses, specify both target initramfs and kernel version:

      # dracut -f -v /boot/initramfs-<TARGET-VERSION>.img <CORRESPONDING-TARGET-KERNEL-VERSION>
  6. Restart the system:

    $ reboot
Important

The changes described in this procedure will take effect and persist after rebooting the system. If you incorrectly list a key kernel module in the denylist, you can switch the system to an unstable or non-operational state.

Additional resources

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

    # dnf install kernel-devel-$(uname -r) gcc elfutils-libelf-devel
  • 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"); }
    
    MODULE_LICENSE("GPL");

    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.
  2. Follow the init_module() and cleanup_module() functions to start and end the kernel logging function printk(), which prints text.
  3. 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.

  4. Compile the kernel module.

    # make -C /lib/modules/$(uname -r)/build M=/root/testmodule modules
    make: Entering directory '/usr/src/kernels/5.14.0-70.17.1.el9_0.x86_64'
      CC [M]  /root/testmodule/test.o
      MODPOST /root/testmodule/Module.symvers
      CC [M]  /root/testmodule/test.mod.o
      LD [M]  /root/testmodule/test.ko
      BTF [M] /root/testmodule/test.ko
    Skipping BTF generation for /root/testmodule/test.ko due to unavailability of vmlinux
    make: Leaving directory '/usr/src/kernels/5.14.0-70.17.1.el9_0.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 152
    -rw-r—​r--. 1 root root    16 Jul 26 08:19 Makefile
    -rw-r—​r--. 1 root root    25 Jul 26 08:20 modules.order
    -rw-r—​r--. 1 root root     0 Jul 26 08:20 Module.symvers
    -rw-r—​r--. 1 root root   224 Jul 26 08:18 test.c
    -rw-r—​r--. 1 root root 62176 Jul 26 08:20 test.ko
    -rw-r—​r--. 1 root root    25 Jul 26 08:20 test.mod
    -rw-r—​r--. 1 root root   849 Jul 26 08:20 test.mod.c
    -rw-r—​r--. 1 root root 50936 Jul 26 08:20 test.mod.o
    -rw-r—​r--. 1 root root 12912 Jul 26 08:20 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/5.14.0-1.el9.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

Additional resources