NetBird-VPN-Server auf einem VPS selbst hosten

Was Ihnen das Self-Hosting des NetBird-VPN-Servers bietet

Beim Self-Hosting des NetBird-VPN-Servers läuft die Control Plane auf einem VPS, den Sie selbst besitzen. Sie verwaltet die Peer-Liste, entscheidet, welche Maschine welche andere erreichen darf, und hilft zwei Peers dabei, sich hinter NAT (Network Address Translation) zu finden. Die Tunnel verwenden weiterhin WireGuard und werden direkt zwischen Ihren Maschinen verschlüsselt. Geändert hat sich, dass kein externes Unternehmen Ihre Geräteübersicht oder Ihren Anmeldeablauf verwaltet. Sie sollten genau verstehen, welchen Vorteil das bietet. Eine gehostete Control Plane besitzt niemals die Schlüssel, mit denen Ihr Datenverkehr verschlüsselt wird. Außerdem ist was ein kompromittierter Koordinationsserver tatsächlich tun kann eine kürzere Liste, als die meisten Menschen vor der Lektüre annehmen.

NetBird verbindet zwei Konzepte, die Sie möglicherweise bereits kennen. Es ist ein Mesh-Overlay. Peers verbinden sich also direkt miteinander, statt den gesamten Datenverkehr über ein Gateway zu senden. Gleichzeitig lässt es sich vollständig selbst hosten. Damit steht es Headscale, dem selbst gehosteten Tailscale-Control-Server, gegenüber. Wenn Sie bisher nur einen Tunnel mit einem einzelnen Gateway betrieben haben, lesen Sie zuerst den Unterschied zwischen einfachem WireGuard und einem Mesh-Overlay. Dieses Verständnis macht den restlichen Inhalt dieser Seite nachvollziehbar.

Wenn Sie tatsächlich nur einen Server benötigen, über den Ihr gesamter Datenverkehr ins Internet gelangt, ist ein Mesh aufwendiger als erforderlich. Ein einfaches WireGuard-VPN auf einem einzelnen VPS oder ein Tailscale-Exit-Node erfüllt diese Aufgabe mit deutlich weniger Betriebsaufwand. Wenn Sie dagegen ein privates Netzwerk erreichen möchten, statt Maschinen miteinander zu verbinden, kündigt ein Tailscale-Subnet-Router auf einem VPS diesen Bereich in einem vorhandenen Tailnet an, ohne dass Sie den folgenden Stack benötigen.

Was der Stack tatsächlich ausführt

Das Layout wurde kürzlich geändert, und die meisten älteren Anleitungen beschreiben noch die alte Struktur. Im Oktober 2026 mit v0.80.0 sowie mit v0.76.2 geprüft, auf das diese Anleitung festgelegt ist, schreibt das Quickstart-Skript standardmäßig eine Compose-Datei mit drei Services.

• netbird-server stellt die Management-API, den Signal-Service, das Relay mit integriertem STUN-Listener und einen integrierten Identity Provider bereit. In älteren Releases liefen diese Komponenten in separaten Containern, und der Identity Provider war eine separate Zitadel-Installation, die Sie zuerst erstellen mussten.
• dashboard ist die Webkonsole für die Administration.
• traefik übernimmt die TLS-Terminierung (Transport Layer Security) und fordert beim ersten Start ein Zertifikat von Let's Encrypt an.

Zwei weitere Services sind vorhanden und bleiben deaktiviert, sofern Sie an einer Eingabeaufforderung nicht zustimmen. Der NetBird Proxy-Service veröffentlicht interne Services unter öffentlichen Hostnamen. CrowdSec filtert missbräuchlichen Netzwerkverkehr. Für den Aufbau eines funktionierenden Mesh sind beide nicht erforderlich. Auf einem kleinen System belegen beide zusätzlichen Arbeitsspeicher.

