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 change
  • value (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_kept
  • state (present or boot_setting_removed_live_value_kept; default present): 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.

  • status
  • change
  • value.live_value_before
  • value.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

  • name is written as sysctl writes it, such as net.ipv4.ip_forward.
  • value is text, as sysctl shows it; quote a number, such as "1". MMX compares values word by word, so "32768 60999" matches the kernel's 32768 60999, which has a tab.
  • MMX reads the live value from /proc/sys. When the live value differs from value, MMX writes value to the setting's file under /proc/sys and reports value.live_value_before and value.live_value_after.
  • Only the kernel setting in name is applied: MMX does not restart systemd-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 as net.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_module node 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 of systemd-sysctl.service. Kernel settings are common in real projects: 46 independent authors set them in the Ansible projects MMX was checked against. With a file node task and a restart of systemd-sysctl.service, MMX reports only the file's difference. The file node task silently keeps misspelled setting names, and the service restart applies every setting file again. sysctl_setting compares 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_kept leaves 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.