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 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 on GitHub.

Install DKMS

The kernel-native-dkms bundle provides the dkms program and Linux kernel headers, which are required for compiling 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:

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

  2. 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
    
  3. Update the Clear Linux OS bootloader and reboot.

    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 the mixer tool 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 and/or precompiled 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.

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

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

  2. Verify the kernel module is detected by checking the output of the dkms status command.

    dkms status
    
  3. 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 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:

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

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

  3. Add the kernel module to the DKMS tree so that it is tracked by DKMS.

    sudo dkms add -m <MODULE-NAME>
    
  4. 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>
    
  5. 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.

  1. Load the installed module with the modprobe command.

    sudo modprobe <MODULE-NAME>
    
  2. 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