Hinweis zur KI-Beteiligung: Dieser Adapter wurde mit Unterstützung einer KI (Claude) entwickelt. Den Code habe ich selbst manuell geprüft.

Hallo zusammen,

ich stelle pfSense (pfsense) Version 0.1.1 zum Testen bereit.

Überwacht und steuert pfSense-Firewalls über das pfSense-REST-API-Paket: Systemzustand, Schnittstellen, Gateways, Dienste, DHCP und Anwesenheit, VPN, CARP, Firewall-Regeln und Wake-on-LAN

Was der Adapter macht

Der Adapter verbindet ioBroker mit einer pfSense-Firewall (Community Edition oder pfSense Plus) über das Community-Paket pfSense REST API (pfrest, v2.x). Eine Instanz entspricht einer Firewall.

• System: Version, CPU, Load, RAM, Swap, Disk, mbuf, Temperatur, Uptime, Version des REST-API-Pakets mit Update-Hinweis
• Schnittstellen: Link-Status, Adressen, MAC, Medium, Zähler und live berechnete Datenraten (bit/s)
• Gateways: online/offline, Latenz, Paketverlust
• Dienste: Status jedes Dienstes, Start/Stopp/Neustart-Buttons
• Netzwerk und Anwesenheit: DHCP-Leases und ARP-Tabelle als Hostliste; Anwesenheitsgeräte (nach MAC) mit Karenzzeit, „zuletzt gesehen“ und Wake-on-LAN-Button. Ruhige Geräte werden vor der Abwesenheitsmeldung von der Firewall angepingt.
• VPN: OpenVPN-Server (verbundene Clients) und -Clients, WireGuard-Tunnel und -Peers, IPsec-Tunnel
• CARP: Ein/Aus und Wartungsmodus, Master/Backup je virtueller IP
• Firewall: Regeln mit Ein/Aus-Schalter (wird sofort angewendet), Aliase, Hinweis auf nicht angewendete Änderungen
• Optional: Neustart/Herunterfahren der Firewall (standardmäßig aus)
• Skripte: sendTo-Befehle für Wake-on-LAN, Dienste, Regeln, Alias-Einträge und die Hostliste

Getestet mit

pfSense CE 2.8.1 (VM unter Proxmox) mit REST-API-Paket v2.10.2. Live getestet: alle Werte oben, Dienst-Neustart, Regel-Schalter, Alias-Einträge, Wake-on-LAN, OpenVPN in beide Richtungen, WireGuard, IPsec (IKEv2), ein CARP-Paar mit Umschaltung über den Wartungsmodus, ein ausgefallenes Gateway, DHCP mit ISC und Kea, Anwesenheit eines LAN-Clients (gehen, wiederkommen, ruhiges Gerät).

Nicht getestet: pfSense Plus und echte Netgate-Hardware (z. B. mit Temperatursensor). Rückmeldungen dazu sind besonders willkommen.

Einrichtung auf der Firewall

1. Das pfSense REST API-Paket installieren – es ist nicht im pfSense-Paketmanager, siehe die Installationsanleitung auf https://pfrest.org/.
2. Unter System > REST API die Key-Authentifizierung aktivieren und einen API-Schlüssel anlegen (am besten für einen eigenen Benutzer mit nur den nötigen Rechten; api-v2-status-system-get ist immer erforderlich).
3. In der Instanz Adresse eintragen, „Zertifikats-Fingerabdruck auslesen“ klicken (funktioniert mit dem selbstsignierten Standardzertifikat), API-Schlüssel eintragen, „Verbindung testen“.

Bekannte Einschränkungen

