Netbird control plane down

The control plane runs on vps-net: management + signal + relay behind TLS, reachable only over the wgr-vpsnet tunnel from pi-home. A dead control plane means no new mesh negotiation; established WireGuard tunnels keep passing traffic.

Triage order

1. Classify the outage.

symptom	meaning
single peer unreachable	that peer's own agent/tunnel
every peer can't re-register	control plane down
intermittent	relay path vs signalling issues

1. Reach vps-net — only through pi-home (ssh -J pi-home <user>@<vps-net-ip>, credentials live in the hermes container; jump host must be up).

2. Inspect the stack as the restricted account, via the docker:cli driver:

docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
  docker:cli docker ps
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
  docker:cli docker logs --tail 100 netbird-server

1. Recover: first restart the failing container alone, then up -d the whole project. If the store volume is dead, restore from the pre-change archive taken in the last upgrade (runbooks/restore.md).

2. If the mesh is losing traffic but control plane is alive: check peers re-connect (netbird status on each node) and that the relay containers run.

While the mesh is down

• LAN services on pi-home stay available locally.
• User peers can't resolve *.mesh names until the mesh is back; use ordinary public DNS for public-domain services (tunnel still routes them if cloudflared is alive — cloudflared doesn't need the mesh).
• vps-appsreachable only from LAN.

Practice

Walk this runbook end to end on a scheduled cadence so the access path is never discovered in an emergency.