The webui/API runs unprivileged (secubox); operations touching root-owned config
or driving systemd/LXC/apps MUST delegate to the root helper secubox-<module>ctl
via scoped exact-command sudoers (shipped by the package), which acts as root and
audits each change. Documented in MODULE-COMPLIANCE (authoritative), MODULE-GUIDELINES
§7 (CTL), WEBUI-PANEL-GUIDELINES, and wiki/Architecture. Ref: secubox-cvectl fix.
Co-Authored-By: Gerald KERMA <devel@cybermind.fr>
Anchor the pattern that secubox-lyrion v1.1.0 demonstrated (admin
static page on the canonical hub vhost + real app served at the root
of its own dedicated vhost) as a REQUIRED rule across the docs:
- docs/MODULE-GUIDELINES.md §4 — new "REQUIRED: dual-vhost pattern"
subsection with the URL table, the JS pattern for reading the
public URL from /access, and the explicit forbidden anti-pattern
(`proxy_pass /<module>/ → app LXC`).
- docs/MODULE-GUIDELINES.md §5 — nginx template updated: `/<module>/`
is `alias` (static), the dedicated vhost is a separate file. The
previous "Iframe pattern for LXC web UIs" + "LXC daemon iframe
target" sections are flagged deprecated.
- .claude/PATTERNS.md Pattern 12 — same rule reproduced for the
Claude-facing pattern catalog with the source-of-truth JS snippet.
- .claude/HISTORY.md + .claude/WIP.md — entry for today's three-
module alignment (lyrion 1.1.0 + zigbee + authelia).
- wiki/Architecture.md — short reference + pointer back to
MODULE-GUIDELINES.
- packages/secubox-lyrion/README.md — adds the URLs table at the top.
- packages/secubox-zigbee/README.md — was a verbatim copy of the
lyrion README, rewritten as a proper zigbee README with the new
URLs table + API surface + ports + files.
- packages/secubox-authelia/README.md — Quickstart points at
sso.gk2.secubox.in (was auth.maegia.tv); URLs table added.
The forbidden anti-pattern catches LMS Material, Nextcloud,
Grafana, z2m and any future module whose UI uses absolute asset
URLs — incident on gk2 2026-05-24, see secubox-lyrion 1.1.0
changelog.
Field-deploying v2.11.0's three new LXC modules on arm64 MOCHAbin
(gk2 192.168.1.200) surfaced nine bugs that the local smoke build
doesn't exercise (no lxc-create in dpkg-buildpackage). All three
modules now reach overall=green on the board with the canonical hub
vhost (admin.gk2.secubox.in) routing /api/v1/<m>/* and /<m>/ correctly.
install-lxc.sh (all 3 modules)
1. lxc-create -t download (the legacy `debian` template fails on
bookworm unprivileged containers).
2. ensure_masquerade() — nftables MASQUERADE rule for 10.100.0.0/24,
idempotent. systemd-networkd's IPMasquerade=ipv4 doesn't land on
appliances using ifupdown/NetworkManager.
3. ensure_resolv() — seed /etc/resolv.conf via lxc-attach AFTER
start_lxc + wait_for_network (rootfs is owned by mapped uid 100000,
host root can't write directly). Unlink the symlink the download
template ships (→ /run/systemd/resolve/stub-resolv.conf which
doesn't exist before systemd-resolved is up).
install-lxc.sh (grafana)
4. gpg --dearmor on apt.grafana.com key (signed-by= needs binary,
wget delivers ASCII-armored).
install-lxc.sh (yacy)
5. YACY_RELEASE_URL: v1.940 → v1.941 (old URL now returns 404).
install-lxc.sh (rustdesk)
6. Detect host arch (arm64/amd64/armhf) and pull the matching
RustDesk server build. Hardcoded amd64 binary failed with
"Exec format error" on the arm64 MOCHAbin.
7. Flatten any of amd64/, arm64v8/, armv7/ subdirs the zip ships.
debian/secubox-<m>.service (all 3 modules)
8. ExecStartPre prefix with `+` (run as root). The mkdir + chown
pre-steps run as User=secubox by default, chown fails ("Operation
not permitted") and the service can't start.
debian/rules + nginx/<m>.conf (all 3 modules)
9. Install nginx snippet to BOTH /etc/nginx/secubox.d/ AND
/etc/nginx/secubox-routes.d/. The canonical hub vhost
(sites-enabled/webui.conf serving admin.gk2.secubox.in) only
includes routes.d/, NOT secubox.d/ which is only included by the
legacy sites-available/secubox vhost. Also switch the
/api/v1/<m>/ location from `proxy_pass http://unix:.../sock:/` to
explicit `rewrite ^/api/v1/<m>/(.*)$ /$1 break; proxy_pass
http://unix:.../sock;` — matches the canonical pattern used by
secubox-users; the previous syntax did not strip the prefix so
FastAPI saw the full path and returned 404 on every route.
Docs
* docs/MODULE-GUIDELINES.md §7 extended with mandatory lifecycle
verbs install / repair / wizard / reload / uninstall. Repair detects
+ fixes drift idempotently; wizard chains interactive seed + install;
uninstall asks for confirmation, removes LXC + state + secrets.
Implementation in grafanactl/yacyctl/rustdeskctl deferred to v2.12.0
(currently install + reload are wired, the rest is on the v2.12.0
backlog).
* docs/superpowers/specs/2026-05-20-secubox-wall-ep06.md (#236) —
Quectel EP06-E modem-based rogue-base-station sensor (WALL layer).
* docs/superpowers/specs/2026-05-20-secubox-sentinelle-gsm.md (#237) —
RTL-SDR + gr-gsm passive RX-only false-BTS detection (MIND layer,
feeds WALL/OPAD). Privacy-by-design HMAC-truncated identifiers.
* .claude/{WIP,TODO}.md refreshed with v2.11.1 fix trail + v2.12.0
target + P2 sensor backlog.
Package version bump: 1.0.0 → 1.0.7 (grafana/rustdesk) / 1.0.7 (yacy),
all three end at the same .deb revision suitable for v2.11.1 tag.
Validated end-to-end on board gk2:
grafanactl status → overall=green (lxc + grafana-server + host-api all up,
admin/<password> at /etc/secubox/secrets/grafana-admin,
6 dashboards + secubox-metrics datasource provisioned)
yacyctl status → overall=green (lxc + JVM + YaCy v1.941 standalone,
admin password at /etc/secubox/secrets/yacy-admin)
rustdeskctl status → overall=green (lxc + hbbs + hbbr + host-api,
PSK at /etc/secubox/secrets/rustdesk-key,
nftables DNAT 21116/udp installed)
https://admin.gk2.secubox.in/api/v1/grafana/healthz → HTTP 200
https://admin.gk2.secubox.in/api/v1/yacy/healthz → HTTP 200
https://admin.gk2.secubox.in/api/v1/rustdesk/healthz → HTTP 200
Co-authored-by: CyberMind-FR <gandalf@Gk2.net>
- docs/MODULE-GUIDELINES.md (new) — canonical reference for authoring a
secubox-<module> package: file structure, LXC layout, WebUI conventions,
nginx wiring, Debian packaging, CTL three-fold, FastAPI shape, tests,
validation checklist. Sister doc to docs/grammar.md and docs/UI-GUIDE.md.
- docs/grammar.md — cross-reference MODULE-GUIDELINES.md in the header
sister-docs block.
- docs/MODULES.md — point new-module authors at MODULE-GUIDELINES.md.
- docs/superpowers/plans/2026-05-20-grafana-yacy-rustdesk-lxc-modules.md
(new) — concrete implementation plan for three new LXC-hosted modules:
secubox-grafana (#229), secubox-yacy (#230), secubox-rustdesk (#231).
All three follow the new MODULE-GUIDELINES.md. IP allocations 10.100.0.{70,80,90}.
