From 568a96d31ece3d48d0323fca89e31f89a259aa6f Mon Sep 17 00:00:00 2001
From: Tommaso Bailetti <tommaso.bailetti@nethesis.it>
Date: Wed, 14 Oct 2026 15:52:16 +0200
Subject: [PATCH 01/13] feat: added background management skill

---
 .agents/skills/ns-background-work/SKILL.md    | 262 ++++++++++++++++++
 .../ns-background-work/references/hotplug.md  |  86 ++++++
 .../references/procd-init.md                  | 166 +++++++++++
 3 files changed, 514 insertions(+)
 create mode 100644 .agents/skills/ns-background-work/SKILL.md
 create mode 100644 .agents/skills/ns-background-work/references/hotplug.md
 create mode 100644 .agents/skills/ns-background-work/references/procd-init.md

diff --git a/.agents/skills/ns-background-work/SKILL.md b/.agents/skills/ns-background-work/SKILL.md
new file mode 100644
index 000000000..35468d481
--- /dev/null
+++ b/.agents/skills/ns-background-work/SKILL.md
@@ -0,0 +1,262 @@
+---
+name: ns-background-work
+description: Pick and write the right mechanism for code that runs on its own on a NethSecurity device — a procd daemon, a procd one-shot job, a cron job, a hotplug handler or a uci-default. Use whenever a task needs something to run periodically, at boot, on a config change, on an interface event, persistently in the background, or once after install/upgrade, even when the user just says "schedule", "keep running", "every N minutes", "on startup", "when the WAN comes up" or "service". Also use it when editing any `/etc/init.d` procd script or `/etc/hotplug.d` handler, or when looking up `procd_set_param` params, procd triggers, or hotplug `ACTION`/environment variables. Covers the decision, canonical templates, package install/upgrade/remove behavior, full procd and hotplug references, and on-device checks.
+metadata:
+  domain: nethsecurity-packages
+  type: runtime
+---
+
+## Pick the mechanism
+
+| Need | Mechanism |
+|---|---|
+| Process that stays up (server, listener, forwarder) | procd daemon |
+| Job that must run at boot and/or when a UCI config changes, maybe also periodically | procd one-shot, kicked by cron when periodic |
+| Periodic housekeeping only (cleanup, rotation), no boot or config-change run | cron calling the script directly |
+| React to an interface going up/down | hotplug handler in `/etc/hotplug.d/iface/` |
+| One-time setup or migration after install, upgrade or first boot | uci-default |
+
+When unsure between cron-direct and one-shot: if the job ever needs to run outside its schedule (boot, config change, API trigger), it's a one-shot.
+
+Going through procd for periodic jobs gives syslog output for free and no overlapping runs: `/etc/init.d/X start` on a still-running instance with unchanged params is a no-op (procd `instance_update`).
+
+Keepalived/HA events are not covered here.
+
+## References
+
+The templates below cover the common case. For anything they don't show, read the matching reference before writing code instead of guessing a `procd_*` helper or a hotplug variable:
+
+- `references/procd-init.md` — every init action and what it really does, all `procd_set_param` params, all trigger helpers (UCI, interface, mount, data, raw), signals, extra commands, jails, debugging. Read it for multiple instances, reload via signal, interface- or mount-bound services, running as a non-root user, or custom actions.
+- `references/hotplug.md` — how iface and other subsystems dispatch scripts, every `ACTION` and environment variable per subsystem, debugging. Read it for any event other than `iface` `ifup`/`ifdown`.
+
+Both list the upstream sources (OpenWrt wiki and source files pinned to the release tag). Prefer those over memory when something isn't covered.
+
+## Package lifecycle facts (OpenWrt v25.12, apk)
+
+These come from `default_postinst`/`default_prerm` in `package/base-files/files/lib/functions.sh` and `include/package-pack.mk`. Re-check them if `OWRT_VERSION` in `build.conf.defaults` changes.
+
+- **Fresh install**: package uci-defaults run (then `uci commit`), then every shipped init script is **enabled and started**, then the Makefile `postinst` body runs.
+- **Upgrade**: same, with `PKG_UPGRADE=1`. Uci-defaults run again. Init scripts are **started but not enabled** — an init script that's new in this version stays disabled unless a uci-default enables it.
+- **Image build**: init scripts get enabled in the rootfs; uci-defaults run at first boot (`/etc/init.d/boot`, `START=10`, before cron at 50).
+- **Image upgrade (sysupgrade)**: `/etc/crontabs/` and `/etc/config/` are kept; uci-defaults run again on first boot.
+- **Remove**: `default_prerm` stops and disables shipped init scripts, then the Makefile `prerm` body runs. Prerm does not run on upgrade.
+- A running daemon is **not restarted** by an upgrade: `start` with unchanged params is a no-op, so the old binary keeps running. Restart it in `postinst`.
+
+So every uci-default must be idempotent, and anything the package adds outside its own files (cron lines) must be removed in `prerm`.
+
+## Cron rules
+
+- Add the line from a package uci-default, remove it in `prerm`.
+- Always write through `crontab -`. It drops `cron.update`, which busybox crond picks up within a minute. A plain `echo >> /etc/crontabs/root` is **ignored** until crond restarts (tested on a live device).
+- Jitter with `sleep $(( RANDOM % N ))` when the job contacts a remote endpoint (controller, my, update servers, any public API). Local housekeeping runs at a fixed time, no jitter.
+- Match the line by the command path, not the whole line, so a schedule change in a later release replaces the old line.
+
+## Templates
+
+All files carry the license header. Shell init and hotplug scripts use the procd helpers shown; don't hand-roll pid files or `start-stop-daemon`.
+
+### procd daemon
+
+`packages/ns-foo/files/ns-foo.init`, installed with `$(INSTALL_BIN)` to `/etc/init.d/ns-foo`:
+
+```sh
+#!/bin/sh /etc/rc.common
+
+#
+# Copyright (C) <YEAR> Nethesis S.r.l.
+# SPDX-License-Identifier: GPL-2.0-only
+#
+
+USE_PROCD=1
+START=99
+
+start_service() {
+	config_load ns-foo
+
+	local enabled
+	config_get_bool enabled daemon enabled 0
+	[ "$enabled" -eq 0 ] && return 0
+
+	local log_level
+	config_get log_level daemon log_level "info"
+
+	procd_open_instance
+	procd_set_param command "/usr/sbin/ns-foo"
+	procd_append_param command "-log-level"
+	procd_append_param command "$log_level"
+	procd_set_param stdout 1
+	procd_set_param stderr 1
+	procd_set_param respawn 3600 5 0
+	procd_close_instance
+}
+
+service_triggers()
+{
+	procd_add_reload_trigger "ns-foo"
+}
+
+reload_service()
+{
+	stop
+	start
+}
+```
+
+- On/off is the UCI `enabled` option; the init script itself stays enabled. Turning it on or off is a UCI change, and the reload trigger applies it on `ns.commit`.
+- `reload_service` is `stop; start` because the default reload is just `start`, which procd ignores while the command line is unchanged. A config value the daemon reads itself would never be applied. If the daemon re-reads config on a signal, use `procd_set_param reload_signal HUP` and drop `reload_service` instead.
+- `START`: 99 unless something depends on it starting earlier.
+- Add other configs the daemon reads to `procd_add_reload_trigger` (e.g. `"ns-foo" "ns-plug"`).
+- Never put secrets on the command line (visible in `ps`). Write them to a `umask 077` file under `/var/run/ns-foo/` and pass the path, as `vmalert.initd` does.
+- Makefile:
+
+```makefile
+define Package/ns-foo/postinst
+#!/bin/sh
+[ -z "$${IPKG_INSTROOT}" ] && /etc/init.d/ns-foo restart
+exit 0
+endef
+```
+
+### procd one-shot (optionally periodic)
+
+`packages/ns-foo/files/ns-foo-update.init` → `/etc/init.d/ns-foo-update`:
+
+```sh
+#!/bin/sh /etc/rc.common
+
+#
+# Copyright (C) <YEAR> Nethesis S.r.l.
+# SPDX-License-Identifier: GPL-2.0-only
+#
+
+USE_PROCD=1
+START=50
+
+start_service() {
+	procd_open_instance
+	procd_set_param command "/usr/sbin/ns-foo-update"
+	procd_set_param stdout 1
+	procd_set_param stderr 1
+	procd_close_instance
+}
+
+reload_service()
+{
+	start
+}
+
+service_triggers() {
+	procd_add_reload_trigger "ns-foo"
+}
+```
+
+- No `respawn`: the command runs to completion and exits.
+- The script (`/usr/sbin/ns-foo-update`) exits 0 quickly when there's nothing to do (feature disabled, no subscription), since it runs on every boot, upgrade and config change.
+- When periodic, cron calls `/etc/init.d/ns-foo-update start`, not the script.
+
+uci-default `packages/ns-foo/files/99-ns-foo-update-cron` → `/etc/uci-defaults/99-ns-foo-update-cron`:
+
+```sh
+#!/bin/sh
+
+#
+# Copyright (C) <YEAR> Nethesis S.r.l.
+# SPDX-License-Identifier: GPL-2.0-only
+#
+
+(crontab -l | grep -v '/etc/init.d/ns-foo-update'; echo '8 4 * * * sleep $(( RANDOM % 3600 )); /etc/init.d/ns-foo-update start') | crontab -
+
+# new init scripts are not enabled on package upgrade
+/etc/init.d/ns-foo-update enabled || /etc/init.d/ns-foo-update enable
+```
+
+Makefile:
+
+```makefile
+define Package/ns-foo/prerm
+#!/bin/sh
+if [ -z "$${IPKG_INSTROOT}" ]; then
+	crontab -l | grep -v '/etc/init.d/ns-foo-update' | crontab -
+fi
+exit 0
+endef
+```
+
+### cron calling the script directly
+
+Same uci-default and prerm as above, matching on the script path:
+
+```sh
+(crontab -l | grep -v '/usr/sbin/ns-foo-cleanup'; echo '4 0 * * * /usr/sbin/ns-foo-cleanup') | crontab -
+```
+
+No init script, no enable line.
+
+### hotplug handler (interface events)
+
+`packages/ns-foo/files/hotplug` → `/etc/hotplug.d/iface/90-ns-foo`, installed with `$(INSTALL_DATA)` (it's sourced, not executed):
+
+```sh
+#!/bin/sh
+
+#
+# Copyright (C) <YEAR> Nethesis S.r.l.
+# SPDX-License-Identifier: GPL-2.0-only
+#
+
+[ "$ACTION" = "ifup" ] || exit 0
+
+. /lib/functions/network.sh
+network_flush_cache
+network_find_wan wan_if
+[ "$INTERFACE" = "$wan_if" ] || exit 0
+
+config_load ns-foo
+config_get_bool enabled config enabled 0
+[ "$enabled" -eq 1 ] || exit 0
+
+/etc/init.d/ns-foo-update start
+```
+
+- `hotplug-call` sources each script in a subshell, in name order, and netifd waits for the whole run before dispatching the next interface event. `exit` is fine, but anything slow delays mwan3, the firewall and every later handler. Hand real work to a one-shot (`/etc/init.d/X start`) instead of doing it inline.
+- Filter on `ACTION` and `INTERFACE` first, then read config.
+- Output goes nowhere useful; log with `logger -t ns-foo`.
+
+### uci-default (one-time setup)
+
+Use for UCI seeding, migrations and the cron/enable lines above. Never for recurring work. It runs on install, every package upgrade and first boot after sysupgrade, so guard every change:
+
+```sh
+if ! uci -q get ns-foo.config > /dev/null; then
+	uci -q import ns-foo << EOI
+config main 'config'
+	option enabled '0'
+EOI
+fi
+```
+
+One concern per file: don't mix cron registration into a config-import uci-default.
+
+## Don't copy
+
+These exist in the tree but are not the current pattern:
+
+- `packages/ns-dpi/files/99-dpi-*-cron.uci-defaults` — the "temporary fix" block deletes and re-adds the line on every run via `echo >>`, which crond ignores.
+- `packages/ns-dpi/files/20_dpi` — cron line mixed into a config import (its own TODO says so).
+- `packages/ns-plug/files/20_ns-plug`, `packages/ns-objects/files/20_ns_objects` — `echo >> /etc/crontabs/root`, no cleanup in `prerm`, mixed with other setup.
+- `packages/ns-storage/files/ns-storage-check.init` — plain `rc.common` without procd, writes UCI and the crontab from the init script.
+- `mwan3`, `keepalived`, `adblock`, `banip` — forks of upstream OpenWrt packages that follow upstream style. Keep upstream style when editing them, but don't use them as templates for `ns-*` packages.
+
+Good references: `ns-monitoring/files/ns-flows.init` (daemon with enable flag), `victoria-metrics/files/vmalert.initd` (daemon with a secret), `ns-dpi/files/dpi-data-update.init` (one-shot).
+
+## Verify on a device
+
+```sh
+/etc/init.d/ns-foo enabled && echo enabled
+ubus call service list '{"name":"ns-foo"}'   # instance, running, command line
+logread -e ns-foo                             # procd stdout/stderr
+crontab -l | grep ns-foo
+ls /etc/uci-defaults/                         # a leftover file means the uci-default exited non-zero
+```
+
+Install the package, upgrade it over itself, then remove it, and check after each step that the cron line and service state are what the lifecycle facts above predict.
diff --git a/.agents/skills/ns-background-work/references/hotplug.md b/.agents/skills/ns-background-work/references/hotplug.md
new file mode 100644
index 000000000..dc87984ba
--- /dev/null
+++ b/.agents/skills/ns-background-work/references/hotplug.md
@@ -0,0 +1,86 @@
+# hotplug reference
+
+Covers OpenWrt v25.12 (`OWRT_VERSION` in `build.conf.defaults`). Re-check the sources when the version changes.
+
+Sources:
+
+- Wiki, hotplug (subsystems, variables, examples): https://openwrt.org/docs/guide-user/base-system/hotplug
+- `/sbin/hotplug-call`: https://github.com/openwrt/openwrt/blob/v25.12.5/package/base-files/files/sbin/hotplug-call
+- netifd interface events (`interface-event.c`): https://github.com/openwrt/netifd
+- procd hotplug dispatcher (`hotplug-dispatch.c`) and kernel rules (`hotplug.json`): https://github.com/openwrt/procd, https://github.com/openwrt/openwrt/blob/v25.12.5/package/system/procd/files/hotplug.json
+
+## How scripts get run
+
+Scripts live in `/etc/hotplug.d/<subsystem>/`. Every file in the directory runs for every event of that subsystem, **in name order**, so use a two-digit prefix (`90-ns-foo`). The script has to filter `ACTION` and the other variables itself.
+
+There are two dispatchers:
+
+- **`iface`**: netifd runs `/sbin/hotplug-call iface` with the event in the environment. `hotplug-call` sources `/lib/functions.sh`, then sources each script in a subshell (`( . $script )`). netifd runs one hotplug call at a time and queues the next interface event until it finishes. A slow script delays every later handler **and** the next interface event (e.g. mwan3 and firewall reacting to a WAN change).
+- **Everything else** (`net`, `block`, `usb`, `ntp`, `dhcp`, `neigh`, ...): procd's hotplug dispatcher runs each script as `/bin/sh -c '. /lib/functions.sh; . <script>'` with stdio on `/dev/null`, one after the other.
+
+Consequences for scripts:
+
+- They're sourced, so the file doesn't need the exec bit (install with `$(INSTALL_DATA)`), and `exit` only ends that script.
+- stdout/stderr are lost or useless. Log with `logger -t ns-foo`.
+- Filter first, then do work. Anything long-running goes to a one-shot procd job (`/etc/init.d/ns-foo-x start`) so the dispatcher isn't blocked.
+- `/lib/functions.sh` is already loaded. Source `/lib/functions/network.sh` yourself if you need `network_find_wan`, `network_get_device`, etc.
+
+## Subsystems
+
+Directories present on a NethSecurity 8 device: `acme block dhcp iface ipsec keepalived leds neigh net ntp openvpn tftp tty`. Some are created by packages (`acme`, `ipsec`, `keepalived`, `openvpn`) rather than OpenWrt core. Their variables are documented in those packages, not here.
+
+### iface (netifd logical interfaces)
+
+| `ACTION` | When |
+|---|---|
+| `ifup` | interface came up |
+| `ifdown` | interface went down |
+| `ifupdate` | address/route/prefix/data changed on an up interface |
+| `ifup-failed` | bring-up failed |
+| `iflink` | link came up (before L3 is up) |
+| `create` | interface object created |
+| `reload` | interface config reloaded |
+| `free` | interface object freed |
+
+Variables: `INTERFACE` (logical name, e.g. `wan`), `DEVICE` (Linux device, e.g. `eth1`). On `ifupdate`, `IFUPDATE_ADDRESSES`, `IFUPDATE_ROUTES`, `IFUPDATE_PREFIXES` and `IFUPDATE_DATA` are set to `1` for what changed.
+
+### net (kernel network devices)
+
+`ACTION`: `add`, `remove`. Variables: `INTERFACE` (device name, not the logical one), `DEVICENAME`, `DEVTYPE`, `DEVPATH`, `IFINDEX`, `SUBSYSTEM=net`, `SEQNUM`.
+
+### block (disks, partitions)
+
+`ACTION`: `add`, `remove`, `change` (for example dm-crypt). Variables: `DEVNAME`, `DEVICENAME`, `DEVPATH`, `DEVTYPE` (`disk`/`partition`), `MAJOR`, `MINOR`, `SUBSYSTEM=block`, `SEQNUM`.
+
+### ntp (sysntpd)
+
+`ACTION`: `step`, `stratum`, `unsync`, `periodic`. Variables: `stratum`, `offset`, `freq_drift_ppm`, `poll_interval`. Without sync, a `periodic` event with `stratum=16` fires about every 11 minutes. Use `stratum` to run something once the clock is trustworthy (certificate checks, license validation).
+
+### usb / tty / usbmisc
+
+`ACTION`: `add`, `remove` (`usb` and `tty` also `bind`, `unbind`). Variables: `DEVNAME`, `DEVPATH`, `DEVICENAME`, `MAJOR`, `MINOR`, `SEQNUM`, plus `PRODUCT`, `TYPE`, `BUSNUM`, `DEVNUM`, `DEVTYPE` on `usb`. `bind` also fires at boot for already-plugged devices (coldplug).
+
+### dhcp, neigh, tftp
+
+Emitted by dnsmasq (`dhcp`, `tftp`) and the neighbor tracker (`neigh`). The wiki doesn't list their variables. Dump the environment (below) before relying on any.
+
+## Debugging
+
+Dump the environment of real events:
+
+```sh
+cat > /etc/hotplug.d/iface/00-debug <<'EOF'
+logger -t hotplug "$(env | tr '\n' ' ')"
+EOF
+ifup wan          # or unplug/replug, or wait for the event
+logread -e hotplug
+rm /etc/hotplug.d/iface/00-debug
+```
+
+Fire a handler by hand with a fake event (iface only, since that path goes through `hotplug-call`):
+
+```sh
+ACTION=ifup INTERFACE=wan DEVICE=eth1 /sbin/hotplug-call iface
+```
+
+That runs **every** script in `/etc/hotplug.d/iface/`, not just yours. Do it only on a test device.
diff --git a/.agents/skills/ns-background-work/references/procd-init.md b/.agents/skills/ns-background-work/references/procd-init.md
new file mode 100644
index 000000000..08e0a7f53
--- /dev/null
+++ b/.agents/skills/ns-background-work/references/procd-init.md
@@ -0,0 +1,166 @@
+# procd init scripts reference
+
+Covers OpenWrt v25.12 (`OWRT_VERSION` in `build.conf.defaults`). Facts come from the sources below. When the version changes or something here looks off, re-read those files at the new tag rather than trusting this page.
+
+Sources:
+
+- `package/base-files/files/etc/rc.common` — actions and default handlers: https://github.com/openwrt/openwrt/blob/v25.12.5/package/base-files/files/etc/rc.common
+- `package/system/procd/files/procd.sh` — every `procd_*` helper and the accepted params: https://github.com/openwrt/openwrt/blob/v25.12.5/package/system/procd/files/procd.sh
+- procd daemon (`service/instance.c` decides restart vs no-op): https://github.com/openwrt/procd
+- Wiki, procd init scripts: https://openwrt.org/docs/guide-developer/procd-init-scripts
+- Wiki, init script example: https://openwrt.org/docs/guide-developer/procd-init-script-example
+- Wiki, legacy init scripts: https://openwrt.org/docs/techref/initscripts
+
+## Contents
+
+1. Script skeleton
+2. Actions and what they really do
+3. Functions you can define
+4. `procd_set_param` / `procd_append_param`
+5. Triggers
+6. Signals, status and helpers
+7. Extra commands
+8. Jails
+9. Debugging
+
+## 1. Script skeleton
+
+```sh
+#!/bin/sh /etc/rc.common
+USE_PROCD=1
+START=99        # boot order: /etc/rc.d/S99<name>
+STOP=10         # optional: shutdown order, /etc/rc.d/K10<name>
+```
+
+The process must run in the **foreground**. procd supervises it directly, so a daemon that forks itself away is seen as exited.
+
+## 2. Actions and what they really do
+
+| Action | Behavior with `USE_PROCD=1` |
+|---|---|
+| `start` | Runs `start_service` inside `procd_open_service`/`procd_close_service` and sends the whole service definition to procd ("set"), then calls `service_started` if defined. |
+| `stop` | Runs `stop_service`, asks procd to kill all instances (or the one named in `$1`), then calls `service_stopped` if defined. |
+| `restart` | `stop` then `start`. |
+| `reload` | Calls `reload_service` if defined. **Otherwise it calls `start`.** |
+| `boot` | Same as `start`. Used by `/etc/rc.d/S*` at boot. |
+| `enable` / `disable` | Create or remove the `/etc/rc.d/S<START><name>` (and `K<STOP>`) symlinks. |
+| `enabled` | Exit 0 if those symlinks exist. |
+| `running` | `service_running`, defaulting to `procd_running <name> [instance]`. |
+| `status` | `status_service` if defined, else procd's status of the instances. |
+| `info` | Dumps procd's view of the service (`ubus call service list` with verbose). |
+| `trace` | Starts with syscall tracing (`TRACE_SYSCALLS=1`). |
+
+What `start` does to a service that already exists, per instance (procd `instance_update`):
+
+- **Not running**: started.
+- **Running, definition unchanged**: nothing happens. This is what makes cron'd one-shot jobs safe from overlap.
+- **Running, definition changed**: restarted.
+
+"Definition" means what procd sees: command line, env, `file` checksums, `netdev`, `data`, limits, etc. A daemon that reads its UCI config itself (not through command-line args) looks unchanged to procd. That's why the default `reload` (which is `start`) won't restart it, and NethSecurity daemons define `reload_service() { stop; start; }`.
+
+Because `start` sends the full service definition with method "set", an instance you stop declaring in `start_service` (for example `return 0` when disabled) gets removed. That's how the `enabled` UCI flag pattern stops a daemon on reload.
+
+## 3. Functions you can define
+
+| Function | When it runs |
+|---|---|
+| `start_service` | On `start`/`boot`/default `reload`. Declares instances. |
+| `stop_service` | Before procd kills the instances. Use for cleanup that needs the process still alive or for side effects (removing nft rules). |
+| `service_started` | After `start_service` was sent. |
+| `service_stopped` | After the kill. |
+| `reload_service` | On `reload` (including UCI reload triggers). Without it, reload is `start`. |
+| `service_triggers` | Declares triggers (see 5). Called during `start`. |
+| `service_running` | Override for `running`. |
+| `status_service` | Override for `status`. |
+| `service_data` | Adds service-level data. |
+
+## 4. `procd_set_param` / `procd_append_param`
+
+One function argument per command-line argument. No space splitting: `procd_append_param command "-addr" "$addr"`, never `"-addr $addr"`.
+
+`procd_set_param` replaces the value. `procd_append_param` appends to arrays/tables.
+
+| Param | Type | Meaning |
+|---|---|---|
+| `command` | array | argv of the process |
+| `respawn` | array | `threshold timeout retry`: if the process dies within `threshold` seconds it counts as a failure; wait `timeout` seconds before restarting; give up after `retry` failures (`0` = never give up). With no values: `system.@service[0].respawn_*` or `3600 5 5`. Omit entirely for one-shot jobs. |
+| `env` | table | `procd_set_param env KEY=val KEY2=val2` |
+| `limits` | table | resource limits (ulimits) passed to the process, `name=value` pairs |
+| `data` | table | arbitrary key=value; changes cause a restart on next `start` |
+| `file` | array | files whose content changes cause a restart on next `start` (procd checksums them) |
+| `netdev` | array | network devices; an ifindex change causes a restart |
+| `stdout` / `stderr` | bool | `1` relays the stream to syslog (`logread`) |
+| `facility` | string | syslog facility for the above (default `daemon`) |
+| `user` / `group` | string | run as that user/group instead of root |
+| `pidfile` | string | procd writes the pid there (only for tools that expect it) |
+| `term_timeout` | int | seconds between SIGTERM and SIGKILL on stop (default 5) |
+| `reload_signal` | signal name | on `reload`, send this signal instead of restarting (e.g. `HUP`) |
+| `nice` | int | -20..19 |
+| `error` | string | mark the instance as failed with this message and don't start it (shown in `ubus call service list`) |
+| `watch` | array | ubus namespaces to watch for JSON triggers |
+| `watchdog` | array | procd instance watchdog settings; read procd's `service/instance.c` before using |
+| `seccomp` | string | path to a seccomp JSON policy |
+| `capabilities` | string | path to a capabilities JSON policy |
+| `no_new_privs` | bool | set `PR_SET_NO_NEW_PRIVS` |
+| `extroot` / `overlaydir` / `tmpoverlaysize` | string | jail rootfs options |
+
+Multiple instances: call `procd_open_instance <name>` ... `procd_close_instance` more than once. Unnamed instances get `instance1`, `instance2`, ...
+
+## 5. Triggers
+
+Declared inside `service_triggers()`. All of them run with a delay of `PROCD_RELOAD_DELAY` (1000 ms by default), so a burst of events collapses into one reload.
+
+| Helper | Fires on | Runs |
+|---|---|---|
+| `procd_add_reload_trigger cfg1 [cfg2...]` | `config.change` for those UCI packages | `/etc/init.d/<name> reload` |
+| `procd_add_reload_interface_trigger <iface>` | netifd `interface.*` event for that logical interface | `/etc/init.d/<name> reload` |
+| `procd_add_reload_data_trigger <name>` | `service.data.update` for that service | `/etc/init.d/<name> reload` |
+| `procd_add_reload_mount_trigger <path...>` | `mount.add` for the fstab mount that holds the path | `reload` |
+| `procd_add_restart_mount_trigger <path...>` | same | `restart` |
+| `procd_add_config_trigger <event> <cfg> <cmd...>` | custom: arbitrary command on a config change | `<cmd...>` |
+| `procd_add_interface_trigger <event> <iface> <cmd...>` | custom: arbitrary command on an interface event | `<cmd...>` |
+| `procd_add_raw_trigger <event> <timeout_ms> <cmd...>` | any procd event, no filter | `<cmd...>` |
+| `procd_add_validation <func>` | — | registers the `uci_validate_section` rules `<func>` declares for the service's config |
+
+`config.change` is emitted by `reload_config` (`ubus call uci reload_config`), which `ns.commit` runs after committing. A bare `uci commit` from a shell does **not** emit it. After manual edits, run `reload_config` or reload the service yourself.
+
+Mount triggers depend on `blockd` and the path being under a mount defined in `/etc/config/fstab` (`ns-storage` uses `ns_data`).
+
+## 6. Signals, status and helpers
+
+- `procd_send_signal <service> [instance] [SIGNAL]` sends a signal without knowing the pid (default SIGHUP). Use `'*'` for all instances.
+- `procd_kill <service> [instance]` removes instances.
+- `procd_running <service> [instance]` returns 0 if running.
+- `procd_set_config_changed <cfg>` emits `config.change` for a package, which fires every reload trigger watching it.
+- `procd_add_mdns <service> <proto> <port> [txt...]` advertises via umdns.
+- `uci_load_validate <pkg> <type> <section> <callback> 'opt:type:default' ...` loads and validates a section, then calls `<callback> <section> <result>`.
+
+## 7. Extra commands
+
+```sh
+extra_command "check" "Run a consistency check"
+
+check() {
+	...
+}
+```
+
+`extra_command` adds the action to `help` and to the accepted commands. The old `EXTRA_COMMANDS`/`EXTRA_HELP` variables still work but are legacy.
+
+## 8. Jails
+
+`procd_add_jail <name> [log] [ubus] [udebug] [procfs] [sysfs] [ronly] [requirejail] [netns] [userns] [cgroupsns]` runs the instance in a ujail. `procd_add_jail_mount <path...>` and `procd_add_jail_mount_rw <path...>` bind paths into it. Nothing in NethSecurity uses jails today; check the procd source before relying on the flag list.
+
+## 9. Debugging
+
+```sh
+INIT_TRACE=1 /etc/init.d/ns-foo start        # set -x the whole rc.common run
+PROCD_DEBUG=1 /etc/init.d/ns-foo start       # dump the JSON sent to procd on stderr
+/etc/init.d/ns-foo info                      # procd's view of the service
+ubus call service list '{"name":"ns-foo","verbose":true}'
+logread -e ns-foo                            # stdout/stderr when stdout/stderr=1
+```
+
+procd only tracks the main process. Children started by a shell wrapper (pipes, `&`) survive `stop` unless the wrapper traps TERM and kills them, so `exec` the real binary at the end of any wrapper script.
+
+Init scripts are also executed on the build host with `enable`/`disable` during image creation (`IPKG_INSTROOT` set). Code at file scope (outside functions) runs there too, so keep top-level code limited to variable assignments.

From 152181d65866c4f3a4dc106700a8af5c02b6715c Mon Sep 17 00:00:00 2001
From: Tommaso Bailetti <tommaso.bailetti@nethesis.it>
Date: Wed, 14 Oct 2026 16:05:11 +0200
Subject: [PATCH 02/13] feat: added another skill for state and persistence

---
 .../skills/ns-state-and-persistence/SKILL.md  | 179 ++++++++++++++++++
 AGENTS.md                                     |   2 +
 2 files changed, 181 insertions(+)
 create mode 100644 .agents/skills/ns-state-and-persistence/SKILL.md

diff --git a/.agents/skills/ns-state-and-persistence/SKILL.md b/.agents/skills/ns-state-and-persistence/SKILL.md
new file mode 100644
index 000000000..e6d70c5d3
--- /dev/null
+++ b/.agents/skills/ns-state-and-persistence/SKILL.md
@@ -0,0 +1,179 @@
+---
+name: ns-state-and-persistence
+description: Decide where a NethSecurity package keeps configuration, secrets, runtime state, caches and historical data, and make it survive (or not) reboot, package upgrade, sysupgrade, backup/restore and HA sync. Use whenever a task adds a config file or UCI option, writes any file on the device, stores a token or password, keeps a database/history/log, touches `/etc/config`, `conffiles`, `/lib/upgrade/keep.d`, `/etc/sysupgrade.conf`, `/var`, `/tmp`, `/mnt/data`, `ns-storage`, `sync-data`, or when the user asks "where should this live", "will it survive an upgrade", "is it in the backup", even if persistence isn't mentioned explicitly.
+metadata:
+  domain: nethsecurity-packages
+  type: runtime
+---
+
+## The filesystem you're writing to
+
+Checked on a NethSecurity 8.8 x86 device (OpenWrt 25.12, apk):
+
+| Path | Backed by | Reboot | Package upgrade | sysupgrade / backup / HA sync |
+|---|---|---|---|---|
+| `/etc/config/*` (UCI) | root overlay | kept | kept (see conffiles) | **kept**: `base-files-essential` keep.d lists `/etc/config/` |
+| other files under `/etc`, `/usr`, `/opt` | root overlay | kept | overwritten if shipped by the package, unless a conffile | kept only if declared in a package's `conffiles` (or listed in keep.d) |
+| `/var/*` (symlink to `/tmp`) | tmpfs (RAM) | **lost** | kept | not kept |
+| `/mnt/data/*` | optional ext4 disk (`ns-storage`, `fstab.ns_data`) | kept | kept | not kept (not part of the backup) |
+
+The root overlay is small (222M with 82% used on the test box) and shared with packages. Anything that grows over time doesn't belong there.
+
+sysupgrade, the backup archive (`ns.backup` runs `sysupgrade -k -b`) and HA sync (`ns-rsync.sh` iterates `sysupgrade -l`) all use **the same list**:
+
+1. every path in `/etc/sysupgrade.conf` and `/lib/upgrade/keep.d/*`, unconditionally;
+2. every package conffile whose content differs from the checksum shipped in the package (`/lib/apk/packages/*.conffiles_static`).
+
+The Makefile's `conffiles` define feeds both. At build time (`include/package-pack.mk`), each entry the package ships as a regular file gets a checksum in `conffiles_static`. Every other entry (a file created at runtime, a directory) is written to a generated `/lib/upgrade/keep.d/<pkg>`.
+
+So one `conffiles` line makes a path survive sysupgrade, land in backups and get synced to the HA backup node. Check the result with `sysupgrade -l`.
+
+## Pick the location
+
+| What | Where |
+|---|---|
+| User-facing configuration, anything the API/UI reads or writes | UCI: `/etc/config/<pkg>` |
+| Secrets (tokens, passwords, keys) | UCI option in the package's config |
+| File generated from UCI (daemon config, nft snippet, JSON) | regenerate it from UCI at service start; don't persist it |
+| Non-UCI file that's genuinely user data (certificates, an uploaded list) | `/etc/<pkg>/...` declared in the Makefile `conffiles` |
+| Runtime state: pid, socket, lock, cache, last-run marker | `/var/run/<pkg>/` |
+| Small runtime values shell scripts share | UCI state: `uci -P /var/state set <pkg>.<section>.<opt>=...` |
+| Data that grows (DB, history, metrics, logs) | `/mnt/data/<pkg>/` when storage is ok, else `/var/lib/<pkg>/` with a size/retention cap |
+
+The test for "UCI or file": if a human or the API would ever edit it, it's UCI. Files that are a function of UCI are build artifacts. Persisting them creates two sources of truth that drift after a restore or HA sync.
+
+## UCI configuration
+
+Ship the default config in the package and declare it as a conffile:
+
+```makefile
+define Package/ns-foo/conffiles
+/etc/config/ns-foo
+endef
+
+define Package/ns-foo/install
+	$(INSTALL_DIR) $(1)/etc/config
+	$(INSTALL_CONF) ./files/ns-foo.conf $(1)/etc/config/ns-foo
+	...
+endef
+```
+
+```
+config main 'config'
+	option enabled '0'
+```
+
+- Use named sections (`config main 'config'`) for singletons so code can address `ns-foo.config.enabled` directly.
+- The `conffiles` define must use the package's own name (`Package/ns-foo/conffiles`). A typo there silently drops the declaration.
+- **Adding or renaming options later is a migration, not a change to the shipped file.** apk keeps a conffile the user modified and writes the new version next to it as `*.apk-new`, which nothing reads (several are sitting in `/etc` on the test device). Write a uci-default that sets the new option only when missing:
+
+  ```sh
+  uci -q get ns-foo.config.new_opt > /dev/null || uci set ns-foo.config.new_opt='default'
+  ```
+
+  See the `ns-background-work` skill for uci-default rules (idempotent, runs on every upgrade).
+- APIs don't commit; `ns.commit` commits and fires reload triggers. Shell scripts outside the API that change UCI commit their own package (`uci commit ns-foo`).
+
+Reading config from shell uses `/lib/functions.sh`: `config_load`, `config_get <var> <section> <option> [default]`, `config_get_bool`, `config_foreach`, `config_list_foreach`. Python uses `EUci` (see the `python-nethsecurity` skill).
+
+## Secrets
+
+Keep them as an option in the package's UCI config, like `ns-plug.config.secret`. That way they're in the backup, survive sysupgrade and reach the HA peer with no extra work. The backup archive is encrypted only when `/etc/backup.pass` is set, so treat it as potentially plaintext.
+
+When handing a secret to a process:
+
+- never on the command line: argv is world-readable in `ps` and `/proc`;
+- write it to a file under `/var/run/<pkg>/` created with `umask 077` and pass the path, as `victoria-metrics/files/vmalert.initd` does;
+- or pass it through `procd_set_param env` when the program only reads env.
+
+Never log a secret, and keep it out of API responses: return a boolean like `has_secret` instead.
+
+## Runtime state
+
+- Create directories at service start (`mkdir -p /var/run/ns-foo` in `start_service`), never at package install: `/var` is empty after every reboot.
+- Anything under `/var` must be rebuildable. If losing it on reboot is a bug, it belongs in UCI or on storage.
+
+## Persistent data and ns-storage
+
+Data storage is optional. `storage-status` (from `ns-storage`) prints `ok` only when `fstab.ns_data` is configured **and** its label is actually mounted at the target. It prints `error` when configured but not mounted, and `not_configured` otherwise.
+
+Decide the path from the real status, not from the fstab config. A configured-but-failed disk leaves an empty `/mnt/data` directory on the overlay, and writing there fills the root filesystem:
+
+```sh
+local data_dir max_size
+if [ "$(storage-status 2>/dev/null)" = "ok" ]; then
+	data_dir="$(uci -q get fstab.ns_data.target)/ns-foo"
+else
+	data_dir="/var/lib/ns-foo"
+	max_size="50MB"
+fi
+mkdir -p "$data_dir"
+```
+
+- Without storage, data lives on tmpfs (RAM) and is lost on reboot. Always cap it there: retention, max size, or row count.
+- Let the user override the path with a UCI option (e.g. `storage_path`), and only auto-detect when it's empty.
+
+**Storage added or removed**: `ns-storage/files/add-storage` and `remove-storage` restart each consumer explicitly. A new consumer adds its own line to both:
+
+```sh
+# add-storage, after the mount and existing restarts
+/etc/init.d/ns-foo restart
+
+# remove-storage, stop before the unmount and start after it
+/etc/init.d/ns-foo stop
+...
+/etc/init.d/ns-foo start
+```
+
+When the consumer keeps something in `/var` that should move to the disk on mount, put a merge step next to the restart in `add-storage` (as the OpenVPN connections DB does). Don't watch block hotplug events for it.
+
+**Nightly flush**: `sync-data` runs from cron at 01:40 and executes every executable in `/usr/libexec/sync-data/`. Drop a script there to copy tmpfs data to the disk when the consumer can't write to storage directly.
+
+## Non-UCI files that must persist
+
+Declare them in the Makefile `conffiles`, next to the UCI config. Don't ship a separate `.keep` file:
+
+```makefile
+define Package/ns-foo/conffiles
+/etc/config/ns-foo
+/etc/ns-foo/certs/
+/etc/ns-foo/token
+endef
+```
+
+- Shipped files (`/etc/config/ns-foo`) are kept once they differ from the package version, and aren't overwritten on upgrade.
+- Paths the package doesn't ship (`/etc/ns-foo/token` created at runtime, the `certs/` directory) land in the generated `/lib/upgrade/keep.d/ns-foo` and are kept unconditionally.
+- Directories are listed with a trailing `/` by convention.
+
+Everything listed is also copied to the HA backup node. Whether the backup node actually applies it is handled by `ns-ha` restore hooks, not by `conffiles`.
+
+Don't add generated files, caches or anything large. On subscribed systems the backup archive is uploaded nightly by `ns-plug` (`send-backup`).
+
+## Don't copy
+
+- `packages/ns-dpi/files/20_dpi` creates `/etc/config/dpi` with `uci import` from a uci-default instead of shipping it as a conffile. The ns-dpi Makefile also declares the conffile under `Package/ns-plug/conffiles`. Its own TODO says so.
+- `packages/ns-openvpn/files/20-openvpn-merge-connections-db` is a block hotplug handler that polls `/proc/mounts` in a sleep loop to detect storage. Use the explicit call from `add-storage` instead.
+- `*.keep` files installed to `/lib/upgrade/keep.d` by hand (`ns-plug`, `ns-api`, `ns-api-server`, `ns-dedalo`). Put those paths in `conffiles` instead.
+- `victoria-metrics/files/victoria-metrics.initd` and `victoria-logs/files/victoria-logs.initd` pick `/mnt/data` when `fstab.ns_data.target` is set, without checking it's mounted. Copy their tmpfs fallback and caps, not their detection.
+
+## Verify on a device
+
+```sh
+sysupgrade -l | grep ns-foo          # in backup, sysupgrade and HA sync?
+ls /lib/upgrade/keep.d/
+find /etc -name '*.apk-new'          # conffiles skipped on upgrade
+storage-status
+df -h / /tmp /mnt/data               # overlay and RAM headroom
+du -sh /var/lib/ns-foo /mnt/data/ns-foo
+```
+
+## Sources
+
+Re-check against these when `OWRT_VERSION` changes:
+
+- `sysupgrade` (keep list, conffile checksums): https://github.com/openwrt/openwrt/blob/v25.12.5/package/base-files/files/sbin/sysupgrade
+- conffile packaging for apk (`conffiles_static`): https://github.com/openwrt/openwrt/blob/v25.12.5/include/package-pack.mk
+- Wiki, UCI: https://openwrt.org/docs/guide-user/base-system/uci
+- Wiki, configuration in scripts (`config_load`, `config_get`, ...): https://openwrt.org/docs/guide-developer/config-scripting
+- Wiki, backup and restore: https://openwrt.org/docs/guide-user/troubleshooting/backup_restore
+- `packages/ns-storage/README.md`, `packages/ns-ha/README.md` in this repo
diff --git a/AGENTS.md b/AGENTS.md
index e7e044165..32d76f03f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -11,6 +11,8 @@
 This project has domain-specific skills available. You MUST activate the relevant skill whenever you work in that domain—don't wait until you're stuck.
 
 - `netifyd` — **ACTIVATE** when working with the netifyd DPI daemon. Triggers: `/etc/netifyd` config, `plugins.d` loaders, `netify-proc-*`/`netify-sink-*` plugins, flow-actions rules, criteria/flow expressions, address groups, nfqueue capture, DPI conntrack labels, netify telemetry, or when user mentions netifyd, netify, DPI or flow actions. Fetches the live Netify v5 docs index; covers the config graph, plugin wiring, and which files are generated.
+- `ns-background-work` — **ACTIVATE** when something must run on its own on the device. Triggers: periodic jobs, cron entries, procd init scripts (daemon or one-shot), running at boot or on UCI change, hotplug iface handlers, uci-defaults that register cron or enable services, or when user mentions service, cron, schedule, "every N minutes", startup. Covers picking the mechanism, templates, apk install/upgrade/remove behavior and which existing examples not to copy.
+- `ns-state-and-persistence` — **ACTIVATE** when deciding where a package keeps config, secrets, runtime state or growing data. Triggers: new UCI config or option, `conffiles`, `/lib/upgrade/keep.d`, `/etc/sysupgrade.conf`, writing under `/var`, `/tmp` or `/mnt/data`, `ns-storage`, `sync-data`, or questions about surviving upgrade, backup/restore or HA sync. Covers the filesystem layout, the shared sysupgrade/backup/HA keep list, UCI migrations, secrets handling and storage fallback.
 - `ns-api` — **ACTIVATE** when writing, modifying, or reviewing Python RPCD API scripts. Triggers: creating or updating `ns.*` RPCD API endpoints, handling UCI configuration changes, managing pre/post-commit hooks, defining ACL permissions, documenting methods in OpenAPI 3.1.0, or when user mentions ns-api, API endpoints, hooks, or references `/usr/libexec/rpcd/ns.` files. Covers stdin/stdout JSON protocol, error handling, naming conventions, code style, and spec file updates.
 - `openwrt-package` — **ACTIVATE** when creating or modifying OpenWrt `ns-*` packages. Triggers: building new packages for NethSecurity, managing package dependencies, patching upstream feeds, modifying Makefiles, or when user mentions Makefile, package structure, config fragments, or upstream patches. Covers naming conventions, required Makefile fields, architecture selection, external version management, and patch workflows.
 - `openwrt-package-update` — **ACTIVATE** when updating forked OpenWrt packages from the upstream feed (adblock, mwan3, banip, etc.). Triggers: updating non-ns- packages, comparing local forks against openwrt/packages, merging upstream improvements, or when user mentions upstream package updates. Auto-discovers packages; extracts old/new snapshots for side-by-side comparison; guides cross-package impact detection.

From 5a32a11b6dc9c06f045d45185fc0136f89523e20 Mon Sep 17 00:00:00 2001
From: Tommaso Bailetti <tommaso.bailetti@nethesis.it>
Date: Wed, 14 Oct 2026 16:17:36 +0200
Subject: [PATCH 03/13] feat: added fw4 integration, added references to state

---
 .../skills/ns-firewall-integration/SKILL.md   | 144 +++++++++++
 .../references/fw4-uci.md                     | 232 ++++++++++++++++++
 .../skills/ns-state-and-persistence/SKILL.md  |   2 +
 .../references/uci.md                         |  81 ++++++
 AGENTS.md                                     |   1 +
 5 files changed, 460 insertions(+)
 create mode 100644 .agents/skills/ns-firewall-integration/SKILL.md
 create mode 100644 .agents/skills/ns-firewall-integration/references/fw4-uci.md
 create mode 100644 .agents/skills/ns-state-and-persistence/references/uci.md

diff --git a/.agents/skills/ns-firewall-integration/SKILL.md b/.agents/skills/ns-firewall-integration/SKILL.md
new file mode 100644
index 000000000..24179d289
--- /dev/null
+++ b/.agents/skills/ns-firewall-integration/SKILL.md
@@ -0,0 +1,144 @@
+---
+name: ns-firewall-integration
+description: Make a NethSecurity package or API change the firewall the right way — fw4 UCI rules, zones and forwardings through `nethsec.firewall`, or raw nftables snippets auto-included by fw4. Use whenever a task opens a port, allows or blocks traffic, adds a zone, forward, NAT/redirect or netmap rule, marks/labels/logs packets (ct label, dscp, nflog), touches `/etc/config/firewall`, `/usr/share/nftables.d`, `/etc/nftables.d`, `fw4`, `nft`, `ns_tag`, `ns_link`, `system_rule`, or the templates database, even when the user only says "the service needs to be reachable", "block this", "add a rule" or "firewall".
+metadata:
+  domain: nethsecurity-packages
+  type: runtime
+---
+
+## How the firewall is built
+
+fw4 (firewall4, pinned at `b6e5157` in OpenWrt v25.12.5) renders `/etc/config/firewall` plus the include files into one ruleset for `table inet fw4`. `fw4 reload` loads it in a single `nft -f` transaction that starts with `flush table inet fw4`. As a consequence:
+
+- Anything added to `inet fw4` at runtime with `nft add ...` is wiped on the next reload. Every rule in that table must come from UCI or an include file.
+- If the rendered ruleset has an error, the whole transaction fails. On reload the old ruleset stays loaded. At boot nothing gets loaded, so the box has **no firewall at all**.
+- Other tables (`inet banIP`, `inet netifyd`) are untouched by `fw4 reload`. `fw4 flush` deletes every table.
+
+`ns.commit` runs `reload_config` after committing, which reloads the firewall when `firewall` changed. APIs only stage changes.
+
+## Pick the mechanism
+
+| Need | Mechanism |
+|---|---|
+| Open a port on the firewall, allow/deny between zones, port forward, SNAT/masquerade, zone, forwarding | fw4 UCI via `nethsec.firewall`, tagged `automated` and linked to its owner |
+| Something fw4 UCI can't express: ct labels, dscp/marks, nflog, custom chains or hooks | nft snippet in `/usr/share/nftables.d/` |
+| Snippet content depends on UCI | generate the snippet from UCI, `fw4 reload` only when the content changed |
+
+The default for non-UCI rules is a snippet inside `inet fw4`, not a separate table. It's atomic with the rest of the ruleset, can reference fw4 sets and chains, and survives reloads. `banIP` and `netifyd` have their own tables because they come from upstream. Don't take them as a model for `ns-*` code.
+
+## References
+
+- `references/fw4-uci.md`: every option of every fw4 section type (`defaults`, `zone`, `forwarding`, `rule`, `redirect`, `nat`, `ipset`, `include`), value formats, unsupported options, and the NethSecurity `ns_*` options. Read it before setting any firewall option by hand, or when a helper doesn't cover what you need. Don't guess option names, since fw4 only warns about unknown ones and ignores them.
+- nftables syntax for snippets: https://wiki.nftables.org/wiki-nftables/index.php/Quick_reference-nftables_in_10_minutes. Check the `nft` version on the device (`nft --version`) before using newer statements.
+
+## fw4 UCI from Python
+
+Use `nethsec.firewall` (`packages/python3-nethsec/src/nethsec/firewall/__init__.py`) from APIs and scripts. Read the function before relying on it; signatures and defaults matter.
+
+| Function | Use |
+|---|---|
+| `add_service(uci, name, port, proto, link)` | ACCEPT rule from `wan` to the device for a service port; section id `ns_allow_<name>` |
+| `remove_service` / `disable_service` | remove / disable it |
+| `add_template_rule(uci, name, proto, port, link)` | rule from a `template_rule` in the templates database (`docs/design/templates_database.md`) |
+| `add_template_zone`, `add_template_forwarding`, `add_template_service_group` | zones, forwardings and service groups from templates |
+| `add_trusted_zone`, `add_vpn_interface`, `add_device_to_zone`, `add_interface_to_zone` | VPN/LAN wiring |
+| `add_rule` / `edit_rule` / `delete_rule`, `add_nat_rule`, `add_netmap_rule` | user-facing rules, as the `ns.firewall`/`ns.nat` APIs do |
+| `get_all_linked`, `disable_linked_rules`, `delete_linked_sections` | find, disable or remove everything a feature created |
+
+Conventions these helpers already apply. Follow them when you set options by hand:
+
+- **IDs**: `ns_` prefix, from `utils.get_id(name)` (stable, derived from a name) or `utils.get_random_id()`. Zones are `ns_<zonename>`.
+- **`ns_tag` list**: `automated` marks a rule the system created. `enrich_rule` turns it into `system_rule: true`, and the UI warns before the user edits such a rule. Every rule a package or API creates on its own carries `automated`.
+- **`ns_link`**: `<config>/<section>` of the object that owns the rule (e.g. `network/wg1`, `openvpn/ns_roadwarrior1`). When that object is deleted, call `delete_linked_sections(uci, link)` so its firewall rules, zones and forwardings go with it. Without a link, rules leak.
+- **Order**: the helpers call `reorder_firewall_config`, which keeps defaults/includes, zones, forwardings, then forward, output and input rules. Section order is rule order.
+- **No commit**: helpers `uci.save('firewall')` only. `firewall.apply()` commits and reloads; use it only in scripts outside the API flow.
+
+`nethsec.firewall.enable_service()` currently sets `enabled` to `'0'` (same as `disable_service`). Set `enabled` to `'1'` directly until it's fixed.
+
+## nft snippets in `/usr/share/nftables.d`
+
+fw4 auto-includes every readable `*.nft` file here. The position comes from the directory:
+
+| Directory | Included | Content |
+|---|---|---|
+| `ruleset-pre/`, `ruleset-post/` | before/after `table inet fw4 { ... }` | whole statements at ruleset level (`table ...`, `define ...`) |
+| `table-pre/`, `table-post/` | inside `inet fw4`, before the first / after the last chain | chain, set, map declarations |
+| `chain-pre/<chain>/`, `chain-post/<chain>/` | inside chain `<chain>` of `inet fw4`, before the first / after the last rule | rule lines only |
+
+- `<chain>` is a chain fw4 renders: `input`, `forward`, `output`, `prerouting`, `dstnat`, `srcnat`, `mangle_*`, or zone chains like `input_lan`, `forward_wan`, `dstnat_lan`. If the chain doesn't exist (zone not configured), the file is simply not included.
+- Files in one directory are included in name order; use `NN-ns-foo.nft`.
+- A chain declared in `table-pre` with its own `hook` and `priority` runs alongside fw4's chains (`filter` = 0 for input/forward/output). That's how `dpi_actions` hooks `prerouting` at `filter + 10`.
+- Snippets can reference fw4's named sets and chains, since they're in the same table.
+- `/etc/nftables.d/` is the **user's** directory: same table context, kept on sysupgrade. Packages never write there.
+
+Static snippet (`ns-don`):
+
+```makefile
+	$(INSTALL_DIR) $(1)/usr/share/nftables.d/chain-pre/input
+	$(INSTALL_DATA) ./files/20-ns-foo.nft $(1)/usr/share/nftables.d/chain-pre/input/
+```
+
+```
+iifname "tunFOO" tcp dport 9443 counter accept comment "ns-foo"
+```
+
+Package files are reinstalled and removed by apk, so a static snippet needs no cleanup. After install and removal, the firewall needs a reload to pick up the change. Do it in `postinst` and `prerm` under the `IPKG_INSTROOT` guard.
+
+### Generated snippets
+
+When the rules depend on UCI, a one-shot (see `ns-background-work`) renders the snippet and reloads fw4 **only if the content changed**. A reload re-renders everything, so skipping no-op reloads matters:
+
+```python
+NFT_FILE = '/usr/share/nftables.d/table-pre/20-ns-foo.nft'
+
+def write_snippet(render):
+    current = None
+    if os.path.exists(NFT_FILE):
+        with open(NFT_FILE) as f:
+            current = f.read()
+    if current == render:
+        return
+    os.makedirs(os.path.dirname(NFT_FILE), exist_ok=True)
+    with open(NFT_FILE, 'w') as f:
+        f.write(render)
+    if subprocess.run(['fw4', '-q', 'check']).returncode != 0:
+        # fw4 refuses to reload a broken ruleset, and at boot it wouldn't load at all
+        if current is None:
+            os.remove(NFT_FILE)
+        else:
+            with open(NFT_FILE, 'w') as f:
+                f.write(current)
+        raise RuntimeError('invalid_nft_snippet')
+    subprocess.run(['fw4', '-q', 'reload'], check=True)
+```
+
+- When the feature is disabled, remove the file (and reload) instead of writing an empty one.
+- The file isn't owned by the package, so `prerm` must delete it and reload the firewall. `ns-dpi` and `ns-netmap` don't do this yet.
+- Render with Jinja2 or plain string building. Any value that comes from UCI or user input must be validated before it reaches nft syntax (IPs, ports, interface names).
+
+## Don't copy
+
+- `firewall.ns_hs_include` (dedalo, `type script`, `/opt/icaro/dedalo/dedalo.user`, created from the Makefile postinst) and `firewall.ns_user_include` (`/etc/firewall.user`). Script includes are fw3-era: they run shell after the ruleset loads and need `fw4_compatible`. Use an nft snippet.
+- `ns-binding` managing its own `table inet ns-binding` and deleting it in `stop_service`. Use a generated snippet in `inet fw4`.
+- `nethsec.firewall.enable_service()`, see above.
+
+Good references: `ns-don` (static chain snippet), `ns-dpi/files/dpi-nft` (generated `table-pre` chain with change detection), `ns-netmap/files/ns-netmap` (generated `chain-pre/srcnat` and `chain-post/dstnat` rules). Copy the generation, but add the validation and prerm cleanup they lack.
+
+## Verify on a device
+
+```sh
+fw4 check                          # renders the ruleset and runs nft -c
+fw4 print | less                   # rendered ruleset, includes expanded
+nft list chain inet fw4 input      # what's actually loaded
+uci show firewall | grep -E 'ns_tag|ns_link'
+logread -e firewall
+```
+
+Check behavior after `fw4 reload` and after a reboot. A rule that only exists until the next reload was added at runtime, not through UCI or a snippet.
+
+## Sources
+
+- firewall4 at the pinned commit (`root/usr/share/ucode/fw4.uc` for includes, `root/usr/share/firewall4/templates/ruleset.uc` for the chain layout, `root/sbin/fw4` for reload): https://github.com/openwrt/firewall4/tree/b6e5157527d361f99ad52eaa6da273cb0f2dfd59 (pinned in https://github.com/openwrt/openwrt/blob/v25.12.5/package/network/config/firewall4/Makefile)
+- `/usr/share/nftables.d/README` on the device (include positions)
+- Wiki, firewall configuration: https://openwrt.org/docs/guide-user/firewall/firewall_configuration
+- `docs/design/templates_database.md` in this repo
diff --git a/.agents/skills/ns-firewall-integration/references/fw4-uci.md b/.agents/skills/ns-firewall-integration/references/fw4-uci.md
new file mode 100644
index 000000000..2bdf1432b
--- /dev/null
+++ b/.agents/skills/ns-firewall-integration/references/fw4-uci.md
@@ -0,0 +1,232 @@
+# fw4 UCI options reference (`/etc/config/firewall`)
+
+Extracted from firewall4 `root/usr/share/ucode/fw4.uc` at `b6e5157527d361f99ad52eaa6da273cb0f2dfd59`, the commit OpenWrt v25.12.5 pins. The `parse_options(...)` block of each `parse_<type>` function is the authoritative list. When `OWRT_VERSION` changes, or an option here doesn't behave as described, re-read that file at the new pin:
+
+- Source: https://github.com/openwrt/firewall4/blob/b6e5157527d361f99ad52eaa6da273cb0f2dfd59/root/usr/share/ucode/fw4.uc
+- Pin: https://github.com/openwrt/openwrt/blob/v25.12.5/package/network/config/firewall4/Makefile
+- Wiki (fw3-era wording, mostly still valid): https://openwrt.org/docs/guide-user/firewall/firewall_configuration
+
+## Contents
+
+1. Reading the tables
+2. Value formats
+3. `defaults`
+4. `zone`
+5. `forwarding`
+6. `rule`
+7. `redirect`
+8. `nat`
+9. `ipset`
+10. `include`
+11. NethSecurity `ns_*` options
+
+## 1. Reading the tables
+
+- **list**: the option accepts a UCI `list` (several values).
+- **unsupported**: fw4 parses it only to warn "not supported by fw4" and ignores it. Never write these.
+- **`!` prefix**: most match options accept a leading `!` to invert (`option src_ip '!10.0.0.0/8'`). Options marked "no invert" reject it.
+- Unknown options produce a warning. NethSecurity patches fw4 (`patches/package/network/config/firewall4/10-hide_warning_ns_options.patch`) so options starting with `ns_` are silently accepted. That's what makes the `ns_*` metadata below safe to store in fw4 sections.
+- `fw4 check` / `fw4 print` show the warnings for the current config.
+
+## 2. Value formats
+
+| Type | Accepted values |
+|---|---|
+| bool | `0`/`1` (also `yes`/`no`, `on`/`off`, `true`/`false`) |
+| policy | `accept`, `reject`, `drop` (case-insensitive; `ACCEPT` is common in configs) |
+| target (rule) | `accept`, `reject`, `drop`, `notrack`, `helper`, `mark`, `dscp` |
+| target (redirect) | `dnat` (default), `snat` |
+| target (nat) | `masquerade` (default), `snat`, `accept` |
+| family | `any`/`all`/`*` (both), `ipv4`/`inet`/anything with `4`, `ipv6`/anything with `6` |
+| zone_ref | a zone `name`, or `*` for any zone |
+| proto | `tcp`, `udp`, `tcpudp` (rule/redirect default, expands to tcp + udp), `icmp`, `icmpv6`/`ipv6-icmp`, `all`/`any`/`*`, other protocol names or numbers |
+| network | IP, CIDR, or `addr/mask` |
+| port | `80`, `8000-8080` |
+| limit | `N[/second\|minute\|hour\|day]`, e.g. `10/minute` (default unit second) |
+| mark | `0xVALUE[/0xMASK]`, up to 32 bit |
+| dscp | class name (`CS0`-`CS7`, `AF11`-`AF43`, `EF`, `BE`, `LE`) or 0-63 |
+| reject_code | `tcp-reset`, `port-unreachable`, `admin-prohibited`, `host-unreachable`, `no-route` |
+| direction | `in`/`ingress`, `out`/`egress` |
+| setmatch (`ipset`) | `<setname> [src\|dst ...]`, e.g. `blocklist src` |
+| ipsettype (`match`) | `[src_\|dst_]ip`, `port`, `mac`, `net`, `set` |
+| weekdays | `Monday` ... `Sunday`, list or space-separated |
+| date | `YYYY[-MM[-DD[Thh:mm:ss]]]`, years 1970-2038 |
+| time | `hh[:mm[:ss]]` |
+
+## 3. `defaults`
+
+| Option | Type | Default |
+|---|---|---|
+| `input`, `output`, `forward` | policy | `drop` |
+| `drop_invalid` | bool | |
+| `tcp_reject_code` | reject_code | `tcp-reset` |
+| `any_reject_code` | reject_code | `port-unreachable` |
+| `syn_flood` / `synflood_protect` | bool | |
+| `synflood_rate` | limit | `25/second` |
+| `synflood_burst` | int | `50` |
+| `tcp_syncookies` | bool | `1` |
+| `tcp_ecn` | int | |
+| `tcp_window_scaling` | bool | `1` |
+| `accept_redirects`, `accept_source_route` | bool | |
+| `auto_helper` | bool | `1` |
+| `flow_offloading`, `flow_offloading_hw` | bool | `0` |
+| `auto_includes` | bool | `1` — set `0` and `/usr/share/nftables.d` stops being included |
+| `custom_chains`, `disable_ipv6` | — | unsupported |
+
+## 4. `zone`
+
+| Option | Type | Default / notes |
+|---|---|---|
+| `enabled` | bool | `1` |
+| `name` | identifier | **required**; the name referenced by rules (`src`, `dest`) |
+| `family` | family | both |
+| `network` | list | logical interfaces from `/etc/config/network` |
+| `device` | list | raw Linux devices (`tun+` wildcard allowed) |
+| `subnet` | list, network | match by subnet instead of device |
+| `input`, `output`, `forward` | policy | inherit from `defaults` |
+| `masq` | bool | masquerade IPv4 leaving this zone |
+| `masq6` | bool | masquerade IPv6 |
+| `masq_src`, `masq_dest` | list, network | restrict masquerading |
+| `masq_allow_invalid` | bool | |
+| `mtu_fix` | bool | MSS clamping |
+| `log` | int | `1` logs traffic dropped/rejected by the zone policy |
+| `log_limit` | limit | |
+| `auto_helper` | bool | `1` |
+| `helper` | list | conntrack helpers |
+| `counter` | bool | `1` |
+| `extra`, `extra_src`, `extra_dest`, `custom_chains` | — | unsupported |
+
+## 5. `forwarding`
+
+| Option | Type | Default / notes |
+|---|---|---|
+| `enabled` | bool | `1` |
+| `name` | string | |
+| `family` | family | |
+| `src`, `dest` | zone_ref | **required**; allows new connections from `src` zone to `dest` zone |
+
+## 6. `rule`
+
+| Option | Type | Default / notes |
+|---|---|---|
+| `enabled` | bool | `1` |
+| `name` | string | section id |
+| `family` | family | |
+| `src` | zone_ref | no `src` = output rule (traffic from the device) |
+| `dest` | zone_ref | no `dest` = input rule (traffic to the device); both = forward rule |
+| `device` | string, no invert | with `direction` |
+| `direction` | direction | |
+| `ipset` | setmatch | match against a named set |
+| `helper` | cthelper | match connections using a helper |
+| `set_helper` | cthelper, no invert | with `target helper` |
+| `proto` | list | `tcpudp` |
+| `src_ip`, `dest_ip` | list, network | |
+| `src_mac` | list | |
+| `src_port`, `dest_port` | list, port | |
+| `icmp_type` | list | names or numbers |
+| `limit` | limit | |
+| `limit_burst` | int | |
+| `utc_time` | bool | interpret time options as UTC (per wiki) |
+| `start_date`, `stop_date` | date | |
+| `start_time`, `stop_time` | time | |
+| `weekdays` | weekdays | |
+| `mark` | mark | match |
+| `set_mark`, `set_xmark` | mark, no invert | with `target mark` |
+| `dscp` | dscp | match |
+| `set_dscp` | dscp, no invert | with `target dscp` |
+| `counter` | bool | `1` |
+| `log` | string | `1` to log matches |
+| `log_limit` | limit | |
+| `target` | target | `accept`, `reject`, `drop`, `notrack`, `helper`, `mark`, `dscp` |
+| `monthdays`, `extra` | — | unsupported |
+
+## 7. `redirect` (port forward / DNAT)
+
+| Option | Type | Default / notes |
+|---|---|---|
+| `enabled` | bool | `1` |
+| `name` | string | section id |
+| `family` | family | |
+| `src` | zone_ref | zone the traffic comes from (usually `wan`) |
+| `dest` | zone_ref | zone of the internal host |
+| `ipset` | setmatch | |
+| `helper` | cthelper, no invert | |
+| `proto` | list | `tcpudp` |
+| `src_ip`, `src_mac`, `src_port` | | match the original source |
+| `src_dip` | network | original destination IP (the public address) |
+| `src_dport` | port | original destination port (the public port) |
+| `dest_ip` | network | internal host |
+| `dest_port` | port | internal port |
+| `limit`, `limit_burst`, time/date options, `mark` | | as in `rule` |
+| `reflection` | bool | `1` — NAT loopback (hairpin) |
+| `reflection_src` | `internal` / `external` | `internal` |
+| `reflection_zone` | list, zone_ref | zones that get reflection rules |
+| `counter` | bool | `1` |
+| `log`, `log_limit` | | |
+| `target` | `dnat` / `snat` | `dnat` |
+| `monthdays`, `extra` | — | unsupported |
+
+## 8. `nat` (SNAT / masquerade rules)
+
+| Option | Type | Default / notes |
+|---|---|---|
+| `enabled` | bool | `1` |
+| `name` | string | section id |
+| `family` | family | |
+| `src` | zone_ref | outgoing zone |
+| `device` | string | outgoing device |
+| `proto` | list | `all` |
+| `src_ip`, `src_port`, `dest_ip`, `dest_port` | | match |
+| `snat_ip`, `snat_port` | no invert | with `target snat` |
+| `limit`, `limit_burst`, `connlimit_ports`, time/date options, `mark` | | |
+| `counter` | bool | `1` |
+| `log` | string | |
+| `target` | `masquerade` / `snat` / `accept` | `masquerade`; `accept` excludes the traffic from NAT |
+| `ipset`, `monthdays`, `extra` | — | unsupported |
+
+## 9. `ipset` (named nftables set)
+
+| Option | Type | Default / notes |
+|---|---|---|
+| `enabled` | bool | `1` |
+| `name` | identifier | **required**; reference it from `rule`/`redirect` `ipset` or from nft snippets as `@name` |
+| `family` | family | `4` |
+| `match` | list, ipsettype | e.g. `src_net`, `dest_port` |
+| `entry` | list | initial elements |
+| `loadfile` | string | file with one element per line |
+| `maxelem` | int | |
+| `timeout` | int | `-1` (no timeout); seconds otherwise |
+| `counters` | bool | |
+| `comment` | string | |
+| `reload_set` | bool | |
+| `storage`, `iprange`, `portrange`, `netmask`, `hashsize`, `external` | — | unsupported |
+
+`fw4 reload-sets` reloads set contents without rebuilding the ruleset.
+
+## 10. `include`
+
+| Option | Type | Default / notes |
+|---|---|---|
+| `enabled` | bool | `1` |
+| `path` | string | **required**; must exist, or the include is skipped with a warning |
+| `type` | `script` / `nftables` | `script` |
+| `fw4_compatible` | bool | required `1` for `script` includes, else ignored |
+| `position` | | `nftables` only: `ruleset-prepend`, `ruleset-append`, `table-prepend` (default `table-append`), `table-append`, `chain-prepend`, `chain-append` |
+| `chain` | identifier | required for `chain-*` positions |
+| `family`, `reload` | — | unsupported |
+
+Files in `/usr/share/nftables.d/<position>/` are turned into `nftables` includes automatically (see the main skill). Prefer them over `include` sections.
+
+## 11. NethSecurity `ns_*` options
+
+Stored in fw4 sections, ignored by fw4 (see the patch in section 1), used by `nethsec.firewall` and the UI:
+
+| Option | On | Meaning |
+|---|---|---|
+| `ns_tag` | rule, zone, forwarding, redirect | list; `automated` = created by the system, exposed as `system_rule` |
+| `ns_link` | any | `<config>/<section>` of the owning object; used by `delete_linked_sections` |
+| `ns_service` | rule | service name from the service suggestions, or `custom` |
+| `ns_src`, `ns_dst` | rule, redirect | object reference `<database>/<id>` (users/objects DB); `update_firewall_rules` expands it into `src_ip`/`dest_ip` or `ipset` |
+| `ns_description` | zone (templates) | human description |
+
+There's also a section `firewall.ns_defaults` (type `defaults`) holding NethSecurity-wide settings such as `rule_log_limit` (`get_default_logging_options` / `apply_default_logging_options`).
diff --git a/.agents/skills/ns-state-and-persistence/SKILL.md b/.agents/skills/ns-state-and-persistence/SKILL.md
index e6d70c5d3..a08f17fa4 100644
--- a/.agents/skills/ns-state-and-persistence/SKILL.md
+++ b/.agents/skills/ns-state-and-persistence/SKILL.md
@@ -76,6 +76,8 @@ config main 'config'
 
 Reading config from shell uses `/lib/functions.sh`: `config_load`, `config_get <var> <section> <option> [default]`, `config_get_bool`, `config_foreach`, `config_list_foreach`. Python uses `EUci` (see the `python-nethsecurity` skill).
 
+`references/uci.md` has the UCI file syntax, every `uci` CLI command, the full shell API (`config_*`, `uci_*`, state helpers) with its gotchas, and links to the sysupgrade/conffiles source. Read it before writing UCI-handling shell code instead of guessing a helper.
+
 ## Secrets
 
 Keep them as an option in the package's UCI config, like `ns-plug.config.secret`. That way they're in the backup, survive sysupgrade and reach the HA peer with no extra work. The backup archive is encrypted only when `/etc/backup.pass` is set, so treat it as potentially plaintext.
diff --git a/.agents/skills/ns-state-and-persistence/references/uci.md b/.agents/skills/ns-state-and-persistence/references/uci.md
new file mode 100644
index 000000000..5bde9b78f
--- /dev/null
+++ b/.agents/skills/ns-state-and-persistence/references/uci.md
@@ -0,0 +1,81 @@
+# UCI reference
+
+Covers OpenWrt v25.12 (`OWRT_VERSION` in `build.conf.defaults`). Facts come from the sources below. Re-read them at the new tag when the version changes.
+
+Sources:
+
+- `package/base-files/files/lib/functions.sh` (`config_*` shell API, `get_bool`): https://github.com/openwrt/openwrt/blob/v25.12.5/package/base-files/files/lib/functions.sh
+- `package/system/uci/files/lib/config/uci.sh` (`uci_*` shell helpers): https://github.com/openwrt/openwrt/blob/v25.12.5/package/system/uci/files/lib/config/uci.sh
+- `uci` CLI usage: run `uci` with no arguments on the device
+- Wiki, UCI system (file syntax, CLI): https://openwrt.org/docs/guide-user/base-system/uci
+- Wiki, configuration in scripts: https://openwrt.org/docs/guide-developer/config-scripting
+- Python: `EUci` (python3-euci), see the `python-nethsecurity` skill
+
+## File syntax
+
+```
+config <type> ['<name>']
+	option <key> '<value>'
+	list <key> '<value1>'
+	list <key> '<value2>'
+```
+
+- Named sections (`config main 'config'`) are addressed as `pkg.config.opt`. Unnamed sections get generated ids (`@type[0]` in CLI, `cfgXXXXXX` internally). Use named sections for anything code addresses directly.
+- Section and option names: `[A-Za-z0-9_]`. NethSecurity-generated ids start with `ns_` (`nethsec.utils.get_id`, `get_random_id`).
+- Values are strings. Booleans are `'0'`/`'1'`. The shell `get_bool` also accepts `on/off`, `true/false`, `yes/no`, `enabled/disabled`.
+
+## CLI (`uci`)
+
+| Command | Use |
+|---|---|
+| `uci show <pkg>[.<sec>[.<opt>]]` | dump in `pkg.sec.opt='val'` form |
+| `uci -q get <pkg>.<sec>[.<opt>]` | read; exit 1 if missing (`-q` silences the error) |
+| `uci set <pkg>.<sec>=<type>` | create a named section |
+| `uci set <pkg>.<sec>.<opt>=<val>` | set an option |
+| `uci add <pkg> <type>` | create an unnamed section, prints its id |
+| `uci add_list` / `uci del_list` `<pkg>.<sec>.<opt>=<val>` | edit lists |
+| `uci delete <pkg>.<sec>[.<opt>]` | remove |
+| `uci rename <pkg>.<sec>[.<opt>]=<new>` | rename |
+| `uci reorder <pkg>.<sec>=<pos>` | change section order (matters for firewall rules) |
+| `uci changes [<pkg>]` / `uci revert <pkg>...` | staged changes |
+| `uci commit [<pkg>]` | write staged changes to `/etc/config/<pkg>` |
+| `uci import <pkg>` / `uci export <pkg>` | whole-file in/out in config syntax (`-m` merges on import) |
+| `uci batch` | many commands from stdin in one process |
+
+Options: `-c <dir>` config dir, `-t <dir>` save dir for staged changes, `-P <dir>` state dir (use `/var/state` for runtime state), `-q` quiet.
+
+Changes are staged in `/tmp/.uci` until commit. `uci commit` alone does **not** reload services. `reload_config` (`ubus call uci reload_config`, run by `ns.commit`) emits `config.change` and fires procd reload triggers.
+
+## Shell API (`. /lib/functions.sh`)
+
+| Function | Notes |
+|---|---|
+| `config_load <pkg>` | parse the whole package into shell variables. One global namespace: loading another package **replaces** the previous one, so reload the first one if you need it again (see `vmalert.initd`). No-op at image build (`IPKG_INSTROOT` set). |
+| `config_get <var> <section> <option> [default]` | `<var>` gets the value or default. The 3-arg form `config_get <section> <option> <default>` prints instead of assigning. |
+| `config_get_bool <var> <section> <option> [default]` | normalizes to `0`/`1` via `get_bool` |
+| `config_set <section> <option> <value>` | in-memory only, never written |
+| `config_foreach <func> [type] [args...]` | calls `func <section> [args...]` for every section (of `type`) |
+| `config_list_foreach <section> <option> <func> [args...]` | calls `func <value> [args...]` for each list item |
+| `config_unset` | |
+| `config_cb`, `option_cb`, `list_cb`, `reset_cb` | parser callbacks, define before `config_load` |
+| `append <var> <value> [sep]`, `list_contains <var> <value>` | string list helpers |
+
+## Shell helpers (`. /lib/config/uci.sh`, sourced by `functions.sh`)
+
+| Function | Wraps |
+|---|---|
+| `uci_get <pkg> [sec] [opt] [default] [state_dir]` | `uci -q get` with a default |
+| `uci_set <pkg> <sec> <opt> <val>` | `uci set` |
+| `uci_add <pkg> <type> [name]` | `uci add` or named `uci set`; unnamed id in `$CONFIG_SECTION` |
+| `uci_add_list`, `uci_remove`, `uci_remove_list`, `uci_rename`, `uci_revert` | as the CLI |
+| `uci_commit [pkg]` | `uci commit` |
+| `uci_set_default <pkg>` | `uci import` + commit **only if** `<pkg>` doesn't exist yet, reading the default config from stdin |
+| `uci_set_state`, `uci_get_state`, `uci_revert_state`, `uci_toggle_state` | same against `/var/state` (runtime state, lost on reboot) |
+
+## Persistence machinery
+
+For which files survive what, see the main skill. Authoritative code:
+
+- `package/base-files/files/sbin/sysupgrade` (`list_static_conffiles`, `list_changed_conffiles`, `build_list_of_backup_config_files`): https://github.com/openwrt/openwrt/blob/v25.12.5/package/base-files/files/sbin/sysupgrade
+- `include/package-pack.mk` (`conffiles` → `conffiles_static` checksums and generated `keep.d`): https://github.com/openwrt/openwrt/blob/v25.12.5/include/package-pack.mk
+- Wiki, backup and restore: https://openwrt.org/docs/guide-user/troubleshooting/backup_restore
diff --git a/AGENTS.md b/AGENTS.md
index 32d76f03f..c5d6e8428 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -13,6 +13,7 @@ This project has domain-specific skills available. You MUST activate the relevan
 - `netifyd` — **ACTIVATE** when working with the netifyd DPI daemon. Triggers: `/etc/netifyd` config, `plugins.d` loaders, `netify-proc-*`/`netify-sink-*` plugins, flow-actions rules, criteria/flow expressions, address groups, nfqueue capture, DPI conntrack labels, netify telemetry, or when user mentions netifyd, netify, DPI or flow actions. Fetches the live Netify v5 docs index; covers the config graph, plugin wiring, and which files are generated.
 - `ns-background-work` — **ACTIVATE** when something must run on its own on the device. Triggers: periodic jobs, cron entries, procd init scripts (daemon or one-shot), running at boot or on UCI change, hotplug iface handlers, uci-defaults that register cron or enable services, or when user mentions service, cron, schedule, "every N minutes", startup. Covers picking the mechanism, templates, apk install/upgrade/remove behavior and which existing examples not to copy.
 - `ns-state-and-persistence` — **ACTIVATE** when deciding where a package keeps config, secrets, runtime state or growing data. Triggers: new UCI config or option, `conffiles`, `/lib/upgrade/keep.d`, `/etc/sysupgrade.conf`, writing under `/var`, `/tmp` or `/mnt/data`, `ns-storage`, `sync-data`, or questions about surviving upgrade, backup/restore or HA sync. Covers the filesystem layout, the shared sysupgrade/backup/HA keep list, UCI migrations, secrets handling and storage fallback.
+- `ns-firewall-integration` — **ACTIVATE** when a change touches the firewall. Triggers: opening ports, allow/deny rules, zones, forwardings, NAT/redirect/netmap, packet marking/labels/logging, `/etc/config/firewall`, `/usr/share/nftables.d`, `fw4`, `nft`, `ns_tag`, `ns_link`, `system_rule`, templates database. Covers fw4 UCI via `nethsec.firewall` vs nft snippets, include positions, generated snippets with validation, and which existing patterns not to copy.
 - `ns-api` — **ACTIVATE** when writing, modifying, or reviewing Python RPCD API scripts. Triggers: creating or updating `ns.*` RPCD API endpoints, handling UCI configuration changes, managing pre/post-commit hooks, defining ACL permissions, documenting methods in OpenAPI 3.1.0, or when user mentions ns-api, API endpoints, hooks, or references `/usr/libexec/rpcd/ns.` files. Covers stdin/stdout JSON protocol, error handling, naming conventions, code style, and spec file updates.
 - `openwrt-package` — **ACTIVATE** when creating or modifying OpenWrt `ns-*` packages. Triggers: building new packages for NethSecurity, managing package dependencies, patching upstream feeds, modifying Makefiles, or when user mentions Makefile, package structure, config fragments, or upstream patches. Covers naming conventions, required Makefile fields, architecture selection, external version management, and patch workflows.
 - `openwrt-package-update` — **ACTIVATE** when updating forked OpenWrt packages from the upstream feed (adblock, mwan3, banip, etc.). Triggers: updating non-ns- packages, comparing local forks against openwrt/packages, merging upstream improvements, or when user mentions upstream package updates. Auto-discovers packages; extracts old/new snapshots for side-by-side comparison; guides cross-package impact detection.

From 30973d4464724238978124d1c00d66d5c735930d Mon Sep 17 00:00:00 2001
From: Tommaso Bailetti <tommaso.bailetti@nethesis.it>
Date: Wed, 14 Oct 2026 17:33:33 +0200
Subject: [PATCH 04/13] feat: added logic on code placement

---
 .agents/skills/ns-code-placement/SKILL.md | 147 ++++++++++++++++++++++
 AGENTS.md                                 |   4 +
 2 files changed, 151 insertions(+)
 create mode 100644 .agents/skills/ns-code-placement/SKILL.md

diff --git a/.agents/skills/ns-code-placement/SKILL.md b/.agents/skills/ns-code-placement/SKILL.md
new file mode 100644
index 000000000..c1303bf19
--- /dev/null
+++ b/.agents/skills/ns-code-placement/SKILL.md
@@ -0,0 +1,147 @@
+---
+name: ns-code-placement
+description: Decide where new NethSecurity logic goes — the `python3-nethsec` library, an `ns.*` RPCD API, a standalone script, a pre/post-commit hook run by `ns.commit`, or a procd reload trigger — and write it there correctly, with library tests. Use whenever a task adds or moves Python logic, adds an API method, needs "something to happen when the user saves/applies", reacts to a UCI change, keeps two configs consistent, touches `packages/python3-nethsec`, `/usr/libexec/ns-api/pre-commit`, `/usr/libexec/ns-api/post-commit`, `ns.commit`, or when the user asks "where should this code live", "should this be a hook", "add it to the library", even if they don't name a layer.
+metadata:
+  domain: nethsecurity-packages
+  type: architecture
+---
+
+## The layers
+
+| Layer | Lives in | Runs when |
+|---|---|---|
+| `nethsec` library | `packages/python3-nethsec/src/nethsec/<module>/__init__.py` | imported by everything else |
+| `ns.*` API | `packages/ns-api/files/ns.<name>` → `/usr/libexec/rpcd/ns.<name>` | UI/controller call, stages UCI changes |
+| `ns.commit` pre-commit hook | `/usr/libexec/ns-api/pre-commit/<name>.py` | on Apply, before the UCI commit |
+| `ns.commit` post-commit hook | `/usr/libexec/ns-api/post-commit/<name>.py` | on Apply, after the commit, before `reload_config` |
+| procd reload trigger | `service_triggers` in the package's init script | when `reload_config` sees the config changed |
+| Script | `/usr/sbin/<name>` or `/usr/libexec/<pkg>/` | cron, init script, hotplug, another script |
+
+The UI's Apply button calls `ns.commit commit` with the output of `ubus call uci changes`, so every staged change goes through the hooks, then gets committed, then `reload_config` fires the procd triggers.
+
+## Pick the layer
+
+| Need | Put it in |
+|---|---|
+| Logic on UCI data: validation, building sections, lookups, anything an API, script or hook could reuse | the library, with tests |
+| Expose an operation to the UI/controller | an API method that parses input, calls the library and prints JSON |
+| Reload/restart your own service when its config changes | procd `service_triggers` on that config, see the `ns-background-work` skill |
+| Keep **another** config consistent with a change (delete references to a removed interface, rewrite a derived option) | pre-commit hook |
+| Side effect after commit that has no owning service to trigger (timezone symlink, invalidating tokens) | post-commit hook |
+| Periodic or boot-time work | script + cron/procd, see `ns-background-work` |
+
+Start from the bottom of the stack: if procd can reload the service from its trigger, don't write a hook. Hooks run on every Apply, for every change, so each one costs time on every save.
+
+## Library (`python3-nethsec`)
+
+Read the existing module before adding to it. Functions take an `EUci` as first argument, raise `utils.ValidationError(parameter, message, value)` for bad input and `ValueError` for other errors, and call `uci.save(config)` without committing. `nethsec.dpi` is the reference for a recent, tested module.
+
+- **New module**: create `src/nethsec/<module>/__init__.py` **and** add `'nethsec.<module>'` to the `packages=[...]` list in `setup.py`. The list is written by hand, so a module missing there is silently left out of the wheel and the import fails on the device.
+- **Tests**: `tests/test_<module>.py` with pytest. Build an `EUci` on a temp dir with the configs the code needs, as `tests/test_dpi.py` does:
+
+  ```python
+  @pytest.fixture
+  def e_uci(tmp_path: pathlib.Path) -> EUci:
+      conf_dir = tmp_path.joinpath('conf')
+      conf_dir.mkdir()
+      save_dir = tmp_path.joinpath('save')
+      save_dir.mkdir()
+      conf_dir.joinpath('foo').write_text(foo_db)
+      return EUci(confdir=conf_dir.as_posix(), savedir=save_dir.as_posix())
+  ```
+
+  Mock `subprocess.run` (pytest-mock's `mocker`) for anything that touches the system, like service reloads.
+- **Run**: `cd packages/python3-nethsec && ./test.sh`. It builds a podman image with Python 3.13 and the OpenWrt `libubox`/`ubus`/`uci` libraries and runs pytest. CI runs the same on changes under `packages/python3-nethsec` (`.github/workflows/python3-nethsec-tests.yml`).
+- **Version**: don't bump `PKG_VERSION`/`PKG_RELEASE`, here or in any other package. Versions are bumped at the end, before the release. `ns-api` depends on `+python3-nethsec` without a version, so an API that needs a new library function ships in the same release as the library change.
+
+New library code must pass ruff like any new Python file (see the `python-nethsecurity` skill).
+
+## API (`ns.*`)
+
+Keep it a dispatcher: parse stdin, call the library, map exceptions to the error format, print JSON. `packages/ns-api/files/ns.dpi` is the model. Protocol, ACLs and docs are in the `ns-api` skill.
+
+APIs stage changes and let `ns.commit` apply them. Committing and restarting from inside an API method is a last resort, for the few operations that by design or by user interaction need an immediate effect (registration, HA setup, adding storage). Avoid it whenever the change can wait for Apply, and say it in the method's README entry when you can't.
+
+## Commit hooks
+
+### How `ns.commit` runs them
+
+Read `packages/ns-api/files/ns.commit` before writing one. Verified on a device (Python 3.13.9):
+
+- Every executable file in the directory runs, in no guaranteed order (`glob.glob`, unsorted).
+- **`*.py` files are `exec()`'d inside `ns.commit`'s `execute_hook()` function**, not run as a process:
+  - `changes` is in scope. It's a dict `{config: [[op, section, option, value], ...]}`, e.g. `{"system": [["set", "cfg01e48a", "hostname", "fw1"]]}`.
+  - Mutating `changes` sticks and reaches the commit and the post-commit hooks. Rebinding it (`changes = {...}`) is lost.
+  - Imports at hook top level aren't visible inside functions the hook defines (`NameError`). Keep the hook flat, or import inside the function, or better, call a library function.
+  - `print()` writes into `ns.commit`'s stdout and corrupts the API's JSON response.
+  - `sys.exit()` raises `SystemExit`, which the `except Exception` around the hook doesn't catch: it aborts `ns.commit` halfway through the commit.
+  - A raised exception is logged to syslog and the path is added to `pre_errors`/`post_errors`. The commit goes on anyway.
+- Other executables run as a subprocess with `changes` as JSON on stdin. Output is ignored and they can't change `changes`.
+- After the pre-commit hooks, `ns.commit` commits every config that is a key of `changes`. That's how a pre-commit hook gets its own edits committed.
+- The whole call runs under rpcd's exec timeout (`rpcd.@rpcd[0].timeout`, 300 s on the device), together with every other hook.
+
+### Writing one
+
+The feature package ships its own hook (as `ns-threat_shield` does), so it exists only when the feature is installed:
+
+```makefile
+	$(INSTALL_DIR) $(1)/usr/libexec/ns-api/pre-commit
+	$(INSTALL_BIN) ./files/ns-foo-pre-commit.py $(1)/usr/libexec/ns-api/pre-commit/ns-foo.py
+```
+
+Pre-commit template, modeled on `ns-threat_shield/files/configure-adblock-devices.py`:
+
+```python
+#!/usr/bin/python3
+
+#
+# Copyright (C) 2026 Nethesis S.r.l.
+# SPDX-License-Identifier: GPL-2.0-only
+#
+
+# Keep ns-foo.config.devices aligned with the devices of the configured zone.
+
+# `changes` is injected by ns.commit when the hook is exec'd.
+if 'network' in changes or 'firewall' in changes or 'ns-foo' in changes:  # noqa: F821
+    from euci import EUci
+    from nethsec import foo
+
+    uci = EUci()
+    if foo.sync_devices(uci):  # library: computes, compares, uci.save('ns-foo'), returns True if changed
+        if 'ns-foo' not in changes:  # noqa: F821
+            changes['ns-foo'] = {}  # noqa: F821
+```
+
+- Return early unless a config you care about is in `changes`.
+- Compare before writing, so an unrelated Apply doesn't generate new changes.
+- `uci.save()` and add the config to `changes`. Never `uci.commit()` in a pre-commit hook.
+- Put the logic in the library and test it there. The hook stays a few lines of glue.
+- No `print()`, no `sys.exit()`, no `subprocess` with `shell=True` on values from `changes` or UCI.
+- In a post-commit hook, don't restart a service that has a procd trigger: `reload_config` runs right after and reloads it.
+
+## Don't copy
+
+Most of these are workarounds that couldn't be avoided at the time. Don't extend the pattern to new code.
+
+- `ns-api/files/post-commit/restart-cron.py`: when `snort` changed it reads `changes['firewall']` (`KeyError` without firewall changes), and runs `["/etc/init.d", "cron", "restart"]`. Cron is managed through `crontab -` now, see `ns-background-work`.
+- `ns-threat_shield/files/adjust-banip.py`: `uci.get(...)` returns `'0'`, which is truthy, so it never stops a disabled banIP; it stop/starts banIP on every network change; bare `except:`.
+- `ns-threat_shield/files/configure-banip-wans.py`: calls `uci.commit('banip')` inside a pre-commit hook. Save and add the config to `changes` instead.
+- Fat APIs: `ns.ovpnrw`, `ns.ha`, `ns.devices`, `ns.threatshield` keep their logic inline, with no tests. New logic goes in the library.
+
+## Verify on a device
+
+```sh
+uci set ns-foo.config.x=1                    # stage a change
+ubus call uci changes                        # what the UI would send
+api-cli ns.commit commit --data "$(ubus call uci changes)"
+logread -e ns.commit -e python               # hook exceptions land in syslog
+```
+
+A non-empty `pre_errors`/`post_errors` in the response names the failing hook.
+
+## Sources
+
+- `packages/ns-api/files/ns.commit`, `packages/ns-api/README.md` (ns.commit section), `docs/design/index.md` ("Commit hooks")
+- UI side: https://github.com/NethServer/nethsecurity-ui/blob/main/src/stores/standalone/uciPendingChanges.ts
+- `packages/python3-nethsec/README.md`, `setup.py`, `test.sh`, `tests/`
+- procd triggers and `reload_config`: `ns-background-work` skill, `references/procd-init.md`
diff --git a/AGENTS.md b/AGENTS.md
index c5d6e8428..5c73a4962 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -14,6 +14,7 @@ This project has domain-specific skills available. You MUST activate the relevan
 - `ns-background-work` — **ACTIVATE** when something must run on its own on the device. Triggers: periodic jobs, cron entries, procd init scripts (daemon or one-shot), running at boot or on UCI change, hotplug iface handlers, uci-defaults that register cron or enable services, or when user mentions service, cron, schedule, "every N minutes", startup. Covers picking the mechanism, templates, apk install/upgrade/remove behavior and which existing examples not to copy.
 - `ns-state-and-persistence` — **ACTIVATE** when deciding where a package keeps config, secrets, runtime state or growing data. Triggers: new UCI config or option, `conffiles`, `/lib/upgrade/keep.d`, `/etc/sysupgrade.conf`, writing under `/var`, `/tmp` or `/mnt/data`, `ns-storage`, `sync-data`, or questions about surviving upgrade, backup/restore or HA sync. Covers the filesystem layout, the shared sysupgrade/backup/HA keep list, UCI migrations, secrets handling and storage fallback.
 - `ns-firewall-integration` — **ACTIVATE** when a change touches the firewall. Triggers: opening ports, allow/deny rules, zones, forwardings, NAT/redirect/netmap, packet marking/labels/logging, `/etc/config/firewall`, `/usr/share/nftables.d`, `fw4`, `nft`, `ns_tag`, `ns_link`, `system_rule`, templates database. Covers fw4 UCI via `nethsec.firewall` vs nft snippets, include positions, generated snippets with validation, and which existing patterns not to copy.
+- `ns-code-placement` — **ACTIVATE** when deciding where logic goes or reacting to a UCI change on Apply. Triggers: new Python logic or API method, `packages/python3-nethsec`, library tests, `ns.commit`, pre/post-commit hooks, keeping two configs consistent, "do X when the user saves". Covers library vs API vs hook vs procd trigger, how `ns.commit` exec's hooks and its gotchas, library tests and release, and which existing hooks/APIs not to copy.
 - `ns-api` — **ACTIVATE** when writing, modifying, or reviewing Python RPCD API scripts. Triggers: creating or updating `ns.*` RPCD API endpoints, handling UCI configuration changes, managing pre/post-commit hooks, defining ACL permissions, documenting methods in OpenAPI 3.1.0, or when user mentions ns-api, API endpoints, hooks, or references `/usr/libexec/rpcd/ns.` files. Covers stdin/stdout JSON protocol, error handling, naming conventions, code style, and spec file updates.
 - `openwrt-package` — **ACTIVATE** when creating or modifying OpenWrt `ns-*` packages. Triggers: building new packages for NethSecurity, managing package dependencies, patching upstream feeds, modifying Makefiles, or when user mentions Makefile, package structure, config fragments, or upstream patches. Covers naming conventions, required Makefile fields, architecture selection, external version management, and patch workflows.
 - `openwrt-package-update` — **ACTIVATE** when updating forked OpenWrt packages from the upstream feed (adblock, mwan3, banip, etc.). Triggers: updating non-ns- packages, comparing local forks against openwrt/packages, merging upstream improvements, or when user mentions upstream package updates. Auto-discovers packages; extracts old/new snapshots for side-by-side comparison; guides cross-package impact detection.
@@ -159,6 +160,9 @@ GIN_MODE=debug  # (instead of release)
 | PR branch | branch-named | `<base>-PR<pr_number>.<run>.<timestamp>.<hash>` |
 
 **Package/Image release:**
+
+Don't bump `PKG_VERSION` or `PKG_RELEASE` as part of a change unless explicitly told to. Versions are bumped at the end, when preparing the release.
+
 1. Bump `PKG_VERSION` or `PKG_RELEASE` in `packages/<name>/Makefile`.
 2. Merge the tested change to `release`.
 3. The `release` branch push publishes the stable channel automatically.

From 7a86e5e2119df17f984d92bc9e123437cf97caf2 Mon Sep 17 00:00:00 2001
From: Tommaso Bailetti <tommaso.bailetti@nethesis.it>
Date: Tue, 20 Oct 2026 10:41:52 +0200
Subject: [PATCH 05/13] feat: added platform integration skill

---
 .../skills/ns-platform-integration/SKILL.md   | 176 ++++++++++++++++++
 .../ns-platform-integration/references/ha.md  |  82 ++++++++
 AGENTS.md                                     |   1 +
 3 files changed, 259 insertions(+)
 create mode 100644 .agents/skills/ns-platform-integration/SKILL.md
 create mode 100644 .agents/skills/ns-platform-integration/references/ha.md

diff --git a/.agents/skills/ns-platform-integration/SKILL.md b/.agents/skills/ns-platform-integration/SKILL.md
new file mode 100644
index 000000000..4e33e0ab5
--- /dev/null
+++ b/.agents/skills/ns-platform-integration/SKILL.md
@@ -0,0 +1,176 @@
+---
+name: ns-platform-integration
+description: Plug a NethSecurity package or device service into the platform services around it — High Availability (keepalived master/backup, ns-ha sync), metrics and alerts (telegraf, VictoriaMetrics, vmalert), logging (rsyslog, /var/log/messages, VictoriaLogs, controller log forwarding) and remote management (controller, my.nethesis.it, ns-plug, inventory facts). Use whenever a task adds or changes a daemon, cron job or feature on the device, or touches `/etc/hotplug.d/keepalived`, `ns-ha`, `ns-rsync.sh`, `telegraf.conf.d`, `/etc/vmalert/rules`, `MONITORED_SERVICES`, rsyslog, `logger`, `ns-plug`, `send-inventory`, `fact_*`, `ns.controller`, `ns-push-reports`, even when the user only asks "should it run on the backup node", "add an alert", "where do the logs go", "does the controller see it" or "make it a well-behaved service".
+metadata:
+  domain: nethsecurity-packages
+  type: runtime
+---
+
+## Integration points
+
+Most packages need only some of these. Go through the rows, integrate where the condition holds and skip the rest without adding anything. A tool that just runs, writes config and exits has nothing to do in HA or telegraf.
+
+| Point | Integrate only when | Ships | `DEPENDS` |
+|---|---|---|---|
+| HA | it's a running service or cron job that must not run on both nodes (talks to the outside, sends notifications, owns a listener) | `/etc/hotplug.d/keepalived/NNN-ns-foo` | `+keepalived` (`+ns-ha` too if it uses `update_cron`) |
+| Service-down alert | it's a long-running procd daemon | a line in `MONITORED_SERVICES` (central) | none |
+| Own metrics | it has a health signal worth graphing or alerting on | telegraf drop-in + collector | `+telegraf` |
+| Own alerts | one of its metrics needs an alert | `/etc/vmalert/rules/ns-foo.yaml` | `+victoria-metrics` (ships vmalert) |
+| Logging | always (writing to syslog needs nothing) | an rsyslog include only if the user asks for routing | `+rsyslog` only with an include |
+| Inventory | my or phonehome stats must know the feature is in use | `fact_<name>` in `python3-nethsec` (central) | none |
+| Register/unregister hook | it must react to the unit joining or leaving my | `/usr/share/ns-plug/hooks/{register,unregister}/` | `+ns-plug` |
+| Controller push | the controller needs data it can't get by calling the API | `dump-*` in `ns.controller` (central) | none |
+
+Persistence, firewall, scheduling and code placement have their own skills (`ns-state-and-persistence`, `ns-firewall-integration`, `ns-background-work`, `ns-code-placement`). This one covers what's left.
+
+**Ownership rule**: when a package does integrate, it ships its own files and declares the dependency from the table. Don't add them to `packages/ns-ha`, `packages/telegraf` or `packages/ns-plug` like the existing ones are: those are older layouts. The only central edits are `MONITORED_SERVICES`, inventory facts and controller dumps, which have no drop-in mechanism.
+
+## HA
+
+On a cluster both nodes boot every service normally. keepalived (`START=70`) then fires `/etc/hotplug.d/keepalived/*` on each state change, and the scripts there stop or restart services. Nothing disables init scripts.
+
+Skip this section when the package runs nothing persistent: a one-shot that writes config gets its config synced like everything else and needs no hotplug. Anything that talks to the outside world, sends things, or owns a VIP-bound listener runs on the master only. Ship this from the package, with `+keepalived` in `DEPENDS`:
+
+```makefile
+define Package/ns-foo/install
+	...
+	$(INSTALL_DIR) $(1)/etc/hotplug.d/keepalived
+	$(INSTALL_DATA) ./files/ns-foo.keepalived $(1)/etc/hotplug.d/keepalived/800-ns-foo
+endef
+```
+
+```sh
+#!/bin/sh
+
+. /lib/functions/keepalived/hotplug.sh
+
+set_service_name ns-foo
+
+set_restart_if_master
+set_stop_if_backup
+
+keepalived_hotplug
+```
+
+- `INSTALL_DATA`, not `INSTALL_BIN`: `hotplug-call` sources the files.
+- Keep `set_service_name` and `set_stop_if_backup` as literal lines. `ns-ha-disable --force` (run on FAULT/STOP) greps hotplug files for them to know what to stop; services stopped only inside callbacks are missed.
+- Cron jobs: the backup receives the master's crontab on every sync, so disable them on `NOTIFY_BACKUP` **and** `NOTIFY_SYNC`, enable on `NOTIFY_MASTER`, with `update_cron` from `/lib/functions/keepalived/ns.sh`. `packages/ns-ha/files/900-ns-plug` is the example.
+- Config reaches the backup through `conffiles` (see `ns-state-and-persistence`). Don't add paths to `ha_peer.sync_list` in `ns.ha`: it's written only when HA is first configured, so existing clusters never get it.
+- Synced config is copied on the backup but not applied. Add `set_reload_if_sync` only when the service also runs on the backup and must follow config changes.
+- Add the service to the list in `packages/ns-ha/README.md`.
+
+`references/ha.md` has the events, every helper, the file-name ordering bands, how sync is applied, and what not to copy.
+
+## Metrics and alerts
+
+Pipeline: telegraf (inputs from `/etc/telegraf.conf.d/*.conf`) → local VictoriaMetrics `127.0.0.1:8428` → vmalert (`/etc/vmalert/rules/*.yaml`) → my.nethesis.it alertmanager when the unit is subscribed (`ns-plug.config.notifier_url`), otherwise discarded. The controller doesn't get alerts; it scrapes metrics over the VPN.
+
+**Service down**: `packages/telegraf/files/telegraf-services` exports `procd_service_running` for the names in `MONITORED_SERVICES`, and `ns-plug/files/vmalert-rules/services.yaml` alerts on them. Add a long-running daemon's procd service name there. Skip one-shots.
+
+**Own metric**: a collector that prints a JSON array, plus a drop-in, with `+telegraf` in `DEPENDS`. Only the plugins in `GO_PKG_TAGS` of `packages/telegraf/Makefile` exist; `inputs.exec` with `json_v2` covers almost everything. An unknown plugin breaks the whole telegraf config.
+
+```toml
+# /etc/telegraf.conf.d/ns-foo.conf
+[[inputs.exec]]
+  name_override = "ns_foo"
+  commands = [["/usr/libexec/telegraf-ns-foo"]]
+  interval = "60s"
+  timeout = "5s"
+  data_format = "json_v2"
+
+  [[inputs.exec.json_v2]]
+    [[inputs.exec.json_v2.object]]
+      path = "@this"
+      tags = ["instance"]
+
+  [inputs.exec.tags]
+    influxdb_db = "os-metrics"
+```
+
+The collector prints e.g. `[{"instance": "main", "queue_full": 0}]`, which becomes `ns_foo_queue_full{instance="main"}`. Keep it fast and side-effect free; it runs every interval. telegraf runs with `--watch-config`, so installing or removing the drop-in reloads it.
+
+**Alert rule**, with `+victoria-metrics` in `DEPENDS`, same format as `ns-plug/files/vmalert-rules/storage.yaml`:
+
+```yaml
+# /etc/vmalert/rules/ns-foo.yaml
+groups:
+  - name: "ns-foo"
+    interval: "5m"
+    rules:
+      - alert: NsFooQueueFull
+        expr: 'ns_foo_queue_full == 1'
+        for: "5m"
+        labels:
+          severity: "warning"
+          service: "ns-foo"
+        annotations:
+          summary_en: "..."
+          summary_it: "..."
+          description_en: "..."
+          description_it: "..."
+```
+
+- `severity` is `info`, `warning` or `critical`; use `service:`, not `alertgroup:` (`services.yaml` is the odd one out). English and Italian annotations are both required.
+- vmalert doesn't watch the directory. Run `/etc/init.d/vmalert reload` in the package `postinst` and `postrm` (guarded by `IPKG_INSTROOT`, as `ns-plug`'s postinst does).
+- The UI reads firing alerts through `ns.telegraf list-alerts` and the `/api/alerts` proxy; a new rule shows up there with no UI change.
+
+## Logging
+
+logd isn't built: there is no `logread`. rsyslog writes everything to `/var/log/messages` (size-capped, copied to `/mnt/data/log` when storage is present), and from there it's forwarded to VictoriaLogs when installed, to the controller's promtail when the unit is connected, and to any remote syslog the user configured. Writing to syslog is the whole integration.
+
+| Code | How |
+|---|---|
+| procd daemon | print to stdout/stderr, `procd_set_param stdout 1` and `stderr 1`; the tag is the program name |
+| Python daemon | `logging` with a `StreamHandler()` to stderr, under procd as above |
+| shell script / cron job | `logger -t ns-foo "..."` (always `-t`) |
+| Python script outside procd | `syslog.openlog("ns-foo")` then `syslog.syslog(...)` |
+
+- No private log files (`/var/log/ns-foo.log`): they skip the size cap, the storage copy and every forwarder.
+- Don't touch the rsyslog line or timestamp format: `ns.log`, `ns.report` and `ns.controller` parse `/var/log/messages` with regexes.
+- No per-package rsyslog rules unless the user asks for routing. When needed, depend on `+rsyslog`, ship `/etc/rsyslog.d/ns-foo.conf` and add it to `rsyslog.syslog.includes` from a uci-default, like `victoria-logs/files/35_victoria-logs`.
+- Never log secrets (see `ns-state-and-persistence`).
+
+## Controller and my
+
+The unit can be connected to a controller (`ns-plug.config.server`, `unit_id`, `token` set), subscribed to my (`ns-plug.config.system_id`, `secret` set, `type` is `enterprise` or `community`), both, or neither. Anything remote must exit 0 silently when its keys are missing.
+
+- **APIs**: a new `ns.*` RPCD API is reachable from the controller as-is (VPN → nginx → ns-api-server → rpcd, as the `controller` rpcd user). Nothing to add.
+- **Inventory**: to make the feature visible in my and in phonehome stats, add `fact_<name>(uci)` to `packages/python3-nethsec/src/nethsec/inventory/__init__.py` returning a small dict (`fact_hotspot` is the pattern), and a test in `tests/test_inventory.py`. Every `fact_*` is picked up automatically. Wrap identifiers (IPs, hostnames) in `anonymize()`. Never change an existing fact's shape.
+- **Register/unregister reactions**: install an executable into `/usr/share/ns-plug/hooks/register/` or `hooks/unregister/` (name starts with a two-digit order, e.g. `60ns-foo`), with `+ns-plug` in `DEPENDS`. Exit codes are ignored.
+- **Pushing data to the controller**: add a `dump-*` method to `packages/ns-api/files/ns.controller` and to the list in `ns-plug/files/ns-push-reports`. The controller needs a matching `/ingest/<name>` endpoint in `nethsecurity-controller`, so this is a cross-repo change: ask before starting it.
+- Remote jobs on a cluster run on the master only (HA section, cron).
+
+## Don't copy
+
+- Hotplug scripts installed by hand in `packages/ns-ha/Makefile`, telegraf drop-ins inside `packages/telegraf` and rules inside `packages/ns-plug/files/vmalert-rules`: the old central layout.
+- `packages/ns-ha/files/900-telegraf`: calls `set_service_name` with no flags, so the service part does nothing.
+- `telegraf/files/telegraf.conf.d/banip.conf`: parses `/var/log/messages` with grok. Use a collector instead.
+- `logger` without `-t` (`ns-ha/files/conntrackd.sh`), `SysLogHandler('/dev/log')` with a custom formatter (`ns-ha-enable`), `echo >> /etc/rsyslog.conf` (`ns-storage/files/30_ns-storage`).
+- `ns-plug` shell scripts pass secrets on the curl command line and build JSON by string concatenation.
+
+## Verify on a device
+
+```sh
+# HA (on both nodes; force a switch with /etc/init.d/keepalived restart on the master)
+ls /etc/hotplug.d/keepalived/
+ubus call service list '{"name":"ns-foo"}'     # running on master, absent on backup
+crontab -l | grep ns-foo                       # commented out on backup
+
+# Metrics and alerts
+/usr/libexec/telegraf-ns-foo                   # valid JSON array
+curl -s 'http://127.0.0.1:8428/api/v1/query?query=ns_foo_queue_full'
+curl -s 'http://127.0.0.1:8428/api/v1/query?query=procd_service_running{service="ns-foo"}'
+api-cli ns.telegraf list-alerts
+
+# Logging
+grep ns-foo /var/log/messages | tail
+
+# Inventory
+/usr/sbin/inventory | jq .features.foo
+```
+
+## Sources
+
+- `packages/ns-ha/README.md`, `packages/telegraf/README.md`, `packages/victoria-metrics/README.md`, `packages/victoria-logs/README.md`, `packages/ns-plug/README.md`, `packages/ns-api-server/README.md` in this repo
+- keepalived hotplug helpers: `packages/keepalived/files/lib/functions/keepalived/hotplug.sh`
+- `hotplug-call`: https://github.com/openwrt/openwrt/blob/v25.12.5/package/base-files/files/sbin/hotplug-call
diff --git a/.agents/skills/ns-platform-integration/references/ha.md b/.agents/skills/ns-platform-integration/references/ha.md
new file mode 100644
index 000000000..f98384785
--- /dev/null
+++ b/.agents/skills/ns-platform-integration/references/ha.md
@@ -0,0 +1,82 @@
+# HA reference
+
+## Events
+
+`keepalived.init` calls `hotplug-call keepalived` with `ACTION` set to:
+
+| ACTION | When |
+|---|---|
+| `NOTIFY_MASTER` | this node became master |
+| `NOTIFY_BACKUP` | this node became backup |
+| `NOTIFY_FAULT` | interface/track failure; default handling is a no-op, `999-stop-fault` runs `ns-ha-disable --force` |
+| `NOTIFY_STOP` | keepalived stopped |
+| `NOTIFY_SYNC` | on the backup, after `ns-rsync.sh` on the master pushed files (every 600 s) |
+| `startup` / `shutdown` | keepalived service start/stop |
+
+## Helpers
+
+From `packages/keepalived/files/lib/functions/keepalived/hotplug.sh`, sourced by every script:
+
+| Helper | Effect |
+|---|---|
+| `set_service_name <init script>` | which `/etc/init.d/<name>` the flags act on |
+| `set_restart_if_master` / `set_reload_if_master` | restart/reload on `NOTIFY_MASTER` |
+| `set_stop_if_backup` | stop on `NOTIFY_BACKUP` |
+| `set_reload_if_backup` | despite the name, restarts on `NOTIFY_BACKUP` |
+| `set_reload_if_sync` / `set_restart_if_sync` | on `NOTIFY_SYNC` |
+| `set_master_cb` / `set_backup_cb` / `set_fault_cb` / `set_sync_cb <fn>` | custom function per event |
+| `keepalived_hotplug` | dispatch; must be the last line |
+
+From `packages/ns-ha/files/ns.sh` (installed to `/lib/functions/keepalived/ns.sh`): `update_cron enable|disable "<space-separated command patterns>"` comments or uncomments matching crontab lines.
+
+Logging inside hotplugs: `log_info` / `log_err` from `/lib/functions/keepalived/common.sh`.
+
+## Ordering
+
+`hotplug-call` runs `ls /etc/hotplug.d/keepalived/*`, so names sort as text, not numbers: `10-adjust` runs before `100-conntrackd`, and a `1000-x` would run before `500-*`. Stick to three-digit prefixes in the existing bands:
+
+| Prefix | Used for |
+|---|---|
+| `00`–`10` | lock, rsync restore, alert state, network import (ns-ha internals) |
+| `100` | conntrackd |
+| `5xx` | core: firewall, dhcp, netmap, rpcd, system, dropbear |
+| `6xx` | VPN, WAN and network services: openvpn, ipsec, mwan3, acme, qosify, snort |
+| `700` | nginx |
+| `800` | applications: ui, banip, adblock, netifyd, flashstart, dedalo |
+| `900` | cloud and telemetry: ns-plug, telegraf, phonehome, ddns |
+| `999` | stop-fault, unlock (must stay last) |
+
+A new application goes in `800`, a new cloud/reporting service in `900`.
+
+## Patterns in the tree
+
+| Pattern | Examples |
+|---|---|
+| restart on master, stop on backup | `600-openvpn`, `800-flashstart`, `800-banip`, `800-ui` |
+| same, plus cron toggling | `600-acme`, `800-netifyd`, `900-ns-plug` |
+| runs on both, reloaded on sync | `500-netmap`, keepalived's `501-rpcd`, `511-firewall`, `555-dropbear` |
+| restart on master, never stopped | `700-nginx` |
+| custom logic only | `05-alert-state`, `10-adjust`, `100-conntrackd`, `500-dhcp-force` |
+
+## How sync works
+
+1. On the master, `ns-rsync.sh` (`/usr/libexec/ns-rsync.sh`, a keepalived `vrrp_script`) runs `ns-ha-export` (dumps WAN, VPN, routes, hotspot into `/etc/ha`), then rsyncs `sysupgrade -l` plus `ha_peer.sync_list`, minus `ha_peer.exclude_list`, into `/tmp/ns-ha` on the backup, with a `restore_list`.
+2. On the backup, keepalived's `02-rsync` (`NOTIFY_SYNC`) copies every `restore_list` entry into place: files with `cp -a`, directories with `rsync --delete`.
+3. `10-adjust` runs `ns-ha-import`, rebuilding network sections tagged `ns_tag=ha` with `auto=0`.
+4. Nothing else is reloaded unless a script set `set_reload_if_sync`/`set_restart_if_sync`. Other services pick up the new config when they're restarted on `NOTIFY_MASTER`.
+
+Never synced: `/etc/config/network`, `/etc/config/keepalived`, `/etc/dropbear/authorized_keys`, `conntrackd.conf`.
+
+A file deleted on the master stays on the backup unless it's inside a synced directory. `900-ns-plug` removes `/etc/backup.pass` by hand for that reason.
+
+## Alerts
+
+`05-alert-state` and `ns-rsync.sh` write `keepalived.ha_alert.*_failed_at` to `/var/state`; `telegraf-ha-alert` turns them into metrics, `ns-plug/files/vmalert-rules/ha.yaml` alerts on them (`HaPrimaryFailed`, `HaSyncFailed`).
+
+## Don't copy
+
+- `ns-ha-disable:58` references an undefined `proc`.
+- `ns-ha-enable:149` calls `/sbin/ifup link set` where `/sbin/ip` is meant.
+- `500-dhcp-force` runs `uci commit` from a hotplug and redirects with `2&>/dev/null`.
+- `100-conntrackd` has no shebang.
+- `packages/ns-ha/README.md` gives `/etc/keepalived/scripts/ns-rsync.sh` and `/tmp/restore_list`; the real paths are `/usr/libexec/ns-rsync.sh` and `/tmp/ns-ha/tmp/restore_list`. It also calls the alerts `ha:sync:failed`.
diff --git a/AGENTS.md b/AGENTS.md
index 5c73a4962..aaff0c204 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -15,6 +15,7 @@ This project has domain-specific skills available. You MUST activate the relevan
 - `ns-state-and-persistence` — **ACTIVATE** when deciding where a package keeps config, secrets, runtime state or growing data. Triggers: new UCI config or option, `conffiles`, `/lib/upgrade/keep.d`, `/etc/sysupgrade.conf`, writing under `/var`, `/tmp` or `/mnt/data`, `ns-storage`, `sync-data`, or questions about surviving upgrade, backup/restore or HA sync. Covers the filesystem layout, the shared sysupgrade/backup/HA keep list, UCI migrations, secrets handling and storage fallback.
 - `ns-firewall-integration` — **ACTIVATE** when a change touches the firewall. Triggers: opening ports, allow/deny rules, zones, forwardings, NAT/redirect/netmap, packet marking/labels/logging, `/etc/config/firewall`, `/usr/share/nftables.d`, `fw4`, `nft`, `ns_tag`, `ns_link`, `system_rule`, templates database. Covers fw4 UCI via `nethsec.firewall` vs nft snippets, include positions, generated snippets with validation, and which existing patterns not to copy.
 - `ns-code-placement` — **ACTIVATE** when deciding where logic goes or reacting to a UCI change on Apply. Triggers: new Python logic or API method, `packages/python3-nethsec`, library tests, `ns.commit`, pre/post-commit hooks, keeping two configs consistent, "do X when the user saves". Covers library vs API vs hook vs procd trigger, how `ns.commit` exec's hooks and its gotchas, library tests and release, and which existing hooks/APIs not to copy.
+- `ns-platform-integration` — **ACTIVATE** when adding or changing a daemon, cron job or feature on the device. Triggers: HA/keepalived master-backup behavior, `/etc/hotplug.d/keepalived`, `ns-ha`, telegraf inputs, vmalert rules, `MONITORED_SERVICES`, service-down alerts, logging (`logger`, rsyslog, `/var/log/messages`), controller or my.nethesis.it visibility, `ns-plug`, inventory `fact_*`, `ns.controller` dumps. Covers which platform services a package must plug into, package-owned hotplug/metric/alert files, and which existing layouts not to copy.
 - `ns-api` — **ACTIVATE** when writing, modifying, or reviewing Python RPCD API scripts. Triggers: creating or updating `ns.*` RPCD API endpoints, handling UCI configuration changes, managing pre/post-commit hooks, defining ACL permissions, documenting methods in OpenAPI 3.1.0, or when user mentions ns-api, API endpoints, hooks, or references `/usr/libexec/rpcd/ns.` files. Covers stdin/stdout JSON protocol, error handling, naming conventions, code style, and spec file updates.
 - `openwrt-package` — **ACTIVATE** when creating or modifying OpenWrt `ns-*` packages. Triggers: building new packages for NethSecurity, managing package dependencies, patching upstream feeds, modifying Makefiles, or when user mentions Makefile, package structure, config fragments, or upstream patches. Covers naming conventions, required Makefile fields, architecture selection, external version management, and patch workflows.
 - `openwrt-package-update` — **ACTIVATE** when updating forked OpenWrt packages from the upstream feed (adblock, mwan3, banip, etc.). Triggers: updating non-ns- packages, comparing local forks against openwrt/packages, merging upstream improvements, or when user mentions upstream package updates. Auto-discovers packages; extracts old/new snapshots for side-by-side comparison; guides cross-package impact detection.

From 5e035171ecd6ececd8d18da5bc601d16f75ea503 Mon Sep 17 00:00:00 2001
From: Tommaso Bailetti <tommaso.bailetti@nethesis.it>
Date: Tue, 20 Oct 2026 12:08:41 +0200
Subject: [PATCH 06/13] made the harness force print the proposed issue

---
 .agents/skills/create-issue/SKILL.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.agents/skills/create-issue/SKILL.md b/.agents/skills/create-issue/SKILL.md
index 3d5101ba8..a4bdede15 100644
--- a/.agents/skills/create-issue/SKILL.md
+++ b/.agents/skills/create-issue/SKILL.md
@@ -99,12 +99,12 @@ Presentation matters (per handbook): use code fences for logs and commands, list
 
 ### 4. Show the draft, then get go-ahead
 
-**Showing the draft means printing, in chat: the title, the complete body, the type, the milestone and the assignee.** Printing the `gh` command instead of the body is not showing the draft. Neither is describing what the body says.
+**Showing the draft means printing, in chat: the title, the complete body, the type, the milestone and the assignee.** Printing the `gh` command instead of the body is not showing the draft. Neither is describing what the body says. Text printed in the same response as an `AskUserQuestion` call is hidden behind the dialog, so the draft goes in a response of its own: print it and end the turn, with the question in plain text at the bottom.
 
 Fields first, permission second — they are separate exchanges:
 
 1. Resolve the field candidates: `gh api repos/NethServer/nethsecurity/milestones --jq '.[].title'` and `gh api user --jq '.login'`. Ask milestone and assignee in one question, offering the nearest open milestone and the user's own login as the suggested answers (both may legitimately be "none"). Ask about type here too if it was ambiguous in step 1.
-2. Re-show the corrected draft in full, then ask separately whether to file it.
+2. Re-show the corrected draft in full and end the turn, asking in plain text whether to file it.
 
 **Never write to GitHub without explicit confirmation for that specific write.** This gate covers every write: `gh issue create`, `gh issue edit`, `gh issue comment`, `gh pr edit`, and any label/milestone/assignee change. Permission to file is not permission to then edit, comment, or touch a PR — each one is asked for on its own. Issues are public and notify subscribers.
 

From 029e87963d472389764995c7def80d335198806c Mon Sep 17 00:00:00 2001
From: Tommaso Bailetti <tommaso.bailetti@nethesis.it>
Date: Tue, 20 Oct 2026 11:37:49 +0200
Subject: [PATCH 07/13] feat: added user calling the function to python
 handlers

---
 .../ns-api-server/files/src/methods/ubus.go   | 16 +++++++
 .../files/src/methods/ubus_test.go            | 44 +++++++++++++++++++
 .../src/nethsec/users/__init__.py             | 33 ++++++++++++++
 packages/python3-nethsec/tests/test_users.py  | 43 ++++++++++++++++++
 4 files changed, 136 insertions(+)
 create mode 100644 packages/ns-api-server/files/src/methods/ubus_test.go

diff --git a/packages/ns-api-server/files/src/methods/ubus.go b/packages/ns-api-server/files/src/methods/ubus.go
index fba672e12..7cf407ee0 100644
--- a/packages/ns-api-server/files/src/methods/ubus.go
+++ b/packages/ns-api-server/files/src/methods/ubus.go
@@ -13,13 +13,16 @@ import (
 	"encoding/json"
 	"io"
 	"net/http"
+	"os"
 	"os/exec"
 	"fmt"
 
 	"github.com/NethServer/nethsecurity-api/models"
 	"github.com/NethServer/nethsecurity-api/response"
 	"github.com/NethServer/nethsecurity-api/logs"
+	"github.com/NethServer/nethsecurity-api/utils"
 	"github.com/Jeffail/gabs/v2"
+	jwt "github.com/appleboy/gin-jwt/v2"
 	"github.com/fatih/structs"
 	"github.com/gin-gonic/gin"
 	"github.com/gin-gonic/gin/binding"
@@ -41,11 +44,14 @@ func UBusCallAction(c *gin.Context) {
 	// convert payload to JSON
 	jsonPayload, _ := json.Marshal(jsonUBusCall.Payload)
 
+	username := jwt.ExtractClaims(c)["id"].(string)
+
 	// check if path starts with ns.
 	if jsonUBusCall.Path[:3] == "ns." {
 		// force base path to avoid calling other system binaries
 		jsonUBusCall.Path = "/usr/libexec/rpcd/" + jsonUBusCall.Path
 		cmd = exec.Command(jsonUBusCall.Path, "call", jsonUBusCall.Method)
+		cmd.Env = append(os.Environ(), "NS_API_USER="+username)
 
 		// execute direct script call
 		stdin, err := cmd.StdinPipe()
@@ -79,7 +85,17 @@ func UBusCallAction(c *gin.Context) {
 				}
 			}
 		}
+		// FIXME: Replace the UI's generic uci get/set with ns.* methods and drop them from authorizedPaths.
+		// Until then rpcd and users are blocked here, they hold admin logins and password hashes that only ns.users may change.
+		if jsonUBusCall.Path == "uci" && (jsonUBusCall.Method == "get" || jsonUBusCall.Method == "set") {
+			payload, _ := jsonUBusCall.Payload.(map[string]interface{})
+			config, _ := payload["config"].(string)
+			if config == "rpcd" || config == "users" {
+				forbidden = true
+			}
+		}
 		if forbidden {
+			logs.Logs.Println("[INFO][AUTH] ubus call forbidden for user " + utils.SanitizeForLog(username) + ". " + utils.SanitizeForLog(jsonUBusCall.Path) + " " + utils.SanitizeForLog(jsonUBusCall.Method))
 			c.AbortWithStatusJSON(http.StatusForbidden, structs.Map(response.StatusBadRequest{
 				Code:    403,
 				Message: "ubus call action forbidden",
diff --git a/packages/ns-api-server/files/src/methods/ubus_test.go b/packages/ns-api-server/files/src/methods/ubus_test.go
new file mode 100644
index 000000000..a497a7225
--- /dev/null
+++ b/packages/ns-api-server/files/src/methods/ubus_test.go
@@ -0,0 +1,44 @@
+/*
+Copyright (C) 2026 Nethesis S.r.l.
+SPDX-License-Identifier: GPL-2.0-only
+*/
+
+package methods
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	jwt "github.com/appleboy/gin-jwt/v2"
+	"github.com/gin-gonic/gin"
+)
+
+func TestUBusCallUciForbiddenConfigs(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	r := gin.New()
+	r.POST("/ubus/call", func(c *gin.Context) {
+		c.Set("JWT_PAYLOAD", jwt.MapClaims{"id": "admin"})
+		UBusCallAction(c)
+	})
+
+	cases := []struct {
+		body          string
+		wantForbidden bool
+	}{
+		{`{"path":"uci","method":"get","payload":{"config":"rpcd"}}`, true},
+		{`{"path":"uci","method":"set","payload":{"config":"users","section":"x","values":{}}}`, true},
+		{`{"path":"uci","method":"get","payload":{"config":"network"}}`, false},
+		{`{"path":"uci","method":"revert","payload":{"config":"rpcd"}}`, false},
+	}
+	for _, tc := range cases {
+		w := httptest.NewRecorder()
+		req, _ := http.NewRequest(http.MethodPost, "/ubus/call", strings.NewReader(tc.body))
+		req.Header.Set("Content-Type", "application/json")
+		r.ServeHTTP(w, req)
+		if (w.Code == http.StatusForbidden) != tc.wantForbidden {
+			t.Errorf("%s: got status %d, want forbidden=%v", tc.body, w.Code, tc.wantForbidden)
+		}
+	}
+}
diff --git a/packages/python3-nethsec/src/nethsec/users/__init__.py b/packages/python3-nethsec/src/nethsec/users/__init__.py
index 5ee701e3b..de5e08e72 100644
--- a/packages/python3-nethsec/src/nethsec/users/__init__.py
+++ b/packages/python3-nethsec/src/nethsec/users/__init__.py
@@ -485,6 +485,9 @@ def add_local_user(uci, name, password="", description="", database="main", extr
       - The user identifier
     '''
     utils.validate_username(name)
+    # nethsupport is reserved even while support access is off, its rpcd login exists only when on
+    if is_superuser(uci, name.lower()) or name.lower() == 'nethsupport':
+        raise utils.ValidationError('name', 'reserved_name', name)
     if get_user_by_name(uci, name, database):
         raise utils.ValidationError('name', 'user_already_exists', name)
     if get_database_type(uci, database) != "local":
@@ -908,6 +911,36 @@ def is_admin(uci, username):
             return True
     return False
 
+def is_superuser(uci, username):
+    '''
+    Check if a user is root, the controller account or the support account
+
+    Arguments:
+      - uci -- EUci pointer
+      - username -- User name
+
+    Returns:
+      - True if user is a superuser, False otherwise
+    '''
+    if username == 'root':
+        return True
+    for section in ('controller', 'ns_don'):
+        if username and uci.get('rpcd', section, 'username', default='') == username:
+            return True
+    return False
+
+def caller_is_superuser(uci):
+    '''
+    Check if the user calling the API is a superuser, callers outside ns-api-server are trusted as root
+
+    Arguments:
+      - uci -- EUci pointer
+
+    Returns:
+      - True if the caller is a superuser, False otherwise
+    '''
+    return is_superuser(uci, os.environ.get('NS_API_USER', 'root'))
+
 
 def used_by(uci, database_name):
     """
diff --git a/packages/python3-nethsec/tests/test_users.py b/packages/python3-nethsec/tests/test_users.py
index cdf8ba134..5c0f9c547 100644
--- a/packages/python3-nethsec/tests/test_users.py
+++ b/packages/python3-nethsec/tests/test_users.py
@@ -604,3 +604,46 @@ def test_get_database(tmp_path):
         "user_display_attr": "cn",
         "starttls": "0"
     }
+
+def _setup_superusers_db(tmp_path):
+    u = _setup_db(tmp_path)
+    with tmp_path.joinpath('rpcd').open('w') as fp:
+        fp.write("""
+config login
+	option username 'root'
+
+config login 'controller'
+	option username '3fe5ac6d66e2b8952b194aa1'
+
+config login 'ns_don'
+	option username 'nethsupport'
+
+config login 'ns_1234'
+	option username 'admin3'
+""")
+    return u
+
+def test_is_superuser(tmp_path):
+    u = _setup_superusers_db(tmp_path)
+    assert users.is_superuser(u, 'root')
+    assert users.is_superuser(u, '3fe5ac6d66e2b8952b194aa1')
+    assert users.is_superuser(u, 'nethsupport')
+    assert not users.is_superuser(u, 'admin3')
+    assert not users.is_superuser(u, '')
+
+def test_caller_is_superuser(tmp_path, monkeypatch):
+    u = _setup_superusers_db(tmp_path)
+    monkeypatch.delenv('NS_API_USER', raising=False)
+    assert users.caller_is_superuser(u)
+    monkeypatch.setenv('NS_API_USER', 'nethsupport')
+    assert users.caller_is_superuser(u)
+    monkeypatch.setenv('NS_API_USER', 'admin3')
+    assert not users.caller_is_superuser(u)
+
+def test_add_local_user_reserved_name(tmp_path):
+    u = _setup_superusers_db(tmp_path)
+    for name in ['root', 'Root', '3fe5ac6d66e2b8952b194aa1', 'nethsupport']:
+        with pytest.raises(utils.ValidationError) as e:
+            users.add_local_user(u, name, password="nethesis", database="second")
+        assert e.value.parameter == 'name'
+        assert e.value.message == 'reserved_name'

From 079d5ffb74b36da2f659d2c6c3de6142007b26ea Mon Sep 17 00:00:00 2001
From: Tommaso Bailetti <tommaso.bailetti@nethesis.it>
Date: Tue, 20 Oct 2026 11:38:16 +0200
Subject: [PATCH 08/13] fix(inventory): removing nethsupport from user count

---
 packages/python3-nethsec/src/nethsec/inventory/__init__.py | 4 ++--
 packages/python3-nethsec/tests/test_inventory.py           | 3 +++
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/packages/python3-nethsec/src/nethsec/inventory/__init__.py b/packages/python3-nethsec/src/nethsec/inventory/__init__.py
index ae8134f94..d57fb85b0 100644
--- a/packages/python3-nethsec/src/nethsec/inventory/__init__.py
+++ b/packages/python3-nethsec/src/nethsec/inventory/__init__.py
@@ -419,8 +419,8 @@ def fact_controller(uci: EUci):
 def fact_rpcd_users(uci: EUci):
     count = 0
     for section, options in (utils.get_all_by_type(uci, 'rpcd', 'login') or {}).items():
-        # skip root and the controller user (controller has a random username)
-        if options.get('username') == 'root' or section == 'controller':
+        # skip root, the controller user (controller has a random username) and the support user
+        if options.get('username') == 'root' or section in ('controller', 'ns_don'):
             continue
         count += 1
     return { 'count': count }
diff --git a/packages/python3-nethsec/tests/test_inventory.py b/packages/python3-nethsec/tests/test_inventory.py
index a9618346e..46475354b 100644
--- a/packages/python3-nethsec/tests/test_inventory.py
+++ b/packages/python3-nethsec/tests/test_inventory.py
@@ -797,6 +797,9 @@
 
 config login 'ns_7fe3e016'
 	option username 'example'
+
+config login 'ns_don'
+	option username 'nethsupport'
 """
 
 def _setup_db(tmp_path):

From 81797f44609be8ee11ac27461d9506491618d2c6 Mon Sep 17 00:00:00 2001
From: Tommaso Bailetti <tommaso.bailetti@nethesis.it>
Date: Tue, 20 Oct 2026 15:13:58 +0200
Subject: [PATCH 09/13] feat: added first checks for permissions in api

---
 packages/ns-api/README.md                     |  7 ++-
 packages/ns-api/files/ns.users                | 52 +++++++++++++------
 .../src/nethsec/users/__init__.py             | 22 ++++----
 packages/python3-nethsec/tests/test_users.py  | 39 +++++++++-----
 4 files changed, 82 insertions(+), 38 deletions(-)

diff --git a/packages/ns-api/README.md b/packages/ns-api/README.md
index 0feb5913c..efb261b9e 100644
--- a/packages/ns-api/README.md
+++ b/packages/ns-api/README.md
@@ -5729,6 +5729,10 @@ Response example:
 
 ## ns.users
 
+Admin accounts can be managed only by a superuser: `root`, the controller account and the support account.
+Other admins get `{"error": "forbidden"}` when calling `set-admin`, `remove-admin`, `edit-local-user` and `delete-local-user` on an admin,
+or `delete-local-database` on a database containing admins.
+
 ### list-users
 
 List configured users
@@ -5952,7 +5956,7 @@ May raise the following validation errors:
 
 ### delete-local-database
 
-Delete the local user database and all its users and groups:
+Delete the local user database and all its users and groups, admins lose their admin role:
 ```
 api-cli ns.users delete-local-database --data '{"name": "local2"}''
 ```
@@ -5983,6 +5987,7 @@ May raise the following validation errors:
 - user_already_exists
 - db_not_local
 - invalid_name if `name` contains characters other than letters, digits, dots, underscores, at signs and hyphens
+- reserved_name if `name` is reserved for a system account
 
 ### edit-local-user
 
diff --git a/packages/ns-api/files/ns.users b/packages/ns-api/files/ns.users
index 97b34bcd4..1559aae69 100644
--- a/packages/ns-api/files/ns.users
+++ b/packages/ns-api/files/ns.users
@@ -47,6 +47,8 @@ else:
         else:
             args = json.loads(sys.stdin.read())
 
+        caller_is_superuser = users.caller_is_superuser(u)
+
         if action == "list-users":
             ret = {"users": users.list_users(u, args['database'])}
         elif action == "add-local-database":
@@ -56,8 +58,14 @@ else:
             users.edit_local_database(u, args['name'], args['description'])
             ret = {"result": "success"}
         elif action == "delete-local-database":
-            users.delete_local_database(u, args['name'])
-            ret = {"result": "success"}
+            admins = []
+            if users.get_database_type(u, args["name"]) == "local":
+                admins = [user["name"] for user in users.list_users(u, args["name"]) if user["admin"]]
+            if admins and not caller_is_superuser:
+                ret = utils.generic_error("forbidden")
+            else:
+                users.delete_local_database(u, args["name"])
+                ret = {"result": "success"}
 
         elif action == "add-ldap-database":
             users.add_ldap_database(u, args['name'], args['uri'], args['schema'], args['base_dn'], args['user_dn'], args['user_attr'], args['user_display_attr'], args['start_tls'], args['tls_reqcert'], args['description'], args.get('bind_dn'), args.get('bind_password'), args.get("user_bind_dn"))
@@ -76,17 +84,23 @@ else:
         elif action == "add-local-user":
             ret = {"id": users.add_local_user(u, args['name'], args.get('password'), args.get('description',''), args['database'], args.get("extra"))}
         elif action == "edit-local-user":
-            extra = args.get("extra")
-            if not extra:
-                # preserve existing extra params, like OpenVPN config
-                info = users.get_user_by_name(u, args['name'])
-                for field in info:
-                    if field not in ('id', 'name', 'password', 'description', 'database', 'local', 'admin'):
-                        extra[field] = info[field]
-            ret = {"id": users.edit_local_user(u, args['name'], args.get('password'), args.get('description',''), args['database'], extra)}
+            if users.is_admin(u, args["name"]) and not caller_is_superuser:
+                ret = utils.generic_error("forbidden")
+            else:
+                extra = args.get("extra")
+                if not extra:
+                    # preserve existing extra params, like OpenVPN config
+                    info = users.get_user_by_name(u, args['name'])
+                    for field in info:
+                        if field not in ('id', 'name', 'password', 'description', 'database', 'local', 'admin'):
+                            extra[field] = info[field]
+                ret = {"id": users.edit_local_user(u, args['name'], args.get('password'), args.get('description',''), args['database'], extra)}
         elif action == "delete-local-user":
-            users.delete_local_user(u, args['name'], args['database'])
-            ret = {"result": "success"}
+            if users.is_admin(u, args["name"]) and not caller_is_superuser:
+                ret = utils.generic_error("forbidden")
+            else:
+                users.delete_local_user(u, args['name'], args['database'])
+                ret = {"result": "success"}
 
         elif action == "add-remote-user":
             ret = {"id": users.add_remote_user(u, args['name'], args['database'], args["extra"])}
@@ -97,11 +111,17 @@ else:
             ret = {"result": "success"}
 
         elif action == "set-admin":
-            id = users.set_admin(u, args['name'], args['database'])
-            ret = {"id": id}
+            if not caller_is_superuser:
+                ret = utils.generic_error("forbidden")
+            else:
+                id = users.set_admin(u, args['name'], args['database'])
+                ret = {"id": id}
         elif action == "remove-admin":
-            id = users.remove_admin(u, args['name'])
-            ret = {"result": "success"}
+            if not caller_is_superuser:
+                ret = utils.generic_error("forbidden")
+            else:
+                id = users.remove_admin(u, args['name'])
+                ret = {"result": "success"}
 
         print(json.dumps(ret))
 
diff --git a/packages/python3-nethsec/src/nethsec/users/__init__.py b/packages/python3-nethsec/src/nethsec/users/__init__.py
index de5e08e72..537d049d6 100644
--- a/packages/python3-nethsec/src/nethsec/users/__init__.py
+++ b/packages/python3-nethsec/src/nethsec/users/__init__.py
@@ -419,6 +419,9 @@ def delete_local_database(uci, name):
   uci.delete('users', name)
   for u in uci.get_all('users'):
       if uci.get('users', u, 'database', default='') == name:
+          username = uci.get('users', u, 'name', default='')
+          if uci.get('users', u, default='') == 'user' and is_admin(uci, username):
+              remove_admin(uci, username)
           uci.delete('users', u)
   uci.save("users")
   return True
@@ -486,8 +489,8 @@ def add_local_user(uci, name, password="", description="", database="main", extr
     '''
     utils.validate_username(name)
     # nethsupport is reserved even while support access is off, its rpcd login exists only when on
-    if is_superuser(uci, name.lower()) or name.lower() == 'nethsupport':
-        raise utils.ValidationError('name', 'reserved_name', name)
+    if is_superuser(uci, name.lower()) or name.lower() == "nethsupport":
+        raise utils.ValidationError("name", "reserved_name", name)
     if get_user_by_name(uci, name, database):
         raise utils.ValidationError('name', 'user_already_exists', name)
     if get_database_type(uci, database) != "local":
@@ -912,7 +915,7 @@ def is_admin(uci, username):
     return False
 
 def is_superuser(uci, username):
-    '''
+    """
     Check if a user is root, the controller account or the support account
 
     Arguments:
@@ -921,16 +924,17 @@ def is_superuser(uci, username):
 
     Returns:
       - True if user is a superuser, False otherwise
-    '''
-    if username == 'root':
+    """
+    if username == "root":
         return True
-    for section in ('controller', 'ns_don'):
-        if username and uci.get('rpcd', section, 'username', default='') == username:
+    for section in ("controller", "ns_don"):
+        if username and uci.get("rpcd", section, "username", default="") == username:
             return True
     return False
 
+
 def caller_is_superuser(uci):
-    '''
+    """
     Check if the user calling the API is a superuser, callers outside ns-api-server are trusted as root
 
     Arguments:
@@ -938,7 +942,7 @@ def caller_is_superuser(uci):
 
     Returns:
       - True if the caller is a superuser, False otherwise
-    '''
+    """
     return is_superuser(uci, os.environ.get('NS_API_USER', 'root'))
 
 
diff --git a/packages/python3-nethsec/tests/test_users.py b/packages/python3-nethsec/tests/test_users.py
index 5c0f9c547..d62dba34f 100644
--- a/packages/python3-nethsec/tests/test_users.py
+++ b/packages/python3-nethsec/tests/test_users.py
@@ -317,6 +317,17 @@ def test_delete_local_database(tmp_path):
     with pytest.raises(UciExceptionNotFound) as e:
         u.get('users', 'g1')
 
+def test_delete_local_database_removes_admins(tmp_path):
+    _setup_db(tmp_path)
+    # own savedir, the default one is shared with the other tests
+    tmp_path.joinpath("save").mkdir()
+    u = EUci(confdir=tmp_path.as_posix(), savedir=tmp_path.joinpath("save").as_posix())
+    users.add_local_user(u, "admin9", password="nethesis", database="second")
+    users.set_admin(u, "admin9", "second")
+    users.delete_local_database(u, "second")
+    assert not users.is_admin(u, "admin9")
+
+
 def test_add_local_user(tmp_path):
     u = _setup_db(tmp_path)
     id = users.add_local_user(u, "t1", password="nethesis", description="mydesc", database="second", extra_fields={"openvpn_ipaddr": "1.2.3.4"})
@@ -605,9 +616,10 @@ def test_get_database(tmp_path):
         "starttls": "0"
     }
 
+
 def _setup_superusers_db(tmp_path):
     u = _setup_db(tmp_path)
-    with tmp_path.joinpath('rpcd').open('w') as fp:
+    with tmp_path.joinpath("rpcd").open("w") as fp:
         fp.write("""
 config login
 	option username 'root'
@@ -623,27 +635,30 @@ def _setup_superusers_db(tmp_path):
 """)
     return u
 
+
 def test_is_superuser(tmp_path):
     u = _setup_superusers_db(tmp_path)
-    assert users.is_superuser(u, 'root')
-    assert users.is_superuser(u, '3fe5ac6d66e2b8952b194aa1')
-    assert users.is_superuser(u, 'nethsupport')
-    assert not users.is_superuser(u, 'admin3')
-    assert not users.is_superuser(u, '')
+    assert users.is_superuser(u, "root")
+    assert users.is_superuser(u, "3fe5ac6d66e2b8952b194aa1")
+    assert users.is_superuser(u, "nethsupport")
+    assert not users.is_superuser(u, "admin3")
+    assert not users.is_superuser(u, "")
+
 
 def test_caller_is_superuser(tmp_path, monkeypatch):
     u = _setup_superusers_db(tmp_path)
-    monkeypatch.delenv('NS_API_USER', raising=False)
+    monkeypatch.delenv("NS_API_USER", raising=False)
     assert users.caller_is_superuser(u)
-    monkeypatch.setenv('NS_API_USER', 'nethsupport')
+    monkeypatch.setenv("NS_API_USER", "nethsupport")
     assert users.caller_is_superuser(u)
-    monkeypatch.setenv('NS_API_USER', 'admin3')
+    monkeypatch.setenv("NS_API_USER", "admin3")
     assert not users.caller_is_superuser(u)
 
+
 def test_add_local_user_reserved_name(tmp_path):
     u = _setup_superusers_db(tmp_path)
-    for name in ['root', 'Root', '3fe5ac6d66e2b8952b194aa1', 'nethsupport']:
+    for name in ["root", "Root", "3fe5ac6d66e2b8952b194aa1", "nethsupport"]:
         with pytest.raises(utils.ValidationError) as e:
             users.add_local_user(u, name, password="nethesis", database="second")
-        assert e.value.parameter == 'name'
-        assert e.value.message == 'reserved_name'
+        assert e.value.parameter == "name"
+        assert e.value.message == "reserved_name"

From badb0c9ee392e1aefef8a0f7b6c8792b5ecd91aa Mon Sep 17 00:00:00 2001
From: Tommaso Bailetti <tommaso.bailetti@nethesis.it>
Date: Tue, 20 Oct 2026 15:22:14 +0200
Subject: [PATCH 10/13] feat: added admin informations from the ns.account

---
 packages/ns-api/README.md        | 20 ++++++++
 packages/ns-api/files/ns.account | 83 ++++++++++++++++++--------------
 2 files changed, 68 insertions(+), 35 deletions(-)

diff --git a/packages/ns-api/README.md b/packages/ns-api/README.md
index efb261b9e..6236bc8a7 100644
--- a/packages/ns-api/README.md
+++ b/packages/ns-api/README.md
@@ -4219,6 +4219,26 @@ Parameter list:
 - `username`: target to change the password to, must be present inside `rpcd` configuration
 - `password`: password to set to the user
 
+Admins can change only their own password. Superusers (`root`, the controller account and the support account)
+can change any password. Otherwise the call returns `{"error": "forbidden"}`.
+
+### get-info
+
+Return info about the calling account and the admin accounts.
+
+```bash
+api-cli ns.account get-info
+```
+
+Response example:
+```json
+{"is_superuser": true, "default_password": false, "ordinary_admins": 2}
+```
+
+- `is_superuser`: the caller is `root`, the controller account or the support account
+- `default_password`: `root` still uses the default password
+- `ordinary_admins`: number of admins that aren't superusers
+
 ## ns.backup
 
 Allows the backup/restore of the system, some features are only available to subscribed users. Please refer
diff --git a/packages/ns-api/files/ns.account b/packages/ns-api/files/ns.account
index 8afcd306e..c57fe77a6 100755
--- a/packages/ns-api/files/ns.account
+++ b/packages/ns-api/files/ns.account
@@ -6,11 +6,12 @@
 #
 
 import json
+import os
 import subprocess
 import sys
 
 from euci import EUci
-from nethsec import utils, users
+from nethsec import inventory, utils, users
 
 cmd = sys.argv[1]
 
@@ -20,7 +21,8 @@ if cmd == 'list':
             'username': 'str',
             'password': 'str',
             'old_password': 'str',
-        }
+        },
+        'get-info': {}
     }))
 elif cmd == 'call':
     action = sys.argv[2]
@@ -28,45 +30,56 @@ elif cmd == 'call':
     if action == 'set-password':
         try:
             data = json.load(sys.stdin)
-            rpcd_user_list = utils.get_all_by_type(e_uci, 'rpcd', 'login')
-            user_list = utils.get_all_by_type(e_uci, 'users', 'user')
-            # check if username is inside config
-            if data['username'] not in [user['username'] for user in rpcd_user_list.values()]:
-                raise utils.ValidationError('username', 'invalid', data['username'])
+            is_own_account = data["username"] == os.environ.get("NS_API_USER")
+            if not is_own_account and not users.caller_is_superuser(e_uci):
+                print(json.dumps(utils.generic_error("forbidden")))
+            else:
+                rpcd_user_list = utils.get_all_by_type(e_uci, 'rpcd', 'login')
+                user_list = utils.get_all_by_type(e_uci, 'users', 'user')
+                # check if username is inside config
+                if data['username'] not in [user['username'] for user in rpcd_user_list.values()]:
+                    raise utils.ValidationError('username', 'invalid', data['username'])
 
-            if not users.check_old_password(data.get('username'), data.get('old_password', '')):
-                raise utils.ValidationError('old_password', 'invalid_old_password')
-            if users.check_old_password(data.get('username'), data.get('password', '')):
-                raise utils.ValidationError('new_password', 'cannot_reuse_old_password')
-            # if user is not root, change rpcd config
-            if data['username'] != 'root':
-                password_hash = users.shadow_password(data['password'])
-                for user_key, user in rpcd_user_list.items():
-                    if user['username'] == data['username']:
-                        e_uci.set('rpcd', user_key, 'password', password_hash)
-                        e_uci.save('rpcd')
-                        e_uci.commit('rpcd')
-                        break
-                # sync password inside local users db
-                for user_key, user in user_list.items():
-                    is_local = users.get_database_type(e_uci, user['database']) == 'local'
-                    if user['name'] == data['username'] and is_local:
-                        e_uci.set('users', user_key, 'password', password_hash)
-                        e_uci.save('users')
-                        e_uci.commit('users')
-                        break
+                if not users.check_old_password(data.get('username'), data.get('old_password', '')):
+                    raise utils.ValidationError('old_password', 'invalid_old_password')
+                if users.check_old_password(data.get('username'), data.get('password', '')):
+                    raise utils.ValidationError('new_password', 'cannot_reuse_old_password')
+                # if user is not root, change rpcd config
+                if data['username'] != 'root':
+                    password_hash = users.shadow_password(data['password'])
+                    for user_key, user in rpcd_user_list.items():
+                        if user['username'] == data['username']:
+                            e_uci.set('rpcd', user_key, 'password', password_hash)
+                            e_uci.save('rpcd')
+                            e_uci.commit('rpcd')
+                            break
+                    # sync password inside local users db
+                    for user_key, user in user_list.items():
+                        is_local = users.get_database_type(e_uci, user['database']) == 'local'
+                        if user['name'] == data['username'] and is_local:
+                            e_uci.set('users', user_key, 'password', password_hash)
+                            e_uci.save('users')
+                            e_uci.commit('users')
+                            break
 
-            else:
-                # otherwise, change `passwd` file using pre-existing ubus call
-                subprocess.run(['ubus', 'call', 'luci', 'setPassword', json.dumps({
-                    'username': data['username'],
-                    'password': data['password']
-                })], capture_output=True, check=True)
+                else:
+                    # otherwise, change `passwd` file using pre-existing ubus call
+                    subprocess.run(['ubus', 'call', 'luci', 'setPassword', json.dumps({
+                        'username': data['username'],
+                        'password': data['password']
+                    })], capture_output=True, check=True)
 
-            print(json.dumps({'message': 'success'}))
+                print(json.dumps({'message': 'success'}))
         except KeyError as ex:
             print(json.dumps(utils.validation_error(ex.args[0], 'required')))
         except utils.ValidationError as ex:
             print(json.dumps(utils.validation_error(ex.parameter, ex.message, ex.value)))
         except subprocess.CalledProcessError as ex:
             print(json.dumps(utils.generic_error(f'subprocess {ex.cmd[0]} failed')))
+    elif action == "get-info":
+        info = {
+            "is_superuser": users.caller_is_superuser(e_uci),
+            "default_password": inventory.fact_default_password(e_uci)["default_password"],
+            "ordinary_admins": inventory.fact_rpcd_users(e_uci)["count"],
+        }
+        print(json.dumps(info))

From 32643055e1691e77b5d4415b5f8cde7796b4224a Mon Sep 17 00:00:00 2001
From: Tommaso Bailetti <tommaso.bailetti@nethesis.it>
Date: Tue, 20 Oct 2026 17:55:38 +0200
Subject: [PATCH 11/13] feat: added ns.ssh management and token removal on
 delete of users

---
 .../ns-api-server/files/src/methods/ubus.go   |  5 +-
 .../files/src/methods/ubus_test.go            |  1 +
 packages/ns-api/README.md                     | 41 ++++++++-
 packages/ns-api/files/ns.ssh                  | 86 ++++++++++++++++---
 .../files/post-commit/clear-user-tokens.py    | 30 ++++---
 .../src/nethsec/users/__init__.py             | 16 +++-
 packages/python3-nethsec/tests/test_users.py  | 10 +++
 7 files changed, 158 insertions(+), 31 deletions(-)

diff --git a/packages/ns-api-server/files/src/methods/ubus.go b/packages/ns-api-server/files/src/methods/ubus.go
index 7cf407ee0..054edbe96 100644
--- a/packages/ns-api-server/files/src/methods/ubus.go
+++ b/packages/ns-api-server/files/src/methods/ubus.go
@@ -86,11 +86,12 @@ func UBusCallAction(c *gin.Context) {
 			}
 		}
 		// FIXME: Replace the UI's generic uci get/set with ns.* methods and drop them from authorizedPaths.
-		// Until then rpcd and users are blocked here, they hold admin logins and password hashes that only ns.users may change.
+		// Until then rpcd and users are blocked here, they hold admin logins and password hashes that only ns.users may change,
+		// and dropbear can be changed only by superusers through ns.ssh.
 		if jsonUBusCall.Path == "uci" && (jsonUBusCall.Method == "get" || jsonUBusCall.Method == "set") {
 			payload, _ := jsonUBusCall.Payload.(map[string]interface{})
 			config, _ := payload["config"].(string)
-			if config == "rpcd" || config == "users" {
+			if config == "rpcd" || config == "users" || config == "dropbear" {
 				forbidden = true
 			}
 		}
diff --git a/packages/ns-api-server/files/src/methods/ubus_test.go b/packages/ns-api-server/files/src/methods/ubus_test.go
index a497a7225..0c3a790be 100644
--- a/packages/ns-api-server/files/src/methods/ubus_test.go
+++ b/packages/ns-api-server/files/src/methods/ubus_test.go
@@ -29,6 +29,7 @@ func TestUBusCallUciForbiddenConfigs(t *testing.T) {
 	}{
 		{`{"path":"uci","method":"get","payload":{"config":"rpcd"}}`, true},
 		{`{"path":"uci","method":"set","payload":{"config":"users","section":"x","values":{}}}`, true},
+		{`{"path":"uci","method":"set","payload":{"config":"dropbear","section":"main","values":{}}}`, true},
 		{`{"path":"uci","method":"get","payload":{"config":"network"}}`, false},
 		{`{"path":"uci","method":"revert","payload":{"config":"rpcd"}}`, false},
 	}
diff --git a/packages/ns-api/README.md b/packages/ns-api/README.md
index 6236bc8a7..df853539b 100644
--- a/packages/ns-api/README.md
+++ b/packages/ns-api/README.md
@@ -4965,20 +4965,29 @@ Response example:
 
 ## ns.ssh
 
-Read SSH keys
+Manage SSH access for `root`, the only account allowed to log in through SSH.
 
-### list-keys
+Every admin can read the configuration. Only `root` and the support account can change it,
+other admins and the controller account get `{"error": "forbidden"}`.
+`add-key` and `delete-key` also require sudo mode.
 
-Returns list of authorized keys:
+### get-configuration
+
+Returns the SSH configuration and the authorized keys:
 
 ```bash
-api-cli ns.ssh list-keys
+api-cli ns.ssh get-configuration
 ```
 
 Output example:
 
 ```json
 {
+  "configuration": {
+    "Port": "22",
+    "RootPasswordAuth": "off",
+    "GatewayPorts": "off"
+  },
   "keys": [
     {
       "type": "ssh-rsa",
@@ -4989,6 +4998,30 @@ Output example:
 }
 ```
 
+`RootPasswordAuth` is `on` only when both `PasswordAuth` and `RootPasswordAuth` are enabled in `dropbear.main`.
+
+### set-configuration
+
+Change the SSH configuration, changes must be committed with `ns.commit`:
+
+```bash
+api-cli ns.ssh set-configuration --data '{"Port": "22", "RootPasswordAuth": "on", "GatewayPorts": "off"}'
+```
+
+`RootPasswordAuth` is written to both `PasswordAuth` and `RootPasswordAuth`.
+
+Example response:
+
+```json
+{
+  "message": "success"
+}
+```
+
+May raise the following validation errors:
+- invalid_port if `Port` isn't between 1 and 65535
+- invalid_value if `RootPasswordAuth` or `GatewayPorts` aren't `on` or `off`
+
 ### add-key
 
 Add a new key for SSH access:
diff --git a/packages/ns-api/files/ns.ssh b/packages/ns-api/files/ns.ssh
index 705dd9682..941f262a0 100755
--- a/packages/ns-api/files/ns.ssh
+++ b/packages/ns-api/files/ns.ssh
@@ -5,12 +5,14 @@
 # SPDX-License-Identifier: GPL-2.0-only
 #
 
-# Read SSH authorized keys
+# Manage SSH configuration and authorized keys
 
 import os
 import sys
 import json
 
+from euci import EUci
+from nethsec import users
 from nethsec.utils import validation_error, ValidationError, generic_error
 
 
@@ -30,6 +32,43 @@ def __list_keys():
     return keys
 
 
+def __is_on(value):
+    return value in ("1", "on", "true", "yes", "enabled")
+
+
+def __get_configuration(uci):
+    # dropbear defaults both flags to on when unset
+    password_auth = __is_on(uci.get("dropbear", "main", "PasswordAuth", default="1"))
+    root_password_auth = __is_on(uci.get("dropbear", "main", "RootPasswordAuth", default="1"))
+    gateway_ports = __is_on(uci.get("dropbear", "main", "GatewayPorts", default="0"))
+    return {
+        "Port": uci.get("dropbear", "main", "Port", default="22"),
+        # PasswordAuth off disables password login for root too
+        "RootPasswordAuth": "on" if password_auth and root_password_auth else "off",
+        "GatewayPorts": "on" if gateway_ports else "off",
+    }
+
+
+def __set_configuration(uci):
+    data = json.load(sys.stdin)
+    for field in ("Port", "RootPasswordAuth", "GatewayPorts"):
+        if field not in data:
+            raise ValidationError(field, "required")
+    port = str(data["Port"])
+    port_is_valid = port.isdigit() and 1 <= int(port) <= 65535
+    if not port_is_valid:
+        raise ValidationError("Port", "invalid_port", data["Port"])
+    for field in ("RootPasswordAuth", "GatewayPorts"):
+        if data[field] not in ("on", "off"):
+            raise ValidationError(field, "invalid_value", data[field])
+    uci.set("dropbear", "main", "Port", str(data["Port"]))
+    # root is the only SSH account, PasswordAuth follows RootPasswordAuth
+    uci.set("dropbear", "main", "PasswordAuth", data["RootPasswordAuth"])
+    uci.set("dropbear", "main", "RootPasswordAuth", data["RootPasswordAuth"])
+    uci.set("dropbear", "main", "GatewayPorts", data["GatewayPorts"])
+    uci.save("dropbear")
+
+
 def __add_key():
     data = json.load(sys.stdin)
     if 'key' not in data:
@@ -66,23 +105,44 @@ KEYS_FILE = '/etc/dropbear/authorized_keys'
 
 cmd = sys.argv[1]
 
-if cmd == 'list':
-    print(json.dumps({
-        "list-keys": {},
-        "add-key": {"key": "string"},
-        "delete-key": {"key": "string"}
-    }))
+if cmd == "list":
+    print(
+        json.dumps(
+            {
+                "get-configuration": {},
+                "set-configuration": {"Port": "22", "RootPasswordAuth": "on", "GatewayPorts": "off"},
+                "add-key": {"key": "string"},
+                "delete-key": {"key": "string"},
+            }
+        )
+    )
 else:
     action = sys.argv[2]
+    uci = EUci()
+    # SSH is managed on the unit, the controller gets read-only access like ordinary admins
+    caller_is_controller = os.environ.get("NS_API_USER") == uci.get("rpcd", "controller", "username", default="")
+    can_write = users.caller_is_superuser(uci) and not caller_is_controller
     try:
-        if action == "list-keys":
-            print(json.dumps({"keys": __list_keys()}))
+        if action == "get-configuration":
+            print(json.dumps({"configuration": __get_configuration(uci), "keys": __list_keys()}))
+        elif action == "set-configuration":
+            if not can_write:
+                print(json.dumps(generic_error("forbidden")))
+            else:
+                __set_configuration(uci)
+                print(json.dumps({"message": "success"}))
         elif action == "add-key":
-            __add_key()
-            print(json.dumps({"message": "success"}))
+            if not can_write:
+                print(json.dumps(generic_error("forbidden")))
+            else:
+                __add_key()
+                print(json.dumps({"message": "success"}))
         elif action == "delete-key":
-            __delete_key()
-            print(json.dumps({"message": "success"}))
+            if not can_write:
+                print(json.dumps(generic_error("forbidden")))
+            else:
+                __delete_key()
+                print(json.dumps({"message": "success"}))
     except ValidationError as e:
         print(json.dumps(validation_error(e.parameter, e.message, e.value)))
     except Exception as e:
diff --git a/packages/ns-api/files/post-commit/clear-user-tokens.py b/packages/ns-api/files/post-commit/clear-user-tokens.py
index bd78c1449..7c1f1588e 100644
--- a/packages/ns-api/files/post-commit/clear-user-tokens.py
+++ b/packages/ns-api/files/post-commit/clear-user-tokens.py
@@ -6,21 +6,23 @@
 #
 
 # Log out users that have been deleted or demoted from the admin role:
-# remove their token store so the API server invalidates all their sessions.
+# remove their token store so the API server invalidates all their sessions,
+# and delete their 2FA secret so they start over if they become admins again.
 # Only admins (rpcd login sections) can authenticate against the API, so any
-# token file whose username is no longer an admin is stale and must be purged.
+# token file or 2FA secret whose username is no longer an admin is stale and must be purged.
 
 import glob
 import os
 
 from euci import EUci
-from nethsec import utils
+from nethsec import users, utils
 
 TOKENS_DIR = "/var/run/ns-api-server/tokens"
+SECRETS_DIR = "/etc/ns-api-server"
 
 # Admin role changes are tracked in the rpcd configuration.
 # `changes` is injected by ns.commit when the hook is exec'd.
-if "rpcd" in changes and os.path.isdir(TOKENS_DIR):  # noqa: F821
+if "rpcd" in changes:  # noqa: F821
     u = EUci()
     admins = set()
     for login in (utils.get_all_by_type(u, "rpcd", "login") or {}).values():
@@ -28,10 +30,16 @@
         if username:
             admins.add(username)
 
-    for token_file in glob.glob(os.path.join(TOKENS_DIR, "*")):
-        username = os.path.basename(token_file)
-        if username not in admins:
-            try:
-                os.remove(token_file)
-            except OSError:
-                pass
+    if os.path.isdir(TOKENS_DIR):
+        for token_file in glob.glob(os.path.join(TOKENS_DIR, "*")):
+            username = os.path.basename(token_file)
+            if username not in admins:
+                try:
+                    os.remove(token_file)
+                except OSError:
+                    pass
+
+    if os.path.isdir(SECRETS_DIR):
+        for username in os.listdir(SECRETS_DIR):
+            if username not in admins:
+                users.delete_2fa(username)
diff --git a/packages/python3-nethsec/src/nethsec/users/__init__.py b/packages/python3-nethsec/src/nethsec/users/__init__.py
index 537d049d6..9857c8819 100644
--- a/packages/python3-nethsec/src/nethsec/users/__init__.py
+++ b/packages/python3-nethsec/src/nethsec/users/__init__.py
@@ -16,6 +16,7 @@
 import os
 import subprocess
 import secrets
+import shutil
 
 from euci import EUci
 from uci import UciExceptionNotFound
@@ -943,7 +944,20 @@ def caller_is_superuser(uci):
     Returns:
       - True if the caller is a superuser, False otherwise
     """
-    return is_superuser(uci, os.environ.get('NS_API_USER', 'root'))
+    return is_superuser(uci, os.environ.get("NS_API_USER", "root"))
+
+
+def delete_2fa(username, secrets_dir="/etc/ns-api-server"):
+    """
+    Delete the ns-api-server 2FA secret of a user
+
+    Arguments:
+      - username -- User name
+      - secrets_dir -- ns-api-server secrets directory
+    """
+    # an empty name would remove the whole secrets directory
+    if username:
+        shutil.rmtree(os.path.join(secrets_dir, username), ignore_errors=True)
 
 
 def used_by(uci, database_name):
diff --git a/packages/python3-nethsec/tests/test_users.py b/packages/python3-nethsec/tests/test_users.py
index d62dba34f..524183cc6 100644
--- a/packages/python3-nethsec/tests/test_users.py
+++ b/packages/python3-nethsec/tests/test_users.py
@@ -662,3 +662,13 @@ def test_add_local_user_reserved_name(tmp_path):
             users.add_local_user(u, name, password="nethesis", database="second")
         assert e.value.parameter == "name"
         assert e.value.message == "reserved_name"
+
+
+def test_delete_2fa(tmp_path):
+    tmp_path.joinpath("admin3").mkdir()
+    tmp_path.joinpath("admin3", "secret").write_text("x")
+    users.delete_2fa("", secrets_dir=tmp_path.as_posix())
+    assert tmp_path.exists()
+    users.delete_2fa("admin3", secrets_dir=tmp_path.as_posix())
+    assert not tmp_path.joinpath("admin3").exists()
+    users.delete_2fa("nobody", secrets_dir=tmp_path.as_posix())

From 2735ce039afcb2b5d3743197d52e68ad254153f0 Mon Sep 17 00:00:00 2001
From: Tommaso Bailetti <tommaso.bailetti@nethesis.it>
Date: Wed, 21 Oct 2026 10:54:10 +0200
Subject: [PATCH 12/13] feat: added more restrictions to backups, migrations
 and updates

---
 AGENTS.md                                  |   5 +
 docs/design/admin_users.md                 |  67 ++++++++---
 packages/ns-api-server/files/src/README.md |   3 +
 packages/ns-api/README.md                  |   7 +-
 packages/ns-api/files/ns.backup            | 127 ++++++++++++---------
 packages/ns-api/files/ns.migration         |  31 ++---
 packages/ns-api/files/ns.update            |   9 +-
 7 files changed, 162 insertions(+), 87 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index aaff0c204..cc115ca35 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -122,6 +122,11 @@ APIs are Python 3 scripts placed at `/usr/libexec/rpcd/ns.<name>` on the device.
 **ACL files:**
 - Paired with each handler: `ns.NAME.json` installed to `/usr/share/rpcd/acl.d/`.
 - Consistently leave `"write": {}` empty and declare ubus permissions under `"read": { "ubus": ... }`.
+- `ns-api-server` runs `ns.*` scripts directly, so rpcd ACLs don't restrict what a logged user can call.
+
+**Authorization:**
+- `ns-api-server` only authenticates, it passes the caller's username to `ns.*` scripts in `NS_API_USER`.
+- Restrict a method to superusers (`root`, the controller and remote support accounts) with `nethsec.users.caller_is_superuser()` and return `{"error": "forbidden"}` otherwise. See `docs/design/admin_users.md`.
 
 **UCI conventions:**
 - Zones: `ns_<zonename>` (e.g., `ns_lan`, `ns_guest`).
diff --git a/docs/design/admin_users.md b/docs/design/admin_users.md
index c44f270b8..7c00f510b 100644
--- a/docs/design/admin_users.md
+++ b/docs/design/admin_users.md
@@ -6,20 +6,61 @@ parent: Design
 
 # Administrator users
 
-NethSecurity is designed to allow the creation of multiple administrators, each with full control over the system
-from the web interface.
-Administrators are created using the rpcd interface of OpenWrt. 
+NethSecurity allows multiple administrators, each one logging in to the web interface with a personal account.
+An administrator is a local user of the `main` database with a `login` section in the `rpcd` configuration,
+created by `ns.users set-admin`. The `rpcd` login has the same password hash as the local user.
 
-To create a new administrator named "goodboy" with the password "mypassword" execute the following commands:
+To create an administrator named `goodboy` with the password `mypassword`, run as `root`:
 ```shell
-uci revert rpcd
-uci set rpcd.goodboy=login
-uci set rpcd.goodboy.username=goodboy
-uci add_list rpcd.goodboy.read='*'
-uci add_list rpcd.goodboy.write='*'
-uci set rpcd.goodboy.password=$(uhttpd -m 'mypassword')
-uci commit rpcd
+api-cli ns.users add-local-user --data '{"name": "goodboy", "password": "mypassword", "description": "Good boy", "database": "main", "extra": {}}'
+api-cli ns.users set-admin --data '{"name": "goodboy", "database": "main"}'
+api-cli ns.commit commit --data "{\"changes\": $(ubus call uci changes | jq -c .changes)}"
 ```
 
-Please note that the newly created user does not have SSH access.
-Only `root` user can access the system using SSH.
+Administrators have no system account, so only `root` can access the system using SSH.
+
+## Superusers
+
+`root` is the superuser, together with two service accounts that act on its behalf:
+- the controller account, whose username is in `rpcd.controller.username`
+- the remote support account, whose username is in `rpcd.ns_don.username`, present only while remote support is enabled
+
+Only superusers can:
+- create, edit or delete administrators, or change their password (`ns.users`)
+- promote or demote users (`ns.users set-admin` and `remove-admin`)
+- delete a local database that contains administrators
+- change the password of another account (`ns.account set-password`)
+- change SSH settings and keys (`ns.ssh`), with the controller account kept read-only here
+- download, delete or restore from file a backup, and set the backup passphrase (`ns.backup`)
+- migrate from NethServer 7 (`ns.migration migrate`)
+- install an uploaded image (`ns.update install-uploaded-image`)
+
+Other administrators can manage non-administrator users and change their own password.
+Denied calls return `{"error": "forbidden"}`.
+
+Usernames of the superusers and `nethsupport` are reserved and can't be used for local users.
+
+## Checking the caller
+
+`ns-api-server` authenticates the user and runs `ns.*` scripts directly, so it passes the username of the
+caller to them in the `NS_API_USER` environment variable.
+Authorization is done in Python with the `nethsec.users` library:
+- `is_superuser(uci, username)` tells whether a username belongs to a superuser
+- `caller_is_superuser(uci)` checks `NS_API_USER`, trusting callers that don't set it (like `ubus` or scripts run as `root`) as `root`
+
+The UI reads the role of the logged user from `ns.account get-info`, which also returns whether `root` still uses the
+default password and how many non-superuser administrators exist.
+
+`ns-api-server` refuses generic `uci get` and `uci set` calls on the `rpcd`, `users` and `dropbear` configurations, so
+these can be changed only through `ns.users` and `ns.ssh`. `uci changes` and `uci revert` are still allowed.
+
+## Sessions and 2FA
+
+The post-commit hook `clear-user-tokens.py` runs on every commit that changes `rpcd`: for each username that has no `rpcd`
+login anymore, because it was demoted or deleted, it removes the session tokens from `/var/run/ns-api-server/tokens` and
+the 2FA secret from `/etc/ns-api-server`.
+Password changes don't touch the active sessions.
+
+## Limitations
+
+Administrators can still change the rest of the configuration, so administrator access should be given only to trusted operators.
diff --git a/packages/ns-api-server/files/src/README.md b/packages/ns-api-server/files/src/README.md
index 3a27ffd11..ee4da8c4b 100644
--- a/packages/ns-api-server/files/src/README.md
+++ b/packages/ns-api-server/files/src/README.md
@@ -193,6 +193,9 @@ Where:
        "message": "[UBUS] call action success"
      }
     ```
+
+    `ns.*` paths run `/usr/libexec/rpcd/<path>` directly, with the username of the caller in the `NS_API_USER` environment variable.
+    Other paths are limited to a fixed list of `ubus` calls; `uci get` and `uci set` are refused on the `rpcd`, `users` and `dropbear` configurations.
   ### Files
 - `GET /api/files/<file_name>`
 
diff --git a/packages/ns-api/README.md b/packages/ns-api/README.md
index df853539b..5dfa1846f 100644
--- a/packages/ns-api/README.md
+++ b/packages/ns-api/README.md
@@ -4244,6 +4244,9 @@ Response example:
 Allows the backup/restore of the system, some features are only available to subscribed users. Please refer
 to `ns.subscription` for more info.
 
+Only superusers can call `set-passphrase`, `backup`, `restore`, `registered-download-backup` and `registered-delete-backup`,
+other admins get `{"error": "forbidden"}`.
+
 ### set-passphrase
 
 Set encryption passphrase to be used to encrypt/decrypt backups.
@@ -4488,7 +4491,7 @@ Response example:
 
 ### migrate
 
-Execute the migration:
+Execute the migration, only superusers can call it:
 ```
 api-cli ns.migration migrate --data '{"mappings": [{"old": "52:54:00:75:1C:C1", "new": "53:54:44:75:1A:AA"}], "archive": "upload-1e20f4b3-e581-454c-9162-ca33885eb223"}'
 ```
@@ -4922,7 +4925,7 @@ Response example:
 
 ### install-uploaded-image
 
-Install a previously uploaded image inside `/var/run/ns-api-server/` and reboot the unit:
+Install a previously uploaded image inside `/var/run/ns-api-server/` and reboot the unit, only superusers can call it:
 ```
 api-cli ns.update install-uploaded-image --data '{"image": "upload-204be0f3-4bb2-4cb8-ba28-4ac8e41ac697"}'
 ```
diff --git a/packages/ns-api/files/ns.backup b/packages/ns-api/files/ns.backup
index 9dc4fe242..3ec752958 100755
--- a/packages/ns-api/files/ns.backup
+++ b/packages/ns-api/files/ns.backup
@@ -12,7 +12,8 @@ import subprocess
 import sys
 from datetime import datetime
 
-from nethsec import utils
+from euci import EUci
+from nethsec import utils, users
 
 UPLOAD_PATH = '/var/run/ns-api-server/uploads/'
 DOWNLOAD_PATH = '/var/run/ns-api-server/downloads/'
@@ -118,42 +119,52 @@ if cmd == 'list':
     }))
 elif cmd == 'call':
     action = sys.argv[2]
+    caller_is_superuser = users.caller_is_superuser(EUci())
     if action == 'backup':
-        try:
-            data = json.load(sys.stdin)
-            encrypted = data.get('encrypted', True)
-            # generate backup
-            file_name = create_backup(encrypted)
-            print(json.dumps({'backup': file_name}))
-        except RuntimeError as error:
-            print(json.dumps(utils.generic_error(error.args[0])))
+        if not caller_is_superuser:
+            print(json.dumps(utils.generic_error('forbidden')))
+        else:
+            try:
+                data = json.load(sys.stdin)
+                encrypted = data.get('encrypted', True)
+                # generate backup
+                file_name = create_backup(encrypted)
+                print(json.dumps({'backup': file_name}))
+            except RuntimeError as error:
+                print(json.dumps(utils.generic_error(error.args[0])))
 
     elif action == 'restore':
-        try:
-            data = json.load(sys.stdin)
-            # restore backup
-            backup_path = f'{UPLOAD_PATH}{data.get("backup")}'
-            restore_backup(backup_path, data.get('passphrase', None))
-            # restore successful, restart the system
-            subprocess.run(['/sbin/reboot'], check=True, capture_output=True)
-            # reboot takes a few seconds to complete, enough to send the response
-            print(json.dumps({'message': 'success'}))
-        except RuntimeError as error:
-            print(json.dumps(utils.validation_error('passphrase',error.args[0])))
+        if not caller_is_superuser:
+            print(json.dumps(utils.generic_error('forbidden')))
+        else:
+            try:
+                data = json.load(sys.stdin)
+                # restore backup
+                backup_path = f'{UPLOAD_PATH}{data.get("backup")}'
+                restore_backup(backup_path, data.get('passphrase', None))
+                # restore successful, restart the system
+                subprocess.run(['/sbin/reboot'], check=True, capture_output=True)
+                # reboot takes a few seconds to complete, enough to send the response
+                print(json.dumps({'message': 'success'}))
+            except RuntimeError as error:
+                print(json.dumps(utils.validation_error('passphrase',error.args[0])))
 
     elif action == 'set-passphrase':
-        try:
-            # read passphrase, write into default file
-            data = json.load(sys.stdin)
-            if data['passphrase'] == '':
-                os.remove(PASSPHRASE_PATH)
-            else:
-                open(PASSPHRASE_PATH, 'w').write(data['passphrase'])
-            print(json.dumps({'message': 'success'}))
-        except IOError as error:
-            print(json.dumps(utils.generic_error(f'passphrase write failed')))
-        except KeyError as error:
-            print(json.dumps(utils.validation_error('passphrase', 'required')))
+        if not caller_is_superuser:
+            print(json.dumps(utils.generic_error('forbidden')))
+        else:
+            try:
+                # read passphrase, write into default file
+                data = json.load(sys.stdin)
+                if data['passphrase'] == '':
+                    os.remove(PASSPHRASE_PATH)
+                else:
+                    open(PASSPHRASE_PATH, 'w').write(data['passphrase'])
+                print(json.dumps({'message': 'success'}))
+            except IOError as error:
+                print(json.dumps(utils.generic_error(f'passphrase write failed')))
+            except KeyError as error:
+                print(json.dumps(utils.validation_error('passphrase', 'required')))
 
     elif action == 'registered-list-backups':
         try:
@@ -206,31 +217,37 @@ elif cmd == 'call':
             print(json.dumps(utils.validation_error('passphrase',error.args[0])))
 
     elif action == 'registered-download-backup':
-        os.makedirs(DOWNLOAD_PATH, exist_ok=True)
-        try:
-            # fetch file from remote server
-            data = json.load(sys.stdin)
-            file_name = generate_random_file_name()
-            backup_path = f'{DOWNLOAD_PATH}{file_name}'
-            subprocess.run(['/usr/sbin/remote-backup', 'download', data['file'], backup_path],
-                           check=True, capture_output=True)
-            # return content
-            print(json.dumps({'backup': file_name}))
-        except subprocess.CalledProcessError as error:
-            print(json.dumps(utils.generic_error('remote backup download failed')))
-        except KeyError as error:
-            print(json.dumps(utils.validation_error('file', 'required')))
+        if not caller_is_superuser:
+            print(json.dumps(utils.generic_error('forbidden')))
+        else:
+            os.makedirs(DOWNLOAD_PATH, exist_ok=True)
+            try:
+                # fetch file from remote server
+                data = json.load(sys.stdin)
+                file_name = generate_random_file_name()
+                backup_path = f'{DOWNLOAD_PATH}{file_name}'
+                subprocess.run(['/usr/sbin/remote-backup', 'download', data['file'], backup_path],
+                               check=True, capture_output=True)
+                # return content
+                print(json.dumps({'backup': file_name}))
+            except subprocess.CalledProcessError as error:
+                print(json.dumps(utils.generic_error('remote backup download failed')))
+            except KeyError as error:
+                print(json.dumps(utils.validation_error('file', 'required')))
 
     elif action == 'registered-delete-backup':
-        try:
-            data = json.load(sys.stdin)
-            subprocess.run(['/usr/sbin/remote-backup', 'delete', data['id']],
-                           check=True, capture_output=True, text=True)
-            print(json.dumps({'message': 'success'}))
-        except subprocess.CalledProcessError as error:
-            print(json.dumps(utils.generic_error('remote backup delete failed')))
-        except KeyError as error:
-            print(json.dumps(utils.validation_error('id', 'required')))
+        if not caller_is_superuser:
+            print(json.dumps(utils.generic_error('forbidden')))
+        else:
+            try:
+                data = json.load(sys.stdin)
+                subprocess.run(['/usr/sbin/remote-backup', 'delete', data['id']],
+                               check=True, capture_output=True, text=True)
+                print(json.dumps({'message': 'success'}))
+            except subprocess.CalledProcessError as error:
+                print(json.dumps(utils.generic_error('remote backup delete failed')))
+            except KeyError as error:
+                print(json.dumps(utils.validation_error('id', 'required')))
 
     elif action == 'is-passphrase-set':
         print(json.dumps({'values': {'set': os.path.exists(PASSPHRASE_PATH)}}))
diff --git a/packages/ns-api/files/ns.migration b/packages/ns-api/files/ns.migration
index e4e08ec79..26bd5477f 100755
--- a/packages/ns-api/files/ns.migration
+++ b/packages/ns-api/files/ns.migration
@@ -13,7 +13,7 @@ import subprocess
 import sys
 from euci import EUci
 
-from nethsec import utils
+from nethsec import utils, users
 
 MIGRATE_DIR = '/tmp/migration'
 UPLOAD_PATH = '/var/run/ns-api-server/uploads/'
@@ -39,19 +39,22 @@ if cmd == 'list':
 elif cmd == 'call':
     action = sys.argv[2]
     if action == 'migrate':
-        try:
-            data = json.load(sys.stdin)
-            export_archive = f'{UPLOAD_PATH}{data["archive"]}'
-            cmd = ['/usr/sbin/ns-import']
-            for m in data['mappings']:
-                cmd.append("-m")
-                cmd.append(f'{m["old"]}={m["new"]}')
-            cmd.append(export_archive)
-            subprocess.run(cmd, check=True, capture_output=True)
-            # return success
-            print(json.dumps({'result': 'success'}))
-        except RuntimeError as error:
-            print(json.dumps(utils.generic_error(error.args[0])))
+        if not users.caller_is_superuser(EUci()):
+            print(json.dumps(utils.generic_error('forbidden')))
+        else:
+            try:
+                data = json.load(sys.stdin)
+                export_archive = f'{UPLOAD_PATH}{data["archive"]}'
+                cmd = ['/usr/sbin/ns-import']
+                for m in data['mappings']:
+                    cmd.append("-m")
+                    cmd.append(f'{m["old"]}={m["new"]}')
+                cmd.append(export_archive)
+                subprocess.run(cmd, check=True, capture_output=True)
+                # return success
+                print(json.dumps({'result': 'success'}))
+            except RuntimeError as error:
+                print(json.dumps(utils.generic_error(error.args[0])))
 
     elif action == 'list-source-devices':
         ret = []
diff --git a/packages/ns-api/files/ns.update b/packages/ns-api/files/ns.update
index 5557c0692..3ae9b7c10 100755
--- a/packages/ns-api/files/ns.update
+++ b/packages/ns-api/files/ns.update
@@ -15,7 +15,7 @@ import time
 import subprocess
 import semver
 import requests
-from nethsec import utils
+from nethsec import utils, users
 from urllib.parse import urlparse
 from euci import EUci
 
@@ -243,6 +243,9 @@ elif cmd == "call":
     elif action == "update-system":
         ret = update_system()
     elif action == "install-uploaded-image":
-        args = json.loads(sys.stdin.read())
-        ret = install_uploaded_image(args["image"])
+        if not users.caller_is_superuser(EUci()):
+            ret = utils.generic_error("forbidden")
+        else:
+            args = json.loads(sys.stdin.read())
+            ret = install_uploaded_image(args["image"])
     print(json.dumps(ret))

From 6f76ffffaba4d588f912de31a026cf5469d557af Mon Sep 17 00:00:00 2001
From: Tommaso Bailetti <tommaso.bailetti@nethesis.it>
Date: Wed, 21 Oct 2026 12:14:26 +0200
Subject: [PATCH 13/13] chore: ui pin

---
 packages/ns-ui/Makefile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/ns-ui/Makefile b/packages/ns-ui/Makefile
index e0206cccb..fec7b1aaf 100644
--- a/packages/ns-ui/Makefile
+++ b/packages/ns-ui/Makefile
@@ -12,7 +12,7 @@ PKG_RELEASE:=1
 
 PKG_SOURCE_PROTO:=git
 PKG_SOURCE_URL:=https://github.com/NethServer/nethsecurity-ui.git
-PKG_SOURCE_VERSION:=$(PKG_VERSION)
+PKG_SOURCE_VERSION:=f192a0c34316a6119be947e8141f4ffe803c0602
 PKG_SOURCE_SUBDIR:=nethsecurity-ui-$(PKG_SOURCE_VERSION)
 PKG_BUILD_DIR:=$(BUILD_DIR)/$(PKG_SOURCE_SUBDIR)
 PKG_MIRROR_HASH:=skip