OPNsense - NetBird-Plugin

Aus maxTechCorner

Auf einen Blick

Gilt fürOPNsense ab 25.7.3 mit Plugin os-netbird (Plugin-Version 1.3), NetBird Cloud oder selbst gehosteter NetBird-Server
BereichIT-Security
Dauerca. 20 Minuten (Grundeinrichtung), je Anwendungsfall weitere 10–20 Minuten
RechteAdministrator (OPNsense-WebUI und NetBird-Dashboard)
StandOktober 2026

Mit dem Plugin os-netbird wird eine OPNsense-Firewall zum vollwertigen Teilnehmer eines NetBird-Netzwerks. Die Firewall kann dann als Routing Peer ganze Standortnetze für berechtigte Benutzer erreichbar machen, Standorte untereinander koppeln, als Exit Node dienen oder selbst per NetBird administriert werden – ohne dass auf den Geräten im LAN ein NetBird-Client installiert sein muss. Das Plugin wird von den NetBird-Entwicklern selbst gepflegt und ist als Community-Plugin direkt im OPNsense-Firmware-Menü verfügbar.

Wie NetBird grundsätzlich funktioniert (Management, Signal, Relay, WireGuard-Mesh), erklärt der Artikel NetBird – Zero-Trust-Netzwerk mit WireGuard. Hier geht es um die Integration in OPNsense und die Möglichkeiten des Plugins.

Warum NetBird auf der OPNsense?

Die Firewall ist der natürliche Übergangspunkt zwischen einem Standortnetz und der Außenwelt. Läuft NetBird direkt auf der OPNsense, ergeben sich mehrere Vorteile:

  • Kein zusätzlicher Server: Die Firewall übernimmt die Rolle des Routing Peers, eine eigene VM für NetBird im LAN entfällt.
  • Geräte ohne Client erreichbar: Drucker, NAS, Telefonanlagen, Maschinensteuerungen oder alte Server werden über die Firewall in das NetBird-Netz eingebunden.
  • Doppelte Kontrolle: NetBird-Richtlinien (Wer darf auf welche Ressource?) und OPNsense-Regeln (Was darf über die Schnittstelle?) ergänzen sich – ein klassisches Defense in Depth.
  • Bekannte Werkzeuge: Logging, Live-View, Aliase, IDS/IPS und Traffic Shaping der OPNsense gelten auch für NetBird-Verkehr.
  • Ablösung klassischer VPNs: Remote-Zugänge per OpenVPN oder IPsec lassen sich schrittweise durch identitätsbasierte Zero-Trust-Zugriffe mit SSO und MFA ersetzen.

Die Möglichkeiten des NetBird-Plugins im Überblick

Anwendungsfall Was passiert Wichtige Einstellungen
Remote-Zugriff auf das LAN (VPN-to-Site) Mitarbeitende mit NetBird-Client erreichen freigegebene Server und Dienste im Firmennetz über die OPNsense. NetBird Network mit Ressourcen, OPNsense als Routing Peer, Accept Server Routes, Access LAN
Standortvernetzung (Site-to-Site) Zwei oder mehr Standorte mit je einer OPNsense werden über NetBird gekoppelt – ohne feste IP-Adressen und ohne IPsec-Tunnel-Konfiguration. Pro Standort ein Network/Routing Peer, Accept Client Routes auf der Gegenseite
Exit Node Clients leiten ihren gesamten Internetverkehr über die OPNsense, z. B. um im Hotel-WLAN geschützt zu surfen oder Webfilter zentral anzuwenden. Network Route 0.0.0.0/0 im Dashboard, Outbound-NAT auf der OPNsense
Firewall-Administration über NetBird Die WebUI bzw. SSH der OPNsense ist nur noch über das NetBird-Netz erreichbar, nicht aus dem Internet. Peer-Richtlinie Admins → OPNsense, OPNsense-Regel auf der NetBird-Schnittstelle
SSH über NetBird Der eingebaute NetBird-SSH-Server erlaubt Shell-Zugriff mit Anmeldung über den Identity Provider. Abschnitt SSH im Plugin
Post-Quantum-Schutz Rosenpass ergänzt WireGuard um einen quantensicheren Schlüsselaustausch (experimentell). Enable Rosenpass
OPNsense mit NetBird-Plugin als Routing Peer: Der Remote-Client erreicht über einen WireGuard-Tunnel nur die freigegebenen Ressourcen im Firmen-LAN; Geräte im LAN benötigen keinen eigenen Client.

Schritt 1: Plugin os-netbird installieren

  1. In OPNsense System → Firmware → Plugins öffnen.
  2. Gegebenenfalls Show community plugins aktivieren.
  3. Das Paket os-netbird suchen und über + installieren.
  4. Die Seite neu laden – das neue Menü VPN → NetBird erscheint mit den Unterpunkten Authentication, Settings, Status und Log File.


