02 – Pflichtenheft NetBird

02.1 – Zielarchitektur
Zielarchitektur NetBird
Ziel
Die bestehenden einzeln administrierten WireGuard-Verbindungen werden durch eine zentral verwaltete, selbstgehostete NetBird-Infrastruktur ersetzt. NetBird übernimmt Overlay-Vernetzung, Peer-Verwaltung, Gruppen, Policies und die kontrollierte Veröffentlichung der Standortnetze.
Für neue Site-to-Site-Konfigurationen ist das aktuelle NetBird-Modell Networks / Network Resources / Routing Peers zu verwenden. Die älteren 
Routes gelten für neue Site-to-Site-Implementierungen nicht als bevorzugtes Modell.
Architekturprinzip
Die OPNsense bleibt an jedem Standort Internet-Gateway, lokale Firewall, VLAN-Router und gegebenenfalls DHCP-/Routinginstanz. NetBird ersetzt nicht die Standortfirewall.
Pro Standort wird mindestens ein dedizierter Linux-Routing-Peer vorgesehen. Dieser besitzt Zugriff auf die lokalen Netze, die über NetBird veröffentlicht werden sollen. Für produktionskritische Standorte soll geprüft werden, zwei Routing-Peers auf unterschiedlichen Virtualisierungs-/Hardware-Fehlerdomänen einzusetzen.
Die NetBird-Control-Plane wird selbst gehostet und über einen öffentlichen DNS-Namen mit TLS erreichbar gemacht. Relay-Funktionalität ist insbesondere für Roadwarrior und HomeOffice vorzusehen, wenn keine direkte Peer-to-Peer-Verbindung möglich ist.
Wesentliche Designentscheidung
Für normales Site-to-Site-Routing wird zunächst Masquerading auf den Linux-Routing-Peers vorgesehen. Dies entspricht dem aktuellen NetBird-Site-to-Site-Modell und vermeidet zusätzliche Rückrouten in allen Standortnetzen. Wo Quell-IP-Transparenz zwingend erforderlich ist, muss dies separat bewertet werden, da die Deaktivierung von Masquerading zusätzliche Rückrouten benötigt und Auswirkungen auf Hochverfügbarkeit hat.

02.2 – Schaubild Zielarchitektur
Schaubild – Zielarchitektur
flowchart TB
    CP["Self-hosted NetBird<br/>Management / Signal / Relay<br/>öffentlicher DNS + TLS"]
    subgraph MT["Lathen – Mühlentannen"]
      FWMT["OPNsense"]
      RPMT["Linux NetBird Routing Peer"]
      LANMT["Daten-LAN<br/>192.168.110.0/23"]
      VOMT["Voice-VLAN<br/>TBD / OmniPCX"]
      FWMT --- RPMT
      RPMT --- LANMT
      RPMT --- VOMT
    end
    subgraph BF["Bahnhofstraße – Übergangsphase"]
      FWBF["OPNsense"]
      RPBF["Linux NetBird Routing Peer"]
      NETBF["LAN + Voice<br/>TBD"]
      FWBF --- RPBF --- NETBF
    end
    subgraph GS["Gartenstraße – Übergangsphase"]
      FWGS["OPNsense"]
      RPGS["Linux NetBird Routing Peer"]
      NETGS["LAN + Voice<br/>TBD"]
      FWGS --- RPGS --- NETGS
    end
    subgraph NO["Barsbüttel"]
      FWNO["OPNsense"]
      RPNO["Linux NetBird Routing Peer"]
      NETNO["LAN 192.168.104.0/24<br/>+ Voice-VLAN"]
      FWNO --- RPNO --- NETNO
    end
    subgraph SU["Heppenheim"]
      FWSU["OPNsense"]
      RPSU["Linux NetBird Routing Peer"]
      NETSU["LAN 192.168.0.0/24<br/>+ Voice-VLAN"]
      FWSU --- RPSU --- NETSU
    end
    HO["HomeOffice-PCs<br/>NetBird Client"]
    RW["Tablets / Roadwarrior<br/>NetBird Client"]
    CP -. "Steuerung / Vermittlung" .- RPMT
    CP -.-> RPBF
    CP -.-> RPGS
    CP -.-> RPNO
    CP -.-> RPSU
    CP -.-> HO
    CP -.-> RW
    RPMT <-->|"verschlüsseltes NetBird Overlay"| RPBF
    RPMT <-->|"verschlüsseltes NetBird Overlay"| RPGS
    RPMT <-->|"verschlüsseltes NetBird Overlay"| RPNO
    RPMT <-->|"verschlüsseltes NetBird Overlay"| RPSU
    HO <-->|"NetBird Overlay"| RPMT
    RW <-->|"NetBird Overlay"| RPMT
