core.sysctl

soul-sidesoulstack.systemsystemroot требуется

Управление kernel-параметрами: runtime-значение плюс persist в /etc/sysctl.d.

core.sysctl приводит kernel-параметры к нужному значению сразу с двух сторон: runtime через sysctl -w и persist-запись в /etc/sysctl.d/, чтобы значение переживало reboot. Состояние present работает с одним параметром, applied — с набором параметров одним детерминированным drop-in (ключи отсортированы, контент воспроизводим между прогонами). Оба состояния идемпотентны: если runtime и persist уже совпадают с целевым — шаг сообщает changed=false. Требует root.

Требования

Rootтребуется
Сторонаsoul-side
Коллекцияsoulstack.system
Категорияsystem

Capabilitiesrun_as_rootexec_subprocessfs_write_root

core.sysctl.present — Один kernel-параметр приведён к значению: runtime (sysctl -w) + persist в /etc/sysctl.d/.

Меняется, когда

runtime-значение отличалось (применён sysctl -w), либо persist-файл отсутствовал или содержал другую строку (перезаписан).

Не меняется, когда

runtime-значение и persist-файл уже совпадают.

Параметры

Параметр	Тип	Обяз. / дефолт	Описание
`name`	`string`	required	Имя kernel-параметра (напр. net.ipv4.ip_forward).
`value`	`string`	required	Желаемое значение.
`filename`	`string`	optional	Имя persist-файла в /etc/sysctl.d (default — name с '.'→'-' + .conf).

Пример — Один параметр персистентно

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

Output

Поле	Тип	Описание
`name`	`string`
`value`	`string`
`path`	`string`	/etc/sysctl.d/<filename>.conf

core.sysctl.applied — Набор параметров материализуется одним детерминированным drop-in (sorted keys) + точечный sysctl -p <file> при изменении.

Меняется, когда

Контент drop-in отличался от существующего или файла не было → атомарная перезапись. Сам reload changed не помечает.

Не меняется, когда

Контент drop-in уже совпадает.

Параметры

Параметр	Тип	Обяз. / дефолт	Описание
`settings`	`map<string>`	required	Map kernel-параметр→значение. Ключи сортируются → контент drop-in детерминирован.
`filename`	`string`	required	Имя drop-in в /etc/sysctl.d (напр. 30-redis); суффикс .conf добавляется автоматически.
`reload`	`string` auto \| always \| never	optional · auto	sysctl -p <file> после записи: auto = только при изменении файла, always = безусловно, never = opt-out. Сам reload changed не помечает (реюз словаря core.service daemon_reload).
`ignore_failures`	`bool`	optional · false	sysctl -e -p (--ignore): глушит read-only/несуществующие ключи в контейнерах. Явный opt-in.

Пример — Набор параметров одним drop-in + точечный reload (ignore_failures для контейнеров)

- 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

Поле	Тип	Описание
`path`	`string`	полный путь drop-in
`settings`	`int`	число применённых ключей

Справочник

reload — перечитывание drop-in (applied)

applied пишет drop-in, но запись файла сама по себе не меняет runtime-значения — их применяет отдельный sysctl -p <file> (точечно по этому drop-in, не весь --system). reload решает, когда его делать; на changed reload не влияет.

Значение	Поведение
auto (default)	sysctl -p <file> только при реальном изменении drop-in. Файл совпал — reload не делается.
always	sysctl -p <file> безусловно, даже если файл не менялся.
never	Явный opt-out — reload не делается никогда, только запись файла.

Заметки

present приводит к согласованности обе стороны сразу: runtime (sysctl -w, действует немедленно) и persist в /etc/sysctl.d/<filename>.conf (переживает reboot).
Multi-value ключи (tab-разделённые) нормализуются перед сравнением, чтобы пробелы vs табы не давали ложного diff.
Пустой settings ({}) в applied — ранний no-op: файл не пишется, reload не делается, changed=false.
Отдельного state для удаления persist-записи в MVP нет; откат — present/applied с верным значением (модуль перезапишет и runtime, и файл).
Требует root: sysctl -w / sysctl -p и запись в /etc/sysctl.d/.

Безопасность и умолчания

Главный риск — изменение kernel-параметра под root: параметр глобален для всего хоста, неверное значение = DoS (слишком малый fs.file-max валит процессы на лимитах, net.* рвёт сеть) или ослабление защиты ядра.
Валидации значения и имени нет (by design MVP): value уходит в sysctl -w буквально, невалидное значение ловит сам sysctl (non-zero exit → шаг падает), а не модуль.
value и name из input.* / register.* / soulprint.* должны быть доверенными (автор Destiny/scenario), а не внешним вводом.
filename нормализуется (.→-, суффикс .conf), но путь всегда внутри /etc/sysctl.d/ — записать persist-файл за пределы каталога через filename нельзя.
Персистентность усиливает цену ошибки: неверное значение не «само починится» после reboot — оно сохранено в /etc/sysctl.d/ и применяется снова.