HinweisDas Plugin setzt OPNsense 25.7.3 oder neuer voraus. Halten Sie Firewall und Plugin aktuell – NetBird wird sehr aktiv weiterentwickelt, Sicherheitsupdates des Clients kommen über das Plugin-Paket.

Schritt 2: Setup-Key im NetBird-Dashboard erzeugen

  1. Im NetBird-Dashboard (Cloud oder eigener Server) Setup Keys → Create Setup Key wählen.
  2. Einen sprechenden Namen vergeben (z. B. opnsense-zentrale), den Key als wiederverwendbar nur bei Bedarf markieren und eine sinnvolle Ablaufzeit setzen.
  3. Optional eine Auto-assigned Group wie Firewalls oder Routing-Peers hinterlegen – damit landet die OPNsense direkt in der passenden Gruppe für Richtlinien.
  4. Den Key kopieren.

Schritt 3: OPNsense am NetBird-Netz anmelden

  1. VPN → NetBird → Authentication öffnen.
  2. Management URL eintragen: https://api.netbird.io:443 für NetBird Cloud bzw. die eigene Adresse, z. B. https://netbird.example.com.
  3. Den Setup Key einfügen und speichern.
  4. Unter VPN → NetBird → Settings im Abschnitt General den Haken bei Enable setzen und Apply klicken.
  5. Unter VPN → NetBird → Status prüfen, ob die Verbindung zum Management steht. Im NetBird-Dashboard taucht die Firewall nun unter Peers auf.

Schritt 4: NetBird-Schnittstelle zuweisen

Das Plugin legt die WireGuard-Schnittstelle wt0 an. Damit OPNsense-Regeln darauf greifen, wird sie als Interface zugewiesen:

  1. Interfaces → Assignments öffnen.
  2. Bei Assign a new interface als Gerät wt0 wählen, als Beschreibung NetBird eintragen und auf Add klicken.
  3. Interfaces → [NetBird] öffnen, Enable Interface und Prevent interface removal aktivieren. Keine IP-Adresse und kein Gateway eintragen – das verwaltet NetBird selbst.
  4. Save und Apply changes.


HinweisDie Schnittstelle wt0 gehört vollständig dem NetBird-Dienst. Sie darf nicht zusätzlich über das OPNsense-WireGuard-Menü (VPN → WireGuard) konfiguriert werden.

Schritt 5: Firewall-Regeln auf der NetBird-Schnittstelle

Wichtig zu wissen: NetBird-Richtlinien aus dem Dashboard erzeugen keine Regeln auf der OPNsense. Die Freigaben müssen zusätzlich unter Firewall → Rules → NetBird angelegt werden. Für erste Tests genügt eine offene Regel:

Feld Wert
Action Pass
Interface NetBird
Direction in
Protocol any
Source / Destination any

Im produktiven Betrieb sollte diese Regel durch gezielte Freigaben ersetzt werden, etwa Quelle = NetBird-Netz (100.64.0.0/10), Ziel = Alias „Server-Freigaben“, Ports 443/3389. So greift die Zugriffskontrolle doppelt: einmal im NetBird-Dashboard, einmal auf der Firewall.

Schritt 6: Direkte Verbindungen ermöglichen (Outbound-NAT mit statischem Port)

NetBird versucht immer, eine direkte Peer-to-Peer-Verbindung aufzubauen. OPNsense schreibt beim ausgehenden NAT standardmäßig die Quellports um – das erschwert das NAT-Traversal, und Verbindungen laufen dann unnötig über den Relay. Abhilfe:

  1. Firewall → NAT → Outbound öffnen.
  2. Den Modus Hybrid outbound NAT rule generation wählen.
  3. Eine manuelle Regel anlegen: Interface WAN, Protokoll UDP, Quelle This Firewall (bzw. die NetBird-Hosts), Quellport 51820 bzw. der unter WireGuard Port eingestellte Port, Option Static-port aktivieren.
  4. Speichern und anwenden.

Ob Verbindungen direkt laufen, zeigt VPN → NetBird → Status bzw. auf einem Client netbird status -d (P2P statt Relayed).

Sitzt die OPNsense selbst hinter einem Provider-Router mit öffentlicher IP, hilft die erweiterte Option Force IP Mapping (Settings → General, advanced mode): Dort kann die öffentliche IP-Adresse bzw. die Zuordnung öffentliche IP/Interface fest hinterlegt werden, z. B. 203.0.113.10/igc0.

Die Plugin-Einstellungen im Detail