Wenn Sie von wg-easy in einem einzelnen Docker-Container kommen, erhöht sich die Anzahl der Komponenten deutlich. Dafür erhalten Sie Zugriffsrichtlinien und Benutzerkonten pro Benutzer sowie Peers, die sich direkt miteinander verbinden, statt über ein einziges Gateway zu laufen.

Was Sie vor dem Start benötigen

Ein öffentlicher Domainname ist zwingend erforderlich. Das Dashboard, die API und das Relay verwenden HTTPS über Port 443. Traefik bezieht sein Zertifikat von Let's Encrypt über die TLS-ALPN-01-Challenge, die auf Port 443 beantwortet wird. Dafür muss ein Name aus dem öffentlichen Internet auf diese VPS-Instanz aufgelöst werden. Eine reine IP-Adresse funktioniert in diesem Ablauf nicht.

Erstellen Sie einen A-Record, netbird.example.com der auf die öffentliche IPv4-Adresse der VPS-Instanz zeigt, und warten Sie die DNS-Propagation ab, bevor Sie etwas ausführen.

dig +short netbird.example.com

Dabei muss die Adresse Ihres Servers ausgegeben werden. Wenn Sie das Installationsprogramm ausführen, bevor DNS propagiert wurde, schlägt die Zertifikatsanforderung beim ersten Start fehl. Wiederholte fehlgeschlagene Validierungen führen außerdem zu Rate-Limits von Let's Encrypt. Dann müssen Sie warten, bis das Limit wieder verfügbar ist, bevor Sie es erneut versuchen können.

Drei Ports müssen aus dem Internet erreichbar sein: TCP 80 für die Weiterleitung zu HTTPS, TCP 443 für Dashboard, API, Signal- und Relay-Datenverkehr sowie die Zertifikatschallenge und UDP 3478 für STUN.

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 3478/udp
sudo ufw reload
sudo ufw status

Öffnen Sie diese Ports auch in der Netzwerk-Firewall Ihres Providers. Das ist in den meisten VPS-Konsolen eine separate Einstellung. Deshalb verweigert ein System mit scheinbar korrekter eigener ufw status weiterhin Verbindungen.

STUN (session traversal utilities for NAT) ermöglicht es einem Peer, die öffentliche Adresse und den Port zu ermitteln, die sein eigenes NAT zugewiesen hat. Dadurch können zwei Peers einen direkten Tunnel versuchen. Wenn Sie UDP 3478 blockieren, verbinden sich die Peers weiterhin über das Relay auf TCP 443. Dadurch wirkt zunächst nichts fehlerhaft. Peers, die keinen direkten Pfad finden, zeigen Connection type: Relayed an. Ihr Datenverkehr läuft dann über Ihre VPS-Instanz statt direkt zwischen den Peers. Peers im selben LAN können weiterhin über ihre lokalen Adressen eine direkte Verbindung herstellen.

Auf der Softwareseite benötigen Sie Docker mit dem Compose v2-Plugin sowie jq und curl. Das Skript prüft Docker, Compose und jq und beendet sich, wenn eine Komponente fehlt. curl wird verwendet, ohne vorher darauf zu prüfen. Installieren Sie es daher zuerst. Wenn Docker auf diesem System neu ist, richten Sie zunächst Docker Compose auf der VPS-Instanz ein ein.

Installieren Sie den NetBird-Server mit dem Quickstart-Skript

Die dokumentierte Einzeile leitet das neueste Release direkt an eine Shell weiter:

curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh | bash

Fixieren Sie stattdessen eine Version. latest ändert sich, sodass derselbe Befehl, der im Abstand von zwei Wochen ausgeführt wird, zwei unterschiedliche Installationen erzeugt. Auf dem Datenträger wird außerdem nicht festgehalten, welche Version Ihre Konfiguration geschrieben hat. Laden Sie ein getaggtes Release herunter, lesen Sie es, und führen Sie es anschließend aus.

mkdir -p ~/netbird
cd ~/netbird
curl -fsSL -o getting-started.sh \
  https://github.com/netbirdio/netbird/releases/download/v0.76.2/getting-started.sh
