NetBird hochverfügbar betreiben
Auf einen Blick
| Gilt für | NetBird 0.81 (Cloud oder selbst gehostet), Funktion „Networks“ mit Routing Peers; aktiv-aktiver Server-Betrieb nur mit NetBird-Enterprise-Lizenz |
|---|---|
| Bereich | IT-Security |
| Dauer | Routing-Peer-Redundanz ca. 30 Minuten; Server-Hochverfügbarkeit je nach Variante 1 Tag bis mehrere Tage Planung und Aufbau |
| Rechte | NetBird-Administrator, root/sudo auf Servern und Routing Peers |
| Stand | Oktober 2026 |
NetBird hochverfügbar betreiben heißt, jede Komponente zu betrachten, die ausfallen kann: die Routing Peers, über die Benutzer ins Firmennetz gelangen, die Relay-Server für Verbindungen hinter restriktiven Firewalls sowie Management- und Signal-Dienst als Steuerebene. Dieser Artikel stellt die HA-Strategien für NetBird vor – von mehreren Routing Peers mit automatischem Failover, die in jeder Edition funktionieren, über verteilte Relays und eine abgesicherte Steuerebene bis zum aktiv-aktiven Cluster mit der Enterprise-Lizenz – und hilft bei der Auswahl.
Was passiert, wenn eine NetBird-Komponente ausfällt?
NetBird trennt Steuerung und Datenverkehr: Der Datenverkehr fließt per WireGuard direkt zwischen den Peers oder über einen Relay. Deshalb wirkt sich nicht jeder Ausfall sofort auf die Benutzer aus.
| Komponente | Folge eines Ausfalls | HA-Strategie |
|---|---|---|
| Routing Peer | Ressourcen im dahinterliegenden Netz (z. B. Büro-LAN, Rechenzentrum) sind nicht mehr erreichbar. | Mehrere Routing Peers je Network (Strategie 1) |
| Relay | Verbindungen, die über diesen Relay laufen, brechen ab und bauen sich über einen anderen Relay neu auf; direkte Peer-to-Peer-Verbindungen sind nicht betroffen. | Mehrere Relays (Strategie 2) |
| Management | Keine neuen Peers, keine Anmeldungen, keine Änderungen an Richtlinien. Bestehende Verbindungen laufen eine Zeit lang weiter. | Aktiv-passiv (Strategie 3) oder aktiv-aktiv (Strategie 4) |
| Signal | Neue Verbindungen zwischen Peers können nicht mehr ausgehandelt werden. | wie Management |
| Identity Provider | Benutzer können sich nicht neu anmelden; laufende Sitzungen bleiben bestehen. | Hochverfügbarkeit des IdP (z. B. Entra ID, authentik) |
Faustregel: Die Routing Peers sind für den Alltag am wichtigsten – sie sollten in jeder Umgebung redundant sein. Die Steuerebene muss vor allem schnell wiederherstellbar sein; echter aktiv-aktiv-Betrieb lohnt sich bei großen Umgebungen mit vielen Anmeldungen und Änderungen.
Strategie 1: Mehrere Routing Peers mit automatischem Failover
Ein Routing Peer ist ein NetBird-Client im Zielnetz, der Verkehr an Geräte ohne eigenen Client weiterleitet. Unter Networks lassen sich einem Network mehrere Routing Peers zuweisen. Wie sie zusammenarbeiten, hängt davon ab, wie sie hinzugefügt werden:
| Hinzugefügt als | Verhalten | Einsatz |
|---|---|---|
| Einzelne Peers mit unterschiedlicher Metrik | Der Peer mit der niedrigsten Metrik ist primär, die anderen sind Ersatz. | Klare Primär-/Ersatz-Rollen, z. B. Rechenzentrum A vor B |
| Einzelne Peers mit gleicher Metrik | Jeder Client wählt beim Verbindungsaufbau einen Peer – bevorzugt eine direkte Verbindung, dann die geringste Latenz. Das ist keine Lastverteilung im engeren Sinn. | Mehrere gleichwertige Standorte |
| Peer-Gruppe | Alle Peers teilen sich eine Metrik; keine Primär-/Ersatz-Rolle. | Viele gleichartige Peers, z. B. in Kubernetes |
Wie ein Client den Routing Peer wählt
- Metrik: die niedrigste gewinnt – unabhängig von Verbindungsart und Latenz.
- Verbindungsart: bei gleicher Metrik schlägt eine direkte Verbindung (P2P) eine Verbindung über Relay.
- Latenz: bei sonst gleichen Werten die geringste; gewechselt wird erst ab 10 ms Vorteil, damit die Auswahl nicht hin- und herspringt.
Fällt der aktive Routing Peer aus, wechseln die Clients in der Regel innerhalb weniger Sekunden zum nächsten. Kommt ein Peer mit niedrigerer Metrik zurück, wechseln sie wieder zurück.
Einrichtung
- Zwei oder mehr Linux-Systeme (empfohlen: je 2 vCPU, 4 GB RAM) in unterschiedlichen Fehlerdomänen bereitstellen – also auf verschiedenen Hosts, Hypervisoren oder an verschiedenen Standorten. Zwei VMs auf demselben Host sind keine Hochverfügbarkeit.
- Auf jedem System den NetBird-Client installieren und mit einem Setup-Key anmelden (keine periodische Neuanmeldung nötig, Befehle siehe unten).
- Im Dashboard unter Networks das Network öffnen und mit Add Routing Peer den ersten Peer mit Metrik
100, den zweiten mit200hinzufügen. - Unter Notifications im Dashboard das Ereignis Routing Peer Disconnected aktivieren (E-Mail, Webhook oder Slack), damit ein Ausfall nicht unbemerkt bleibt.
- Failover testen: auf dem primären Peer
sudo netbird downausführen und auf einem Client mitnetbird status -dbeobachten, wie die Ressourcen über den Ersatz-Peer erreichbar bleiben. Danachsudo netbird up.
Client installieren und anmelden (Schritt 2):
curl -fsSL https://pkgs.netbird.io/install.sh | sh
netbird up --management-url https://netbird.example.com --setup-key <SETUP-KEY>
Linux bevorzugen: Linux-Routing-Peers nutzen den WireGuard-Kernelpfad und nftables/iptables und leiten am schnellsten weiter. Windows, macOS und FreeBSD (z. B. eine OPNsense mit NetBird-Plugin) leiten im Userspace weiter. Eine gute Kombination ist eine OPNsense als Routing Peer plus eine Linux-VM als zweiter Peer.
Exit Nodes werden weiterhin über die älteren Network Routes definiert; auch dort lassen sich mehrere Peers bzw. eine Peer-Gruppe mit Metrik hinterlegen.
Strategie 2: Relay-Server verteilen
Kommt keine direkte Verbindung zustande – etwa hinter doppeltem NAT oder restriktiven Firewalls –, läuft der Verkehr über einen Relay. Bei der Standardinstallation läuft der Relay mit auf dem NetBird-Server. Eigene Relay-Server entlasten diesen und machen Relay-Verbindungen ausfallsicher. Das Relay-Image prüft keine Lizenz, mehrere Relays sind also auch in der Community Edition möglich.
Jeder Relay erhält einen eigenen DNS-Namen und ein eigenes Zertifikat und ist direkt erreichbar – nicht hinter einem gemeinsamen Load Balancer. Benötigt werden TCP 443 (WebSocket), UDP 443 (QUIC) und UDP 3478 (STUN). Beispiel für einen Relay mit Docker Compose:
services:
relay:
image: netbirdio/relay:latest
restart: unless-stopped
ports:
- "443:443/tcp"
- "443:443/udp"
- "3478:3478/udp"
environment:
NB_LISTEN_ADDRESS: ":443"
NB_EXPOSED_ADDRESS: "rels://relay1.example.com:443"
NB_AUTH_SECRET: "<gemeinsames-secret>"
NB_ENABLE_STUN: "true"
NB_STUN_PORTS: "3478"
NB_LETSENCRYPT_DOMAINS: "relay1.example.com"
NB_LETSENCRYPT_EMAIL: "it@example.com"
In der config.yaml des NetBird-Servers werden alle Relays und STUN-Server eingetragen; das secret muss mit NB_AUTH_SECRET aller Relays übereinstimmen:
server:
stuns:
- uri: "stun:relay1.example.com:3478"
proto: "udp"
- uri: "stun:relay2.example.com:3478"
proto: "udp"
relays:
addresses:
- "rels://relay1.example.com:443"
- "rels://relay2.example.com:443"
secret: "<gemeinsames-secret>"
credentialsTTL: "24h"
Die Peers erhalten die Liste vom Management-Dienst und weichen beim Ausfall eines Relays auf einen anderen aus. Relays an verschiedenen Standorten oder bei verschiedenen Providern verkürzen zudem die Wege für Außendienst und Homeoffice.
Strategie 3: Steuerebene aktiv-passiv absichern (Community Edition)
In der kostenlosen Community Edition laufen Management und Signal als einzelne Instanz; der Signal-Dienst unterstützt dort nur den Einzelbetrieb. Hochverfügbarkeit bedeutet hier: Ausfälle kurz halten und schnell wiederherstellen.
- PostgreSQL statt SQLite: Die Standarddatenbank SQLite erlaubt keine gleichzeitigen Schreibzugriffe mehrerer Instanzen und liegt auf demselben Server. Mit PostgreSQL (
server.store.engineunddsnin derconfig.yaml; NetBird bietet eine Migrationsanleitung) lässt sich die Datenbank getrennt sichern, replizieren und auf einen Ersatzserver übernehmen. - VM-Hochverfügbarkeit: Den NetBird-Server als VM in einem Cluster mit HA-Funktion betreiben, z. B. Proxmox VE mit Hochverfügbarkeit und gemeinsamem oder repliziertem Speicher. Fällt ein Host aus, startet die VM automatisch auf einem anderen.
- Backups mit Schlüsseln: Regelmäßig die Datenbank, das Installationsverzeichnis und vor allem die
config.yamlsichern. Der darin enthalteneencryptionKeyder Datenbank darf nie verloren gehen oder geändert werden – ohne ihn sind die gespeicherten Daten nicht mehr lesbar. - Ersatzserver und DNS: Einen vorbereiteten Ersatzserver vorhalten, auf dem sich das Backup einspielen lässt. Eine kurze TTL für den DNS-Namen des NetBird-Servers beschleunigt das Umschalten.
- Wiederherstellung üben: Mindestens einmal jährlich die Rücksicherung auf dem Ersatzserver testen und die benötigte Zeit dokumentieren.
Da bestehende Verbindungen bei einem Ausfall der Steuerebene zunächst weiterlaufen, ist dieses Modell für die meisten mittelständischen Umgebungen ausreichend – vorausgesetzt, die Routing Peers (Strategie 1) und Relays (Strategie 2) sind redundant.
Strategie 4: Aktiv-aktiv mit NetBird Enterprise
Mit einer kommerziellen NetBird-Enterprise-Lizenz laufen Management und Signal als Pools mehrerer gleichwertiger Instanzen hinter einem Load Balancer. Fällt eine Instanz aus, übernehmen die anderen ohne Unterbrechung.
| Baustein | Mindestens | Hinweise |
|---|---|---|
| Management | 2 | zustandslos, Enterprise-Image, identische config.yaml auf allen Instanzen
|
| Signal | 2 | Enterprise-Image, Einzelbetrieb abgeschaltet; Nachrichten zwischen den Instanzen laufen über NATS |
| Relay | 2 | Standard-Image, je eigener Name, nicht hinter dem Load Balancer |
| NATS | 3 | mit JetStream, Quorum 2 von 3, je Knoten ein eigener Host |
| PostgreSQL | 1 HA-Endpunkt | z. B. verwalteter Datenbankdienst oder Patroni mit PgBouncer/HAProxy |
| Redis | 1 HA-Endpunkt | Standalone mit Replikation oder Sentinel; kein Redis-Cluster-Modus |
Anforderungen an den Load Balancer: Layer 7 mit HTTP/2 und gRPC durchgängig bis zu den Instanzen, je Pool ein fester DNS-Name, Leerlauf-Timeout von etwa 10 bis 30 Minuten und Verbindungs-Draining für Updates. Sticky Sessions auf Anwendungsebene sind nicht nötig. Als Health Check für Management dient GET /oauth2/.well-known/openid-configuration (HTTP 200).
Identisch auf allen Instanzen müssen unter anderem der Datenbankschlüssel (encryptionKey), der Schlüssel für Sitzungs-Cookies, das Relay-Secret und der Lizenzschlüssel sein – am besten zentral aus einem Secret-Manager verteilt. Updates spielen Sie Instanz für Instanz ein, nachdem die jeweilige Instanz aus dem Load Balancer genommen wurde.
Identity Provider und DNS nicht vergessen
- Identity Provider: Ohne IdP sind keine neuen Anmeldungen möglich. Cloud-IdPs wie Microsoft Entra ID sind bereits hochverfügbar; ein selbst betriebener IdP wie authentik braucht eine eigene HA-Strategie.
- DNS: Unter DNS → Nameservers für interne Domänen immer mindestens zwei Nameserver je Gruppe eintragen.
- Abhängigkeiten der Routing Peers: Ein Routing Peer nützt nichts, wenn er selbst von einem einzelnen Switch, einer Firewall oder einer Internetleitung abhängt – Fehlerdomänen vollständig durchdenken.
Welche HA-Strategie passt?
| Umgebung | Empfehlung |
|---|---|
| Kleines Unternehmen, ein Standort, NetBird Cloud | Zwei Routing Peers (z. B. OPNsense + Linux-VM); die Steuerebene betreibt NetBird |
| Mittelstand, selbst gehostet | Strategie 1 + 2 + 3: redundante Routing Peers, zwei Relays an unterschiedlichen Standorten, Server als HA-VM mit PostgreSQL und getesteter Wiederherstellung |
| Mehrere Standorte, viele Außendienst-Mitarbeiter | zusätzlich Relays nahe an den Benutzern (z. B. je Region), Routing Peers je Standort mit Metrik |
| Großunternehmen, viele Änderungen und Anmeldungen, hohe Verfügbarkeitszusagen | Strategie 4 mit Enterprise-Lizenz |
Hinweise
- Updates der Routing Peers nacheinander einspielen und vor jedem Update prüfen, dass der andere Peer aktiv ist.
- Versionen: NetBird wird sehr aktiv entwickelt; Relays, Server und Clients regelmäßig und aufeinander abgestimmt aktualisieren.
- Monitoring: Erreichbarkeit der Relays (TCP/UDP 443, UDP 3478), des Management-Dienstes und der Routing Peers zusätzlich in einem Monitoring-System wie Zabbix überwachen.
Unterstützung von m.a.x. it
Sie möchten NetBird ausfallsicher aufbauen oder eine bestehende Installation um redundante Routing Peers, eigene Relays und ein Wiederherstellungskonzept erweitern? m.a.x. it unterstützt Sie bei Konzeption, Aufbau und Betrieb – mit Cybersecurity-Leistungen von m.a.x. it rund um Zero Trust und sicheren Fernzugriff.
Siehe auch
- NetBird – Zero-Trust-Netzwerk mit WireGuard – Überblick und Installation
- OPNsense - NetBird-Plugin
- NetBird mit Microsoft Entra ID anbinden
- Tailscale – Mesh-VPN auf WireGuard-Basis
- Proxmox
- Failover
Links und Quellen
- NetBird-Dokumentation: Running a Highly Available Self-Hosted Deployment
- Cybersecurity-Leistungen von m.a.x. it
Über m.a.x. it Die m.a.x. Informationstechnologie AG ist seit über 30 Jahren IT-Partner mittelständischer und großer Unternehmen in München und bietet maßgeschneiderte Lösungen und Services in den Bereichen Cloud, Cybersecurity, Netzwerk, Windows, Linux und Softwareentwicklung. Sie haben eine Frage zu diesem Artikel oder brauchen Unterstützung?
