boma/roles/base/README.md

base

Hardened baseline applied to every boma host. Built incrementally; the first concern implemented is the host firewall (firewall tag).

Firewall (nftables)

Default-deny inbound + east-west allowlisting + permissive egress, per ADR-020. Rules are rendered from the shared firewall_catalog / firewall_zones (in group_vars/all) by the resolve_firewall_rules filter, written to /etc/nftables.conf, syntax-checked with nft -c at render time, and applied with an auto-rollback safety net (systemd-run arms a revert that a follow-up task cancels once connectivity is confirmed). The apply sequence lives in tasks rather than a handler so the confirm/cancel step is controllable.

/etc/nftables.d/*.nft is included by the ruleset — the extension hook the docker_host role uses for container forward/NAT rules.

Variables

See defaults/main.yml (base__firewall_*). SSH is accepted only on base__firewall_mgmt_interface (default wt0, the NetBird overlay — ADR-016); set it to a reachable interface/source until NetBird is built. Set base__firewall_apply: false to render + validate without applying (used by Molecule).

Testing

• tests/test_firewall_rules.py — pytest units for the resolver.
• make test ROLE=base — Molecule renders + nft -c syntax-checks (never applies; it shares the host kernel). Enforcement + the apply/rollback path are verified at ADR-008 Level 2 on staging VMs.

Mesh enrollment (NetBird agent)

Enrols the host as a NetBird agent on the self-hosted mesh (ADR-016): installs the pinned netbird daemon from the upstream APT repo (keyring in /etc/apt/keyrings, mirroring the docker_host repo idiom) and runs netbird up against the coordinator with a setup key. Tagged mesh.

Additive only — this concern makes no firewall change. SSH is already gated to the NetBird overlay interface by the firewall concern (base__firewall_mgmt_interface, default wt0); enrolling a host simply brings that interface up. No port is opened here.

Enrolment is opt-in: base__mesh_enabled defaults to false, so applying base to a host not on the mesh is a no-op for this concern. Re-enrolment is guarded on netbird status reporting Management: Connected, so re-runs are idempotent. The setup key is sourced from vault.netbird.setup_key and passed with no_log (it lands on the process argv).

Variables

Variable	Default	Purpose
base__mesh_enabled	false	Opt-in switch — include the concern at all. Set per-host/group to enrol.
base__mesh_manage	true	Test gate — when false, skips the live network/daemon tasks (apt install, status check, netbird up) so Molecule can exercise the wiring without a coordinator.
base__mesh_management_url	https://netbird.askari.wingu.me	Coordinator (management) URL.
base__mesh_setup_key	{{ vault.netbird.setup_key }}	Enrolment setup key, from vault.
base__mesh_version	"0.72.4"	Pinned agent version (matches the coordinator). The exact apt version string is confirmed on-host at deploy.