jschoubben
cf9357e8e9
What the mesh is, what it is becoming, and why. Implementation lives in the code repositories; the reasoning lives here. 00-GENESIS mission, engineering context, effect, and the rules that hold 01-RESEARCH investigations, before they harden into design 02-DESIGN the authoritative specification adr numbered decisions — what was chosen, and what was rejected DECISIONS.md the ledger: every decision, in the order it was taken Written for a reader who is not its author and has no access to the mesh it describes. Addresses use the documentation ranges of RFC 5737 and RFC 1918; nodes are named by role. Single initial commit by intent. The prior history came from a private repository and carried operational detail — a routable address identified as a VPN hub, real domain names, a hosting provider — which sanitising a tip commit would not have removed from the log.
45 lines
2.2 KiB
Markdown
45 lines
2.2 KiB
Markdown
# 004 — Reproducing the mesh network in a lab
|
|
|
|
- **Status:** ONGOING — topology established and mapped; not yet stood up
|
|
- **Initiated by:** jochen, 2026-08-22 — *"the most difficult part of our VM setup will be
|
|
the networking part"*
|
|
- **Areas touched:** `modules/wireguard`, `modules/dnsmasq-app`, `modules/traefik`,
|
|
`modules/mesh-ca`, `node_accessors`, `nodes.site` / `nodes.underlay_addr`.
|
|
|
|
## Summary
|
|
|
|
The network is **entirely generated from mesh-DB rows by module hooks**. `install.d` performs
|
|
no network configuration whatsoever — no WireGuard, no DNS, no firewall. That makes a faithful
|
|
lab primarily a *data* problem rather than a networking problem, and means the lab exercises
|
|
the real code path instead of a reimplementation of it.
|
|
|
|
One constraint decides whether the lab works at all: the WireGuard endpoint rule tests the
|
|
underlay address against an RFC1918 regex to decide reachability. **A simulated public segment
|
|
addressed from RFC1918 space silently prevents the mesh from forming** — no endpoint is written
|
|
for the hub, so nothing can ever initiate. The simulated public segment must therefore use
|
|
TEST-NET-3 (`203.0.113.0/24`).
|
|
|
|
With that one substitution the lab reproduces the production topology exactly, including the
|
|
case that is hardest to get right: a node that is publicly *named* but sits behind NAT, whose
|
|
endpoint the hub can only learn from a handshake.
|
|
|
|
Detail in [`analysis.md`](analysis.md).
|
|
|
|
## Settled
|
|
|
|
**The lab issues its own certificates.** Public names are certified by an ACME server on the
|
|
lab's wan segment; `.internal` names keep the mesh CA. The lab preserves production's two-CA
|
|
split rather than collapsing it, because a single-CA lab would hide any bug living in that
|
|
split. It also makes the router's port forward load-bearing — HTTP-01 must reach the
|
|
published-but-NATed node on port 80, so a broken forward becomes a reproducible certificate
|
|
failure instead of a mystery.
|
|
|
|
Requires one change: `caServer` is not set on the reverse proxy today, so it defaults to the
|
|
public authority's **production** endpoint. It must become configurable, defaulting to
|
|
production so real nodes are unaffected.
|
|
|
|
## Open
|
|
|
|
- Not yet stood up. `incus` is declared in `modules/hal/developer/module.yml` and merged
|
|
(PR #944); the lab itself is unbuilt.
|