core.sysctl

soul-sidesoulstack.systemsystemroot required

Manage kernel parameters: the runtime value plus persist in /etc/sysctl.d.

core.sysctl brings kernel parameters to the required value from two sides at once: runtime via sysctl -w and a persist entry in /etc/sysctl.d/ so the value survives a reboot. The present state works with a single parameter, applied with a set of parameters in one deterministic drop-in (keys sorted, content reproducible between runs). Both states are idempotent: if runtime and persist already match the target, the step reports changed=false. Requires root.

Requirements

Rootrequired
Sidesoul-side
Collectionsoulstack.system
Categorysystem

Capabilitiesrun_as_rootexec_subprocessfs_write_root

core.sysctl.present — A single kernel parameter is brought to a value: runtime (sysctl -w) + persist in /etc/sysctl.d/.

Changes when

The runtime value differed (sysctl -w was applied), or the persist file was missing or contained a different line (rewritten).

Stays unchanged when

The runtime value and the persist file already match.

Parameters

Param	Type	Required / default	Description
`name`	`string`	required	Kernel parameter name (e.g. net.ipv4.ip_forward).
`value`	`string`	required	Desired value.
`filename`	`string`	optional	Persist file name in /etc/sysctl.d (default — name with '.'→'-' + .conf).

Example — A single parameter persistently

- name: Enable IPv4 forwarding persistently
  module: core.sysctl.present
  params:
    name: net.ipv4.ip_forward
    value: "1"

Output

Field	Type	Description
`name`	`string`
`value`	`string`
`path`	`string`	/etc/sysctl.d/<filename>.conf

core.sysctl.applied — A set of parameters is materialized as one deterministic drop-in (sorted keys) + a targeted sysctl -p <file> on change.

Changes when

The drop-in content differed from the existing one or the file was missing → an atomic rewrite. The reload itself does not mark changed.

Stays unchanged when

The drop-in content already matches.

Parameters

Param	Type	Required / default	Description
`settings`	`map<string>`	required	Map of kernel parameter→value. Keys are sorted → drop-in content is deterministic.
`filename`	`string`	required	Drop-in name in /etc/sysctl.d (e.g. 30-redis); the .conf suffix is added automatically.
`reload`	`string` auto \| always \| never	optional · auto	sysctl -p <file> after the write: auto = only when the file changed, always = unconditionally, never = opt-out. The reload itself does not mark changed (reuses the core.service daemon_reload vocabulary).
`ignore_failures`	`bool`	optional · false	sysctl -e -p (--ignore): suppresses read-only/nonexistent keys in containers. Explicit opt-in.

Example — A set of parameters in one drop-in + a targeted reload (ignore_failures for containers)

- name: Apply redis sysctl kernel parameters
  module: core.sysctl.applied
  params:
    filename: 30-redis
    reload: auto
    ignore_failures: true
    settings:
      vm.overcommit_memory: "1"
      vm.swappiness: "1"
      net.core.somaxconn: "65535"

Output

Field	Type	Description
`path`	`string`	full path of the drop-in
`settings`	`int`	number of applied keys

Reference

reload — re-reading the drop-in (applied)

applied writes the drop-in, but writing the file by itself does not change the runtime values — a separate sysctl -p <file> applies them (targeted at this drop-in, not the whole --system). reload decides when to do it; reload does not affect changed.

Value	Behavior
auto (default)	sysctl -p <file> only when the drop-in actually changed. If the file already matches, no reload is done.
always	sysctl -p <file> unconditionally, even if the file did not change.
never	Explicit opt-out — reload is never done, only the file write.

Notes

present reconciles both sides at once: runtime (sysctl -w, effective immediately) and persist in /etc/sysctl.d/<filename>.conf (survives a reboot).
Multi-value keys (tab-separated) are normalized before comparison so that spaces vs tabs do not produce a false diff.
An empty settings ({}) in applied is an early no-op: the file is not written, no reload is done, changed=false.
There is no separate state for removing the persist entry in the MVP; the rollback is present/applied with the correct value (the module overwrites both runtime and the file).
Requires root: sysctl -w / sysctl -p and writing to /etc/sysctl.d/.

Security & defaults

The main risk is changing a kernel parameter as root: the parameter is global to the whole host, and a wrong value = DoS (too low an fs.file-max crashes processes at their limits, net.* breaks networking) or a weakening of the kernel's protections.
There is no validation of the value or the name (by design in the MVP): value goes to sysctl -w literally, and an invalid value is caught by sysctl itself (non-zero exit → the step fails), not by the module.
value and name from input.* / register.* / soulprint.* must be trusted (the Destiny/scenario author), not external input.
filename is normalized (. → -, a .conf suffix), but the path is always inside /etc/sysctl.d/ — you cannot write a persist file outside the directory through filename.
Persistence raises the cost of a mistake: a wrong value does not "fix itself" after a reboot — it is saved in /etc/sysctl.d/ and applied again.