sysctl_setting
A Kubernetes node, a router, or a busy file watcher needs kernel settings
that differ from the defaults. sysctl_setting manages one kernel setting:
the value that sysctl shows and the kernel keeps under /proc/sys. MMX
sets the value now, and keeps it for the next boot in its own file,
/etc/sysctl.d/90-mmx-<name>.conf.
A setting that a kernel module adds exists only while that module is
loaded; kernel_module loads it.
Inputs
name(string; required): as sysctl writes it, such as net.ipv4.ip_forward; when a part has a dot in it, such as the interface eth0.10, write slashes between all the parts: net/ipv4/conf/eth0.10/rp_filter. A name the kernel does not have fails the task before any changevalue(string; required): the value as sysctl shows it, such as "1"; compared word by word, so "32768 60999" matches the kernel's tab; a value the kernel refuses fails the task with its message; omit with boot_setting_removed_live_value_keptstate(presentorboot_setting_removed_live_value_kept; defaultpresent): boot_setting_removed_live_value_kept deletes MMX's configuration file and accepts only name; the current kernel value stays until boot-time configuration is applied at the next boot
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.live_value_beforevalue.live_value_after
What a dryrun reports
Supported; reports the old and the new live value and the difference of MMX's file; a name the kernel does not have yet is not checked, because an earlier kernel_module task may add it. A file applied at boot after MMX's that sets the setting to another value fails the task, in a dryrun too.
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
Settings for a Kubernetes node
- kernel_module:
name: br_netfilter
- id: kernel_settings
loop:
net.ipv4.ip_forward: "1"
net.bridge.bridge-nf-call-iptables: "1"
fs.inotify.max_user_instances: "1048576"
as: setting
sysctl_setting:
name: "{{ .setting.key }}"
value: "{{ .setting.value }}"
The first node task loads the kernel module br_netfilter on the node now
and at every boot. The loop then sets three kernel settings, one node task
for each. The second setting exists only while br_netfilter is loaded,
which is why the kernel_module node task comes first.
A setting of a VLAN interface
- sysctl_setting:
name: net/ipv4/conf/eth0.10/rp_filter
value: "2"
A name that has a part with a dot in it, such as the VLAN interface
eth0.10, is written with slashes between all its parts. MMX keeps the
setting's name and value in 90-mmx-net.ipv4.conf.eth0.10.rp_filter.conf.
A name with slashes gets dots in the file name.
Remove MMX's file
- sysctl_setting:
name: fs.inotify.max_user_instances
state: boot_setting_removed_live_value_kept
state: boot_setting_removed_live_value_kept takes only name and deletes MMX's file. The live value
stays as it is, because MMX does not know the value the node would have
without the file; the next boot decides it.
How it works
nameis written assysctlwrites it, such asnet.ipv4.ip_forward.valueis text, assysctlshows it; quote a number, such as"1". MMX compares values word by word, so"32768 60999"matches the kernel's32768 60999, which has a tab.- MMX reads the live value from
/proc/sys. When the live value differs fromvalue, MMX writesvalueto the setting's file under/proc/sysand reportsvalue.live_value_beforeandvalue.live_value_after. - Only the kernel setting in
nameis applied: MMX does not restartsystemd-sysctl.service, which would apply every setting file again. - For the next boot, MMX keeps the setting in its own file,
/etc/sysctl.d/90-mmx-<name>.conf, which holds one line, such asnet.ipv4.ip_forward = 1. - The module needs nothing installed beyond what the tested distributions have.
- A dryrun reports the old and the new value. A name the kernel does not
have yet is not checked in a dryrun, because an earlier
kernel_modulenode task may add it.
Which file wins at boot
At boot, systemd-sysctl applies the .conf files of /etc/sysctl.d/,
/run/sysctl.d/, /usr/local/lib/sysctl.d/, and /usr/lib/sysctl.d/. A
file in an earlier directory of that list hides a file of the same name in a
later one; that is how a link to /dev/null in /etc/sysctl.d/ switches a
vendor file off. The remaining files apply in the order of their names,
whatever their directory, and the last value of a setting wins.
sysctl --system reads the same files and then /etc/sysctl.conf. Every tested distribution except Debian 13 also links that file
into /etc/sysctl.d/ as 99-sysctl.conf, so systemd-sysctl reads it
there too. MMX therefore counts /etc/sysctl.conf as the last file
everywhere.
When a file that comes after MMX's sets the same setting to another value,
the node task fails and names that file, because the node would boot with
the other value; in a dryrun too. A pattern such as
net.ipv4.conf.*.rp_filter in a later file does not count:
systemd-sysctl lets a named setting win over a pattern.
Errors and what they mean
A failure that another try cannot fix is not tried again: a refused value, or a later file that assigns a conflicting value to the requested kernel setting.
| The reason holds | What the error means, and what to do |
|---|---|
the kernel has no setting ... (... does not exist); check the setting name, or add a kernel_module task before the sysctl_setting task to load the kernel module that provides the setting |
A name the kernel does not have fails the node task before any change, so a misspelled name is never kept in a file that the kernel ignores. Check the spelling, or load the kernel module first. |
the kernel refused ... = ...: ... |
The kernel refused the value, such as a setting that a container may not change. The reason ends with the kernel's message, and MMX's file keeps its old line. |
... sets the managed kernel setting to ... after MMX's file ... is applied, so the node would boot with ...; remove the conflicting kernel setting from ..., or manage the kernel setting in the conflicting file instead of with MMX |
A later file sets the setting to another value; see Which file wins at boot. Remove the line from that file, or set the value there instead of with MMX. |
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 virtual machines
with Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, and AlmaLinux 10. Virtual machines are needed because kernel settings belong to the
kernel, which a container shares with the container's host.
The suite tests/integration/kernel_settings.py checks the values in
/proc/sys and runs systemd-sysctl as the next boot runs systemd-sysctl.
The validation record has the latest results.
Why it works this way
sysctl_setting, not a file in/etc/sysctl.d/with a restart ofsystemd-sysctl.service. Kernel settings are common in real projects: 46 independent authors set them in the Ansible projects MMX was checked against. With afilenode task and a restart ofsystemd-sysctl.service, MMX reports only the file's difference. Thefilenode task silently keeps misspelled setting names, and the service restart applies every setting file again.sysctl_settingcompares the live value, refuses a name the kernel does not have, and applies only the requested kernel setting.- A later file fails the task. The node would otherwise boot with another value than the one the run reported.
state: boot_setting_removed_live_value_keptleaves the live value alone. MMX does not know the value the node would have without/etc/sysctl.d/90-mmx-<name>.conf.
This page is docs/reference/modules/sysctl_setting.md in the MMX repository.