Die Control-Plane liegt nicht im Nutzdatenpfad einer erfolgreichen direkten Peer-Verbindung. Wo direkte Verbindungen nicht möglich sind, muss Relay-Verkehr berücksichtigt werden.

02.3 – Funktionale Anforderungen
Funktionale Anforderungen
Muss-Anforderungen
ID
Anforderung
Abnahmekriterium
F-001
NetBird muss vollständig selbst gehostet betrieben werden.
Management und erforderliche Vermittlungs-/Relay-Dienste laufen unter eigener administrativer Kontrolle.
F-002
Alle fünf derzeit relevanten Standorte müssen während der Übergangsphase gekoppelt werden können.
Gegenseitige Erreichbarkeit der freigegebenen Testressourcen.
F-003
Standort-LANs müssen ohne NetBird-Agent auf jedem Endgerät erreichbar sein.
Routing über lokale Linux-Routing-Peers funktioniert.
F-004
Voice-VLANs müssen standortübergreifend transportiert werden können.
Erfolgreiche OmniPCX- und Sprachtests.
F-005
Roadwarrior-Tablets müssen gezielt auf freigegebene Ressourcen zugreifen können.
Zugriff entsprechend Policy; nicht freigegebene Ressourcen bleiben gesperrt.
F-006
HomeOffice-Arbeitsplätze müssen über NetBird angebunden werden.
Client verbindet sich und erhält ausschließlich definierte Zugriffe.
F-007
Gruppenbasierte Zugriffspolitik muss möglich sein.
Testnutzer verschiedener Gruppen erhalten unterschiedliche Berechtigungen.
F-008
Standortnetze und Voice-Netze müssen logisch getrennt administrierbar sein.
Separate Network Resources/Resource Groups und Policies vorhanden.
F-009
Der Ausfall eines Remote-Clients darf keine Standortverbindung beeinflussen.
Standort-Routing bleibt unabhängig von Client-Peers verfügbar.
F-010
Bestehendes WireGuard muss während der Migration parallel betreibbar bleiben.
Pilotbetrieb ohne sofortige Abschaltung der Alt-Tunnel.
F-011
Die Lösung muss den späteren Wegfall Bahnhofstraße und Gartenstraße ohne Neuaufbau der Gesamtarchitektur ermöglichen.
Standorte können durch Entfernen ihrer Ressourcen/Peers sauber stillgelegt werden.
F-012
Änderungen müssen nachvollziehbar dokumentiert werden.
Konfigurations- und Änderungsdokumentation vorhanden.
Soll-Anforderungen
Zwei Routing-Peers für besonders kritische Standortnetze, soweit technisch und wirtschaftlich sinnvoll.
Zentrale Anmeldung über den vorhandenen Unternehmens-Identity-Provider, sofern mit der gewählten Self-hosted-Konfiguration vorgesehen.
Automatisierte Sicherung der NetBird-Konfiguration und der zugrunde liegenden persistenten Daten.
Monitoring von Control-Plane, Relay und Routing-Peers.
Benennungskonventionen für Peers, Gruppen, Networks und Resources.
Zeitlich begrenzte Setup Keys für automatisierte bzw. unbeaufsichtigte Routing-Peer-Registrierung.

