From f0e06a93df71bc047c68fe70b5bbec309e0b9ec4 Mon Sep 17 00:00:00 2001 From: cynfo3000 Date: Fri, 6 Mar 2026 09:54:07 +0100 Subject: [PATCH] =?UTF-8?q?docs:=20FIRMWARE.md=20komplett=20=C3=BCberarbei?= =?UTF-8?q?tet=20=E2=80=94=20Installer-ZIP=20vs.=20Agent-Binary=20klar=20g?= =?UTF-8?q?etrennt,=20make=20release=20dokumentiert?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- agent-bsd/README.md | 25 +++++-- docs/FIRMWARE.md | 158 ++++++++++++++++++++++++++++++++------------ 2 files changed, 136 insertions(+), 47 deletions(-) diff --git a/agent-bsd/README.md b/agent-bsd/README.md index 3720c30..4f9918a 100644 --- a/agent-bsd/README.md +++ b/agent-bsd/README.md @@ -18,14 +18,29 @@ make agent # Baut das FreeBSD-Binary make plugin # Paketiert das OPNsense-Plugin (.pkg) ``` -### 2. Installationsskript auf der Firewall ausführen +### 2. Installer-ZIP im Frontend hochladen -Das Skript lädt Binary und Plugin direkt vom Backend-Server per `fetch` (FreeBSD-nativ): +**Frontend → Firmware → Installer-Pakete → freebsd → ZIP hochladen** + +Das ZIP enthält: `rmm-agent` + `rmm-updater-freebsd` + `install.sh` ```bash -# Auf der OPNsense-Firewall (SSH als root) -fetch -o /tmp/install.sh https://BACKEND_IP:8443/api/v1/installers/freebsd/install.sh -/bin/sh /tmp/install.sh +# ZIP bauen (auf dem Build-Server) +cd /opt/rmm +make release VERSION=1.0.3 +# → build/release/rmm-freebsd-1.0.3.zip +``` + +### 3. Installer auf der Firewall ausführen + +Das Frontend zeigt nach dem Upload den fertigen Befehl mit Copy-Button. +Auf der OPNsense-Firewall (SSH als root): + +```bash +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 ``` ### 3. Im WebGUI konfigurieren diff --git a/docs/FIRMWARE.md b/docs/FIRMWARE.md index caa6586..b61f791 100644 --- a/docs/FIRMWARE.md +++ b/docs/FIRMWARE.md @@ -2,66 +2,140 @@ Multi-Plattform Firmware-Verwaltung fuer Agent-Binaries und OPNsense-Updates. -## Agent-Firmware (Binary-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 + +```bash +# 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: + +```bash +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): + +```bash +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 -Der Update-Prozess fuer Agent-Binaries nutzt den **rmm-updater** Daemon: +Fuer Updates auf bereits installierten Agents — der `rmm-updater` Daemon holt das neue Binary selbststaendig vom Backend. -1. Neue Agent-Binary im Frontend hochladen (Firmware-Seite) oder per API +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: + +```bash +# 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 + +```bash +# 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-basierte Agents | -| `windows` | `rmm-agent.exe` | Windows-basierte Agents | - -### API-Endpoints - -| Methode | Endpoint | Beschreibung | -|---------|----------|-------------| -| GET | `/api/v1/firmware` | Alle Firmware-Versionen (pro Plattform) | -| GET | `/api/v1/firmware?platform=freebsd` | Firmware einer Plattform | -| POST | `/api/v1/firmware/upload?version=X&platform=Y` | Binary hochladen (Body = Raw Binary) | -| GET | `/api/v1/firmware/download?platform=Y` | Binary herunterladen (fuer Updater) | -| 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` | Update-Flag fuer alle Agents setzen | -| POST | `/api/v1/agents/{id}/agent-update` | Legacy: Binary direkt via WebSocket pushen | - -### Beispiele - -```bash -# FreeBSD Agent 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 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 fuer einzelnen Agent anfordern -curl -sk -X POST "https://your-backend:8443/api/v1/agents/e92e87a6.../request-update" \ - -H "X-API-Key: YOUR_API_KEY" - -# Update fuer alle Agents anfordern -curl -sk -X POST "https://your-backend:8443/api/v1/agents/request-update-all" \ - -H "X-API-Key: YOUR_API_KEY" -``` +| `linux` | `rmm-agent-linux` | Linux/Proxmox Agents | ### Updater — 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) +- 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