Zum Hauptinhalt springen

OPNsense Smart-Home-Integration, kostenlos und Open Source

OPNsense-Integration für Gladys Assistant

OPNsense-Firewall: Zustand, Gateways, Verkehr, Anwesenheit im Netz, Regeln, WireGuard, Szenen.

Auf GitHub ansehenAlle Integrationen

Überblick​

Diese Integration bringt Ihre OPNsense-Firewall in Gladys, über die API von OPNsense in Ihrem lokalen Netzwerk:

  • ein Firewall-Gerät: CPU-, Speicher- und Festplattenauslastung, Temperatur, Betriebszeit, ausstehende Updates, Version und verbundene WireGuard-Peers;
  • ein Gerät pro Gateway (Status, Latenz, Paketverlust) und pro Schnittstelle (empfangene und gesendete Datenrate, Verbindung, IPv4-Adresse);
  • die Firewall-Regeln einer Kategorie Ihrer Wahl als Schalter: Schalten Sie eine Regel über ein Dashboard oder eine Szene ein oder aus;
  • die Geräte in Ihrem Netzwerk (Telefone, Computer…) als Anwesenheitssensoren, aus der ARP-Tabelle und den DHCP-Leases;
  • Szenen: Gateway ausgefallen, jemand ist nach Hause gekommen, neues Gerät im Netzwerk, VPN-Verbindung, Dienst gestoppt, Update verfügbar; und Aktionen, um einen Computer zu wecken, ein Gerät zu sperren, einen Dienst neu zu starten, nach Updates zu suchen oder neu zu starten;
  • vier Dashboard-Widgets.

Die vier Widgets der Integration: Firewall-Übersicht, Internetverbindung, Netzwerkgeräte und WireGuard-VPN (generierte Illustration, kein Screenshot)

Alles bleibt in Ihrem Netzwerk: Die Integration spricht nur mit OPNsense, nie mit einer Cloud.

Voraussetzungen​

  • Gladys Assistant 5.1.0 oder neuer.
  • OPNsense 25.1 oder neuer (geschrieben anhand der API von OPNsense 26.7), vom Gladys-Rechner aus erreichbar.
  • Ein eigener OPNsense-Benutzer für Gladys, mit einem API-Schlüssel. Legen Sie ihn unter System > Zugang > Benutzer an und geben Sie ihm die Rechte der gewünschten Funktionen (Feld Berechtigungen):
FunktionOPNsense-Recht
Firewall (CPU, Speicher, Festplatte)Lobby: Dashboard
GatewaysSystem: Gateways
SchnittstellenStatus: Interfaces, Reporting: Traffic
NetzwerkgeräteDiagnostics: ARP Table, und Services: Dnsmasq DNS/DHCP oder DHCP: Kea(v4)
WireGuardVPN: WireGuard: Status
Dienste (Auslöser, Neustart)Status: Services
Updates (Prüfung)System: Firmware
Regel-SchalterFirewall: Rules [new], Firewall: Categories
Alias-AktionDiagnostics: PF Table IP addresses
NeustartDiagnostics: Reboot System
Wake-on-LAN (Plugin os-wol)Services: Wake on LAN

Ein nicht erteiltes Recht schaltet einfach seine Funktion ab. „System: Firmware" erlaubt auch, Updates über die API zu installieren: Erteilen Sie es nur, wenn Sie die Update-Prüfung wollen. Die Namen der Rechte sind die der englischen Oberfläche von OPNsense.

Klicken Sie auf der Benutzerseite unter API-Schlüssel auf +: Eine Datei key.txt wird heruntergeladen, mit einer Zeile key= und einer Zeile secret=.

Konfiguration​

Öffnen Sie in Gladys Integrationen > OPNsense, installieren Sie sie und füllen Sie aus:

FeldWas eingeben
Adresse von OPNsenseDie Adresse der Weboberfläche, zum Beispiel https://192.168.1.1 (mit Port, wenn er nicht 443 ist).
API-SchlüsselDie Zeile key= von key.txt.
API-GeheimnisDie Zeile secret= von key.txt. Es wird nie wieder angezeigt und nie in die Logs geschrieben.
Zertifikat prüfenMit dem selbstsignierten Zertifikat von OPNsense nicht ankreuzen; mit einem gültigen ankreuzen.
Leseintervall10 bis 300 Sekunden, standardmäßig 30.
Angebotene NetzwerkgeräteDie im Erkennungsbildschirm angebotenen Geräte: die mit einem Namen (Standard), alle oder keine.
AbwesenheitsverzögerungMinuten ohne Antwort, bevor ein Gerät abwesend ist, standardmäßig 5.
Kategorie der RegelnDie Firewall-Regeln dieser Kategorie werden zu Schaltern (gladys standardmäßig; leer: keine).
Sprache der TexteSprache der Namen, Zustände und Szenen-Zusammenfassungen; automatisch folgt Ihrem Dashboard.

