Netbird ist eine Open-Source-Lösung für den Aufbau sicherer, privater Netzwerke auf Basis von WireGuard.
Das Projekt verfolgt das Konzept eines Mesh-VPNs, bei dem alle teilnehmenden Geräte – sogenannte Peers –
direkt miteinander verbunden werden, anstatt den gesamten Datenverkehr über einen zentralen Server zu leiten.
Als Transportprotokoll setzt Netbird auf WireGuard, das sich durch seine schlanke Codebasis, hohe Geschwindigkeit
und moderne Kryptografie (ChaCha20, Poly1305, Curve25519) auszeichnet. WireGuard ist seit Linux-Kernel 5.6
fester Bestandteil des Linux-Kernels und gilt heute als der de-facto-Standard für leistungsfähige VPN-Tunnel.
Im Unterschied zu klassischen Hub-and-Spoke-VPNs wie OpenVPN oder IPsec, bei denen sämtlicher Datenverkehr
über einen zentralen Gateway-Server läuft, baut Netbird direkte Peer-to-Peer-Verbindungen zwischen den Geräten auf.
Jeder Peer spricht idealerweise direkt mit jedem anderen Peer – ohne Umweg. Das reduziert Latenz erheblich und
eliminiert den zentralen Flaschenhals, der bei traditionellen VPN-Setups entsteht. Der Management Server, der
für die Koordination zuständig ist, übermittelt lediglich Verbindungsmetadaten und Konfiguration – er sieht
keinen Datenstrom zwischen den Peers.
Netbird eignet sich für Einzelpersonen, Heimlabore, kleine Teams und Unternehmen gleichermaßen. Besonders
attraktiv ist die Möglichkeit, den gesamten Stack selbst zu betreiben – einschließlich des Management Servers.
Damit behält man die vollständige Kontrolle über das eigene Netzwerk und ist unabhängig von externen Diensten.
2. Architektur – Wie Netbird funktioniert
Die Architektur von Netbird besteht aus mehreren Komponenten, die zusammenspielen, um ein sicheres Mesh-Netzwerk
aufzubauen. Im Zentrum steht der Management Server, der zwei wesentliche Aufgaben übernimmt: Zum einen
verwaltet er die Konfiguration des Netzwerks – also welche Peers existieren, welche Zugriffsrichtlinien gelten
und welche Routen propagiert werden. Zum anderen fungiert er als Signaling-Server, über den sich Peers initial
finden und ihre WireGuard-Endpunktinformationen austauschen können.
Für die NAT-Traversal-Funktionalität nutzt Netbird das STUN/TURN-Protokoll. STUN (Session Traversal Utilities
for NAT) wird verwendet, um die öffentliche IP-Adresse und den Port eines Peers hinter einem NAT-Router zu
ermitteln. In vielen Fällen reicht das aus, um eine direkte Peer-to-Peer-Verbindung herzustellen. Befinden
sich beide Peers hinter restriktiven NATs, die keine direkte Verbindung erlauben, kommt TURN (Traversal Using
Relays around NAT) zum Einsatz. Hier wird der Datenverkehr über einen Relay-Server weitergeleitet.
Als STUN/TURN-Server nutzt Netbird standardmäßig COTURN – eine weit verbreitete Open-Source-Implementierung.
Im Self-hosted-Setup wird COTURN typischerweise als eigener Container neben dem Management Server betrieben.
Netbird bevorzugt immer die direkte P2P-Verbindung und fällt nur dann auf den Relay-Server zurück, wenn keine
direkte Verbindung möglich ist.
Zusätzlich gibt es den Signal-Server (auch Signaling Service), der als Vermittlungsstelle beim initialen
Verbindungsaufbau zwischen Peers dient. Er übermittelt verschlüsselte Signale, damit sich Peers gegenseitig
ihre Verbindungsparameter mitteilen können – ähnlich wie bei WebRTC-Architekturen. Der gesamte
Signalisierungsverkehr ist dabei verschlüsselt, sodass der Signal-Server selbst keine Kenntnis über den
Inhalt der ausgetauschten Nachrichten hat.
Alle Verbindungen zwischen Peers sind Ende-zu-Ende mit WireGuard verschlüsselt. Der Management Server und
der Signal-Server sehen nie den eigentlichen Datenverkehr zwischen den Peers – sie kennen lediglich die
öffentlichen WireGuard-Keys und Konfigurationsmetadaten.
3. Netbird vs. Tailscale
Tailscale ist das wohl bekannteste Produkt im Bereich WireGuard-basierter Mesh-VPNs und war für viele der
Startschuss, der das Konzept einem breiten Publikum zugänglich machte. Netbird und Tailscale verfolgen sehr
ähnliche Ansätze – es gibt jedoch einen entscheidenden Unterschied: Self-Hosting.
Tailscale setzt für seinen Koordinationsserver (Control Plane) auf die eigene Cloud-Infrastruktur. Headscale,
eine inoffizielle Open-Source-Reimplementierung des Tailscale-Koordinationsservers, ermöglicht zwar eine
eingeschränkte Self-hosted-Lösung, ist aber kein offiziell von Tailscale unterstütztes Produkt. Netbird
hingegen wurde von Anfang an so konzipiert, dass der vollständige Stack – Management Server, Signal-Server
und COTURN – selbst betrieben werden kann. Das ist ein offizieller, dokumentierter und unterstützter
Anwendungsfall.
Beide Lösungen sind Open Source: Netbird steht unter der BSD-3-Clause-Lizenz, Tailscale veröffentlicht seinen
Client unter einer BSD-Lizenz, der Koordinationsserver ist jedoch proprietär. Netbird veröffentlicht den
gesamten Server-Stack als Open Source auf GitHub.
Die Benutzeroberfläche und das Konzept sind vergleichbar: Beide bieten eine Web-UI zur Verwaltung von Peers,
Zugriffsrichtlinien und Netzwerk-Routen. Beide unterstützen Linux, Windows, macOS, iOS und Android.
Beide nutzen WireGuard als Transportprotokoll und STUN/TURN für NAT-Traversal.
Für Nutzer mit Datenschutz- und Souveränitätsanforderungen – etwa im Homelab-Umfeld, in Unternehmen oder bei
sensiblen Einsatzszenarien – ist Netbird aufgrund des vollständig selbst betreibbaren Stacks die überzeugendere
Wahl. Wer hingegen eine verwaltete Lösung ohne eigene Infrastruktur bevorzugt, kann Tailscale oder auch den
von Netbird angebotenen Cloud-Dienst unter app.netbird.io nutzen.
4. Installation – Client und Self-hosted Management Server
Die Installation des Netbird-Clients ist auf allen gängigen Plattformen unkompliziert. Unter Linux kann der
Client über das offizielle Installations-Skript eingerichtet werden:
curl -fsSL https://pkgs.netbird.io/install.sh | sh
Alternativ steht das offizielle APT- bzw. YUM-Repository zur Verfügung. Nach der Installation verbindet man
den Client mit dem gewünschten Management Server (selbst gehostet oder der Netbird-Cloud) und meldet den
Peer an:
netbird up --management-url https://mein-netbird-server.example.com:443
Unter Windows und macOS stehen Installer auf der offiziellen Netbird-Website zur Verfügung. Auf beiden
Systemen läuft der Client als Hintergrunddienst und bringt eine System-Tray-Integration mit, über die der
Verbindungsstatus eingesehen und die Route-Konfiguration angepasst werden kann.
Für den Self-hosted Management Server stellt Netbird ein offizielles Docker-Compose-Setup bereit.
Voraussetzungen sind ein öffentlich erreichbarer Server (z. B. ein günstiger VPS), Docker und Docker Compose
sowie eine Domain mit gültigem TLS-Zertifikat (automatisch via Let's Encrypt und Caddy als Reverse Proxy).
# Repository klonen und in das infrastructure_files-Verzeichnis wechseln
git clone https://github.com/netbirdio/netbird.git
cd netbird/infrastructure_files
# Konfigurationsdatei anpassen
cp setup.env.example setup.env
# In setup.env: NETBIRD_DOMAIN, LETSENCRYPT_EMAIL und
# NETBIRD_AUTH_* (Identity Provider) eintragen
# Setup-Skript ausführen (generiert docker-compose.yml)
./configure.sh
# Stack starten
docker compose up -d
Das Setup-Skript generiert automatisch eine docker-compose.yml mit den passenden Konfigurationen
für Management Service, Signal Service, COTURN und Caddy als Reverse Proxy. Nach dem Start ist das
Netbird-Dashboard unter der konfigurierten Domain erreichbar. Für die Authentifizierung kann ein externer
Identity Provider (z. B. Authentik, Keycloak, Auth0 oder Google OAuth2) eingebunden werden. Für einfache
Setups ohne externen IdP kann auch die eingebaute Authentifizierung über Personal Access Tokens (PAT) genutzt
werden.
5. Netzwerk-Konfiguration – Peers, Policies und Routes
Nach der Installation verwaltet man das Netzwerk über das Netbird-Dashboard oder die REST-API. Die drei
wichtigsten Konzepte sind Peers, Access Policies und Network Routes.
Peers sind alle Geräte, die dem Netbird-Netzwerk beigetreten sind. Jeder Peer erhält eine
eindeutige IP-Adresse aus dem konfigurierten Netzwerk-Prefix (standardmäßig im Bereich
100.64.0.0/10, dem sogenannten Carrier-Grade-NAT-Bereich). Peers können in Gruppen organisiert
werden, was die Verwaltung größerer Netzwerke erheblich vereinfacht. Eine neue Peer-Registrierung erfolgt
über ein Setup-Key, das im Dashboard generiert und an den jeweiligen Nutzer oder das Automatisierungsskript
übergeben wird.
Access Policies definieren, welche Peers oder Peer-Gruppen miteinander kommunizieren dürfen.
Standardmäßig erlaubt Netbird nach der Ersteinrichtung die Kommunikation zwischen allen Peers im selben
Netzwerk. Man kann jedoch granulare Regeln erstellen – etwa: Gruppe "Monitoring" darf die Gruppe "Server" auf
Port 9100 (Prometheus Node Exporter) erreichen, aber nicht umgekehrt. Die Regeln werden im Dashboard
gepflegt und auf jedem Peer lokal als WireGuard-Firewall-Regeln durchgesetzt.
Network Routes ermöglichen es, gesamte Subnetze über einen Peer als Gateway erreichbar zu
machen. Das ist der Schlüsselmechanismus für den Homelab-Zugriff: Ein Peer, der sich im Heimnetzwerk befindet,
kann als Route Advertiser für das lokale Subnetz (z. B. 192.168.1.0/24) konfiguriert werden.
Alle anderen Peers, die dieser Route folgen, können dann über den Netbird-Tunnel auf alle Geräte im
Heimnetzwerk zugreifen – auch auf Geräte, auf denen kein Netbird-Client läuft, wie Smart-Home-Geräte,
NAS-Systeme, Drucker oder Switches.
Network Routes lassen sich direkt im Dashboard unter "Network Routes" anlegen. Man gibt das Ziel-Subnetz,
den Peer der als Gateway fungiert sowie optional eine Beschreibung und eine Metrik an. Clients, die diese
Route nutzen sollen, müssen den Route-Advertiser-Peer per Access Policy erreichen dürfen und die Route
in ihrem lokalen Netbird-Client als aktiv markieren.
6. Praxisbeispiel – Homelab-Zugriff über Netbird
Das folgende Szenario beschreibt ein typisches Homelab-Setup: Man möchte von unterwegs – also vom Laptop
aus einem fremden WLAN oder Mobilnetz – sicher auf das Heimnetzwerk zugreifen. Im Heimnetz befindet sich
ein Proxmox-Hypervisor mit mehreren VMs und LXC-Containern im Subnetz 192.168.10.0/24.
Weder am Heimrouter soll ein Port geöffnet werden, noch sollen alle Dienste direkt über das Internet
exponiert sein.
Setup-Übersicht:
VPS (z. B. Hetzner CX22, 2 vCPU / 4 GB RAM) mit öffentlicher IPv4: hier läuft der Self-hosted Netbird Management Stack
Proxmox-Host im Heimnetz (192.168.10.2): Netbird-Client installiert, fungiert als Route Advertiser für 192.168.10.0/24
Laptop (unterwegs): Netbird-Client installiert, nutzt die Network Route ins Heimnetz
Schritt 1 – Netbird auf dem VPS installieren:
Wie im Abschnitt Installation beschrieben, wird auf dem VPS der Management-Stack via Docker Compose
aufgesetzt. Die Domain netbird.example.com wird auf die öffentliche IP des VPS gezeigt.
TLS wird automatisch über Caddy und Let's Encrypt abgewickelt. In der Firewall des VPS werden folgende
Ports freigegeben:
443/tcp – HTTPS für Management UI und API
10000/tcp – Signal Service
3478/udp – STUN (COTURN)
49152-65535/udp – TURN Relay-Ports (COTURN)
Schritt 2 – Proxmox-Host als Peer hinzufügen:
Auf dem Proxmox-Host wird der Netbird-Client installiert und mit dem eigenen Management Server verbunden:
netbird up --management-url https://netbird.example.com:443
Im Dashboard erscheint der neue Peer. Man weist ihm die Gruppe homelab zu. Damit der Proxmox-Host
als Router für das Heimnetz fungieren kann, muss IP-Forwarding auf dem System aktiviert sein:
echo "net.ipv4.ip_forward=1" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
Schritt 3 – Network Route anlegen:
Im Netbird-Dashboard unter "Network Routes" wird eine neue Route angelegt:
Network Range: 192.168.10.0/24
Peer (Route Advertiser): der Proxmox-Host
Peer Groups (wer die Route nutzen darf): laptops
Description: Heimnetz Proxmox
Schritt 4 – Laptop als Peer hinzufügen und Route aktivieren:
Auf dem Laptop wird der Netbird-Client installiert und ebenfalls mit dem Management Server verbunden.
In der Desktop-App wird die Route 192.168.10.0/24 als aktiv markiert. Ab jetzt ist das
gesamte Heimnetz über den Netbird-Tunnel erreichbar – ganz ohne Port-Forwarding am Heimrouter.
Da Netbird bei direkten P2P-Verbindungen keine Daten über den VPS leitet, fließt der eigentliche
Datenverkehr zwischen Laptop und Proxmox-Host direkt über einen WireGuard-Tunnel, sofern NAT-Traversal
erfolgreich war. Der VPS dient in diesem Fall nur als Koordinationsinstanz und optionaler Relay-Fallback –
nicht als Datenpfad. Das macht das Setup sowohl latenzarm als auch bandbreiteneffizient: Der VPS benötigt
faktisch keine Bandbreite für den Nutzdatenverkehr und kann entsprechend klein dimensioniert werden.
Über den Tunnel kann man anschließend direkt auf die Proxmox-Weboberfläche unter
https://192.168.10.2:8006 zugreifen, SSH-Verbindungen zu VMs aufbauen oder auf andere
Netzwerkdienste im Heimnetz zugreifen – als wäre man physisch im selben Netzwerk.
7. Troubleshooting
Netbird bringt ein praktisches CLI-Werkzeug mit, das bei der Diagnose von Verbindungsproblemen hilft.
Der wichtigste Befehl ist netbird status, der den aktuellen Zustand des lokalen Peers und
aller bekannten Verbindungen anzeigt:
netbird status
Die Ausgabe zeigt für jeden Peer den aktuellen Verbindungsstatus an. Besonders relevant ist dabei, ob
eine Verbindung direkt (P2P) oder über einen Relay-Server (TURN) aufgebaut wurde. Eine direkte Verbindung
ist anzustreben – eine Relay-Verbindung funktioniert zwar, ist aber langsamer und verbraucht mehr
Ressourcen auf dem COTURN-Server.
Für detailliertere Ausgaben steht netbird status --detail zur Verfügung. Hier sieht man
unter anderem die verwendeten WireGuard-Endpunkte, ICE-Verbindungskandidaten und ob der Peer aktuell
über STUN oder TURN kommuniziert.
Häufige Probleme und ihre Ursachen:
Peer verbindet sich nicht: Prüfen, ob der Management Server erreichbar ist
(curl https://netbird.example.com/api/peers). Firewall-Regeln auf dem VPS kontrollieren –
die Ports 443/tcp (Management), 10000/tcp (Signal) und 3478/udp (STUN) sowie der TURN-Port-Bereich
(UDP 49152–65535) müssen von außen erreichbar sein.
Nur Relay-Verbindung statt P2P: Symmetrisches NAT auf einer oder beiden Seiten
verhindert direkte Verbindungen. Das ist bei manchen Mobilfunknetzen oder Carrier-Grade-NATs der Fall.
Hier hilft es, den COTURN-Server korrekt zu konfigurieren – dann funktioniert zumindest die
Relay-Verbindung stabil. Eine direkte Verbindung lässt sich in diesen Fällen nicht erzwingen.
Network Route funktioniert nicht: IP-Forwarding auf dem Route-Advertiser-Peer
aktiviert? Ist die Route im Dashboard korrekt eingetragen und auf dem Client-Peer als aktiv markiert?
Stimmt die Access Policy – darf der Client-Peer den Route-Advertiser-Peer überhaupt erreichen?
Prüfen mit ping 192.168.10.2 vom Laptop aus.
Peer wird als offline angezeigt: Den Daemon-Status auf dem betroffenen Peer prüfen:
systemctl status netbird. Bei Bedarf neu starten:
sudo systemctl restart netbird.
Logs einsehen: Unter Linux können die Logs des Netbird-Daemons über
journalctl -u netbird -f eingesehen werden. Dort finden sich detaillierte Informationen
über den Verbindungsaufbau, ICE-Kandidaten und eventuelle Fehlermeldungen.
Netbird ist insgesamt ein ausgereiftes Projekt mit aktiver Community und guter Dokumentation. Die offizielle
Dokumentation unter docs.netbird.io ist ausführlich und deckt alle beschriebenen Szenarien
mit aktuellen Anleitungen ab. Für komplexere Setups – etwa Multi-Tenant-Umgebungen, SSO-Integration oder
automatisierte Peer-Registrierung via Setup Keys und REST-API – lohnt sich ein Blick in die API-Dokumentation
und den offiziellen Terraform-Provider, den Netbird für Infrastructure-as-Code-Anwendungsfälle bereitstellt.