ducoterra
86c8bf4992
Phase 33 completion pass is done. Final report:
## Phase 33 — completion report
**All 8 task files complete** (`.agents/phases/complete/33_gateway_route_switching/`), full gate green, docs verified.
### Work in this pass
1. **`tests/test_routectl.py` added** (17 tests, all green) — exercises the *real* helper binary unprivileged against a fake tree (`--root`), the real agent parser, the captured gateway fixtures, and stubbed `nginx`/`haproxy`/`systemctl` on `PATH`. Pins the full protocol (locate → state → dry-run → temp-file/fsync/`os.replace` write → checker → restore on checker failure → reload-never-restart → re-read proof → sidecar record), all three route shapes (haproxy `server`, nginx `proxy_pass`, nginx stream `map` via its sink-value id), `drift` / unknown-id / `map-default` refusals, `list`/`verify`, and the `--serve` peer gate (`SO_PEERCRED` uid check, one JSON line per request, exact body shape).
2. **Real helper defect fixed** — `deploy/dashboards-routectl.py`: `main()`'s early-return paths returned `({"ok": False, …}, EXIT_*)` tuples, so `sys.exit()` printed a Python repr instead of a JSON line (usage errors, agent-import refusal). Now prints `json.dumps(…)` and returns only the code, keeping the one-JSON-line contract.
3. **Documentation consistency fixes** (task 08 criterion 6):
- `README.md`: garbled verdict-colour sentence on the switch ("green and to the position") → "in the **on** position and tinted `--gate-on`" (the existence-pair contract).
- `README.md`: audit sentence now names all three event kinds — `route-disabled` / `route-enabled` / **`route-denied`** (the code stores one per refused call; dry runs store none).
- `page-gateway.js`: replaced the stale pre-33 module docstring ("the switch is not wired") with the two-arm `GATEWAY_ALLOW_WRITES` contract.
- `AGENTS.md`: every phase-33 claim re-verified against code (the ten gates, the 35 s/30 s budget pair, `gateway.writes_enabled`, `/api/summary`'s `disabled`, the 1.4.0 agent bullet, the gap list) — no changes needed.
### Verification
- `uv run pytest --cov`: **1970 passed**, 18 skipped — coverage **98.74%** (floor 94%)
- `ruff` clean · `pyright` 0 errors · `bash .agents/validate.sh` **exit 0** (incl. `node --check` on every page script)
- Dev server running; all 10 sources `ok`; bundles exported
### Live infrastructure
**No live changes made.** The live drill remains unexecuted per `data/logs/NOTES-33-switching.md` (no operator approval; checker binaries unavailable in the podman proxy units). All routes stay enabled, config hashes unchanged, and the sandbox rehearsal + backup tree are in place for the operator's own `DANGER` call. All changes are in the working tree only.
67 lines
2.7 KiB
Markdown
67 lines
2.7 KiB
Markdown
# The route-switch helper (gateway hosts)
|
|
|
|
The dashboard's one narrow write is a route switch: one named connection on the
|
|
ingress goes `#off` (a marker the agent's own parser reads) or comes back. It is
|
|
not a sudoers line. The grant is a **file mode systemd enforces**: the socket the
|
|
agent talks to is `0600` and owned by the agent's own user, and the helper's
|
|
peer check (`--allow-uid`) is the second look. No account on the host — `ops`
|
|
included — can reach the write; only the agent's uid can connect, and only that
|
|
uid is accepted on the other end.
|
|
|
|
## The two units
|
|
|
|
| unit | what it is |
|
|
| ---- | ---------- |
|
|
| `dashboards-routectl.socket` | a systemd-activated stream socket at `/run/dashboards-routectl.sock`, `0600`, owned by `dashboards-agent` |
|
|
| `dashboards-routectl@.service` | the helper, **root**, one instance per connection (the connected socket on stdin), answers one request and exits |
|
|
|
|
The service unit's `ReadWritePaths` lists exactly the directories whose file the
|
|
helper replaces — `/etc/haproxy`, `/etc/nginx/conf.d`, `/etc/nginx/stream.d` —
|
|
and nothing else. There is never a long-lived privileged process: each request
|
|
spawns a fresh instance that exits after its one answer.
|
|
|
|
## See them
|
|
|
|
```
|
|
systemctl status dashboards-routectl.socket
|
|
systemctl status 'dashboards-routectl@*.service'
|
|
journalctl -u 'dashboards-routectl@*'
|
|
```
|
|
|
|
## Run the helper by hand on the box
|
|
|
|
The installed copy is `/usr/local/sbin/dashboards-routectl.py`. It takes its
|
|
agent parser by file path and refuses to run without one:
|
|
|
|
```
|
|
# what is off (the state sidecar)
|
|
sudo /usr/local/sbin/dashboards-routectl.py list
|
|
|
|
# preview one route without writing a byte (no checker, no reload, no state)
|
|
sudo /usr/local/sbin/dashboards-routectl.py diff --id nginx:443->127.0.0.1:44450 --action enable
|
|
|
|
# verify the sidecar against the files (drift is reported, never repaired)
|
|
sudo /usr/local/sbin/dashboards-routectl.py verify
|
|
```
|
|
|
|
A manual `disable --apply` runs the whole protocol: write, the proxy's own
|
|
checker (`nginx -t` / `haproxy -c -f`), restore the previous bytes on a checker
|
|
failure, `systemctl reload` (never `restart`) on success, then record the state.
|
|
|
|
## Undo it all
|
|
|
|
```
|
|
sudo ./deploy/install-agent.sh --without-routectl
|
|
```
|
|
|
|
That disables and removes the helper and its two units, **leaves the proxy
|
|
configs and the helper's state directory alone**, and prints the list of
|
|
still-off routes first — those are yours to switch back on.
|
|
|
|
## The one safety sentence
|
|
|
|
No sudoers line is involved. The agent's unit keeps every one of its security
|
|
directives (`NoNewPrivileges=true`, `ProtectSystem=strict`, …); the read-only
|
|
collector stayed read-only in its sandbox and talked to a peer outside it. The
|
|
grant is the socket's mode and ownership, enforced by systemd.
|