Networking

Three isolated network overlays. Addresses are environment values (the operator's SSH config and mesh dashboard hold them); these pages describe topology with placeholders.

network	scope	carries	peers
Netbird mesh (WireGuard)	CGNAT-class 100.64.0.0/16	SSH, service access, agent traffic	all user peers + the three nodes
wg-direct	private point-to-point	NFS only (vps-apps ↔ pi-home)	two tunnel endpoints
wgr-vpsnet	private point-to-point	the only path to vps-net	pi-home ↔ vps-net

Design rules:

1. NFS rides its own static tunnel so backups survive a mesh outage.
2. The mesh control plane node (vps-net) is not a mesh peer and is reachable only over wgr-vpsnet through pi-home.
3. No service publishes on 0.0.0.0 except LAN/DNS/SSH platform services noted on nodes.md.

Netbird mesh

element	placement
Control plane (mgmt + signal + relay + dashboard)	vps-net, TLS on 443
Reverse proxy peers (proxy-*)	relay infrastructure, mesh side
DNS-aware name resolution	each peer resolves <peer>.mesh names locally via NetBird's resolver — survives resolver/host outages

DNS

consumer	resolver	path
LAN clients	pi-hole (pi-home)	DHCP assignment
vps-apps host and containers	pi-home mesh IP + 9.9.9.9	systemd-resolved + docker daemon.json
user peers (laptop, phones, handhelds)	pi-home mesh IP + 9.9.9.9	pushed via Netbird nameserver group
pi-home, vps-apps, proxy-* as nodes	no resolver push	pi-home is the resolver itself

Upstreams: 1.1.1.1 primary, 9.9.9.9 fallback. Ad/tracker filtering applies to every consumer pointing at pi-hole.

Public ingress

• Exactly one public path: the cloudflared tunnel on pi-home — token-managed, routes defined in the Cloudflare dashboard. A wildcard CNAME on the public domain routes into the tunnel.
• The Netbird reverse proxy (proxy-*) fronts selected services for mesh peers.
• Public-facing names ride Cloudflare edge certificates; the tunnel carries the origin leg. Renewal is automatic; manual work is limited to new routes (runbooks/certificate-renewal.md).

Tunnels

wg-direct — NFS (vps-apps ↔ pi-home)

• Exports (verified): /mnt/pi-hdd/backups (nested <host>/<branch> restic repos) and /mnt/pi-hdd/share (open/temp WebDAV drop) — both restricted to the vps-apps tunnel IP.
• Security: all_squash + fixed anon uid/gid — remote access (including root) maps to the unprivileged local user.
• vps-apps mounts appear as Docker volumes under nfs_*.

wgr-vpsnet — admin (pi-home ↔ vps-net)

Static WireGuard terminating on pi-home. Carries vps-net's sshd and its beszel agent reporting. vps-net exposes no other network service.

SSH topology

• Direct mesh targets: vps-apps and pi-home (non-default port).
• vps-net: reachable only by jumping through pi-home over wgr-vpsnet, and only with the dedicated restricted key that lives inside the hermes container. No node or laptop holds that credential; the account has no sudo.
• Concrete aliases, users, ports and keys are environment values tracked outside these pages.

Failure blast radius

outage	impact
vps-net down	mesh control plane unreachable: no new peer sessions/negotiation; established tunnels keep passing traffic
pi-home down	public ingress, LAN DNS/DHCP, NFS backups, mesh ad-blocking, and the vps-net admin path all stop; user peers still resolve via 9.9.9.9
vps-apps down	application fleet unavailable; DNS, mesh, ingress and backups keep working from pi-home