Files
rust-discovery/crates/server/src/bootstrap/opnsense_install.py
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

218 lines
9.7 KiB
Python

"""HTTPS installer for the OPNsense agent. Runs as root on the firewall.
Downloads the fixed program bundle with the one-time enrollment code, checks
each file against the server's size and SHA-256, installs it with the same
steps as the development installation and enrolls the device under the
unprivileged `discovery` account. An existing device identity is kept.
"""
import getpass
import hashlib
import http.client
import json
import os
from pathlib import Path
import re
import ssl
import subprocess
import sys
import time
import urllib.parse
import uuid
STATE = Path('/var/db/discovery-agent')
CONF = Path('/usr/local/etc/discovery-agent')
APP = Path('/usr/local/libexec/discovery-agent')
BINDING = CONF / 'job-binding.json'
PYTHON = '/usr/local/bin/python3'
REQUIRED = ('agent.pyz', 'collect.pyz', 'discovery_agent')
OPTIONAL = ('rmm-opnsense-jobs',)
MAX_FILE = 32 * 1024 * 1024
def stop(message):
raise SystemExit('Installation abgebrochen: ' + message)
def origin(raw):
url = urllib.parse.urlsplit(raw)
if (url.scheme != 'https' or not url.hostname or url.username or url.password or url.query
or url.fragment or url.path not in ('', '/')):
stop('Die Serveradresse muss eine reine HTTPS-Adresse sein, z. B. https://server.example:8443')
return url
def tls():
context = ssl.create_default_context()
if not context.get_ca_certs():
for bundle in ('/usr/local/openssl/cert.pem', '/usr/local/etc/ssl/cert.pem', '/etc/ssl/cert.pem'):
if os.path.isfile(bundle):
context.load_verify_locations(bundle)
break
return context
def get(base, path, token, limit):
conn = http.client.HTTPSConnection(base.hostname, base.port or 443, context=tls(), timeout=30)
try:
conn.request('GET', path, headers={'Authorization': 'Enrollment ' + token})
res = conn.getresponse()
if res.status == 401:
stop('Der Einmalcode ist ungueltig, abgelaufen oder bereits verwendet.')
if res.status != 200:
stop(f'Server antwortet auf {path} mit HTTP {res.status}.')
body = res.read(limit + 1)
if len(body) > limit:
stop('Antwort des Servers ist zu gross.')
return body
finally:
conn.close()
def metadata(raw):
meta = json.loads(raw)
files = meta.get('files')
if (meta.get('schema_version') != 1 or not isinstance(files, dict)
or not all(name in files for name in REQUIRED)
or not all(name in REQUIRED + OPTIONAL for name in files)
or not re.fullmatch('[a-f0-9]{64}', str(meta.get('job_signing_public_key_hex')))
or not str(meta.get('ca_pem', '')).startswith('-----BEGIN CERTIFICATE-----')
or not re.fullmatch(r'[A-Za-z0-9._-]{1,64}', str(meta.get('version')))
or not re.fullmatch(r'https://[a-z0-9.-]+(:[0-9]{1,5})?/?', str(meta.get('gateway_origin')))):
stop('Der Server liefert kein gueltiges OPNsense-Paket.')
uuid.UUID(meta['tenant_id'])
for item in files.values():
if not (re.fullmatch('[a-f0-9]{64}', str(item.get('sha256'))) and isinstance(item.get('bytes'), int)
and 0 < item['bytes'] <= MAX_FILE):
stop('Der Server liefert kein gueltiges OPNsense-Paket.')
return meta
def as_discovery(command, payload, timeout=60):
# `su -m` keeps root's shell; OPNsense may set an interactive menu there.
return subprocess.run(['su', '-m', 'discovery', '-c', command], input=payload, capture_output=True,
timeout=timeout, env={**os.environ, 'SHELL': '/bin/sh'})
# Runs as `discovery`: reads the device-owned key only after dropping privileges.
DEVICE_QUERY = """
import http.client,json,ssl,sys
from pathlib import Path
p=Path('/var/db/discovery-agent')
ctx=ssl.create_default_context(cafile='/usr/local/etc/discovery-agent/ca.pem')
ctx.load_cert_chain(p/'device.pem',p/'device.key')
out={}
for name,path in (('installed','/agent/v1/releases/installed'),('trust','/agent/v1/releases/device-trust')):
c=http.client.HTTPSConnection(sys.argv[1],int(sys.argv[2]),context=ctx,timeout=15)
c.request('GET',path)
r=c.getresponse()
if r.status!=200: raise SystemExit(name+' HTTP '+str(r.status))
out[name]=json.loads(r.read(65537))
print(json.dumps(out))
"""
def device_view(host, port):
res = as_discovery(f'{PYTHON} -I - {host} {port}', DEVICE_QUERY.encode())
if res.returncode:
return None
return json.loads(res.stdout)
def bind_jobs(meta, host, port):
"""Pin the job signing key for the script worker of this exact installation."""
view = device_view(host, port)
if view is None:
stop('Der Gerätekanal ist nicht erreichbar; die Skriptbindung wurde nicht angelegt.')
identity = json.loads((STATE / 'identity.json').read_bytes())
installed, key = view['installed'], view['trust']['job_signing_public_key_hex']
if (installed['tenant_id'], installed['agent_id'], installed['asset_id'], key) != (
meta['tenant_id'], identity['agent_id'], identity['asset_id'], meta['job_signing_public_key_hex']):
stop('Gerätekanal und Installationsserver widersprechen sich.')
payload = dict(agent_id=identity['agent_id'], asset_id=identity['asset_id'], tenant_id=meta['tenant_id'],
enrollment_generation=int(installed['enrollment_generation']),
assignment_version=int(installed['assignment_version']), public_key_hex=key)
with BINDING.open('x') as f:
os.fchmod(f.fileno(), 0o444)
json.dump(payload, f)
f.flush()
os.fsync(f.fileno())
def worker_starts():
"""The native worker must load on this FreeBSD release; resolve all symbols now."""
try:
res = subprocess.run([str(APP / 'rmm-opnsense-jobs'), '--version'], capture_output=True, timeout=15,
env={**os.environ, 'LD_BIND_NOW': '1'})
except OSError:
return False
return res.returncode == 0
def running():
return all(Path(f'/var/run/discovery-{part}.pid').is_file() for part in ('agent', 'collect'))
def main():
if len(sys.argv) not in (3, 5) or (len(sys.argv) == 5 and sys.argv[3] != '--token-file'):
stop('Aufruf: sh opnsense.sh https://server.example:8443')
files_script, base = Path(sys.argv[1]), origin(sys.argv[2])
existing = (STATE / 'identity.json').is_file() and (STATE / 'identity.json').stat().st_size > 0
if existing:
print('Vorhandene Installation gefunden. Programmdateien werden aktualisiert, die Geräteidentität bleibt.')
if len(sys.argv) == 5:
token = Path(sys.argv[4]).read_text().strip()
else:
token = getpass.getpass('Einmalcode: ').strip()
if not re.fullmatch('[0-9a-f]{64}', token):
stop('Der Einmalcode besteht aus 64 Zeichen 0-9 und a-f.')
meta = metadata(get(base, '/agent/v1/bootstrap/opnsense/current', token, 65536))
if existing and BINDING.is_file() and json.loads(BINDING.read_bytes())['tenant_id'] != meta['tenant_id']:
stop('Diese Installation gehört zu einem anderen Kunden. Für einen Kundenwechsel das Gerät neu aufnehmen.')
stage = files_script.parent / 'stage'
stage.mkdir(mode=0o700)
for name, item in sorted(meta['files'].items()):
data = get(base, '/agent/v1/bootstrap/opnsense/files/' + name, token, item['bytes'])
if len(data) != item['bytes'] or hashlib.sha256(data).hexdigest() != item['sha256']:
stop(f'{name} stimmt nicht mit der Prüfsumme des Servers überein.')
(stage / name).write_bytes(data)
(stage / 'ca.pem').write_text(meta['ca_pem'])
print(f'OPNsense-Agent {meta["version"]} geladen und geprüft. Installation läuft …')
subprocess.run(['sh', str(files_script), str(stage)], check=True)
gateway = urllib.parse.urlsplit(meta['gateway_origin'])
host, port = gateway.hostname, gateway.port or 443
if not existing:
res = as_discovery(f'{PYTHON} -I {APP}/agent.pyz enroll', (token + '\n').encode())
if res.returncode:
stop('Die Aufnahme beim Server ist fehlgeschlagen. Bitte einen neuen Einmalcode erzeugen.')
print('Gerät beim Server aufgenommen.')
worker = (APP / 'rmm-opnsense-jobs').is_file()
if worker and not worker_starts():
worker = False
print('Hinweis: Der Skript-Worker startet auf dieser OPNsense-Version nicht. '
'Inventur und Heartbeat laufen, Skripte sind bis zu einem passenden Paket nicht verfügbar.')
if worker and not BINDING.exists():
bind_jobs(meta, host, port)
print('Skriptausführung für diese Installation gebunden.')
before = device_view(host, port)
generation = int(before['installed']['connection_generation']) if before else -1
contact = before['installed'].get('last_contact_at') if before else None
subprocess.run(['service', 'discovery_agent', 'restart' if running() else 'start'], check=True,
stdout=subprocess.DEVNULL)
for _ in range(30):
time.sleep(3)
view = running() and device_view(host, port)
# A new client hello raises the connection generation and reports the installed version;
# only a heartbeat after it (new last contact) shows that telemetry actually flows.
if (view and view['installed'].get('agent_version') == meta['version']
and int(view['installed']['connection_generation']) > generation
and view['installed'].get('last_contact_at') not in (None, contact)):
print(f'Fertig. Das Gerät meldet sich mit Version {view["installed"]["agent_version"]} '
'und erscheint in der WebUI unter Geräte.')
return
stop('Der Dienst läuft, sendet aber keinen Heartbeat. '
'Diagnose: grep discovery-agent /var/log/system/latest.log | tail')
if __name__ == '__main__':
main()