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

In cases where drivers beyond those enabled by default in Clear Linux* OS are needed it may be necessary to manually build out-of-tree modules.

Out-of-tree kernel modules can be can be manually built and maintained. Out-of-tree kernel modules can also be managed with the Dynamic Kernel Module System (DKMS) on Clear Linux OS using the instructions in this document.

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

Kernel module availability in Clear Linux OS

Before continuing, check if the kernel module you’re looking for is already available in Clear Linux OS or can be requested.

Check if the module is already available

Clear Linux OS comes with many upstream kernel modules available for use. If you require a kernel module, be sure to check whether it is already available in Clear Linux OS first.

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.

You can search for kernel module file names, which end with the .ko file extension, using the swupd search command. For example: sudo swupd search ${module_name}.ko. See swupd for more information.

Request the module be added to Clear Linux OS

If the kernel module you need is already open source (e.g. in the Linux upstream) and likely to be useful to others, consider submitting a request to add or enable in the Clear Linux OS kernel.

Make enhancement requests to the Clear Linux OS distribution on GitHub .

Install DKMS on Clear Linux OS

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 modules signature verification by appending a kernel command-line parameter (module.sig_unenforce) from /usr/share/kernel/cmdline.d/clr-ignore-mod-sig.conf.
  • Adds a notification to the Message of the Day (MOTD) indicating kernel modules signature verification is disabled.

Warning

  1. It is important to always review the output of swupd update to make sure kernel modules rebuilt against the new kernel successfully. 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. 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

In some cases you may need an out-of-tree kernel module that is not available through Clear Linux OS.

Prerequisites

You can build and load out-of-tree kernel modules, however you must:

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

This approach works well for individual use or testing. For a more scalable and customizable approach, consider using the mixer tool to provide a custom kernel and updates.

Obtain kernel module source

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

Kernel modules may come packaged as:

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

Precompiled kernel module binaries will not work on Clear Linux OS because it 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, a dkms.conf file will need to be manually created.

  1. Download the kernel module’s source code.

    • Review the available download options. Some kernel modules provide separate archives which 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 will complete many steps for you.

The archive will contain 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 will place the kernel module source under /usr/src/<MODULE-NAME>-<MODULE-VERSION>/, build if necessary, and add the module into the dkms tree.

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

    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, it needs to be manually created.

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

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

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
    

    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> should match the entries in dkms.conf

  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, the dkms.conf may need to be adjusted.

    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>
    

Optional: Specify module options and aliases

Use the modprobe command to load a module and set options.

Because modprobe may add or remove more than one module due to modules having dependencies, a method of specifying what options are to be used with individual modules is useful. This can be done with 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. This can also be used to create convenient aliases for modules or they can override the normal loading behavior altogether for those with special requirements.

You can find more info on module loading in 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.

You can find more info on module loading in the modules-load.d manual page:

man modules-load.d