Files
rust-discovery/deploy/opnsense/README.md
T
kevin_janssenandClaude Opus 5.5 93429e4394 Keep OPNsense telemetry when the script worker cannot start and build it for FreeBSD 14.1
A worker linked on the FreeBSD 15 test guest needs FBSD_1.9 and does not load on
OPNsense 24.7; the agent then retried the job session every 30 s and never sent a
heartbeat or inventory. The agent now pauses script capabilities for an hour and
reconnects without them. tools/dev_opnsense_worker.py links the worker against the
official FreeBSD 14.1 pkgbase libraries. The installer checks that the worker loads
before binding it and reports success only after a heartbeat.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 12:17:34 +01:00

43 lines
9.7 KiB
Markdown

# OPNsense-Testclient
Test-VM `discovery-opnsense` auf `qemu:///system`, 2 vCPU, 1536 MiB RAM, 12 GiB virtuelle Platte. Basis: offizielles Nano-Image OPNsense 26.7 amd64; SHA-256 des komprimierten Images `28d5e2f37e40d87468a924e3006ef10e2ddc6de485b85333d9e3958c84d0cb9d`, gegen die Herstellerankündigung verglichen und die Signatur des entpackten Images geprüft. Start bei Bedarf: `virsh -c qemu:///system start discovery-opnsense`. Konsole: `virsh -c qemu:///system console discovery-opnsense`. Das LAN `192.168.247.0/24` ist eine isolierte libvirt-Bridge, das WAN `192.168.246.0/24` verwendet NAT. Management vom Notebook: `https://192.168.247.1`. Der Hostpin stammt aus der seriellen Konsole; Zugangswerte liegen ausschließlich im privaten Zugangsspeicher des ursprünglichen Checkouts.
## Aufnahme per HTTPS
Unter **Verwaltung → Geräteaufnahme** den Kunden wählen und einen Einmalcode erstellen. Auf der Firewall als `root` (SSH oder Konsole, Option **8) Shell**) den angezeigten Befehl ausführen:
```sh
fetch -o opnsense.sh 'https://discovery.ease-technologies.de:8443/install/opnsense.sh' && sh opnsense.sh 'https://discovery.ease-technologies.de:8443'
```
Das Skript fragt nach dem **Einmalcode**. Es lädt mit diesem Code das OPNsense-Paket des Servers, prüft jede Datei gegen Größe und SHA-256 und installiert es mit denselben Schritten wie [install-dev.sh](install-dev.sh). Danach nimmt es die Firewall unter dem Dienstkonto `discovery` auf. Ist der Skript-Worker im Paket, prüft das Skript zuerst, ob er auf diesem System lädt (`rmm-opnsense-jobs --version` mit `LD_BIND_NOW=1`), und bindet ihn dann über den Gerätekanal an genau diese Installation (`job-binding.json`). Lädt er nicht, meldet das Skript das und legt keine Bindung an. Das Skript startet den Dienst und meldet erst Erfolg, wenn die Firewall sich mit der Paketversion verbunden und danach einen Heartbeat gesendet hat. [Installer](../../crates/server/src/bootstrap/opnsense_install.py)
Ein erneuter Lauf auf einer aufgenommenen Firewall aktualisiert nur die Programmdateien. Geräteidentität, Zertifikat, Journale und Bindung bleiben erhalten; der Einmalcode wird dabei nicht verbraucht. Gehört die vorhandene Bindung zu einem anderen Kunden, bricht das Skript ab. Für einen Kundenwechsel das Gerät neu aufnehmen. Den Root-Helper richtet der Installer nicht ein (siehe unten).
Startet der Worker im laufenden Betrieb nicht (Meldung `job worker unavailable; scripts paused, telemetry continues` im Systemlog), verbindet sich der Agent nach 30 Sekunden ohne Skriptfähigkeiten neu. Heartbeat und Inventur laufen weiter, Skripte sind für eine Stunde ausgesetzt. Danach versucht der Agent den Worker erneut.
**Worker bauen:** `python3 tools/dev_opnsense_worker.py OUT` baut `rmm-opnsense-jobs` im Testgast, linkt ihn aber gegen die Basisbibliotheken von FreeBSD 14.1 (OPNsense 24.7, offizielles `base.txz`, gegen das Release-MANIFEST geprüft). Ein nativ auf dem FreeBSD-15-Testgast gelinkter Worker verlangt `FBSD_1.9` aus der libc und lädt auf OPNsense 24.x nicht. [Worker-Werkzeug](../../tools/dev_opnsense_worker.py)
**Paket bereitstellen:** `python3 tools/dev_opnsense_bundle.py --worker OUT` baut `agent.pyz` und `collect.pyz` aus diesem Verzeichnis, nimmt das rc.d-Skript und den gebauten Worker und legt alles mit `manifest.json` unter `devstate/mvp-releases/config/opnsense/` auf dem Entwicklungsserver ab (Eigentümer wie die übrige Releasekonfiguration, Modus 0600). Die Version stammt aus `VERSION` in `agent.py`. Ohne gültiges Paket zeigt die WebUI keinen OPNsense-Befehl. Das Paket ist nicht signiert. Seine Integrität beruht auf der HTTPS-Verbindung zum Installationsserver, über die auch das Skript selbst kommt. [Paketwerkzeug](../../tools/dev_opnsense_bundle.py)
## Quelle und Entwicklungsinstallation
Der OPNsense-eigene Python-Interpreter führt zwei Zipapps aus. Der lokale Collector läuft mit den für PF, VPN-Sockets und Konfiguration nötigen Rechten. Er veröffentlicht ausschließlich den ausgewählten Bestand atomar in `/var/db/discovery-observations/inventory.json`. Das Dienstkonto `discovery` kann die Datei lesen, aber weder Collector noch Cache verändern. Nur dieses Konto hält die Geräteidentität und nutzt den ausgehenden HTTPS-Kanal. Für die Erfassung wird keine eingehende Netzwerkverbindung benötigt.
1. In einer Build-venv `grpcio-tools==1.76.0` und `protobuf==6.33.5` installieren. `python deploy/opnsense/build.py ARTIFAKTORDNER` generiert die Protobuf-Bindung aus `proto/agent.proto` und packt die portable Python-Laufzeit mit ein. `python deploy/opnsense/test_agent.py ARTIFAKTORDNER/agent.pyz` prüft die Wiederholung einer nicht bestätigten Inventarmeldung mit unveränderter Nachrichtenidentität.
2. Über den gepinnten Entwicklungszugang `agent.pyz`, `collect.pyz`, `discovery_agent` und den **bestätigten öffentlichen CA-Anker des Gerätegateways** als `ca.pem` in einen privaten Stagingordner im Gast übertragen. `sh install-dev.sh STAGINGORDNER` auf dem Gast ausführen. Diese Strecke ist eine direkte Entwicklungsbereitstellung, kein signierter Releasekanal.
3. Bei einer frischen Installation in der Discovery-WebUI den Testkunden wählen und einen Einmalcode erzeugen. Den Code über geschützte Standardeingabe an `su -m discovery -c '/usr/local/bin/python3 -I /usr/local/libexec/discovery-agent/agent.pyz enroll'` übergeben. Danach `service discovery_agent start`. Bei vorhandener Identität nicht neu enrollen. Der Dienst verwaltet beide Prozesse; `rc.conf.local` aktiviert sie beim Start.
4. In **Geräte** den Hostnamen öffnen. Das Inventar wird ungefähr einmal pro Minute erhoben, der Heartbeat etwa alle 20 Sekunden gesendet. Das Betriebssystem liefert CPU-Zeitdifferenzen und eine RAM-Schätzung aus freien und inaktiven Seiten. Fehlgeschlagene Quellen erscheinen als „Nicht ermittelbar“, ein erfolgreicher leerer Befund gesondert. Pro Liste werden höchstens 128 Zeilen gemeldet; Auszüge sind gekennzeichnet.
**Systeminventar:** Kern-Bootzeit, VM-Erkennung, verfügbare SMBIOS-Daten, Netzwerkkarten mit MAC und IPs, angemeldete Benutzer und lokale FreeBSD-Pakete mit Version. Bei Software liegt die Obergrenze bei 1024 Paketen.
**VPN:** Beschreibungen und Aktivierung der OPNsense-Modelle für WireGuard-Instanzen/-Peers, OpenVPN-Instanzen und IPsec-Verbindungen. Separat: WireGuard-Handshakes (kein dauerhafter Online-Status), OpenVPN-Managementstatus und IKE-Sicherheitsassoziationen. Ohne erreichbaren IPsec-Dienst ist der Laufzeitstatus unbekannt. Keine privaten Schlüssel, PSKs, Zertifikate oder vollständige Gerätekonfiguration im Inventar.
**Firewall:** aktiver PF-Hauptregelsatz in Kernelreihenfolge, einschließlich automatisch erzeugter Regeln. Kein Editor und kein rekursives Auslesen der Anchor-Regelsätze.
**Skripte:** Unter **Aufträge → Neuer Auftrag** die OPNsense-Zielgeräte wählen. Unter **Aus der Bibliothek** eine feste POSIX-Shell-Revision wählen, alternativ ein **Einmaliges Skript** eingeben. **Ausführen als** unterstützt Dienstkonto und bei entsprechender Berechtigung `root`. **Zusammenfassung ansehen** bindet das Skript samt Zielen und Grenzen; **Zur Genehmigung einreichen** legt den Antrag an. Die persönliche Freigabe erfolgt unter **Genehmigungen**, die Ausgabe erscheint im Auftrag. OPNsense kann POSIX-Shellskripte ausführen; Linux-spezifische Programme und Optionen werden nicht übersetzt. Zwei [Startrevisionen aus dem Repository](../../migrations/0047_opnsense_library.sql) zeigen Version/Ausführungskonto bzw. aktive Firewallregeln. Im Gerätedetail stehen Inventar und Verweise auf vorhandene Aufträge.
**Probe bereitstellen:** Im Gast steht die gepinnte Toolchain unter `/opt/discovery-rust`. `cargo build --locked -p rmm-opnsense-jobs` nativ bauen und `rmm-opnsense-jobs` root-eigen (0555) neben den Zipapps installieren. Auf der bereits aufgenommenen Testinstallation `python3 -I pin-probe.py TENANT ASSET AGENT ENROLLMENT_GENERATION ASSIGNMENT_VERSION` mit den bestätigten Kennungen aufrufen. Das Skript bezieht den öffentlichen Jobschlüssel über das bestehende Gerätezertifikat und überschreibt keine andere Bindung. Den Agentendienst anschließend neu starten. Der Worker nutzt bestehende Nachrichtenfolgen, den signierten Abgleich und getrennte dauerhafte Start-/Ergebnisjournale. Er läuft ohne Netzwerklistener als `discovery`. Der [native Integrationstest](../../crates/agent-opnsense-jobs/src/native/tests.rs) prüft mit eigener Testidentität und eigenem Schlüssel die Ablehnung einer defekten Signatur, erwartete Ausgabe, einen Verbrauch und keine zweite Ausführung bei Wiederzustellung. Das ist ein separater Beleg vom persönlich genehmigten Geräteauftrag.
**Root-Helper (ab `0.1.0-opnsense.6`):** Native Binärdatei zusätzlich in den privaten Stagingordner kopieren. Auf dem Gast `python3 -I enable-root.py /absoluter/Stagingpfad/rmm-opnsense-jobs` und `sh install-dev.sh /absoluter/Stagingpfad` ausführen. Die lokale Policy bindet Worker-Hash, Gerätebindung, Dienst-UID und Gruppe. Der zusätzliche `rc.d`-Prozess läuft als root, hört ausschließlich auf einem geschützten Unix-Socket und prüft den Peer über `getpeereid`. Den vom Helper bestätigten Binär- und Policyhash mit `tools/dev_opnsense_root_scope.py --help` für die genaue Kopplung und den berechtigten lokalen Principal registrieren. Es gibt keine automatische Freigabe oder automatische Pinrotation. Root akzeptiert `posix_sh` mit `full_maintenance_v1` (bis 300 Sekunden und 65536 Ausgabebyte), verifiziert selbst Sync, Grant, Skriptbytes, Boot und Uhr, und führt ein eigenes Verbrauchsjournal in `/var/db/discovery-root-jobs`. Ohne Startbeleg gibt es kein positives Ergebnis. Bei `unknown` zuerst die bestehenden Journale abgleichen. Der [isolierte native Helper-Test](test_root_helper.py) benutzt nur eine Wegwerfidentität und separate Journale.