Chapter 3. Managing kernel modules
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 kernel modules, which provide optional additional pieces of functionality, without having to reboot the system. On RHEL 9, kernel modules are extra kernel code 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. Similarly to the kernel, modules accept parameters that customize their behavior. You can use the kernel tools to perform the following actions on modules: Inspect modules that are currently running. Inspect modules that are available to load into the kernel. Inspect parameters that a module accepts. Enable 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 corresponding kernel version. depmod The dependency file is generated by the depmod program, included in the kmod package. Many utilities provided by kmod consider module dependencies when performing operations. Therefore, manual dependency-tracking is rarely necessary. Warning The code of kernel modules executes in kernel-space in the unrestricted mode. Be mindful of what modules you are loading. weak-modules In addition to depmod , Red Hat Enterprise Linux provides the weak-modules script, which is a part of the kmod package. weak-modules determines the modules that 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. It processes each module independently of the kernel release. Additional resources The modules.dep(5) manual page The depmod(8) manual page What is the purpose of weak-modules script shipped with Red Hat Enterprise Linux? What is Kernel Application Binary Interface (kABI)? (Red Hat Knowledgebase) 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: 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)" This is the list of installed kernels 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: In the example above: The Module column provides the names of currently loaded modules. The Size column displays the amount of memory per module in kilobytes. 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: For example: You can query information about all available modules, regardless of whether they are loaded. 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 Select a kernel module you want to load. The modules are located in the /lib/modules/USD(uname -r)/kernel/<SUBSYSTEM>/ directory. Load the relevant kernel module: 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: If the module was loaded correctly, this command displays the relevant kernel module. For example: Additional resources The modprobe(8) manual page 3.7. Unloading kernel modules at system runtime 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 You must not unload the kernel modules that are used by the running system because it can lead to an unstable or non-operational system. Important After finishing the unloading of inactive kernel modules, the modules that are defined to be automatically loaded on boot, will not remain unloaded after rebooting the system. For information about how to prevent this outcome, see Preventing kernel modules from being automatically loaded at system boot time . Prerequisites You have root permissions. The kmod package is installed. Procedure List all the loaded kernel modules: 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 . Unload the relevant kernel module: 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: If the module is 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, for example, when the kernel module has a code that causes the system to become unresponsive, and the user is not able to reach the stage to permanently disable the rogue kernel module, you might need to unload a kernel module early in the booting process. To temporarily block the loading of the kernel module, you can use a boot loader. You can edit the relevant boot loader entry to unload the required kernel module before the booting sequence continues. Important The changes described in this procedure will not persist after the 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 Boot the system into the boot loader. Use the cursor keys to highlight the relevant boot loader entry. Press the e key to edit the entry. Figure 3.1. Kernel boot menu 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 The serio_raw kernel module illustrates a rogue module to be unloaded early in the boot process. Press Ctrl + X to boot using the modified configuration. Verification After the system boots, verify that the relevant kernel module is not loaded: Additional resources Managing kernel modules 3.9. Loading kernel modules automatically at system boot time Configure a kernel module to load it automatically during the boot process. Prerequisites Root permissions The kmod package is installed. Procedure Select a kernel module you want to load during the boot process. The modules are located in the /lib/modules/USD(uname -r)/kernel/<SUBSYSTEM>/ directory. Create a configuration file for the module: 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 After reboot, verify the relevant module is loaded: 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 List modules loaded to the currently running kernel by using the lsmod command: In the output, identify the module you want to prevent from getting 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: Create a configuration file serving as a denylist: 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: Because the blacklist command does not prevent the module from getting 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. Create a backup copy of the current initial RAM disk image before rebuilding: 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: Generate a new initial RAM disk image to apply the changes: 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: Restart the system: 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 How do I prevent a kernel module from loading automatically? (Red Hat Knowledgebase) modprobe.d(5) and dracut(8) man pages on your system 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. You have root permissions. You created the /root/testmodule/ directory where you compile the custom kernel module. Procedure 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 that are shared across several source files written in C programming language. Follow the init_module() and cleanup_module() functions to start and end the kernel logging function printk() , which prints text. Create the /root/testmodule/Makefile file with the following content. obj-m := test.o The Makefile contains instructions for the compiler to produce an object file 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 can instruct to build test.ko as a built-in kernel module. Compile the kernel module. 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 Optional: check the contents of the /root/testmodule/ directory: Copy the kernel module to the /lib/modules/USD(uname -r)/ directory: Update the modular dependency list: Load the kernel module: Verify that the kernel module was successfully loaded: Read the latest messages from the kernel ring buffer:
grubby --info=ALL | grep title 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)" 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 ... modinfo < KERNEL_MODULE_NAME > 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 modprobe < MODULE_NAME > lsmod | grep < MODULE_NAME > lsmod | grep serio_raw serio_raw 16384 0 lsmod modprobe -r < MODULE_NAME > lsmod | grep < MODULE_NAME > lsmod | grep serio_raw echo < MODULE_NAME > > /etc/modules-load.d/< MODULE_NAME >.conf lsmod | grep < MODULE_NAME > lsmod Module Size Used by tls 131072 0 uinput 20480 1 snd_seq_dummy 16384 0 snd_hrtimer 16384 1 ... 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... touch /etc/modprobe.d/denylist.conf 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 ... cp /boot/initramfs-USD(uname -r).img /boot/initramfs-USD(uname -r).bak.USD(date +%m-%d-%H%M%S).img cp /boot/initramfs- <VERSION> .img /boot/initramfs- <VERSION> .img.bak.USD(date +%m-%d-%H%M%S) dracut -f -v dracut -f -v /boot/initramfs- <TARGET-VERSION> .img <CORRESPONDING-TARGET-KERNEL-VERSION> reboot dnf install kernel-devel-USD(uname -r) gcc elfutils-libelf-devel #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"); obj-m := test.o make -C /lib/modules/USD(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' 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 cp /root/testmodule/test.ko /lib/modules/USD(uname -r)/ depmod -a modprobe -v test insmod /lib/modules/ 5.14.0-1.el9.x86_64 /test.ko lsmod | grep test test 16384 0 dmesg [ 74422.545004 ] Hello World This is a test