less getting-started.sh
bash getting-started.sh

Das Skript fragt zuerst nach der Domain:

Enter the domain you want to use for NetBird (e.g. netbird.my-domain.com):

Danach fragt es, wie TLS verarbeitet werden soll:

Which reverse proxy will you use?
  [0] Traefik (recommended - automatic TLS, included in Docker Compose)
  [1] Existing Traefik (labels for external Traefik instance)
  [2] Nginx (generates config template)
  [3] Nginx Proxy Manager (generates config + instructions)
  [4] External Caddy (generates Caddyfile snippet)
  [5] Other/Manual (displays setup documentation)
Enter choice [0-5] (default: 0):

Wählen Sie [0]. Die Optionen 2 bis 4 schreiben einen Konfigurationsausschnitt und überlassen Ihnen die weitere Einbindung. Option 5 schreibt die Compose-Datei, dashboard.env und config.yaml und gibt die Einrichtungsdokumentation im Terminal aus. Das ist auf einem System korrekt, auf dem bereits ein Proxy läuft, aber auf einem neuen System falsch. Option 0 fragt anschließend nach einer E-Mail-Adresse, die Traefik bei Ihrem Let's-Encrypt-Konto registriert. Die Eingabeaufforderung bezeichnet sie weiterhin als Adresse für Zertifikatsbenachrichtigungen. Let's Encrypt versendet jedoch seit dem 4. Juni 2025 keine E-Mails mehr zu ablaufenden Zertifikaten. Probleme bei der Erneuerung erscheinen daher im Traefik-Log und nicht in Ihrem Posteingang.

Lehnen Sie den NetBird-Proxy-Dienst bei der ersten Installation ab. Er benötigt einen weiteren DNS-Eintrag: einen Wildcard-*.netbird.example.com-CNAME, der auf netbird.example.com zeigt. Für ein einfaches Mesh bringt er keinen Nutzen. Die CrowdSec-Abfrage erscheint nur, wenn der Proxy aktiviert ist. Wenn Sie den Proxy ablehnen, wird CrowdSec ebenfalls übersprungen. Beide Komponenten können später hinzugefügt werden.

Das Skript schreibt in das aktuelle Verzeichnis: docker-compose.yml, config.yaml mit dem Modus 600 und dashboard.env. Mit dem enthaltenen Traefik fügt es traefik-dynamic.yaml und proxy.env nur hinzu, wenn Sie den NetBird-Proxy aktivieren. Behandeln Sie dieses Verzeichnis als dauerhaften Zustandsbestand, da config.yaml den Schlüssel enthält, der die Daten im Store verschlüsselt. Ein Verlust dieses Schlüssels lässt sich nicht durch eine Neuinstallation beheben.

docker compose ps
docker compose logs -f netbird-server

Jeder Dienst sollte den Status running anzeigen. Das Server-Log sollte sich stabilisieren und nicht in einer Neustartschleife laufen. Überwachen Sie das Zertifikat separat:

docker compose logs traefik | grep -i acme

ACME (automatic certificate management environment) ist das Protokoll, das Traefik zum Abrufen des Zertifikats verwendet. Fehler an dieser Stelle werden fast immer durch DNS oder einen geschlossenen Port 443 verursacht.

Erstellen des ersten Administratorkontos

Öffnen Sie https://netbird.example.com. Bei einer neuen Installation wird eine Einrichtungsseite statt eines Anmeldeformulars angezeigt. Geben Sie eine E-Mail-Adresse, einen Namen und ein Passwort ein. Klicken Sie anschließend auf Create Account. Dieses Konto ist das erste Administratorkonto. Danach wird das Anmeldeformular angezeigt.

