Add kernel modules manually¶
This guide describes how to add kernel modules manually.
Overview¶
Certain kernel modules are enabled by default in Clear Linux* OS. To use additional kernel modules that are not part of the Linux source tree, you may need to build out-of-tree kernel modules. Use this guide to add kernel modules manually, or refer to Add kernel modules with DKMS.
Description¶
Kernel modules are additional pieces of software capable of being inserted into the Linux kernel to add functionality, such as a hardware driver. Kernel modules may already be part of the Linux source tree (in-tree) or may come from an external source, such as directly from a vendor (out-of-tree).
Kernel module availability¶
Clear Linux OS comes with many upstream kernel modules available for use. Using an existing module is significantly easier to maintain and retains signature verification of the Clear Linux OS kernel. For more information on Clear Linux OS security practices, see the OS Security page.
Before continuing, check if the kernel module you’re looking for is already available in Clear Linux OS or submit a request to add the module.
Check if the module is already available¶
You can search for kernel module file names, which end with the .ko
file extension, using the swupd search command, as shown in the
following example. See swupd for more information.
sudo swupd search ${module_name}.ko
Submit a request to add the module¶
If the kernel module you need is already open source (for example, in the Linux kernel upstream) and likely to be useful to others, consider submitting a request to add or enable it in the Clear Linux OS kernel.
Make enhancement requests to the Clear Linux OS Distribution Project on GitHub.
Build, install, and load an out-of-tree module¶
Follow the steps in this section if you are an individual user or testing, and you need an out-of-tree kernel module that is not available through Clear Linux OS. For a more scalable and customizable approach, we recommend using the mixer to provide a custom kernel and updates.
Prerequisites¶
Before you begin, you must:
Disable Secure Boot.
Disable kernel module integrity checking.
Have a kernel module package in the form of source code.
Rebuild the module against new versions of the Linux kernel.
Note
Any time the kernel is upgraded on your Clear Linux system, you must rebuild your out-of-tree modules.
Build and install kernel module¶
Determine which kernel variant is running on Clear Linux OS. In the example below, the native kernel is in use.
$ uname -r 5.XX.YY-ZZZZ.native
Install the kernel dev bundle corresponding to the installed kernel. The kernel dev bundle contains the kernel headers, which are placed under
/usr/lib/modules/$(uname -r)/build/include/
and are required to compile kernel modules. For example:linux-dev for developing against the native kernel.
linux-lts-dev for developing against the LTS kernel.
sudo swupd bundle-add linux-dev
Follow instructions from the kernel module source code to compile the kernel module. For example:
curl -O http://<URL-TO-KERNEL-MODULE-SOURCE>.tar.gz tar -xvf <KERNEL-MODULE-SOURCE>.tar.gz cd <KERNEL-MODULE-SOURCE>/ cat README
Load kernel module¶
Disable Secure Boot in your system’s UEFI settings, if you have enabled it. The loading of new out-of-tree modules modifies the signatures that Secure Boot relies on for trust.
Disable signature checking for the kernel by modifying the kernel boot parameters and reboot the system.
All kernel modules from Clear Linux OS have been signed to enforce kernel security. However, out-of-tree modules break this chain of trust so this mechanism needs to be disabled.
sudo mkdir -p /etc/kernel/cmdline.d echo "module.sig_unenforce" | sudo tee /etc/kernel/cmdline.d/allow-unsigned-modules.conf
Update the boot manager and reboot the system to implement the changed kernel parameters.
sudo clr-boot-manager update sudo reboot
Note
If successful, the clr-boot-manager update command does not return any console output.
After rebooting, manually load out-of-tree modules using the insmod command.
sudo insmod </PATH/TO/MODULE.ko>
Examples¶
Optional: Specify module options and aliases¶
Use the modprobe command to load a module and set options.
modprobe may add or remove more than one module due to module
interdependencies. You can specify which options to use with individual
modules, by using configuration files under the /etc/modprobe.d
directory.
sudo mkdir /etc/modprobe.d
All files underneath the /etc/modprobe.d
directory that end with the
.conf
extension specify module options to use when loading. You can
use .conf
files to create convenient aliases for modules or to
override the normal loading behavior altogether for those with special
requirements.
Learn more about modprobe on the modprobe.d manual page:
man modprobe.d
Optional: Configure kernel modules to load at boot¶
Use the /etc/modules-load.d
configuration directory to specify kernel
modules to load automatically at boot.
sudo mkdir /etc/modules-load.d
All files underneath the /etc/modules-load.d
directory that end with
the .conf
extension contain a list of module names of aliases (one per
line) to load at boot.
Learn more about module loading in the modules-load.d manual page:
man modules-load.d