Add an HTTPS installer for the OPNsense agent and show its command in the WebUI

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-21 09:25:51 +01:00
co-authored by Claude Opus 5.5
parent 20bf40adce
commit 7201b18300
9 changed files with 468 additions and 10 deletions
+3 -1
View File
@@ -2,6 +2,7 @@
//! the tenant's one-time enrollment token until the final enrollment consumes it.
use super::*;
mod starter;
pub(super) mod opnsense;
pub(super) use starter::publish_missing as publish_starters;
@@ -135,7 +136,8 @@ pub(super) async fn issue(
.await?;
tx.commit().await?;
Ok(private_json(
json!({"token":token,"expires_at":expires,"bootstrap_origin":bootstrap_origin,"release_platforms":release_platforms}),
json!({"token":token,"expires_at":expires,"bootstrap_origin":bootstrap_origin,"release_platforms":release_platforms,
"opnsense_installer":opnsense::available()}),
))
}
async fn token_tenant(s: &crate::State, h: &HeaderMap) -> Result<Uuid, Error> {
+105
View File
@@ -0,0 +1,105 @@
//! HTTPS installation of the OPNsense agent. The program files are a fixed
//! bundle in the release configuration (`opnsense/` next to the Linux bootstrap
//! file). The public script holds no credentials; the bundle is served only
//! against a valid one-time enrollment token, until enrollment consumes it.
use super::*;
use std::collections::BTreeMap;
/// Files the installer needs; `rmm-opnsense-jobs` (script worker) is optional.
const REQUIRED: [&str; 3] = ["agent.pyz", "collect.pyz", "discovery_agent"];
const OPTIONAL: [&str; 1] = ["rmm-opnsense-jobs"];
const MAX_FILE_BYTES: u64 = 32 * 1024 * 1024;
#[derive(Deserialize, serde::Serialize, Clone)]
#[serde(deny_unknown_fields)]
pub(super) struct File {
sha256: String,
bytes: u64,
}
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct Manifest {
schema_version: u32,
version: String,
files: BTreeMap<String, File>,
}
fn bundle_dir() -> Result<std::path::PathBuf, Error> {
std::env::var_os("RMM_AGENT_BOOTSTRAP_LINUX_FILE")
.and_then(|slot| FsPath::new(&slot).parent().map(|p| p.join("opnsense")))
.ok_or_else(|| fail("BOOTSTRAP_NOT_CONFIGURED"))
}
fn manifest() -> Result<Manifest, Error> {
let raw = protected_file(&bundle_dir()?.join("manifest.json"), 8192)?;
let m: Manifest = serde_json::from_slice(&raw).map_err(|_| fail("OPNSENSE_BUNDLE_INVALID"))?;
valid(&m).then_some(m).ok_or_else(|| fail("OPNSENSE_BUNDLE_INVALID"))
}
fn valid(m: &Manifest) -> bool {
m.schema_version == 1
&& (1..=64).contains(&m.version.len())
&& m.version.bytes().all(|b| b.is_ascii_alphanumeric() || b"._-".contains(&b))
&& REQUIRED.iter().all(|name| m.files.contains_key(*name))
&& m.files.iter().all(|(name, f)| {
(REQUIRED.contains(&name.as_str()) || OPTIONAL.contains(&name.as_str()))
&& rmm_domain::agent_update::digest(&f.sha256)
&& (1..=MAX_FILE_BYTES).contains(&f.bytes)
})
}
/// Whether the enrollment dialog can offer the OPNsense command.
pub(super) fn available() -> bool {
manifest().is_ok()
}
pub(crate) async fn current(State(s): State<crate::State>, headers: HeaderMap) -> Result<Response, Error> {
let tenant = token_tenant(&s, &headers).await?;
let m = manifest()?;
// The device gateway is the same for every platform; the Linux slot names it.
let gateway = config(&s, Platform::LinuxX64, tenant, None).await?.gateway_origin;
let ca = s.signer.as_ref().ok_or_else(missing)?.ca.to_pem().map_err(|_| invalid())?;
let trust = device_trust_data(&s)?;
Ok(private_json(json!({"schema_version":1,"tenant_id":tenant,"version":m.version,"gateway_origin":gateway,
"ca_pem":String::from_utf8(ca).map_err(|_| invalid())?,
"job_signing_public_key_hex":trust["job_signing_public_key_hex"],"files":m.files})))
}
pub(crate) async fn file(
State(s): State<crate::State>,
headers: HeaderMap,
Path(name): Path<String>,
) -> Result<Response, Error> {
token_tenant(&s, &headers).await?;
let expected = manifest()?.files.remove(&name).ok_or_else(missing)?;
let raw = protected_file(&bundle_dir()?.join(&name), MAX_FILE_BYTES)?;
if raw.len() as u64 != expected.bytes || hex::encode(openssl::sha::sha256(&raw)) != expected.sha256 {
return Err(fail("OPNSENSE_BUNDLE_INVALID"));
}
Ok(([("content-type", "application/octet-stream"), ("cache-control", "private, no-store"),
("x-content-type-options", "nosniff")], raw).into_response())
}
#[cfg(test)]
mod tests {
use super::*;
fn bundle(files: &[(&str, u64)]) -> Manifest {
Manifest { schema_version: 1, version: "0.1.0-opnsense.6".into(),
files: files.iter().map(|(n, b)| (n.to_string(), File { sha256: "a".repeat(64), bytes: *b })).collect() }
}
#[test]
fn bundle_needs_the_program_files_and_accepts_only_known_names() {
let base = [("agent.pyz", 10), ("collect.pyz", 10), ("discovery_agent", 10)];
assert!(valid(&bundle(&base)));
assert!(valid(&bundle(&[base[0], base[1], base[2], ("rmm-opnsense-jobs", 10)])));
assert!(!valid(&bundle(&base[..2])));
assert!(!valid(&bundle(&[base[0], base[1], base[2], ("../ca.pem", 10)])));
assert!(!valid(&bundle(&[base[0], base[1], ("discovery_agent", 0)])));
assert!(!valid(&bundle(&[base[0], base[1], ("discovery_agent", MAX_FILE_BYTES + 1)])));
let mut bad = bundle(&base);
bad.version = "1.0 ; rm".into();
assert!(!valid(&bad));
}
}
+13
View File
@@ -0,0 +1,13 @@
#!/bin/sh
# OPNsense (FreeBSD amd64). Usage as root: sh opnsense.sh https://bootstrap.example
set -eu
umask 077
if [ "$(id -u)" != 0 ]; then
echo 'Bitte als root ausfuehren (Konsole: Option 8, Shell).' >&2; exit 1
fi
if [ "$(uname -s)" != FreeBSD ] || [ ! -x /usr/local/sbin/opnsense-version ] || [ ! -x /usr/local/bin/python3 ]; then
echo 'Dieses Installationsskript ist nur fuer OPNsense.' >&2; exit 1
fi
work=$(mktemp -d /var/tmp/discovery-install.XXXXXX)
trap 'rm -rf "$work"' EXIT
cat >"$work/install-files.sh" <<'RMM_OPNSENSE_FILES'
@@ -0,0 +1,199 @@
"""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 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.')
if (APP / 'rmm-opnsense-jobs').is_file() and not BINDING.exists():
bind_jobs(meta, host, port)
print('Skriptausführung für diese Installation gebunden.')
before = device_view(host, port) if existing else None
generation = int(before['installed']['connection_generation']) if before else -1
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.
if (view and view['installed'].get('agent_version') == meta['version']
and int(view['installed']['connection_generation']) > generation):
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, hat sich aber noch nicht beim Server gemeldet. '
'Diagnose: tail /var/log/messages und service discovery_agent restart.')
if __name__ == '__main__':
main()