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>
This commit is contained in:
2026-11-21 12:17:34 +01:00
co-authored by Claude Opus 5.5
parent 19163a2efe
commit 93429e4394
8 changed files with 216 additions and 15 deletions
+6 -2
View File
@@ -10,11 +10,15 @@ Unter **Verwaltung → Geräteaufnahme** den Kunden wählen und einen Einmalcode
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, wird er über den Gerätekanal an genau diese Installation gebunden (`job-binding.json`). Das Skript startet den Dienst und wartet, bis sich die Firewall mit der Paketversion meldet. [Installer](../../crates/server/src/bootstrap/opnsense_install.py)
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).
**Paket bereitstellen:** `python3 tools/dev_opnsense_bundle.py --worker-from-guest` baut `agent.pyz` und `collect.pyz` aus diesem Verzeichnis, nimmt das rc.d-Skript und den nativen Worker aus dem Testgast 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)
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
+14 -4
View File
@@ -20,9 +20,13 @@ STATE = Path('/var/db/discovery-agent')
CA = '/usr/local/etc/discovery-agent/ca.pem'
HOST = 'discovery.ease-technologies.de'
MEDIA = 'application/x-protobuf'
VERSION = '0.1.0-opnsense.6'
VERSION = '0.1.0-opnsense.7'
WORKER = Path('/usr/local/libexec/discovery-agent/rmm-opnsense-jobs')
BINDING = Path('/usr/local/etc/discovery-agent/job-binding.json')
# A worker that cannot start (e.g. built for a newer FreeBSD) must not stop
# heartbeat and inventory. Script capabilities pause until this moment.
WORKER_RETRY = 3600
worker_paused_until = 0.0
def post(ctx, path, data, media):
@@ -177,11 +181,12 @@ def session(db, identity, boot, instance):
def run_channel(db, identity, boot, instance, stack):
global worker_paused_until
ctx = context()
ctx.load_cert_chain(STATE/'device.pem', STATE/'device.key')
generation = 0
jobs = None
enabled = BINDING.is_file() and WORKER.is_file()
enabled = BINDING.is_file() and WORKER.is_file() and time.monotonic() >= worker_paused_until
def send(kind, payload, captured=None):
# A lost inventory ACK replays the exact durable envelope, including its
@@ -249,8 +254,13 @@ def run_channel(db, identity, boot, instance, stack):
p.stdout.close()
stack.callback(close)
jobs = Jobs(p)
if jobs.read()!=b'ready':
raise ValueError('job worker unavailable')
try:
ready = jobs.read()==b'ready'
except ValueError:
ready = False
if not ready:
worker_paused_until = time.monotonic()+WORKER_RETRY
raise ValueError('job worker unavailable; scripts paused, telemetry continues')
last = None
previous = None
check_cert = time.monotonic()+12*3600
+41
View File
@@ -76,5 +76,46 @@ class Reconnect(unittest.TestCase):
self.assertEqual(captures[0],captures[1])
def test_broken_worker_pauses_scripts_but_keeps_heartbeat(self):
with tempfile.TemporaryDirectory() as temp:
db = sqlite3.connect(':memory:')
db.executescript('CREATE TABLE sequence(id INTEGER PRIMARY KEY,n INTEGER);INSERT INTO sequence VALUES(1,0);'
'CREATE TABLE pending(id INTEGER PRIMARY KEY,envelope BLOB,observed INTEGER);')
worker = Path(temp)/'worker'
# Same effect as a loader failure: exits before printing "ready".
worker.write_text('#!/bin/sh\nexit 1\n')
worker.chmod(0o755)
binding = Path(temp)/'binding.json'
binding.write_text('{}')
seen = []
def gateway(_ctx,path,data,media):
req = a.pb.MessageBatch.FromString(data).messages[0]
reply = a.pb.Envelope()
reply.CopyFrom(req)
kind = req.WhichOneof('payload')
seen.append((kind, list(req.client_hello.capabilities)))
if kind == 'client_hello':
reply.connection_generation = len(seen)
reply.server_hello.CopyFrom(a.pb.ServerHello(connection_generation=len(seen),max_message_bytes=1024*1024))
else:
reply.ack.CopyFrom(a.pb.Ack(message_id=req.message_id))
return a.pb.MessageBatch(protocol_major=1,messages=[reply]).SerializeToString()
with patch.object(a,'context'), patch.object(a,'renew',return_value=False), \
patch.object(a,'post',gateway), patch.object(a,'WORKER',worker), patch.object(a,'BINDING',binding), \
patch.object(a,'worker_paused_until',0.0), \
patch.object(a,'usage',return_value=(a.pb.SystemUsage(),[])), \
patch.object(a.time,'clock_gettime',return_value=100), \
patch.object(a.time,'CLOCK_UPTIME',1,create=True), patch.object(a.time,'sleep',side_effect=StopIteration):
identity = {'agent_id':str(uuid.uuid4()),'asset_id':str(uuid.uuid4())}
with self.assertRaisesRegex(ValueError,'telemetry continues'):
a.session(db,identity,str(uuid.uuid4()),str(uuid.uuid4()))
with self.assertRaises(StopIteration):
a.session(db,identity,str(uuid.uuid4()),str(uuid.uuid4()))
self.assertEqual([k for k,_ in seen],['client_hello','client_hello','heartbeat'])
self.assertIn('run_script',seen[0][1])
self.assertEqual(seen[1][1],['heartbeat/1','opnsense.base/1'])
if __name__=='__main__':
unittest.main()