Unter VPN → NetBird → Settings stehen folgende Optionen zur Verfügung (Standardwerte in Klammern):

Abschnitt Einstellung Bedeutung
General Enable (aus) Startet den NetBird-Dienst.
General WireGuard Port (51820) UDP-Port des Tunnels. Bei Änderung NAT- und ggf. WAN-Regeln anpassen.
General Force IP Mapping (leer) Feste Zuordnung externer IPs zu lokalen Adressen/Interfaces – nützlich bei vorgeschaltetem Router oder mehreren WAN-Adressen.
Client Firewall Enable Firewall (an) NetBird filtert mit seiner eigenen eingebauten Firewall und setzt die Dashboard-Richtlinien durch. Ausschalten nur, wenn alle Regeln vollständig auf der OPNsense gepflegt werden – Routing und DNS funktionieren dann eventuell nicht wie vorgesehen.
Client Firewall Block Inbound Connection (aus) Blockiert alle eingehenden Verbindungen über NetBird zur Firewall selbst und zu gerouteten Netzen. Sinnvoll, wenn die OPNsense nur als Client (z. B. für ausgehende Verbindungen) dienen soll.
SSH Enable, Enable Root Login, Enable SFTP, Enable Local/Remote Port Forwarding (alle aus) Eingebauter NetBird-SSH-Server auf der Firewall.
SSH Enable SSH Authentication (an) Erzwingt die Anmeldung über den Identity Provider (JWT). Nicht deaktivieren – sonst darf jeder Peer mit Netzwerkzugriff per SSH verbinden.
DNS Enable (an) NetBird-DNS (Peer-Namen, interne Nameserver-Gruppen) auf der Firewall nutzen.
Routing Access LAN (an) Erlaubt den Zugriff auf lokale Netze, wenn die OPNsense Routing Peer oder Exit Node ist.
Routing Accept Client Routes (an) Die OPNsense übernimmt Routen zu entfernten Netzen anderer Routing Peers – Voraussetzung für Site-to-Site.
Routing Accept Server Routes (an) Die OPNsense darf selbst als Router für Netze/Routen aus dem Dashboard arbeiten.
Post-Quantum Enable Rosenpass (aus), Rosenpass Permissive Mode (aus) Zusätzlicher quantensicherer Schlüsselaustausch (experimentell). Im Permissive-Modus sind auch Verbindungen zu Peers ohne Rosenpass erlaubt.
Syslog Logging Log Level (info) Detailtiefe der Protokollierung unter VPN → NetBird → Log File; zur Fehlersuche vorübergehend debug.

Anwendungsfall: OPNsense als Routing Peer für das Firmen-LAN

Der häufigste Einsatzzweck: Remote-Mitarbeitende sollen gezielt einzelne Dienste im LAN erreichen.

  1. Im NetBird-Dashboard Networks → Add Network wählen, z. B. Zentrale.
  2. Ressourcen hinzufügen – einzelne IPs (192.168.10.20/32), ganze Subnetze (192.168.10.0/24) oder Domains (intranet.firma.local) – und einer Ressourcengruppe wie Interne Apps zuordnen.
  3. Die OPNsense als Routing Peer für dieses Network auswählen. Masquerade bleibt aktiv – die Server im LAN sehen dann die LAN-IP der Firewall als Absender und brauchen keine Rückroute.
  4. Eine Access Policy anlegen, z. B. Gruppe Mitarbeiter → Interne Apps, TCP 443 und 3389.
  5. Auf der OPNsense unter Firewall → Rules → NetBird die passende Freigabe zum LAN-Ziel setzen.

Ergebnis: Mitarbeitende erreichen genau die freigegebenen Dienste – alles andere im LAN bleibt unsichtbar. Für Ausfallsicherheit kann ein zweiter Routing Peer (z. B. eine zweite OPNsense oder ein Linux-Server) demselben Network zugeordnet werden.

Anwendungsfall: Standortvernetzung (Site-to-Site)

Für die Kopplung zweier Standorte erhält jede OPNsense das Plugin und wird Routing Peer für das jeweils eigene LAN (eigenes Network pro Standort). Eine Policy zwischen den Gruppen der beiden Standortnetze gibt die gewünschten Verbindungen frei; Accept Client Routes muss auf beiden Firewalls aktiv sein. Damit Geräte im LAN direkt die echte Quell-IP der Gegenstelle sehen, kann Masquerade deaktiviert werden – dann sind jedoch Rückrouten nötig, und die Konfiguration wird aufwendiger. Für viele Szenarien ist der Betrieb mit Masquerade die einfachere und robustere Variante.

