rmm2/docs/AGENT.md

Agent — Installation & Konfiguration

Der RMM-Agent laeuft auf OPNsense (FreeBSD) und wird als OPNsense-Plugin mit WebGUI-Konfiguration installiert.

Komponenten

• Collectors: Hardware, CPU, Memory, Disk, Network, Services, WireGuard, DHCP, Routing, Gateways, Zertifikate, Plugins, Updates, Cron
• WebSocket Client: Persistente Verbindung zum Backend, automatisches Reconnect mit Backoff
• Command Handler: Remote-Befehlsausfuehrung, Tunnel-Connect/Disconnect
• Tunnel Manager: Session-basierte TCP-Verbindungen zu lokalen Diensten

1. Agent bauen

make agent    # Erzeugt build/rmm-agent (freebsd/amd64)

2. Plugin installieren

# Binary + Installer auf die Firewall kopieren
scp build/rmm-agent root@OPNSENSE:/tmp/
scp opnsense-plugin/install.sh root@OPNSENSE:/tmp/

# Installer ausfuehren
ssh root@OPNSENSE '/bin/sh /tmp/install.sh'

Der Installer richtet alles ein:

• Binary nach /usr/local/rmm/rmm-agent
• rc.d Service (/usr/local/etc/rc.d/rmm_agent)
• OPNsense MVC Plugin (Model, Controller, View)
• configd Actions (start/stop/restart/status/reconfigure)
• Plugin-Hook fuer Service-Integration
• Setup-Script das Config aus dem Model generiert

3. WebGUI konfigurieren

1. OPNsense WebGUI oeffnen
2. Services > RMM Agent
3. Felder ausfuellen:
   • Aktiviert: Ankreuzen
   • Backend URL: https://BACKEND_IP:8443
   • API Key: Backend API-Key eintragen
   • Agent Name: Optional (Standard: Hostname)
   • Heartbeat Intervall: 60 (Sekunden)
   • Self-Signed Zertifikate: Ankreuzen bei self-signed Backend-Certs
4. Speichern & Anwenden klicken

Der Agent startet automatisch und meldet sich am Backend an.

OPNsense Plugin WebGUI Fix (v1.0.3)

Der SettingsController wurde gefixt:

• Config-Parsing: Korrektes Parsen von rmmagent[general][KEY] Formular-Feldern (OPNsense MVC-Konvention)
• Initialer config.xml Eintrag: Beim ersten Speichern wird automatisch der <rmmagent> Knoten in der config.xml angelegt

4. Verifizieren

# Status in der WebGUI: Badge zeigt "Running"

# Oder per SSH:
ssh root@OPNSENSE 'service rmm_agent status'

# Auf dem Backend: Agent sollte erscheinen
curl -sk -H "X-API-Key: DEIN_API_KEY" https://BACKEND_IP:8443/api/v1/agents

Pre-Registration

Firewalls koennen vorab im System registriert werden, bevor der Agent installiert wird:

1. Im Frontend auf "Firewall hinzufuegen" klicken (oder POST /api/v1/agents)
2. Name und optionalen Kunden angeben
3. Agent wird mit hostname="(ausstehend)" angelegt
4. Bei der eigentlichen Agent-Registration wird automatisch nach Name gematcht (GetAgentByName)
5. Der pre-registrierte Eintrag wird mit den echten Agent-Daten aktualisiert

Agent-Update (via Updater — empfohlen)

Der rmm-updater ist ein separater Daemon, der auf jeder Firewall neben dem Agent laeuft. Er prueft alle 60 Sekunden ob ein Update ansteht und fuehrt es automatisch durch.

Flow:

1. Neue Agent-Binary im Frontend hochladen (Firmware-Seite)
2. Update-Button bei einzelnem Agent oder "Alle updaten" klicken
3. Updater erkennt den Flag, laedt die Binary vom Backend, stoppt Agent, ersetzt Binary, startet Agent
4. Flag wird automatisch zurueckgesetzt

Technische Details:

• Separates Go-Binary (rmm-updater), laeuft als rmm_updater rc.d Service
• Liest die gleiche config.yaml wie der Agent (Backend-URL, API-Key)
• Download ueber GET /api/v1/firmware/download?platform=freebsd
• SHA256-Verifizierung vor Ersetzung
• Automatisches Rollback bei fehlgeschlagenem Agent-Start
• Backup der alten Binary als .bak waehrend des Updates
• Logs: /var/log/rmm-updater.log

Manuelles Update (Fallback):

make agent
scp build/rmm-agent root@OPNSENSE:/tmp/
ssh root@OPNSENSE '/bin/sh -c "service rmm_agent stop; cp /tmp/rmm-agent /usr/local/rmm/rmm-agent; chmod +x /usr/local/rmm/rmm-agent; service rmm_agent start"'

Oder Plugin komplett neu installieren (install.sh ist idempotent — installiert Agent + Updater).

Service-Filter (v1.0.3)

Boot- und Init-Scripts werden nicht mehr in der Dienste-Liste angezeigt:

• Gefiltert: bgfsck, cleanvar, dmesg, hostid, ldconfig, motd, newsyslog, ntpd, resolv, syslogd, var und andere System-Boot-Scripts
• Angezeigt: Nur echte OPNsense-Dienste (OpenVPN, Unbound, DHCPd, WireGuard, etc.)
• pluginctl wird mit vollem Pfad /usr/local/sbin/pluginctl aufgerufen (FreeBSD-Kompatibilitaet)

Hinweise

• Agent-ID wird persistent in /usr/local/rmm/agent_id gespeichert — ueberlebt Neuinstallationen
• Config wird bei "Speichern & Anwenden" aus dem OPNsense-Model nach /usr/local/rmm/config.yaml generiert
• Logs: /var/log/rmm-agent.log
• PID-File: /var/run/rmm_agent.pid
• Agent braucht root auf OPNsense (fuer Hardware-/Service-Daten)
• OPNsense WebGUI typischerweise auf Port 4444 (nicht 443)