Klicken Sie auf Verbindung testen: Gladys zeigt den Namen und die Version Ihrer OPNsense.

Verwendung​

Geräte​

Öffnen Sie Integrationen > OPNsense > Erkennung und fügen Sie die gewünschten Geräte hinzu. Nichts wird ohne Sie angelegt.

GerätFunktionen
OPNsense (Firewall)CPU-, Speicher- und Festplattenauslastung (%), Temperatur, Betriebszeit (Tage), ausstehende Updates, Version, VPN-Peers
GatewayStatus (online, offline, beeinträchtigt, ausstehend), Latenz (ms), Paketverlust (%)
SchnittstelleEmpfangene und gesendete Datenrate (Mbit/s, aus Sicht der Schnittstelle: am WAN ist empfangen der Download), Verbindung, IPv4-Adresse
RegelAktiviert: ein Schalter
NetzwerkgerätAnwesenheit

Anwesenheit der Geräte​

Ein Gerät Ihres Netzwerks ist anwesend, sobald es in der ARP-Tabelle von OPNsense antwortet, und abwesend, wenn es seit der Abwesenheitsverzögerung weg ist. Der Anwesenheitssensor sendet jede Minute 1, solange das Gerät da ist, wie die Bluetooth-Anwesenheit von Gladys: Verwenden Sie ihn in der Szenen-Aktion Anwesenheit von Benutzern überprüfen, um zu wissen, ob jemand zu Hause ist. Ein Telefon mit privater (zufälliger) WLAN-Adresse behält in Ihrem Netzwerk nur dann dieselbe Adresse, wenn die Option pro Netzwerk eingestellt ist: Prüfen Sie es am Telefon.

Firewall-Regeln​