Gegenüber einem klassischen IPsec-Tunnel entfällt die Pflege von Phase-1/Phase-2-Parametern, und auch Standorte ohne feste öffentliche IP-Adresse (DSL, LTE/5G, CGNAT) lassen sich koppeln.

Anwendungsfall: OPNsense als Exit Node

Exit Nodes werden in NetBird weiterhin über Network Routes abgebildet:

  1. Im Dashboard Network Routes → Add Route wählen, als Netz 0.0.0.0/0 eintragen und die OPNsense als Routing Peer auswählen.
  2. Die Gruppen festlegen, deren Internetverkehr über die Firewall laufen soll.
  3. Auf der OPNsense unter Firewall → NAT → Outbound (Hybrid-Modus) eine Regel anlegen, die Verkehr mit Quelle NetBird net bzw. 100.64.0.0/10 auf die WAN-Adresse übersetzt.
  4. Unter Firewall → Rules → NetBird den Verkehr ins Internet erlauben – auf Wunsch kombiniert mit Webfilter oder IDS/IPS.

Sicherheitsempfehlungen für den Betrieb

  • Doppelte Freigaben bewusst gestalten: Die offene Testregel auf der NetBird-Schnittstelle nach der Einrichtung durch gezielte Regeln ersetzen und im Dashboard die Default-Policy deaktivieren.
  • Setup-Keys begrenzen: Einmal-Keys mit Ablaufdatum verwenden und nach der Anmeldung im Dashboard widerrufen.
  • WebUI nicht ins Internet: Die OPNsense-Administration nur noch über LAN oder NetBird erlauben.
  • SSH-Authentifizierung aktiv lassen und Root-Login nur bei Bedarf freigeben.
  • Protokolle auswerten: Das NetBird-Log der OPNsense und die Activity-Events des Dashboards an ein zentrales SIEM weiterleiten, z. B. ein Open-Source-SIEM auf Wazuh-Basis.
  • Hochverfügbarkeit beachten: In CARP-Clustern muss vorab geklärt werden, wie sich der NetBird-Dienst bei einem Failover verhält; alternativ mehrere Routing Peers im NetBird-Network einsetzen.

Fehlerbehebung

Symptom Mögliche Ursache und Lösung
Peer erscheint nicht im Dashboard Management URL oder Setup Key falsch bzw. abgelaufen; ausgehende Verbindung zu TCP 443 der Management-URL prüfen; Log File kontrollieren.
Verbindungen laufen nur über Relayed Outbound-NAT ohne Static-port; UDP-Port blockiert; ggf. Force IP Mapping setzen.
Clients erreichen das LAN nicht Keine Pass-Regel auf der NetBird-Schnittstelle; Policy im Dashboard fehlt; Access LAN oder Accept Server Routes deaktiviert.
Peer-Namen werden nicht aufgelöst DNS im Plugin deaktiviert oder Konflikt mit Unbound-Einstellungen; Nameserver-Gruppen im Dashboard prüfen.
Schnittstelle wt0 fehlt nach Neustart Dienst nicht aktiviert (Enable) oder Plugin veraltet – Plugin aktualisieren und Interface-Zuweisung prüfen.

Fazit

Mit dem Plugin os-netbird wird die OPNsense zum zentralen Baustein eines Zero-Trust-Netzwerks: Sie verbindet Remote-Mitarbeitende identitätsbasiert mit genau den Diensten, die sie benötigen, koppelt Standorte ohne IPsec-Aufwand und bleibt dabei Herr über jede Verbindung. Wer die Grundregeln beachtet – Schnittstelle zuweisen, Regeln gezielt setzen, statischen Port für direkte Verbindungen – erhält eine schlanke und gut kontrollierbare Alternative zu klassischen Remote-Access-VPNs.

Unterstützung von m.a.x. it

Sie möchten NetBird auf Ihren OPNsense-Firewalls einführen oder bestehende OpenVPN- und IPsec-Zugänge auf Zero Trust umstellen? m.a.x. it unterstützt Sie als OPNsense-Gold-Partner mit OPNsense-Firewall-Services von m.a.x. it sowie einer Managed Firewall von m.a.x. it.

Siehe auch

Links und Quellen


Über m.a.x. it Die m.a.x. Informationstechnologie AG ist seit über 30 Jahren IT-Partner mittelständischer und großer Unternehmen in München und bietet maßgeschneiderte Lösungen und Services in den Bereichen Cloud, Cybersecurity, Netzwerk, Windows, Linux und Softwareentwicklung. Sie haben eine Frage zu diesem Artikel oder brauchen Unterstützung? Kontakt aufnehmen

Abgerufen von „http://techcorner.max-it.de/index.php?title=OPNsense_-_NetBird-Plugin&oldid=3786“