02.4 – Routing- und Policy-Konzept
Routing- und Policy-Konzept
Grundsatz
NetBird wird nicht als flaches VPN aufgebaut. Zugriffe werden nach Funktion, Standort und Geräteklasse getrennt.
Vorgesehene Gruppen
site-lathen-muehlentannen-router
site-lathen-bahnhof-router
site-lathen-garten-router
site-barsbuettel-router
site-heppenheim-router
clients-homeoffice
clients-roadwarrior
resources-data
resources-voice
optional weitere fachliche Benutzer-/Gerätegruppen
Networks und Resources
Pro Standort soll mindestens ein logisch abgegrenztes Network angelegt werden. Daten-LAN und Voice-VLAN werden als getrennte Ressourcen geführt. Damit können Policies für Telefonie unabhängig von normalen Standortzugriffen gepflegt werden.
Policy-Grundsätze
Default-Deny als Zielzustand.
Site-to-Site nur für tatsächlich benötigte Netze.
Voice-Verkehr ausschließlich zwischen den benötigten Voice-Ressourcen und OmniPCX-Komponenten.
Roadwarrior erhalten keinen pauschalen Zugriff auf komplette Standortnetze.
HomeOffice-Zugriffe werden nach benötigten Diensten bzw. Ressourcengruppen freigegeben.
Administrative Netze und Managementoberflächen erhalten eigene restriktive Regeln.
Änderungen an Policies müssen dokumentiert und getestet werden.
Masquerading
Für die erste Site-to-Site-Implementierung wird Masquerading auf Linux-Routing-Peers verwendet. Dadurch sehen Zielsysteme grundsätzlich die LAN-Adresse des lokalen Routing-Peers als Quelle. Für Systeme, bei denen die tatsächliche Client-/Overlay-IP benötigt wird, ist eine gesonderte technische Entscheidung erforderlich.

02.5 – Telefonie-Konzept
Telefonie-Konzept
Ziel
Die bestehende OmniPCX-Topologie muss über NetBird mindestens dieselbe funktionale Konnektivität erhalten wie über die heutigen WireGuard-Tunnel.
Umsetzung
Jedes Voice-VLAN wird als eigene NetBird-Netzressource dokumentiert und veröffentlicht. Der lokale Linux-Routing-Peer muss das Voice-VLAN über die lokale Routing-Infrastruktur erreichen können. Die OPNsense bleibt für die lokale Segmentierung verantwortlich.
Vor Freigabe werden die tatsächlich benötigten Verbindungen anhand der OmniPCX-Konfiguration und Paketmitschnitten der bestehenden WireGuard-Verbindungen ermittelt. Es werden keine pauschalen 
ANY-ANY-Freigaben als Dauerlösung vorgesehen.
Abnahmetests Telefonie
Registrierung bzw. Status aller abgesetzten OmniPCX-Komponenten
interne Telefonate Standort ↔ Hauptstandort
Telefonate zwischen Niederlassungen
eingehende und ausgehende Gespräche entsprechend der bestehenden Telefoniearchitektur
Rufaufbauzeit
bidirektionales Audio
Halten, Rückfrage und Vermitteln
längere Gespräche
mehrere parallele Gespräche
Neustart einer Außenstelle
Ausfall und Wiederherstellung des NetBird-Pfades
Messung von Latenz, Jitter und Paketverlust
Prüfung auf MTU-/Fragmentierungsprobleme

