WireGuard Mesh Overview

Cross-project overview of how WireGuard connects the Hydra streaming infrastructure. This is the central entry point — individual project docs cover their specific areas.

Topology

Hub-and-spoke WireGuard mesh with a single hub in Brussels (OVHcloud). All inter-site traffic routes through the hub.

                        ┌─────────────────────────────┐
                        │   Hub (141.227.136.12)       │
                        │   10.10.0.1/24               │
                        │   OVHcloud Brussels           │
                        │                              │
                        │   Also runs:                 │
                        │   - hydraneckwebrtc controller│
                        │   - hydraneckwebrtc worker   │
                        │   - coturn TURN server       │
                        └──────────┬───────────────────┘
                                   │
              ┌────────────────────┼────────────────────┐
              │                    │                     │
     ┌────────┴────────┐  ┌───────┴────────┐  ┌────────┴────────┐
     │  Venues          │  │  Air Units      │  │  Neck Air       │
     │  10.10.1-49.x    │  │  10.10.100.x    │  │  10.10.50-99.x  │
     │  + LAN subnet    │  │  Windows bodies  │  │  + LAN subnet   │
     │  (Omada/Gateway) │  │  (render nodes)  │  │  (Mikrotik)     │
     └──────────────────┘  └─────────────────┘  └─────────────────┘

Address Scheme

| Type | WG tunnel range | LAN range | Capacity | |------|----------------|-----------|----------| | Hub | 10.10.0.1/24 | -- | 1 | | Venues | 10.10.1-49.1/32 | 10.0.X.0/24 | 49 | | Neck Air | 10.10.50-99.1/32 | 10.0.X.0/24 | 50 | | Hydra Air | 10.10.100.1-254/32 | -- (no LAN) | 254 |

How Each Project Touches WireGuard

hydraguard (mesh manager)

Manages the hub-and-spoke mesh from a single mesh.yaml inventory.

| What | Where | |------|-------| | Repo | github.com/cederikdotcom/hydraguard | | Runs on | Hub server (141.227.136.12) | | Source of truth | /root/.hydraguard/mesh.yaml | | Generated config | /etc/wireguard/wg0.conf | | API | http://hydraguard.experiencenet.com:8081 (keep stopped when not enrolling) | | Binary | /usr/local/bin/hydraguard | | Docs | runbook.md, DEPLOYMENT.md, OPERATIONS.md |

Key commands: hydraguard status, hydraguard air add <id>, hydraguard apply, hydraguard export

hydracluster (node provisioning)

Provisions WireGuard on body machines via recipes. Calls hydraguard API to enroll peers.

| What | Where | |------|-------| | Repo | github.com/cederikdotcom/hydracluster | | Runs on | hydracluster.experiencenet.com | | Recipes | recipes/hydraguard-air-windows.yaml, recipes/hydraguard-air-linux.yaml | | Config key | hydraguard.url + hydraguard.token in hydracluster config | | Integration | pkg/api/handlers_body.go → provisionHydraGuardAir() calls /api/v1/air/provision |

When a node is assigned the hydraguard-air role:

Hydracluster calls hydraguard API to create the peer (gets WireGuard config back)
The recipe is sent to the hydranode agent on the body
Recipe installs WireGuard, writes config, starts the tunnel service

hydraneckwebrtc (WebRTC relay)

Runs on the same box as the hub. Reaches body machines via WireGuard tunnel addresses (10.10.100.x) to pair with Sunshine on port 47990 and proxy WebRTC streams.

| What | Where | |------|-------| | Repo | github.com/cederikdotcom/hydraneckwebrtc | | Runs on | Hub server (141.227.136.12) — same box as hydraguard | | Connects to bodies via | WireGuard tunnel (10.10.100.x:47990 for Sunshine API) | | TURN relay | coturn on same box, port 3478, forces iceTransportPolicy: relay |

The worker is on the hub's WireGuard interface (10.10.0.1), so it has direct mesh access to all peers without needing a separate WireGuard peer entry.

hydranode (node agent)

Runs on every body machine. Executes the hydraguard-air recipe steps that install and configure WireGuard.