Das Konto wird in NetBirds eigenem Benutzerspeicher gespeichert. Dieser wird von einem Identity Provider bereitgestellt, der in den Container netbird-server integriert ist. Es ist keine externe Komponente erforderlich. Das ist die größte Änderung gegenüber dem selbst gehosteten NetBird von vor einem Jahr. Damals musste für eine funktionierende Installation zuerst Zitadel oder Keycloak eingerichtet werden. Anschließend mussten vier OIDC-Werte (OpenID Connect) in setup.env kopiert werden. Erst dann konnte der Dienst überhaupt starten.

Wenn im Browser eine Zertifikatswarnung statt der Einrichtungsseite angezeigt wird, wurde das Zertifikat nicht ausgestellt. Beheben Sie dieses Problem, bevor Sie fortfahren. Das Dashboard kommuniziert über denselben Hostnamen mit der API. Bei einem fehlerhaften Zertifikat schlägt diese Kommunikation auf schwer nachvollziehbare Weise fehl.

Ihren ersten Peer verbinden

Installieren Sie den Client auf einem beliebigen Linux-Rechner. Das kann auch der VPS selbst sein, wenn er Teil des Mesh-Netzwerks werden soll:

curl -fsSL https://pkgs.netbird.io/install.sh | sh

Unter Debian und Ubuntu konfiguriert das Skript das Paket-Repository von NetBird und installiert anschließend den Client über apt. Damit wird er in jedem Fall vom Paketmanager verwaltet. Wenn Sie ein Skript nicht per Pipe an eine Shell übergeben möchten, speichern Sie es mit curl -fsSL -o install.sh https://pkgs.netbird.io/install.sh und lesen Sie es, bevor Sie sh install.sh ausführen. Prüfen Sie anschließend in jedem Fall, was installiert wurde:

apt-cache policy netbird

netbird ist der Befehlszeilen-Client und der Daemon. netbird-ui ist die Desktop-Tray-Anwendung. Auf einem Headless-Server wird sie nicht benötigt.

Verweisen Sie den Client nun auf Ihren Server:

sudo netbird up --management-url https://netbird.example.com

Lassen Sie --management-url weg, registriert sich der Client beim gehosteten Dienst von NetBird, weil dies der kompilierte Standardwert ist. Der Befehl wird trotzdem erfolgreich ausgeführt, der Rechner erhält trotzdem eine Adresse, und Ihr selbst gehostetes Dashboard bleibt leer. Das passiert fast jedem mindestens einmal.

Der Befehl gibt eine URL aus. Öffnen Sie diese in einem Browser, um die Anmeldung abzuschließen. Führen Sie danach Folgendes aus:

netbird status
ip addr show wt0

Lesen Sie vier Zeilen aus netbird status: Management: Connected, Signal: Connected, eine Relays:-Zeile mit jedem verfügbaren Relay und eine NetBird IP: im Overlay-Bereich. wt0 ist die WireGuard-Schnittstelle, die NetBird erstellt. Sie sollte dieselbe Adresse führen.

Einen zweiten Rechner unbeaufsichtigt mit einem Einrichtungsschlüssel verbinden

Die Browser-Anmeldung funktioniert nicht auf einem Rechner ohne Browser und ohne anwesende Person. Ein Einrichtungsschlüssel ist ein Token zur Vorabauthentifizierung. Damit registrieren Sie einen Rechner ohne interaktiven Schritt. Erstellen Sie ihn im Dashboard unter Setup Keys.

Es gibt zwei Arten. Ein einmaliger Schlüssel authentifiziert genau einen Rechner und ist danach verbraucht. Ein wiederverwendbarer Schlüssel registriert mehrere Rechner. Optional können Sie die Anzahl begrenzen. Beide Schlüssel haben ein Ablaufdatum. Beide können den neuen Peer automatisch einer Gruppe zuweisen. Dadurch gelten die Zugriffsregeln dieser Gruppe sofort, sobald der Rechner erscheint.

sudo netbird up --setup-key <SETUP-KEY> \
  --management-url https://netbird.example.com \
  --hostname build-runner-01

