NetBird: Vollständige Installationsanleitung auf Hetzner Cloud
Interessiert an gemanagtem NetBird-Hosting oder Installation auf Ihrer eigenen Infrastruktur? Bei WZ-IT kümmern wir uns um Beratung, Installation, Support, Betrieb, Wartung und Monitoring Ihrer NetBird-Infrastruktur - ob bei uns oder bei Ihnen. Vereinbaren Sie hier Ihr kostenloses und unverbindliches Erstgespräch: Termin vereinbaren.
NetBird ist ein WireGuard-basiertes Zero-Trust Overlay-Netzwerk, das Ihnen eine zentrale Management-Ebene (Benutzer, Geräte, Routen, Policies) bietet und dabei den Traffic Ende-zu-Ende verschlüsselt hält. Dieser Artikel führt Sie durch ein praktisches Self-Hosted Deployment auf einem Hetzner Cloud CPX Server mit Docker und NetBirds offiziellem "Self-hosted Quickstart mit Zitadel"-Ansatz.
Wir installieren NetBird auf einem frischen Ubuntu Server und verwenden die Beispiel-Domain: netbird-demo.wz-it.com
Inhaltsverzeichnis
- High-Level Architektur
- Voraussetzungen
- Schritt 1: Server auf Hetzner Cloud erstellen
- Schritt 2: Per SSH verbinden und Pakete aktualisieren
- Schritt 3: Docker Engine und Docker Compose installieren
- Schritt 4: DNS-Einträge verifizieren
- Schritt 5: NetBird Self-Hosted Quickstart ausführen
- Schritt 6: Container und Logs prüfen
- Schritt 7: Dashboard und Zitadel Console öffnen
- Schritt 8: Benutzer hinzufügen und erstes Gerät registrieren
- Schritt 9: Konnektivität prüfen
- Schritt 10: Backup und Upgrades
- Fazit
- Quellen
High-Level Architektur
Der Quickstart startet mehrere Services via Docker Compose, darunter:
- NetBird Management + Dashboard (Web UI)
- NetBird Signal Service
- STUN/TURN (Coturn) für NAT Traversal/Relay
- Zitadel als Identity Provider (SSO/MFA/Benutzerverwaltung)
Der NetBird Quickstart ist dafür gedacht, schnell loszulegen. Für benutzerdefinierte Identity Provider und ein maßgeschneidertes Produktions-Setup bietet NetBird auch einen Advanced Self-Hosting Guide.
Voraussetzungen
1. Hetzner Cloud Server
- Eine Hetzner Cloud CPX-Instanz (CPX11 oder höher reicht typischerweise)
- Ubuntu 22.04 LTS (oder Debian; Befehle unten gehen von Ubuntu/Debian aus)
- Eine öffentliche IPv4-Adresse
2. Domain und DNS
Erstellen Sie einen A-Record, der auf Ihren Server zeigt:
netbird-demo.wz-it.com -> IHRE_SERVER_IPV4
3. Erforderliche Ports (NetBird Self-Hosted)
Die VM muss öffentlich erreichbar sein auf:
| Protokoll | Ports |
|---|---|
| TCP | 80, 443, 33073, 10000, 33080 |
| UDP | 3478, 49152-65535 |
Wichtiger Hinweis zur Hetzner Cloud Firewall
Ohne angehängte Hetzner Cloud Firewall blockiert Hetzner keine eingehenden Ports automatisch. Der Server verhält sich dann wie eine normale öffentliche VM - welche Ports erreichbar sind, hängt vom Betriebssystem und den laufenden Diensten ab.
Das "implizite Deny"-Verhalten greift nur bei aktivierter Hetzner Cloud Firewall:
- Die Firewall-Regeln bestimmen, welcher eingehende Traffic erlaubt ist
- Alles andere wird blockiert (implizites Deny)
- Ohne konfigurierte Inbound-Regeln ist der Server nicht erreichbar
Zusammenfassung:
- Ohne Cloud Firewall: Betriebssystem und Dienste bestimmen die offenen Ports
- Mit Cloud Firewall: Die oben genannten Ports müssen explizit freigegeben werden
Schritt 1: Server auf Hetzner Cloud erstellen
- Neuen Server erstellen (Ubuntu 22.04)
- SSH-Key hinzufügen
- (Optional, empfohlen) Hetzner Cloud Firewall anhängen
Bei Nutzung einer Firewall diese Inbound-Regeln hinzufügen:
| Protokoll | Ports | Hinweis |
|---|---|---|
| TCP | 22 | Auf Ihre IP beschränken wenn möglich |
| TCP | 80, 443, 33073, 10000, 33080 | NetBird Services |
| UDP | 3478 | STUN |
| UDP | 49152-65535 | TURN Relay Range |
Schritt 2: Per SSH verbinden und Pakete aktualisieren
Per SSH mit dem Server verbinden:
ssh root@IHRE_SERVER_IP
Pakete aktualisieren:
apt update && apt -y upgrade
Grundlegende Abhängigkeiten installieren:
apt -y install ca-certificates curl gnupg git jq
Schritt 3: Docker Engine und Docker Compose installieren
NetBird Self-Hosting nutzt Docker und docker compose (Compose v2). Docker von den offiziellen Quellen installieren:
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh
rm get-docker.sh
Installation überprüfen:
docker --version
docker compose version
Schritt 4: DNS-Einträge verifizieren
Vor dem Quickstart die DNS-Konfiguration prüfen. Vom lokalen Rechner aus den A-Record abfragen:
dig netbird-demo.wz-it.com +short
Die Ausgabe sollte die IP-Adresse des Servers zeigen. Bei fehlerhafter DNS-Konfiguration schlägt die Let's Encrypt TLS-Zertifikatserstellung fehl.
Schritt 5: NetBird Self-Hosted Quickstart ausführen
Der offizielle NetBird Quickstart installiert alles mit einem einzigen Script und Docker-Containern.
Arbeitsverzeichnis erstellen:
mkdir -p /opt/netbird
cd /opt/netbird
Quickstart-Script herunterladen und ausführen:
curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started-with-zitadel.sh -o getting-started-with-zitadel.sh
chmod +x getting-started-with-zitadel.sh
./getting-started-with-zitadel.sh
Während des Setups werden Sie nach folgenden Informationen gefragt:
- Ihre Domain (z.B.
netbird-demo.wz-it.com) - Bestätigung, dass Ports 80/443 für die Zertifikatsausstellung erreichbar sind
Das Script erledigt folgende Schritte:
- Generiert die Konfiguration (Docker Compose, Reverse Proxy, TLS)
- Lädt NetBird, Zitadel und Coturn Images herunter
- Richtet TLS/HTTPS für das Dashboard ein
- Startet den kompletten Stack
Nach erfolgreicher Installation zeigt das Script die Zugangsdaten und URLs an:
Schritt 6: Container und Logs prüfen
Vom Installationsverzeichnis aus (dort liegen die Docker Compose Dateien):
docker compose ps
Alle Container sollten den Status "healthy" oder "running" haben.
Logs auf Probleme prüfen:
docker compose logs -f --tail=200
Typische Fehlerursachen bei unhealthy Containern:
- DNS zeigt nicht auf die VM
- Firewall blockiert benötigte Ports
- Docker/Compose nicht korrekt installiert
Schritt 7: Dashboard und Zitadel Console öffnen
Das NetBird Dashboard im Browser aufrufen:
https://netbird-demo.wz-it.com
Für die Benutzerverwaltung stellt Zitadel einen eigenen Console-Endpoint bereit (die URL wird in der Quickstart-Ausgabe angezeigt).
Die Zitadel Console dient zur Verwaltung von Benutzern und Authentifizierung:
Schritt 8: Benutzer hinzufügen und erstes Gerät registrieren
- Benutzer anlegen oder einladen über Zitadel (IdP)
- NetBird Client installieren auf einem Gerät (Windows/macOS/Linux)
- Anmelden über Ihre NetBird-Domain (SSO)
- Prüfen, ob das Gerät im NetBird Dashboard erscheint
Schritt 9: Konnektivität prüfen
A) Lauschen die erforderlichen Ports?
TCP-Ports prüfen:
ss -tulpn | grep -E ':(80|443|33073|10000|33080)\b'
UDP-Ports prüfen:
ss -uulpn | grep -E ':(3478)\b'
B) Firewall-Regeln überprüfen
Falls Sie eine Hetzner Cloud Firewall nutzen, kontrollieren Sie Ihre Inbound-Regeln. Zur Erinnerung: Eingehender Traffic wird standardmäßig blockiert - nur explizit erlaubte Ports sind erreichbar.
C) NAT Traversal und Relay prüfen
Für Clients hinter restriktiven NATs sind diese Ports besonders wichtig:
- UDP 3478
- UDP 49152-65535
Schritt 10: Backup und Upgrades
Backups
Folgende Daten sollten gesichert werden:
- Generierte Config-Dateien (Compose-Dateien, Env-Dateien)
- Persistente Docker Volumes (Zitadel-Daten, NetBird Management-Daten)
# Volumes auflisten
docker volume ls
# Ein Volume sichern
docker run --rm -v netbird_management:/data -v $(pwd):/backup ubuntu tar czf /backup/netbird-management-backup.tar.gz /data
Upgrades
Empfohlene Upgrade-Vorgehensweise:
cd /opt/netbird
# Zuerst Backup erstellen
docker compose down
# Neue Images herunterladen
docker compose pull
# Mit neuen Images starten
docker compose up -d
Für ein produktionsreifes Setup jenseits des Quickstarts empfiehlt sich der Advanced Self-Hosting Guide samt Release Notes.
Fazit
Mit dieser Anleitung läuft eine vollständige, selbst gehostete NetBird Control Plane auf Hetzner Cloud unter netbird-demo.wz-it.com. Die wichtigsten Erfolgsfaktoren sind:
- Korrektes DNS - der A-Record muss auf den Server zeigen
- Docker/Compose - korrekt installiert und lauffähig
- Offene Ports - alle TCP- und UDP-Ports erreichbar (besonders die UDP Relay Range für NAT-Szenarien)
Der Quickstart eignet sich hervorragend für einen schnellen Einstieg. Für einen eigenen Identity Provider oder produktionsreife Anpassungen bietet der Advanced Self-Hosting Guide den nächsten Schritt.
Unsere NetBird-Services
Sie möchten NetBird nicht selbst verwalten? Bei WZ-IT bieten wir:
- Managed NetBird Hosting - Wir betreiben und warten Ihre NetBird-Infrastruktur
- Installation auf Ihrer Infrastruktur - Wir richten NetBird auf Ihren eigenen Servern ein
- Beratung & Support - Expertenunterstützung bei Planung, Konfiguration und Troubleshooting
Vereinbaren Sie ein kostenloses Erstgespräch, um Ihre Anforderungen zu besprechen.
Quellen
Häufig gestellte Fragen
Antworten auf wichtige Fragen zu diesem Thema
Der NetBird Server kann auf allen gängigen Linux-Distributionen installiert werden, die Docker unterstützen - darunter Debian, Ubuntu, CentOS, RHEL, Rocky Linux, AlmaLinux, Fedora und openSUSE. Auch andere Systeme mit Docker-Unterstützung sind möglich.
Die VM muss öffentlich erreichbar sein auf: TCP 80, 443, 33073, 10000, 33080 und UDP 3478, 49152-65535.
Nur wenn Sie die Hetzner Cloud Firewall aktivieren und an den Server anhängen. In diesem Fall gilt ein implizites Deny für eingehenden Traffic und nur explizit erlaubte Regeln werden durchgelassen. Ohne angehängte Firewall verhält sich die VM wie ein normaler öffentlicher Server.
Der Quickstart konfiguriert HTTPS/TLS für das Dashboard. Für die automatische TLS-Zertifikatserstellung muss DNS auf die VM zeigen und Ports 80/443 erreichbar sein.
Ja. NetBird bietet einen Advanced Self-Hosting Guide, der auf benutzerdefinierte Identity Provider abzielt statt auf den Zitadel-basierten Quickstart.
Die häufigste Ursache sind fehlende UDP-Freigaben für NAT-Traversal/Relay: UDP 3478 und UDP 49152-65535. Prüfen Sie auch, ob die zusätzlichen TCP-Ports erreichbar sind.
Das können Sie, aber achten Sie darauf, Ports nicht doppelt zu blockieren. Wenn Sie sowohl Hetzner Cloud Firewall als auch ufw nutzen, müssen Sie die NetBird-Ports an beiden Stellen freigeben.
Quickstart ist optimiert für schnelles, funktionierendes Self-Hosting mit einem gebündelten IdP (Zitadel). Advanced bietet mehr Kontrolle mit benutzerdefiniertem IdP und flexibleren Deployment-Optionen.
NetBird speichert das getting-started-with-zitadel.sh Script in ihrem GitHub-Repository; es ist nützlich um zu prüfen, was erstellt wird und wie Umgebungsvariablen/Konfiguration generiert werden.
Lassen Sie uns über Ihre Idee sprechen
Ob konkrete IT-Herausforderung oder einfach eine Idee – wir freuen uns auf den Austausch. In einem kurzen Gespräch prüfen wir gemeinsam, ob und wie Ihr Projekt zu WZ-IT passt.
Vertraut von führenden Unternehmen
Timo Wevelsiep & Robin Zins
Geschäftsführer