kernel_module
Some nodes need a kernel module that is not loaded by default, such as
br_netfilter on a Kubernetes node. kernel_module manages one loadable
kernel module: it loads the module now with modprobe, and names it in
/etc/modules-load.d/mmx-<name>.conf, which systemd-modules-load reads
at every boot. MMX keeps the kernel module's options in
/etc/modprobe.d/mmx-<name>.conf.
Use a separate sysctl_setting node task to configure
a kernel setting made available by the kernel module.
Place the sysctl_setting node task after the kernel_module node task.
Inputs
name(string; required): as lsmod shows it, such as br_netfilter; a module that does not exist for the running kernel fails the task with modprobe's message; a module built into the kernel counts as loadedoptions(mapping of option name to text; optional): omitted keeps the saved options file; {} deletes the saved options file. For example: {hashsize: "65536"}. MMX saves the options in one options line for modprobe and compares the requested values with/sys/module/<name>/parameters/. A loaded module keeps the current option values until the module is loaded again. If the loaded values differ, the node task writes the files and fails with instructions to unload the module or reboot. A module built into the kernel refuses options because built-in module options belong on the kernel command line.state(loadedorunloaded; defaultloaded): unloaded accepts only name; deletes MMX's two files and unloads the module with modprobe -r; a module in use fails the task with modprobe's message
Outputs
The node task's result holds these fields. A later node task reads them as .node_tasks.<id>.<field>, where <id> is the node task's id.
statuschangevalue.loaded_beforevalue.loaded_aftervalue.files_changed
What a dryrun reports
Supported; reports whether the module would be loaded or unloaded, and the difference of each file; a module modprobe cannot find yet is not checked, because an earlier task may install it; needs modprobe from the package kmod.
Retries and time limits
Bounded automatic retries by default; retry: false turns them off.
The node task takes the time limits time_limit and time_limit_per_try; without them, the project's node_task_defaults apply. mmx describe-module task describes the settings every node task accepts.
Examples
Load a module for a Kubernetes node
- kernel_module:
name: br_netfilter
- sysctl_setting:
name: net.bridge.bridge-nf-call-iptables
value: "1"
The first node task loads the kernel module br_netfilter on the node now
and at every boot. The setting of the second node task exists only while
br_netfilter is loaded, which is why the kernel_module node task comes
first. The page of sysctl_setting
shows more settings for such a node.
On AlmaLinux 10, br_netfilter is in the package
kernel-modules-extra; install it with a dnf_package
node task before the kernel_module node task. That package installs the
modules for the newest kernel, so a node that has not rebooted into its
newest kernel yet finds the module only after that reboot.
Load a module with options
- kernel_module:
name: nf_conntrack
options:
hashsize: "65536"
MMX keeps the options as one options line in
/etc/modprobe.d/mmx-nf_conntrack.conf, which modprobe reads whenever it
loads the module. MMX compares the node task's options values with the
values the loaded module shows under /sys/module/nf_conntrack/parameters/.
Unload a module
- kernel_module:
name: br_netfilter
state: unloaded
state: unloaded takes only name. MMX deletes its two files and unloads
the module with modprobe -r.
How it works
- MMX reads
/proc/modulesand loads a missing module now withmodprobe. - MMX writes a module's name with underscores, as the kernel lists it, so
br-netfilterandbr_netfilterare the same module and the same file. - A module that is built into the kernel counts as loaded. The
kernel_modulenode task takes nooptionsfor a built-in module, becausemodprobecannot give options to the built-in module. Options for a built-in module belong on the kernel command line, as<name>.<option>=<value>, so the node task refusesoptions. A built-in module cannot be unloaded either. - A module that is already loaded with other option values keeps them until
it is loaded again. MMX never unloads a module that something may use.
The
kernel_modulenode task then writes/etc/modules-load.d/mmx-<name>.confand/etc/modprobe.d/mmx-<name>.conf. The node task then fails. The error message says to unload the module (modprobe -r <name>, or akernel_modulenode task withstate: unloaded) or to reboot the node. After the unload,mmx resumeloads the module with the new options. - An option that the module does not show under
/sys/module/<name>/parameters/cannot be compared, so MMX does not compare it. An option whose value is yes or no shows asYorNunder/sys/module/<name>/parameters/. MMX reads1,y, andonasY, and0,n, andoffasN, as the kernel does. - The result's
value.loaded_beforeandvalue.loaded_aftersay whether the module was loaded before the node task and after it, when that changes, andvalue.files_changedlists the files MMX wrote or deleted. With--diff, the result shows the difference of each file. A dryrun reports whether the module would be loaded or unloaded and the difference of each file. - MMX's
kernel_moduleneeds nothing installed beyond what the tested distributions have: it runsmodprobefrom the packagekmod.
Errors and what they mean
A failure that another try cannot fix is not tried again: a built-in module
with options or state: unloaded, and a module loaded with other options.
| The reason holds | What the error means, and what to do |
|---|---|
modprobe cannot load the kernel module ... for the running kernel: ... |
The module does not exist for the running kernel. The reason ends with modprobe's message. MMX wrote no file, so a misspelled name never fails systemd-modules-load at the next boot. A dryrun reports the node task not checked, because an earlier node task may install the package that brings the module. |
the kernel module ... is loaded with options that differ from the node task (...); ... |
MMX wrote both files. Unload the module (modprobe -r <name>, or a kernel_module node task with state: unloaded) and run again, or reboot the node. |
the kernel module ... is built into the kernel, so modprobe cannot set the module options; set the options on the kernel command line instead, as ... |
Put the options on the kernel command line, as <name>.<option>=<value>. |
the kernel module ... is built into the kernel and cannot be unloaded |
A built-in module cannot be unloaded. |
Module bridge is in use |
state: unloaded failed with modprobe's message, because something uses the module. |
modprobe is not installed; install the package kmod first |
Install kmod in an earlier node task. A dryrun reports the kernel_module node task as not_checked. |
Tested on
Distributions: Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10.
The suite tests/integration/kernel_settings.py runs in a virtual machine
on Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, and AlmaLinux 10, because kernel modules belong to the
kernel, which a container shares with its host: Debian 12 and 13, Ubuntu
24.04 and 26.04, Rocky Linux 9, and AlmaLinux 10. It checks /proc/modules
and /sys/module, and runs systemd-modules-load as the next boot runs it.
The validation record has the latest results.
Why it works this way
- A module, not a file in
/etc/modules-load.d/. Kernel modules are common in real projects: 26 independent authors load them in the Ansible projects MMX was checked against. MMX'skernel_modulerefuses a name the running kernel does not have, before it writes a file. - MMX never unloads a module that something may use. A module loaded with other options therefore keeps them, and the node task fails and says what to do.
Omitting options keeps the saved options file. Writing options: {} deletes
/etc/modprobe.d/mmx-<name>.conf, following the
omission rule.
Preserving saved options when options is omitted prevents a node task
that only loads a kernel module from discarding saved settings.
This page is docs/reference/modules/kernel_module.md in the MMX repository.