--hostname legt den im Dashboard angezeigten Namen fest. Ohne diese Option verwendet der Peer den Namen, unter dem sich der Rechner selbst meldet. Eine Liste mit Einträgen, die alle ubuntu heißen, ist nicht hilfreich.

Für Container und kurzlebige Build-Agenten markieren Sie den Schlüssel beim Erstellen als ephemeral. Peers, die mit einem ephemeral-Schlüssel registriert wurden, werden automatisch entfernt, sobald sie länger als 10 Minuten offline sind. Dadurch bleiben veraltete Einträge aus der Peer-Liste entfernt.

Beachten Sie vor der Planung mit Einrichtungsschlüsseln eine wichtige Einschränkung: Wenn ein Schlüssel abläuft oder widerrufen wird, werden keine neuen Registrierungen mehr zugelassen. Rechner, die bereits damit registriert wurden, werden dadurch nicht getrennt. Um den Zugriff eines Rechners zu entfernen, müssen Sie den entsprechenden Peer entfernen.

Benötigen Sie weiterhin einen separaten Identity Provider?

Für eine kleine Installation ist das nicht erforderlich. Der integrierte Benutzerspeicher verwaltet Konten, die über das Dashboard angelegt werden. Für wenige Benutzer ist das ausreichend.

Ein externer Identity Provider ist sinnvoll, wenn Sie bereits einen betreiben und keine zweite Benutzerliste pflegen möchten. NetBird akzeptiert jeden Provider, der OIDC unterstützt. Registrieren Sie in Ihrem Provider einen vertraulichen OIDC-Client. Fügen Sie ihn anschließend im NetBird-Dashboard mit vier Werten hinzu: Name, Client-ID, Client-Secret und Issuer. NetBird stellt Ihnen eine Redirect-URL bereit, die Sie wieder im Provider eintragen. Benannte Integrationen gibt es für Google, Microsoft Entra ID, Okta, Zitadel, Keycloak, Authentik und Pocket ID. Alle anderen Provider werden als generisches OIDC konfiguriert. Wenn Sie bereits Authentik als selbst gehostetes Single Sign-On betreiben, behalten Sie auf diesem Weg eine gemeinsame Benutzerliste statt zwei getrennter Listen.

Die lokale Anmeldung bleibt verfügbar, nachdem Sie einen Provider hinzugefügt haben. Jeder konfigurierte Provider erscheint auf der Anmeldeseite. Behalten Sie ein lokales Administratorkonto mit einem starken Passwort. Bei einer fehlerhaften OIDC-Konfiguration haben Sie dann weiterhin Zugriff.

NetBird oder Headscale: Welche Control Plane sollten Sie betreiben?

Beide beseitigen dieselbe Abhängigkeit: den gehosteten Control Server, den Ihre Clients sonst kontaktieren würden. Die Projekte sind jedoch unterschiedlich aufgebaut.

Headscale implementiert den Tailscale-Control-Server neu. Sie verwenden weiterhin die offiziellen Tailscale-Clients. Eine offizielle Webkonsole gibt es nicht. Benutzer und Pre-Authentication-Keys verwalten Sie mit dem Befehl headscale anhand einer Konfigurationsdatei. Community-Weboberflächen existieren, gehören aber nicht zum Projekt. Das eignet sich für Personen, die ihren Zustand in Dateien speichern und Änderungen in der Versionsverwaltung nachverfolgen möchten.

NetBird liefert das vollständige Produkt: einen eigenen Client, ein eigenes Dashboard, einen integrierten Identity Provider und Zugriffsrichtlinien, die im Browser bearbeitet werden. Dadurch laufen auf Ihrem VPS mehr Komponenten. Die Verwaltung lässt sich außerdem deutlich einfacher an einen Kollegen übergeben, der nie ein Terminal öffnen wird. Wenn Sie NetBird tatsächlich mit dem gehosteten Tailscale und nicht mit Headscale vergleichen, verwenden beide im Hintergrund WireGuard. Daher zeigt der Vergleich zwischen NetBird und Tailscale, worin sie sich tatsächlich unterscheiden: Wer die Control Plane betreibt, wie Zugriffsregeln formuliert werden und wie Relays den Netzwerkverkehr übertragen.