• Bei mehreren OpenVPN-Instanzen lassen sich diese über die API nicht starten/stoppen (Fehler im REST-API-Paket, gemeldet als pfrest/pfSense-pkg-RESTAPI#953). Der Status wird trotzdem angezeigt.
• WireGuard kennt keinen Verbindungsstatus: ein Peer gilt als verbunden, wenn der letzte Handshake jünger als 3 Minuten ist.
• Abwesenheit wird erst gemeldet, wenn der ARP-Eintrag der Firewall abgelaufen ist (bis 20 Minuten) plus Karenzzeit.

Bitte testen

• Verschiedene Hardware und pfSense Plus; Firewalls mit vielen Schnittstellen, Regeln oder Diensten
• Anwesenheit mit Handys (Schlafmodus, WLAN-Wechsel)
• Multi-WAN / Gateway-Gruppen, HA-Paare (eine Instanz pro Knoten)
• Ob Logmeldungen verständlich sind, wenn etwas fehlt (Paket, Rechte, Zertifikat)

Voraussetzungen:

• Node.js 22 oder neuer
• js-controller 6.0.11 oder neuer
• Admin 7.6.20 oder neuer

Änderungen in v0.1.x:

• 0.1.1: Veröffentlichung über CI mit npm-Provenienz; Dependabot-Konfiguration für Abhängigkeitsupdates
• 0.1.0: Erste Version: System, Schnittstellen, Gateways, Dienste, DHCP/ARP-Hostliste und Anwesenheit, OpenVPN, WireGuard, IPsec, CARP, Firewall-Regeln und Aliase, Wake-on-LAN, optional Neustart/Herunterfahren

Installation (noch nicht im Latest-Repository): Admin → Adapter → "Benutzerdefiniert installieren" (GitHub-Symbol) → URL: https://github.com/AlanSRU/ioBroker.pfsense

Feedback, Fehlerberichte und Wünsche bitte hier im Thread oder als GitHub-Issue. Bei Fehlern bitte das Log (Loglevel "debug") und das Gerätemodell angeben.

English

AI involvement: this adapter was developed with the help of an AI (Claude). The code has been manually reviewed by myself.

pfSense (pfsense) version 0.1.1 is ready for testing.

Monitor and control pfSense firewalls through the pfSense REST API package: system health, interfaces, gateways, services, DHCP and presence, VPN, CARP, firewall rules and Wake-on-LAN

What the adapter does

The adapter connects ioBroker to a pfSense firewall (Community Edition or pfSense Plus) through the community pfSense REST API package (pfrest, v2.x). One instance per firewall.

• System: version, CPU, load, memory, swap, disk, mbuf, temperature, uptime, REST API package version with update flag
• Interfaces: link state, addresses, MAC, media, counters and live traffic rates (bit/s)
• Gateways: online/offline, latency, packet loss
• Services: status of every service, start/stop/restart buttons
• Network and presence: DHCP leases and ARP table as a host list; presence devices (by MAC) with a grace period, last-seen time and a Wake-on-LAN button. Quiet devices are pinged by the firewall before they are reported away.
• VPN: OpenVPN servers (connected clients) and clients, WireGuard tunnels and peers, IPsec tunnels
• CARP: enable and maintenance mode, master/backup per virtual IP
• Firewall: rules with an on/off switch (applied immediately), aliases, pending-changes flag
• Optional: reboot/shutdown of the firewall (off by default)
• Scripts: sendTo commands for Wake-on-LAN, services, rules, alias entries and the host list

Tested with

pfSense CE 2.8.1 (VM on Proxmox) with REST API package v2.10.2. Tested live: all values above, service restart, rule switch, alias entries, Wake-on-LAN, OpenVPN in both directions, WireGuard, IPsec (IKEv2), a CARP pair with failover through maintenance mode, a failed gateway, DHCP with ISC and Kea, presence of a LAN client (leaving, returning, quiet device).

Not tested: pfSense Plus and real Netgate hardware (e.g. with a temperature sensor). Feedback on these is especially welcome.

Firewall setup

1. Install the pfSense REST API package — it is not in the pfSense package manager; see the installation guide at https://pfrest.org/.
2. Under System > REST API, enable key authentication and create an API key (ideally for a dedicated user with only the privileges needed; api-v2-status-system-get is always required).
3. In the instance, enter the address, click "Read certificate fingerprint" (works with the default self-signed certificate), enter the API key, "Test connection".

Known limitations

• With several OpenVPN instances, the API cannot start/stop them (bug in the REST API package, reported as pfrest/pfSense-pkg-RESTAPI#953). Their status is still shown.
• WireGuard has no connection state: a peer counts as connected when its last handshake is less than 3 minutes old.
• A device is reported away only once the firewall's ARP entry has expired (up to 20 minutes) plus the grace period.

Please test

• Different hardware and pfSense Plus; firewalls with many interfaces, rules or services
• Presence with phones (sleep mode, Wi-Fi roaming)
• Multi-WAN / gateway groups, HA pairs (one instance per node)
• Whether the log messages make sense when something is missing (package, privileges, certificate)

Requirements:

• Node.js 22 or newer
• js-controller 6.0.11 or newer
• Admin 7.6.20 or newer

Changes in v0.1.x:

• 0.1.1: Published through CI with npm provenance; Dependabot configuration for dependency updates
• 0.1.0: Initial release: system, interfaces, gateways, services, DHCP/ARP host list and presence, OpenVPN, WireGuard, IPsec, CARP, firewall rules and aliases, Wake-on-LAN, optional reboot/shutdown

Install (not yet in the latest repository): Admin → Adapters → "Custom install" (GitHub icon) → URL: https://github.com/AlanSRU/ioBroker.pfsense

Feedback and bug reports welcome here or as GitHub issues; please include a debug log and the device model.