| What | Where | |------|-------| | Repo | github.com/cederikdotcom/hydranode | | Runs on | Every body machine (Windows/Linux) | | WireGuard config (Windows) | C:\ProgramData\hydraguard-air\hydraguard-air.conf | | Tunnel service (Windows) | WireGuardTunnel$hydraguard-air | | Recipe execution | pkg/body/recipe.go → runPendingProvisions() |

Peer Lifecycle

1. Enroll body in hydracluster (web UI or API)
2. Assign hydraguard-air role
3. Hydracluster calls hydraguard API → peer added to mesh.yaml
4. Hydracluster sends recipe to hydranode agent
5. Hydranode installs WireGuard + writes config + starts tunnel
6. Peer handshakes with hub → body reachable at 10.10.100.x
7. hydraneckwebrtc can now create streaming sessions to the body

Key Files

On the hub (`ubuntu@141.227.136.12`)

| File | Purpose | |------|---------| | /root/.hydraguard/mesh.yaml | Peer inventory (source of truth) | | /root/.hydraguard/api.yaml | API server config (token, listen, auto_apply) | | /etc/wireguard/hub.key | Hub WireGuard private key | | /etc/wireguard/wg0.conf | Generated WireGuard config (from mesh.yaml) | | /root/.hydraneckwebrtc/config.yaml | Worker config (sessions, TURN, controller URL) | | /root/.hydraneckwebrtc-controller/config.yaml | Controller config (domain, admin token) | | /root/.hydraneckwebrtc-turn-credential | coturn TURN credential |

On body machines (Windows)

| File | Purpose | |------|---------| | C:\ProgramData\hydraguard-air\hydraguard-air.conf | WireGuard tunnel config | | C:\hydranode\hydranode.exe | Node agent binary |

In hydracluster

| File | Purpose | |------|---------| | recipes/hydraguard-air-windows.yaml | Recipe: install WG, write config, start tunnel, configure Sunshine | | recipes/hydraguard-air-linux.yaml | Same for Linux bodies | | recipes/hydraguard-gateway-linux.yaml | Recipe for on-prem LAN gateways |

Cross-Project Troubleshooting

Body can't reach the hub

Check peer in mesh: hydraguard status on the hub
Verify keys match: body's public key must match what's in mesh.yaml
Check the body's tunnel: hydracluster exec <nodeId> '& "C:\Program Files\WireGuard\wg.exe" show hydraguard-air'

If endpoint shows old IP, restart the tunnel on the body:

& 'C:\Program Files\WireGuard\wireguard.exe' /uninstalltunnelservice hydraguard-air
Start-Sleep 3
& 'C:\Program Files\WireGuard\wireguard.exe' /installtunnelservice 'C:\ProgramData\hydraguard-air\hydraguard-air.conf'

hydraneckwebrtc can't reach a body ("Sunshine unreachable")

Ping the body from the hub: ping 10.10.100.x
If ping works but port 47990 fails: Windows Firewall on the body is blocking. Check the HydraGuard WG firewall rule allows remoteip=10.10.0.0/16
If ping fails: body's WireGuard tunnel is down or key mismatch (see above)
Check body's Sunshine is running: hydracluster exec <nodeId> 'Get-Service SunshineService | Format-Table Name,Status'

Peer keys got out of sync

This can happen when the hydraguard API regenerates keypairs (issue #64). Symptoms: handshake never completes, transfer: 0 B received.

Fix:

Get the body's actual public key: hydracluster exec <nodeId> '& "C:\Program Files\WireGuard\wg.exe" show hydraguard-air'
Update mesh.yaml on the hub to match
Regenerate wg0.conf: hydraguard export > /etc/wireguard/wg0.conf
Hot-reload: wg set wg0 peer <correct-key> allowed-ips 10.10.100.x/32 (remove old key too)

Recipe provisioning doesn't run on Linux nodes

The hydranode agent reports the full distro name (e.g. Ubuntu 24.04) but recipes use os: linux. Fixed in hydracluster v1.9.32 — ensure the hydracluster server is on v1.9.32+.

HydraBooks