Add kernel modules with DKMS¶

This guide describes how to add kernel modules with DKMS.

Overview
Description
Kernel module availability
Install DKMS
Build, install, and load an out-of-tree module
Examples
Related topics

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 with DKMS or refer to Add kernel modules manually.

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

DKMS is a framework that facilitates the building and installation of kernel modules. DKMS allows Clear Linux OS to provide hooks that automatically rebuild modules against new kernel versions.

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.

Install DKMS ¶

The kernel-native-dkms bundle provides the DKMS program and Linux kernel headers, which are placed under /usr/lib/modules/$(uname -r)/build/include/ and are required to compile kernel modules.

The kernel-native-dkms bundle also:

Adds a systemd update trigger (/usr/lib/systemd/system/dkms-new-kernel.service) to automatically run DKMS to rebuild modules after a kernel upgrade occurs with swupd update.
Disables kernel module signature verification by appending a kernel command-line parameter (module.sig_unenforce) from the /usr/share/kernel/cmdline.d/clr-ignore-mod-sig.conf file.
Adds a notification to the Message of the Day (MOTD) indicating kernel module signature verification is disabled.

Warning

We recommend that you always review the swupd update output to make sure kernel modules were successfully rebuilt against the new kernel. This is especially important for systems where a successful boot relies on a kernel module.

Install the kernel-native-dkms or kernel-lts-dkms bundle.

Determine which kernel variant is running on Clear Linux OS. Only the native and lts kernels are enabled to build and load out-of-tree kernel modules with DKMS.
```
$ uname -r
5.XX.YY-ZZZZ.native
```
Ensure .native or .lts is in the kernel name.
Install the DKMS bundle corresponding to the installed kernel. Use kernel-native-dkms for the native kernel or kernel-lts-dkms for the lts kernel.
```
sudo swupd bundle-add kernel-native-dkms
```
or
```
sudo swupd bundle-add kernel-lts-dkms
```
Update the Clear Linux OS bootloader and reboot, and ensure that you can start the new kernel.
```
sudo clr-boot-manager update
reboot
```

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 mixer to provide a custom kernel and updates.

Prerequisites¶

Before you begin, you must:

Disable Secure Boot in UEFI/BIOS. The loading of new out-of-tree modules modifies the signatures that Secure Boot relies on for trust.
Obtain a kernel module package in the form of source code or pre-compiled binaries.

Obtain kernel module source¶

A required dkms.conf file inside of the kernel module’s source code directory informs DKMS how the kernel module should be compiled.

Kernel modules may come packaged as:

Source code without a dkms.conf file
Source code with a premade dkms.conf file
Source code with a premade dkms.conf file and precompiled module binaries
Precompiled module binaries only (without source code)

Of the package types listed above, only precompiled kernel module binaries will not work, because Clear Linux OS requires kernel modules to be built against the same kernel source tree before they can be loaded. If you are only able to obtain source code without a dkms.conf file, you must manually create a dkms.conf file, described later in this document.

Download the kernel module’s source code.
- Review the available download options. Some kernel modules provide separate archives that are specifically enabled for DKMS support.
- Review the README documentation, because it often provides required information to build the module with DKMS support.
```
curl -O http://<URL-TO-KERNEL-MODULE-SOURCE>.tar.gz
tar -xvf <KERNEL-MODULE-SOURCE>.tar.gz
cd <KERNEL-MODULE-SOURCE>/
cat README
```

Build kernel module with an existing dkms.conf¶

If the kernel module maintainer packaged the source archive with the dkms mktarball command, the entire archive can be passed to the dkms ldtarball which completes many steps for you.

The archive contains the required dkms.conf file, and may contain a dkms_source_tree directory and a dkms_binaries_only directory.

Run the dkms ldtarball command against the kernel module archive.
```
dkms ldtarball <KERNEL-MODULE-SOURCE_WITH_DKMS>.tar.gz
```
dkms ldtarball places the kernel module source under /usr/src/<MODULE-NAME>-<MODULE-VERSION>/, builds it if necessary, and adds the module into the DKMS tree.
Verify the kernel module is detected by checking the output of the dkms status command.
```
dkms status
```

Install the kernel module.

dkms install -m <MODULE-NAME> -v <MODULE-VERSION>

Build kernel module without an existing dkms.conf¶

If the kernel module source does not contain a dkms.conf file or the dkms ldtarball command encounters errors, you must manually create the file.

Review the kernel module README documentation for guidance on what needs to be in the dkms.conf file, including special variables that may be required to build successfully.

Here are some additional resources that can be used for reference:

DKMS manual page (man dkms) shows detailed syntax in the DKMS.CONF section.
Ubuntu community wiki entry for the Kernel DKMS Package shows an example where a single package contains multiple modules.
Sample dkms.conf file in the GitHub* repository for the DKMS project.

Note

AUTOINSTALL=yes must be set in the dkms.conf for the module to be automatically recompiled with Clear Linux OS updates.

The instructions below show a generic example:

Create or modify the dkms.conf file inside of the extracted source code directory.

$ EDITOR dkms.conf

MAKE="make -C src/ KERNELDIR=/lib/modules/${kernelver}/build"
CLEAN="make -C src/ clean"
BUILT_MODULE_NAME=custom_module
BUILT_MODULE_LOCATION=src/
PACKAGE_NAME=custom_module
PACKAGE_VERSION=1.0
DEST_MODULE_LOCATION=/kernel/drivers/other
AUTOINSTALL=yes

This example identifies a kernel module named custom_module with version 1.0.

Copy the kernel module source code into the /usr/src/ directory.
```
sudo mkdir /usr/src/<PACKAGE_NAME>-<PACKAGE_VERSION>
sudo cp -Rv . /usr/src/<PACKAGE_NAME>-<PACKAGE_VERSION>
```
Note

<PACKAGE_NAME> and <PACKAGE_VERSION> must match the entries in the dkms.conf file.
Add the kernel module to the DKMS tree so that it is tracked by DKMS.
```
sudo dkms add -m <MODULE-NAME>
```
Build the kernel module using DKMS. If the build encounters errors, you may need to edit the dkms.conf file.
```
sudo dkms build -m <MODULE-NAME> -v <MODULE-VERSION>
```

Install the kernel module using DKMS.

sudo dkms install -m <MODULE-NAME> -v <MODULE-VERSION>

Load kernel module¶

By default, DKMS installs modules “in-tree” under /lib/modules so the modprobe command can be used to load them.

Load the installed module with the modprobe command.
sudo modprobe <MODULE-NAME>
Validate the kernel module is loaded.
```
lsmod | grep <MODULE-NAME>
```

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

Add kernel modules with DKMS¶

Overview¶

Description¶

Kernel module availability¶