Betreiben Sie Headscale, wenn Sie bereits Tailscale-Clients einsetzen oder eine möglichst schlanke Control Plane benötigen. Betreiben Sie NetBird, wenn mehrere Personen Peers verwalten müssen und Sie eine Konsole sowie SSO nutzen möchten, ohne diese selbst zusammenzustellen. Prüfen Sie vor der Entscheidung welche Leistungen der kostenlose Tailscale-Tarif tatsächlich abdeckt, denn eine nicht kommerzielle Gruppe mit höchstens sechs Benutzern zahlt für eine gehostete Control Plane nichts. Sie erhält zunächst unbegrenzt viele Geräte pro Benutzer und 50 getaggte Ressourcen und hat möglicherweise überhaupt keinen Grund, eine eigene Control Plane zu betreiben. Oberhalb dieser Grenze steigt die Rechnung mit der Anzahl der Personen und nicht mit der Anzahl der Maschinen. Deshalb zeigt Ihnen die Berechnung der Tailscale-Kosten für Ihre Gruppe, welchen Betrag Sie mit den Kosten für den VPS und dem Zeitaufwand für diesen Stack vergleichen können.

Wie klein darf ein VPS für diesen Betrieb sein?

Das dokumentierte Minimum sind 1 CPU und 2 GB Arbeitsspeicher. Verwenden Sie 2 GB.

Drei Dinge können Sie auf einem kleinen System problemlos weglassen. Lehnen Sie den NetBird Proxy-Dienst ab. Er veröffentlicht interne Dienste unter öffentlichen Hostnamen und hat nichts mit der Verbindung zwischen Peers zu tun. Überspringen Sie CrowdSec. Das Skript bietet es nur zusammen mit dem Proxy an. Auf einem exponierten System können Sie es später hinzufügen, statt es am ersten Tag einzurichten. Verwenden Sie den standardmäßigen SQLite-Speicher im Volume netbird_data. Wechseln Sie erst zu PostgreSQL, wenn Sie die Bereitstellung auf mehrere Maschinen aufteilen oder tatsächlich parallele Zugriffe bewältigen müssen. Eine solche Migration ist laut Dokumentation später möglich.

Auf das Relay können Sie nicht verzichten. Wenn die NAT-Konfiguration zweier Peers für jedes Ziel einen anderen Port zuweist, können die Peers niemals einen direkten Tunnel aufbauen. Das Relay ist dann der einzige Pfad, über den sie überhaupt funktionieren. Durch die Deaktivierung sparen Sie nur sehr wenig Arbeitsspeicher und unterbrechen Verbindungen auf eine schwer nachvollziehbare Weise.

Wenn eine Maschine nicht mehr ausreicht, sollten Sie zuerst die Relays auslagern. Ein eigenständiges Relay läuft mit NB_LISTEN_ADDRESS, NB_EXPOSED_ADDRESS, NB_AUTH_SECRET und NB_ENABLE_STUN. Das gemeinsame Secret muss auf dem Relay und dem Hauptserver identisch sein. Andernfalls können sich Clients dort nicht authentifizieren.

Fehlerszenarien und was Sie sehen werden

Das Dashboard zeigt eine Zertifikatswarnung. Traefik hat kein Zertifikat erhalten. Führen Sie docker compose logs traefik | grep -i acme aus. Es gibt zwei Ursachen. Entweder zeigt dig +short netbird.example.com noch nicht auf diesen VPS, oder TCP 443 ist irgendwo zwischen Let's Encrypt und dem Container geschlossen, normalerweise in der Netzwerk-Firewall des Providers und nicht auf ufw. Die Challenge wird auf 443 beantwortet. Ein offener Port 80 hilft daher nicht. Beheben Sie die Ursache, bevor Sie wiederholt einen Versuch starten. Let's Encrypt erlaubt pro Hostnamen und Account nur fünf fehlgeschlagene Autorisierungen pro Stunde. Bei einer Schleife sind weitere Versuche gesperrt, bis dieses Limit wieder verfügbar ist.

