NetBird Mesh-VPN
Self-hosted Zero-Trust Mesh-VPN auf WireGuard-Basis. Einfache Verwaltung, automatische Peer-Erkennung, Web-Dashboard.
🤔 Was ist NetBird?
NetBird ist eine Open-Source Mesh-VPN-Loesung, die auf WireGuard aufbaut. Im Gegensatz zu klassischem WireGuard muss man keine Keys manuell verteilen oder Peer-Konfigurationen pflegen - NetBird uebernimmt das automatisch.
Vorteile gegenueber WireGuard pur
- ✓ Automatische Peer-Erkennung
- ✓ Kein manuelles Key-Management
- ✓ Web-Dashboard zur Verwaltung
- ✓ Setup Keys fuer einfaches Onboarding
- ✓ Access Control Lists (ACLs)
- ✓ Netzwerk-Routen & DNS-Management
Architektur
- Management Server: Koordination & Config
- Signal Server: Peer-Vermittlung
- STUN/Relay: NAT-Traversal & Fallback
- Dashboard: Web-UI zur Verwaltung
- Clients: WireGuard-Tunnel (Peers)
Zero-Trust Networking
NetBird implementiert ein Zero-Trust Modell: Geraete muessen sich authentifizieren, bevor sie Zugriff auf das Netzwerk erhalten. Standardmaessig koennen Peers miteinander kommunizieren - ueber ACLs kann der Zugriff granular eingeschraenkt werden.
🏗️ Self-Hosted Architektur
NetBird laeuft self-hosted als Docker-Compose Stack mit vier Services.
| Service | Funktion | Protokoll |
|---|---|---|
| Dashboard | Web-UI fuer Verwaltung | HTTPS |
| Management | API & Konfiguration | HTTPS (REST + gRPC) |
| Signal | Peer-Discovery & Signaling | gRPC |
| Relay/STUN | NAT-Traversal & Fallback-Relay | UDP (STUN), HTTPS (Relay) |
Client A Server Client B
| | |
|--- Authentifizierung --->| |
| |<--- Authentifizierung ---|
| | |
|<-- Peer-Info (B) --------|-------- Peer-Info (A) -->|
| | |
|========= WireGuard-Tunnel (Peer-to-Peer) =========|
| (oder via Relay bei NAT) |Reverse Proxy empfohlen
Fuer den Zugriff von aussen empfiehlt sich ein Reverse Proxy (z.B. Nginx Proxy Manager) vor dem NetBird-Stack. So werden Dashboard, Management API, Signal und gRPC ueber eine einzige Domain mit SSL-Terminierung erreichbar.
💻 Client einrichten
NetBird-Clients sind fuer alle Plattformen verfuegbar. Die Einrichtung erfolgt ueber Setup Keys - kein manuelles Key-Management noetig.
# NetBird installieren
curl -fsSL https://pkgs.netbird.io/install.sh | sh
# Mit Setup Key verbinden
netbird up \
--setup-key DEIN_SETUP_KEY \
--management-url https://vpn.example.com
# Status pruefen
netbird status
# Verbundene Peers anzeigen
netbird status --detail
# 1. Download von https://netbird.io/download
# 2. Installieren und starten
# 3. In den Settings:
# Management URL: https://vpn.example.com
# 4. Setup Key eingeben und verbinden
# Alternativ per CLI (Windows PowerShell / macOS Terminal):
netbird up --setup-key DEIN_SETUP_KEY --management-url https://vpn.example.com
Android
- 1. "NetBird" aus dem Play Store installieren
- 2. Settings: Management URL eintragen
- 3. Setup Key eingeben
- 4. Verbinden
iOS
- 1. "NetBird" aus dem App Store installieren
- 2. Settings: Management URL eintragen
- 3. Setup Key eingeben
- 4. Verbinden
Setup Keys
Setup Keys werden im Dashboard unter "Setup Keys" erstellt. Sie koennen einmalig oder wiederverwendbar (Reusable) sein, mit einem Ablaufdatum und einer maximalen Anzahl an Peers konfiguriert werden.
📊 Dashboard & Verwaltung
Das NetBird Dashboard bietet eine uebersichtliche Web-Oberflaeche fuer die Verwaltung aller Peers, Routen und Zugriffsregeln.
Peers
Alle verbundenen Geraete mit Status, IP, OS und letzter Aktivitaet. Peers koennen Gruppen zugewiesen und einzeln verwaltet werden.
Setup Keys
Erstelle und verwalte Setup Keys fuer das Onboarding neuer Geraete. Einmalig oder wiederverwendbar, mit Ablaufdatum und Peer-Limit.
Access Control
Definiere Zugriffsregeln zwischen Peer-Gruppen. Standardmaessig: Alle duerfen mit allen kommunizieren. Kann granular eingeschraenkt werden.
Netzwerk-Routen
Definiere Routen, damit Peers auf lokale Netzwerke hinter einem "Routing Peer" zugreifen koennen - z.B. Zugriff auf das Heim-/Buero-LAN von unterwegs.
Embedded IdP
Die Self-Hosted-Version nutzt standardmaessig einen eingebetteten Identity Provider (Dex). Login erfolgt ueber das Dashboard mit Benutzername/Passwort. Externe IdPs (OIDC) koennen ebenfalls angebunden werden.
🔀 Routen & LAN-Zugriff
Mit Netzwerk-Routen koennen Remote-Peers auf lokale Netzwerke zugreifen, die hinter einem "Routing Peer" liegen.
Remote Laptop (100.x.x.10)
|
+--- NetBird Tunnel
|
Routing Peer (100.x.x.1) im Heim-Netz
|
+--- Route: 192.168.0.0/24 (Masquerading)
|
Heim-Server (192.168.0.50)
NAS (192.168.0.60)
Drucker (192.168.0.70)
Route einrichten (Dashboard)
- 1. Dashboard → Network Routes → Add Route
- 2. Network Range: z.B.
192.168.0.0/24 - 3. Routing Peer: Das Geraet im Zielnetzwerk auswaehlen
- 4. Masquerade: Aktivieren (empfohlen)
- 5. Peer Groups: Welche Gruppen Zugriff erhalten
Masquerading aktivieren
Ohne Masquerading muessen alle Geraete im Zielnetzwerk eine Rueckroute zum NetBird-Subnetz kennen. Mit Masquerading sieht der Traffic so aus, als kaeme er vom Routing Peer selbst - deutlich einfacher zu konfigurieren.
DNS-Management
NetBird kann DNS-Eintraege fuer Peers verwalten. Damit erreichst du Geraete
ueber Namen statt IPs - z.B. mein-server.netbird.cloud.
Konfigurierbar im Dashboard unter "DNS".
📋 Voraussetzungen Self-Hosting
Was du brauchst, um NetBird self-hosted zu betreiben.
Server-Anforderungen
- CPU: 2 Cores
- RAM: 2 GB
- Storage: 10 GB
- OS: Linux (Debian, Ubuntu, etc.)
- Docker: Docker + Docker Compose
Netzwerk-Anforderungen
- Domain: z.B. vpn.example.com
- SSL: Let's Encrypt (via Reverse Proxy)
- Port 443: HTTPS (Management, Dashboard)
- Port 3478: UDP (STUN/Relay)
- Reverse Proxy: Empfohlen (z.B. NPM)
# NetBird besteht aus 4 Services:
# - netbird-dashboard (Web-UI)
# - netbird-management (API & Config)
# - netbird-signal (Peer Discovery)
# - netbird-relay (STUN/Relay)
# Verwaltet ueber:
# docker-compose.yml - Service-Definitionen
# management.json - Server-Konfiguration (STUN, Relay, IdP)
# dashboard.env - Dashboard-Umgebungsvariablen
# relay.env - Relay/STUN-Konfiguration
# Status aller Services
docker compose ps
# Logs eines Services anzeigen
docker compose logs --tail=50 management
# Alle Services neustarten
docker compose restart
# Update auf neueste Version
docker compose pull && docker compose up -d
Secrets sichern!
Die Konfigurationsdateien enthalten Secrets (Relay Auth Secret, Encryption Key). Diese muessen sicher gespeichert und gebackupt werden - ohne den Encryption Key sind die Management-Daten nicht wiederherstellbar.
🌍 Port-Forwarding & DNS
Damit Clients von aussen verbinden koennen, muessen bestimmte Ports und DNS-Eintraege konfiguriert werden.
| Port | Protokoll | Beschreibung |
|---|---|---|
| 443 | TCP | HTTPS (Dashboard, Management API, Signal, gRPC) |
| 3478 | UDP | STUN/Relay (NAT-Traversal) |
# Oeffentlicher DNS (bei deinem Domain-Provider)
vpn.example.com → A-Record → Deine oeffentliche IP
# Interner DNS (optional, fuer lokalen Zugriff)
vpn.example.com → A-Record → IP deines Reverse Proxy
Reverse Proxy Setup
Der Reverse Proxy leitet Anfragen basierend auf URL-Pfaden an die richtigen Services weiter. Wichtig: HTTP/2 und WebSockets aktivieren, da gRPC (fuer Signal) HTTP/2 benoetigt.
🔧 Troubleshooting
# Verbindungsstatus
netbird status
# Detaillierter Status mit allen Peers
netbird status --detail
# Debug-Logs aktivieren
netbird up --log-level debug
# Client neustarten
netbird down && netbird up
# NetBird-Interface pruefen
ip a show wt0 # Linux
ifconfig utun100 # macOS
# Container-Status pruefen
docker compose ps
# Logs der einzelnen Services
docker compose logs --tail=50 management
docker compose logs --tail=50 signal
docker compose logs --tail=50 relay
# Management API testen
curl -s https://vpn.example.com/api/
| Problem | Loesung |
|---|---|
| Dashboard nicht erreichbar | Reverse Proxy pruefen, SSL-Zertifikat gueltig? Browser-Cache / HSTS leeren |
| Client verbindet nicht | Management URL pruefen, Setup Key gueltig? Port 443 von aussen erreichbar? |
| Peers sehen sich nicht | Signal-Service pruefen, gRPC via HTTP/2 aktiviert? ACLs pruefen |
| Routen funktionieren nicht | Routing Peer online? Masquerading aktiviert? IP-Forwarding auf dem Routing Peer |
| Langsame Verbindung | STUN-Port (3478/UDP) offen? Ohne STUN wird Relay genutzt (langsamer) |
Browser-Cache bei SSL-Problemen
Nach fehlgeschlagenen SSL-Verbindungen kann der Browser HSTS-Eintraege cachen, die den Zugriff blockieren. Loesung: Private Browsing nutzen oder den HSTS-Cache manuell loeschen.
⚖️ NetBird vs. WireGuard pur
Wann NetBird, wann reines WireGuard?
NetBird waehlen wenn:
- ✓ Mehrere Geraete/Peers verwaltet werden
- ✓ Einfaches Onboarding gewuenscht ist
- ✓ Web-Dashboard fuer Verwaltung gebraucht wird
- ✓ ACLs und Gruppen benoetigt werden
- ✓ NAT-Traversal ohne manuelle Config noetig
WireGuard pur waehlen wenn:
- ✓ Nur 2-3 feste Peers (z.B. Site-to-Site)
- ✓ Maximale Einfachheit (kein Management-Server)
- ✓ Minimaler Ressourcenverbrauch gewuenscht
- ✓ Volle Kontrolle ueber jeden Parameter
- ✓ Eingebettet in Firewall (z.B. OPNsense)
Kombination moeglich
NetBird und WireGuard pur koennen parallel betrieben werden. NetBird fuer den komfortablen Remote-Zugriff, WireGuard pur fuer Site-to-Site Verbindungen ueber die Firewall.
Mesh-VPN gewuenscht?
Wir richten NetBird self-hosted fuer dich ein - von der Installation bis zum Peer-Management.
Beratung anfragen →