imported>TechCorner-Redaktion: Neuer Artikel: NetBird-Plugin (os-netbird) für OPNsense, Stand 10/2026

2026-10-05T00:00:00Z

Neuer Artikel: NetBird-Plugin (os-netbird) für OPNsense, Stand 10/2026

Neue Seite

{{Steckbrief
| gilt_fuer = OPNsense ab 25.7.3 mit Plugin os-netbird (Plugin-Version 1.3), NetBird Cloud oder selbst gehosteter NetBird-Server
| bereich = IT-Security
| dauer = ca. 20 Minuten (Grundeinrichtung), je Anwendungsfall weitere 10–20 Minuten
| rechte = Administrator (OPNsense-WebUI und NetBird-Dashboard)
| stand = Oktober 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 ==
{| class="wikitable"
! 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 <code>0.0.0.0/0</code> 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''
|}

[[Datei:OPNsense-NetBird-Routing-Peer.png|thumb|center|700px|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 ==
# In OPNsense '''System → Firmware → Plugins''' öffnen.
# Gegebenenfalls '''Show community plugins''' aktivieren.
# Das Paket '''os-netbird''' suchen und über '''+''' installieren.
# Die Seite neu laden – das neue Menü '''VPN → NetBird''' erscheint mit den Unterpunkten ''Authentication'', ''Settings'', ''Status'' und ''Log File''.

{{Hinweis|Das 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 ==
# Im NetBird-Dashboard (Cloud oder eigener Server) '''Setup Keys → Create Setup Key''' wählen.
# Einen sprechenden Namen vergeben (z. B. ''opnsense-zentrale''), den Key als '''wiederverwendbar''' nur bei Bedarf markieren und eine sinnvolle Ablaufzeit setzen.
# Optional eine '''Auto-assigned Group''' wie ''Firewalls'' oder ''Routing-Peers'' hinterlegen – damit landet die OPNsense direkt in der passenden Gruppe für Richtlinien.
# Den Key kopieren.

== Schritt 3: OPNsense am NetBird-Netz anmelden ==
# '''VPN → NetBird → Authentication''' öffnen.
# '''Management URL''' eintragen: <code><nowiki>https://api.netbird.io:443</nowiki></code> für NetBird Cloud bzw. die eigene Adresse, z. B. <code><nowiki>https://netbird.example.com</nowiki></code>.
# Den '''Setup Key''' einfügen und speichern.
# Unter '''VPN → NetBird → Settings''' im Abschnitt ''General'' den Haken bei '''Enable''' setzen und '''Apply''' klicken.
# 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:
# '''Interfaces → Assignments''' öffnen.
# Bei ''Assign a new interface'' als Gerät '''wt0''' wählen, als Beschreibung '''NetBird''' eintragen und auf '''Add''' klicken.
# '''Interfaces → [NetBird]''' öffnen, '''Enable Interface''' und '''Prevent interface removal''' aktivieren. '''Keine''' IP-Adresse und kein Gateway eintragen – das verwaltet NetBird selbst.
# '''Save''' und '''Apply changes'''.

{{Hinweis|Die 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:

{| class="wikitable"
! 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:
# '''Firewall → NAT → Outbound''' öffnen.
# Den Modus '''Hybrid outbound NAT rule generation''' wählen.
# 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.
# Speichern und anwenden.

Ob Verbindungen direkt laufen, zeigt '''VPN → NetBird → Status''' bzw. auf einem Client <code>netbird status -d</code> (''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. <code>203.0.113.10/igc0</code>.

== Die Plugin-Einstellungen im Detail ==
Unter '''VPN → NetBird → Settings''' stehen folgende Optionen zur Verfügung (Standardwerte in Klammern):

{| class="wikitable"
! 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.
# Im NetBird-Dashboard '''Networks → Add Network''' wählen, z. B. ''Zentrale''.
# '''Ressourcen''' hinzufügen – einzelne IPs (<code>192.168.10.20/32</code>), ganze Subnetze (<code>192.168.10.0/24</code>) oder Domains (<code>intranet.firma.local</code>) – und einer Ressourcengruppe wie ''Interne Apps'' zuordnen.
# 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.
# Eine '''Access Policy''' anlegen, z. B. Gruppe ''Mitarbeiter'' → ''Interne Apps'', TCP 443 und 3389.
# 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:
# Im Dashboard '''Network Routes → Add Route''' wählen, als Netz <code>0.0.0.0/0</code> eintragen und die OPNsense als Routing Peer auswählen.
# Die Gruppen festlegen, deren Internetverkehr über die Firewall laufen soll.
# Auf der OPNsense unter '''Firewall → NAT → Outbound''' (Hybrid-Modus) eine Regel anlegen, die Verkehr mit Quelle ''NetBird net'' bzw. <code>100.64.0.0/10</code> auf die WAN-Adresse übersetzt.
# 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 [https://www.max-it.de/it-services/siem-open-source/ 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 ==
{| class="wikitable"
! 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 [https://www.max-it.de/it-services/opnsense/ OPNsense-Firewall-Services von m.a.x. it] sowie einer [https://www.max-it.de/it-services/managed-firewall/ Managed Firewall von m.a.x. it].

== Siehe auch ==
* [[NetBird – Zero-Trust-Netzwerk mit WireGuard]]
* [[OPNsense - Plugin-Liste]]
* [[OPNsense - Eine kurze Einführung]]
* [[OPNsense - NAT before IPSEC]]
* [[VPN Techniken für das Homeoffice]]
* [[WireGuard]]
* [[Zero Trust]]
* [[Source NAT]]

== Links und Quellen ==
* [https://docs.opnsense.org/manual/how-tos/netbird.html OPNsense-Doku – NetBird Plugin Setup Guide]
* [https://docs.netbird.io/get-started/install/opnsense NetBird-Doku – Installation auf OPNsense]
* [https://docs.netbird.io/manage/networks NetBird-Doku – Networks und Routing Peers]
* [https://www.max-it.de/it-services/opnsense/ m.a.x. it – OPNsense-Firewall-Services]

{{Uebermax}}
[[Kategorie:IT-Security]]

OPNsense - NetBird-Plugin - Versionsgeschichte

imported>TechCorner-Redaktion: Neuer Artikel: NetBird-Plugin (os-netbird) für OPNsense, Stand 10/2026