Der Client meldet eine Verbindung, aber das Dashboard ist leer. Der Client hat sich beim gehosteten Dienst von NetBird registriert, weil --management-url fehlte. Führen Sie netbird status --detail aus und lesen Sie die Zeile Management:. Sie nennt den Server, mit dem der Client tatsächlich kommuniziert. Wenn Management: Connected to https://api.netbird.io:443 angezeigt wird, wurde der Cloud-Dienst verwendet. Führen Sie sudo netbird down und anschließend erneut sudo netbird up --management-url https://netbird.example.com aus.

Jeder Peer zeigt Connection type: Relayed. Es werden keine direkten Tunnel aufgebaut. Daher läuft der gesamte Datenverkehr über Ihren VPS und verursacht einen zusätzlichen Latenzsprung. Prüfen Sie UDP 3478 in der Firewall des VPS und in der Firewall des Providers. STUN ermöglicht es einem Peer, seine eigene öffentliche Adresse und seinen Port zu ermitteln. netbird status --detail gibt außerdem Direct: false und die ICE-Kandidatentypen (Interactive Connectivity Establishment) für jeden Peer aus. Daraus ist ersichtlich, wie weit der Verbindungsversuch gekommen ist. In manchen Netzwerken ist relayed das einzige verfügbare Ergebnis. Das ist kein Fehler.

Ein Peer tritt bei, kann aber nichts erreichen. Die Mitgliedschaft im Mesh bedeutet nicht, dass zwei Peers miteinander kommunizieren dürfen. Das wird durch Zugriffsrichtlinien festgelegt. Eine Gruppe ohne zugewiesene Richtlinie kann nichts erreichen. Prüfen Sie die Richtlinie im Dashboard, bevor Sie mit der Fehlersuche bei Routen und Firewalls beginnen.

netbird status meldet ein Daemon-Problem. Der Dienst läuft nicht. Verwenden Sie sudo netbird service status und sudo netbird service start. Die Client-Logs befinden sich unter /var/log/netbird/client.log. Wenn Sie etwas nicht zuordnen können, sammelt netbird debug bundle --anonymize --system-info Logs, Status, Routen, DNS-Einstellungen und den Firewall-Status in einem Archiv.

Backups und Upgrades

Für die gesamte Installation sind zwei Dinge entscheidend: das Verzeichnis mit docker-compose.yml und config.yaml sowie das Docker-Volume mit der Datenbank und den Verschlüsselungsschlüsseln. Sichern Sie beides gemeinsam. config.yaml enthält den Schlüssel, mit dem die Daten im Speicher verschlüsselt werden. Eine Datenbankkopie ohne diesen Schlüssel lässt sich nicht in lesbare Daten wiederherstellen.

docker volume ls
docker compose down
sudo tar czf netbird-config.tgz -C ~ netbird
docker run --rm -v netbird_netbird_data:/data -v "$PWD":/backup \
  alpine tar czf /backup/netbird-data.tgz -C /data .
docker compose up -d

Compose versieht Volume-Namen mit dem Verzeichnisnamen des Projekts. Das als netbird_data dokumentierte Volume erscheint daher normalerweise als netbird_netbird_data. Führen Sie zuerst docker volume ls aus und verwenden Sie den ausgegebenen Namen. Andernfalls schlägt docker run unbemerkt fehl, weil ein leeres Volume erstellt und nichts archiviert wird. Speichern Sie die Archive nicht auf dem VPS. Wenn Sie bereits ein Backup-Tool verwenden, übernimmt restic oder BorgBackup den Offsite-Teil.

Das Upgrade des Servers besteht aus einem Pull und einer Neuerstellung:

