rmm2/docs/FIRMWARE.md

Firmware-Management & Update-Prozess

Multi-Plattform Firmware-Verwaltung fuer Agent-Binaries und OPNsense-Updates.

Die Firmware-Seite im Frontend hat zwei unabhaengige Bereiche:

Bereich	Zweck	Format
Agent-Binary	OTA-Updates auf bestehenden Agents	Raw Binary (kein ZIP)
Installer-Paket	Erstinstallation auf neuen Geraeten	ZIP (Agent + Updater + install.sh)

---

1. Installer-Paket (Erstinstallation)

Inhalt des ZIP

Das Installer-ZIP enthaelt beide Binaries + Installationsskript:

rmm-freebsd-1.0.3.zip
├── rmm-agent          ← Agent-Binary (FreeBSD)
├── rmm-updater-freebsd ← Updater-Binary (FreeBSD)
└── install.sh         ← Installationsskript

ZIP bauen

# Auf dem Build-Server (Linux mit Go 1.24+)
cd /opt/rmm
make release VERSION=1.0.3
# → build/release/rmm-freebsd-1.0.3.zip
# → build/release/rmm-linux-1.0.3.zip

ZIP im Frontend hochladen

Frontend → Firmware → Installer-Pakete → Plattform waehlen → ZIP hochladen

Oder per API:

curl -sk -X POST "https://your-backend:8443/api/v1/installer/upload?platform=freebsd" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@build/release/rmm-freebsd-1.0.3.zip"

Erstinstallation auf neuem Geraet (OPNsense)

Nach dem Upload zeigt das Frontend den fertigen Installationsbefehl mit Copy-Button. Auf der OPNsense-Firewall (SSH als root):

fetch --no-verify-peer --no-verify-hostname \
  -o /tmp/installer.zip \
  "https://BACKEND_IP:8443/api/v1/installer/download?platform=freebsd&api_key=DEIN_API_KEY" \
&& cd /tmp && unzip -o installer.zip && sh /tmp/install.sh

API-Endpoints (Installer)

Methode	Endpoint	Beschreibung
GET	/api/v1/installer	Hochgeladene Installer-Pakete anzeigen
POST	/api/v1/installer/upload?platform=X	ZIP hochladen
GET	/api/v1/installer/download?platform=X&api_key=Y	ZIP herunterladen (fuer Firewall)

---

2. Agent-Binary (OTA-Updates bestehender Agents)

Ueberblick

Fuer Updates auf bereits installierten Agents — der rmm-updater Daemon holt das neue Binary selbststaendig vom Backend.

Ablauf:

1. Neue Agent-Binary im Frontend hochladen (nur das Binary, kein ZIP)
2. Update-Flag bei einzelnem Agent oder "Alle updaten" setzen
3. Updater auf der Firewall erkennt den Flag (pollt alle 60s)
4. Binary wird vom Backend heruntergeladen und SHA256-verifiziert
5. Agent wird gestoppt, Binary ersetzt, Agent gestartet
6. Flag wird automatisch zurueckgesetzt

Binary im Frontend hochladen

Frontend → Firmware → Agent-Binary → Version + Plattform → Binary hochladen

Oder per API:

# FreeBSD Agent-Binary hochladen
curl -sk -X POST "https://your-backend:8443/api/v1/firmware/upload?version=1.0.3&platform=freebsd" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-binary @build/rmm-agent

# Linux Agent-Binary hochladen
curl -sk -X POST "https://your-backend:8443/api/v1/firmware/upload?version=1.0.3&platform=linux" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-binary @build/rmm-agent-linux

Update ausloesen

# Einzelnen Agent updaten
curl -sk -X POST "https://your-backend:8443/api/v1/agents/AGENT_ID/request-update" \
  -H "X-API-Key: YOUR_API_KEY"

# Alle Agents updaten
curl -sk -X POST "https://your-backend:8443/api/v1/agents/request-update-all" \
  -H "X-API-Key: YOUR_API_KEY"

API-Endpoints (Agent-Binary)

Methode	Endpoint	Beschreibung
GET	/api/v1/firmware	Alle hochgeladenen Binaries
GET	/api/v1/firmware?platform=freebsd	Binaries einer Plattform
POST	/api/v1/firmware/upload?version=X&platform=Y	Binary hochladen (Raw)
GET	/api/v1/firmware/download?platform=Y	Binary herunterladen (Updater intern)
POST	/api/v1/agents/{id}/request-update	Update-Flag setzen
DELETE	/api/v1/agents/{id}/request-update	Update-Flag zuruecksetzen
POST	/api/v1/agents/request-update-all	Alle Agents updaten

Unterstuetzte Plattformen

Plattform	Binary	Ziel
freebsd	rmm-agent	OPNsense Firewalls (amd64)
linux	rmm-agent-linux	Linux/Proxmox Agents

Updater — Technische Details

• Separates Go-Binary (rmm-updater-freebsd), laeuft als rmm_updater rc.d Service
• Liest dieselbe config.yaml wie der Agent (Backend-URL, API-Key)
• Prueft alle 60s ob update_requested = true fuer den eigenen Agent
• 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

OPNsense-Updates (Core + Packages)

Normales Update

Patches innerhalb der gleichen Version:

1. opnsense-update — Core-Update herunterladen
2. pkg upgrade -y — Paket-Updates installieren
3. Nachpruefung: opnsense-update -c — Exit 1 = Reboot noetig

Response enthaelt reboot_required: true/false fuer das Frontend.

Major-Upgrade

z.B. 25.7 → 26.1:

1. opnsense-update -r <version> -bkp — Repository wechseln + Base + Kernel + Packages herunterladen
2. pkg-static update -f — Repository-Katalog forciert aktualisieren
3. pkg-static upgrade -y — Alle Pakete auf neue Version installieren
4. Reboot erforderlich (immer bei Major-Upgrade)

API-Endpoints

Methode	Endpoint	Beschreibung
POST	/api/v1/agents/{id}/update-check	Verfuegbare Updates pruefen
POST	/api/v1/agents/{id}/update	Normales Update (Core + Packages)
POST	/api/v1/agents/{id}/major-update	Major-Upgrade auf Zielversion
POST	/api/v1/agents/{id}/reboot	Reboot ausfuehren

Beispiele

# Verfuegbare Updates pruefen
curl -sk -H "X-API-Key: YOUR_API_KEY" -X POST \
  https://your-backend:8443/api/v1/agents/e92e87a684b20db15d8d2344583c5887/update-check

# Normales Update mit Reboot
curl -sk -H "X-API-Key: YOUR_API_KEY" -X POST \
  https://your-backend:8443/api/v1/agents/e92e87a684b20db15d8d2344583c5887/update \
  -d '{"reboot":true}'

# Major-Upgrade auf Version 26.7
curl -sk -H "X-API-Key: YOUR_API_KEY" -X POST \
  https://your-backend:8443/api/v1/agents/e92e87a684b20db15d8d2344583c5887/major-update \
  -d '{"version":"26.7","reboot":true}'

# Reboot (5s Verzoegerung default)
curl -sk -H "X-API-Key: YOUR_API_KEY" -X POST \
  https://your-backend:8443/api/v1/agents/e92e87a684b20db15d8d2344583c5887/reboot