From e92e12aac5dafca3e5df5f24fdfe31bc4be96cac Mon Sep 17 00:00:00 2001 From: Eratostenes de Gitjabia Date: Sat, 9 May 2026 12:32:40 +0000 Subject: [PATCH] docs(architecture): network topology and VLANs --- docs/01-architecture/network-topology.md | 98 ++++++++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 docs/01-architecture/network-topology.md diff --git a/docs/01-architecture/network-topology.md b/docs/01-architecture/network-topology.md new file mode 100644 index 0000000..3e5cd8e --- /dev/null +++ b/docs/01-architecture/network-topology.md @@ -0,0 +1,98 @@ +# Network topology + +Per-site network design. Defaults shown — most are configurable in the wizard. + +## VLAN layout + +| VLAN | Name | Purpose | Subnet (default) | +|---|---|---|---| +| 1 | DEFAULT | Untagged native (avoid using) | — | +| 10 | CAM | Cameras (quarantined) | 192.168.10.0/24 | +| 20 | CELL | Compute (Cell, Core if present) | 192.168.20.0/24 | +| 30 | MGMT | Management (operator workstation, ops CLI) | 192.168.30.0/24 | +| 40 | GUEST | Optional guest WiFi (no Blocao access) | 192.168.40.0/24 | +| 100 | WAN | WAN side, transit | (DHCP / static / PPPoE) | + +The router is the only device with interfaces on all VLANs. Switching is done by the router or by a managed switch trunked to the router. + +## Firewall zones and forwardings + +Zones map 1:1 to VLANs (`cam`, `hai`/`cell`, `mgmt`, `guest`, `wan`). Forwarding policies: + +| From → To | cam | cell | mgmt | guest | wan | +|---|---|---|---|---|---| +| **cam** | reject | rtsp/onvif only | reject | reject | DROP | +| **cell** | rtsp/onvif only | self | reject | reject | bridge endpoint + balena only | +| **mgmt** | reject | https/api only | self | reject | full | +| **guest** | reject | reject | reject | self | full (NAT) | +| **wan** | reject | reject | reject | reject | self | + +Notes: + +- "rtsp/onvif only" = TCP 554 + UDP 8554 + ONVIF discovery. +- "https/api only" from mgmt to cell = TCP 443 (proxied by router). +- "bridge endpoint + balena only" from cell = TCP 8883 to hub, balenaCloud endpoints (whitelisted). +- Inter-cam traffic within VLAN-10 is allowed only for cameras that legitimately discover each other (rare); usually rejected. + +## DNS + +Cameras VLAN: dnsmasq on the router answers all queries with NXDOMAIN except for an explicit allowlist (typically: pool.ntp.org if a camera needs it, vendor portal hostnames blocked). + +Cell VLAN: full DNS resolution, with adblock filter list for known phone-home domains. + +Mgmt VLAN: full DNS resolution, no adblock. + +The DNS sinkhole on cam VLAN is **the** sovereignty mechanism preventing cameras from contacting their cloud. Phone-home attempts visible in Frigate logs and security checklist. + +## DHCP + +Per-VLAN DHCP server on the router. + +- **cam**: static reservations by MAC for known cameras. Unknown MACs get an address but in a "quarantine" lease range (192.168.10.200-220) flagged in the UI. +- **cell**: short range, 192.168.20.10-20. +- **mgmt**: short range, 192.168.30.10-50. +- **guest**: short range with idle timeout. + +Static reservations are part of the GitOps repo (`/etc/config/dhcp` or per-host files). + +## WAN options + +Configured at first boot: + +- **DHCP** (most common): get IP from upstream. +- **Static**: manual IP, gateway, DNS. +- **PPPoE**: legacy ADSL / fiber. +- **4G/LTE**: cellular modem (USB or M.2). Useful as primary in remote sites. + +**Failover**: optional dual-WAN with mwan3. + +- **Standby**: use ETH primary, switch to LTE on failure. +- **Active-active**: load-balance both. Used rarely; complicates traffic shaping. + +## VPN + +Tailscale is the default. Each site's router has its own Tailscale identity. ACLs configured at hub level so operator workstations can reach `-router.ts.net` over the VPN. + +Why Tailscale over WireGuard direct: handles NAT traversal, rotates keys, has a strong ACL model, plays nicely with Hetzner-hosted hub. + +## HaLow extension (future variant) + +When the Cell or external bridge has 802.11ah radio, an additional VLAN (or an extension of VLAN-10) covers HaLow-connected devices. Sub-GHz band gives ~1km range at low data rates — useful for cameras in extensive sites (agro, marina) where running PoE is impractical. + +See [`../04-deployments/halow-extended-range.md`](../04-deployments/halow-extended-range.md) for the deployment pattern. + +## Switch recommendations + +For sites needing more than the router's ports (~4-8 LAN ports typical): + +- **Mikrotik CRS305-1G-4S+IN** (small, 4×SFP+ for fiber backbone). +- **Mikrotik CRS326-24G-2S+** (24×1GbE, larger sites). +- **TP-Link TL-SG2210MP** (PoE+ for cameras, budget). + +The switch must support 802.1Q VLAN tagging on a trunk port to the router. PoE+ is convenient for cameras but optional (separate PoE injectors work). + +## Why this design + +The VLAN+firewall layout makes **the sovereignty story visible**. An auditor can verify VLAN-10 has no internet egress in 30 seconds with a packet capture or by reading the firewall rules. The same is impossible to verify on a flat-network deployment. + +The design also makes the BLAST RADIUS of any compromise small: a hijacked camera can't see the Cell except through the RTSP path the Cell already initiated.