docker compose pull
docker compose up -d
docker compose ps

Bevor Sie sich darauf verlassen, führen Sie docker compose config | grep image: aus. Jeder Tag mit dem Wert latest sollte auf eine Version festgelegt werden. Das gilt aus demselben Grund wie für das Installationsskript: Sie müssen wissen, was ausgeführt wird, und eine Version zum Zurückkehren haben, falls sich ein Upgrade fehlerhaft verhält. Clients werden über den Paketmanager aktualisiert, mit dem sie installiert wurden.

FAQ

Benötige ich einen eigenen Identitätsanbieter, um NetBird selbst zu hosten?

Nein. Aktuelle Releases enthalten einen integrierten Benutzerspeicher. Sie erstellen das erste Administratorkonto im Browser unter https://netbird.example.com und fügen anschließend Benutzer über das Dashboard hinzu. Ein externer OIDC-Anbieter ist optional und kann später mit vier Werten hinzugefügt werden: Name, Client-ID, Client-Secret und Issuer. Anleitungen, die vor NetBird die Bereitstellung von Zitadel oder Keycloak verlangen, beschreiben eine Einrichtung, die nicht mehr erforderlich ist. Wenn Sie ihnen folgen, müssen Sie einen zusätzlichen Dienst betreiben.

Warum zeigen alle meine Peers Connection type: Relayed?

Direkte Verbindungen werden nicht hergestellt. Deshalb läuft der Netzwerkverkehr über das Relay auf Ihrem VPS. Die häufigste Ursache ist, dass UDP 3478 blockiert wird. Dies ist der STUN-Port, über den Peers ihre eigene öffentliche Adresse und ihren eigenen Port ermitteln. Öffnen Sie den Port in der Firewall des VPS und in der separaten Netzwerk-Firewall Ihres Anbieters. Führen Sie anschließend erneut netbird status --detail aus und lesen Sie die Zeile Direct:. Wenn sich beide Peers hinter NAT befinden, das für jedes Ziel einen anderen Port zuweist, ist relayed das erwartete Ergebnis. Die Konfiguration ist dann korrekt.

Mein Client wurde verbunden, aber im Dashboard werden keine Peers angezeigt. Was ist passiert?

Der Client hat sich beim gehosteten Dienst von NetBird statt bei Ihrem Server registriert. Das passiert, wenn --management-url nicht gesetzt ist. netbird status --detail gibt in der Zeile Management: den Server aus, mit dem der Client kommuniziert. Ein Wert wie https://api.netbird.io:443 bestätigt dies. Führen Sie sudo netbird down und anschließend sudo netbird up --management-url https://netbird.example.com aus. Danach erscheint der Peer in Ihrem Dashboard.

Worin unterscheidet sich selbst gehostetes NetBird von Headscale?

Beide ersetzen einen gehosteten Control-Server durch einen Server, den Sie selbst betreiben. Headscale ist ausschließlich eine Control Plane. Sie verwalten sie mit dem Befehl headscale und einer Konfigurationsdatei. Es gibt keine offizielle Webkonsole. Headscale steuert die offiziellen Tailscale-Clients. NetBird liefert im selben Stack einen eigenen Client, ein Administrations-Dashboard und die Integration eines Identitätsanbieters. Headscale ist kleiner im Betrieb und speichert seinen Zustand in Dateien. NetBird lässt sich einfacher an Personen übergeben, die kein Terminal verwenden.

Welche Größe muss ein VPS für einen selbst gehosteten NetBird-Server haben?

Das dokumentierte Minimum beträgt 1 CPU und 2 GB Arbeitsspeicher. 2 GB ist daher die passende Größe für den Kauf. Lehnen Sie den optionalen Proxy-Dienst während der Installation ab. Dadurch wird auch die Abfrage zu CrowdSec übersprungen. Verwenden Sie weiterhin den standardmäßigen SQLite-Speicher, bis Sie PostgreSQL tatsächlich benötigen.