Öffnen Sie in OPNsense Firewall > Regeln, bearbeiten Sie eine Regel (zum Beispiel „Tablet der Kinder sperren") und geben Sie ihr die Kategorie gladys (anzulegen unter Firewall > Kategorien). Nach einer Erkennung erscheint die Regel als Schalter: ein aktiviert die Regel, aus deaktiviert sie, und OPNsense wendet die Änderung sofort an. Nur die Regeln des neuen Regel-Editors lassen sich schalten, nicht die automatischen Regeln.

Dashboard-Widgets​

  • OPNsense-Firewall: Anzeigen für CPU, Speicher und Festplatte, Temperatur, Gateways, Betriebszeit, Updates und zwei Schaltflächen: Updates prüfen und neu starten (mit Bestätigung).
  • Internetverbindung: Latenz, Paketverlust, Download und Upload eines Gateways und einer Schnittstelle (standardmäßig das WAN), mit dem Verkehrsdiagramm, sobald das Gerät der Schnittstelle hinzugefügt ist.
  • Netzwerkgeräte: die jetzt verbundenen Geräte, die gegangenen oder alle.
  • WireGuard-VPN: die Peers, verbunden oder nicht, und ihr letzter Handshake.

Szenen​

Auslöser:

  • Gateway-Status geändert: online, beeinträchtigt (Latenz, Verlust) oder offline, gefiltert nach Gateway und Status.
  • Gerät gekommen oder gegangen: für ein in Gladys hinzugefügtes Netzwerkgerät.
  • Neues Gerät im Netzwerk: eine nie gesehene MAC-Adresse, einmal pro Adresse.
  • VPN-Peer verbunden oder nicht: ein WireGuard-Peer.
  • Dienst gestartet oder beendet: Unbound, Dnsmasq, WireGuard…
  • Update verfügbar: eine Update-Prüfung hat neue Updates gefunden.

Aktionen: Status lesen (CPU, Gateways, anwesende Geräte… für eine Nachricht), ein Gerät wecken (Wake-on-LAN, Plugin os-wol, über VLANs hinweg), eine Adresse in einem Alias hinzufügen oder entfernen, einen Dienst neu starten, nach Updates suchen, neu starten.

Beispiele:

  • Wenn das Gateway WAN_DHCP offline geht → eine Nachricht senden „Internet ist ausgefallen, 4G übernimmt".
  • Wenn ein neues Gerät im Netzwerk erscheint → seinen Namen, Hersteller und seine IP-Adresse an den Administrator senden.
  • Jeden Abend um 21 Uhr → die IP des Tablets der Kinder zum Alias kids_block hinzufügen, den eine Sperrregel nutzt; um 7 Uhr wieder entfernen.

Transport​

Nur lokal: Die Integration spricht per HTTPS in Ihrem Netzwerk mit der API von OPNsense, mit dem API-Schlüssel. Keine Daten verlassen Ihr Netzwerk (OPNsense selbst kontaktiert bei einer Update-Prüfung seinen Mirror).

Fehlerbehebung​

  • „OPNsense lehnt den API-Schlüssel ab": Kopieren Sie Schlüssel und Geheimnis erneut aus key.txt, ohne Leerzeichen.
  • „Das HTTPS-Zertifikat wird abgelehnt": Deaktivieren Sie „Zertifikat prüfen" oder installieren Sie ein für die eingegebene Adresse gültiges Zertifikat.
  • „fehlt ein Recht": Fügen Sie dem OPNsense-Benutzer des Schlüssels die oben genannten Rechte hinzu.
  • Kein Netzwerkgerät: Prüfen Sie das Recht „Diagnostics: ARP Table" und die Option „Angebotene Netzwerkgeräte".
  • Eine Regel fehlt: Sie muss die Kategorie tragen und aus dem neuen Regel-Editor stammen.
  • Wake-on-LAN schlägt fehl: Installieren Sie das Plugin os-wol unter System > Firmware > Plugins und geben Sie für ein nie gesehenes Gerät die Schnittstelle ein (lan, opt1…).
  • Logs: Fügen Sie die Umgebungsvariable DEBUG=gladys-integration-sdk hinzu und eröffnen Sie ein Issue auf GitHub mit den Versionen von Gladys, der Integration und OPNsense sowie den Logs (API-Schlüssel und Geheimnis erscheinen nie darin).

Konfigurationseinstellungen​

Diese Einstellungen fragt OPNsense in seinem Konfigurationsbildschirm in Gladys ab.

EinstellungTypPflichtfeldBeschreibung
OPNsense-API-SchlüsselsectionNeinLegen Sie in OPNsense einen eigenen Benutzer an (System > Zugang > Benutzer), geben Sie ihm die in der Dokumentation genannten Rechte und fügen Sie einen API-Schlüssel hinzu: Eine Datei key.txt mit Schlüssel und Geheimnis wird heruntergeladen. Alles bleibt in Ihrem Netzwerk.
Adresse von OPNsensestringJaDie Adresse seiner Weboberfläche, mit dem Port, wenn er nicht 443 ist.
API-SchlüsselstringJaDie Zeile „key=“ von key.txt.
API-GeheimnissecretJaDie Zeile „secret=“ von key.txt.
Zertifikat prüfenbooleanNeinMit dem selbstsignierten Zertifikat von OPNsense nicht ankreuzen. Mit einem gültigen Zertifikat (Let’s Encrypt, interne Stelle) ankreuzen.
OptionensectionNeinFirewall-Regeln werden zu Schaltern, wenn sie die unten stehende Kategorie tragen. Geräte im Netzwerk werden zu Anwesenheitssensoren, sobald Sie sie im Erkennungsbildschirm hinzufügen.
Leseintervall (s)numberNein10 bis 300 Sekunden, standardmäßig 30.
Angebotene NetzwerkgeräteselectNeinWelche Geräte aus ARP-Tabelle und DHCP-Leases im Erkennungsbildschirm erscheinen.
Abwesenheitsverzögerung (Min.)numberNeinEin Gerät gilt nach dieser Zeit ohne Antwort als abwesend. 1 bis 60, standardmäßig 5: Ein schlafendes Telefon verlässt das Netz eine Weile.
Kategorie der RegelnstringNeinFirewall-Regeln dieser Kategorie (Firewall > Regeln) werden zu Schaltern. Leer: keine.
Sprache der TexteselectNeinNamen, Zustände und Szenen-Zusammenfassungen. Automatisch: die Sprache Ihres Dashboards, sobald ein OPNsense-Widget angezeigt wurde.

So installierst du OPNsense in Gladys​

  1. Öffne in Gladys Integrationen: OPNsense erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
  2. Klicke auf Installieren. Gladys lädt das Docker-Image (ghcr.io/william-de71/gladys-opnsense:0.1.0) herunter, startet es in einer vom Kern isolierten Sandbox und erzeugt die Oberfläche der Integration (Geräte, Erkennung und Konfiguration).
  3. Öffne den Bildschirm Konfiguration der Integration, fülle die Einstellungen aus und speichere.
  4. Du kannst sie auch direkt über die URL ihres Repositorys installieren: https://github.com/William-De71/gladys-opnsense.

OPNsense benötigt Gladys >=5.1.0. Der Katalog in Gladys wird stündlich aktualisiert, eine neue Version ist also spätestens eine Stunde nach ihrer Veröffentlichung verfügbar.

Du nutzt Gladys noch nicht? Es ist kostenlos und Open Source: folge der Installationsanleitung, um loszulegen.

Über externe Integrationen​

OPNsense ist eine externe Integration: eine Community-Integration, die als Docker-Container verpackt und auf GitHub veröffentlicht wird. Gladys installiert sie mit einem Klick und führt sie in einer vom Kern isolierten Sandbox aus. Sie wird von William-De71 veröffentlicht und gepflegt, nicht vom Gladys-Kernteam.

Abonniere den Newsletter von Gladys Assistant

Ein paar E-Mails im Monat zu neuen Releases und Neuigkeiten aus dem Projekt. Verschickt von Pierre-Gilles Leymarie, dem Gründer des Projekts. Jederzeit abbestellbar 🙂
Zuletzt aktualisiert am