02.6 – Remote Access
HomeOffice und Roadwarrior
HomeOffice
Auf verwalteten HomeOffice-Arbeitsplätzen wird der NetBird-Client installiert. Die Geräte werden einer eigenen Gruppe zugeordnet. Der Zugriff erfolgt nicht über eine pauschale Standort-Vollroute, sondern über definierte Ressourcen und Policies.
Roadwarrior / Tablets
Tablets und andere mobile Geräte werden als eigene Geräteklasse behandelt. Aufgrund wechselnder Netze, Carrier-NAT und restriktiver WLANs ist die Relay-Funktion für diese Geräte betriebsrelevant.
Sicherheitsanforderungen
eindeutige Gerätezuordnung
Entzug eines Gerätes muss zentral möglich sein
Gruppenmitgliedschaften nach dem Least-Privilege-Prinzip
keine pauschale Erreichbarkeit der Voice-VLANs durch Roadwarrior
administrative Zugriffe nur für explizit berechtigte Geräte/Benutzer
Prüfung von Posture Checks für verwaltete Endgeräte, soweit für die eingesetzten Plattformen sinnvoll

02.7 – Migration und Abnahme
Migration und Abnahme
Phase 1 – Inventarisierung
Alle LANs, VLANs, Gateways, WireGuard-Tunnel, AllowedIPs, Firewallregeln und Telefonie-Kommunikationsbeziehungen werden aufgenommen. Fehlende 
TBD-Werte dieses Dokuments werden ersetzt.
Phase 2 – NetBird-Control-Plane
Self-hosted NetBird wird produktionsnah aufgebaut, mit öffentlichem DNS, TLS, Relay-Funktion, Backup und Monitoring.
Phase 3 – Pilot
Ein nicht kritischer Standort bzw. ein abgegrenztes Testnetz wird parallel zum bestehenden WireGuard angebunden. Datenverkehr und Policies werden validiert.
Phase 4 – Standortmigration
Die Standorte werden einzeln migriert. Der bestehende WireGuard-Tunnel bleibt je Standort zunächst als Rückfallweg vorhanden, darf aber nicht gleichzeitig konkurrierende aktive Routen erzeugen.
Phase 5 – Telefonie
Voice-Ressourcen werden zunächst parallel getestet. Die Altverbindung wird erst entfernt, wenn Signalisierung und Sprachpfade nachweislich stabil funktionieren.
Phase 6 – HomeOffice und Roadwarrior
Clients werden gruppenweise migriert. Bestehender WireGuard-Remote-Access bleibt bis zum erfolgreichen Abschluss als Rückfalloption erhalten.
Phase 7 – Abschaltung Altbestand
Direkte WireGuard-Tunnel und der bisherige Remote-Access-WireGuard-Server werden erst nach dokumentierter Abnahme und definierter Beobachtungsphase außer Betrieb genommen.
Abbruchkriterien
Die Migration eines Standortes wird zurückgerollt bei:
instabiler OmniPCX-Kommunikation
reproduzierbaren Audiofehlern
nicht erklärbaren Routing-Loops
unzulässigem Zugriff zwischen Sicherheitszonen
erheblichem Paketverlust oder nicht akzeptabler zusätzlicher Latenz
fehlender Rückfallmöglichkeit

02.8 – Betriebs- und Dokumentationsanforderungen
Betrieb und Dokumentation
Für alle Komponenten sind Soll-Konfiguration und Abweichungen vom Standard zu dokumentieren. Bei jeder Abweichung ist nicht nur die technische Änderung, sondern ausdrücklich auch der Grund für die Abweichung festzuhalten.
Zu dokumentieren sind mindestens:
NetBird-Versionen
Hostsysteme der Control-Plane
öffentliche DNS-Namen und Zertifikatsverfahren
verwendete Ports
Relay-Konfiguration
Backup- und Restore-Verfahren
Routing-Peers inklusive Standort, IP und Fehlerdomäne
Networks, Resources und Resource Groups
Peer-/Benutzergruppen
Policies
Setup Keys und deren Verwendungszweck, jedoch keine geheimen Schlüsselwerte
lokale OPNsense-Routen und Firewallregeln
Voice-VLANs und OmniPCX-Kommunikationsmatrix
Monitoring und Alarmierung
Notfall-/Rollback-Verfahren
Änderungsprotokoll