From 8e831e241a153356546d4e87eb67e23d8ffaa76f Mon Sep 17 00:00:00 2001 From: cynfo3000 Date: Fri, 6 Mar 2026 09:58:50 +0100 Subject: [PATCH] =?UTF-8?q?docs:=20FIRMWARE.md=20in=20agent-bsd/README.md?= =?UTF-8?q?=20zusammengef=C3=BChrt=20und=20gel=C3=B6scht?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- agent-bsd/README.md | 138 ++++++++++++++++++++++++++----- docs/FIRMWARE.md | 195 -------------------------------------------- 2 files changed, 119 insertions(+), 214 deletions(-) delete mode 100644 docs/FIRMWARE.md diff --git a/agent-bsd/README.md b/agent-bsd/README.md index 4f9918a..fa28223 100644 --- a/agent-bsd/README.md +++ b/agent-bsd/README.md @@ -7,33 +7,28 @@ Systemdaten via Heartbeat sowie Remote-Commands über WebSocket. - OPNsense (FreeBSD, amd64) -## Installation via OPNsense Plugin +--- -### 1. Repo klonen und Plugin bauen (auf dem Backend-Server) +## Installation (Erstinstallation) + +### 1. Repo klonen und Release bauen (auf dem Build-Server) ```bash git clone https://git.cynfo.net/christian/rmm2.git /opt/rmm cd /opt/rmm -make agent # Baut das FreeBSD-Binary -make plugin # Paketiert das OPNsense-Plugin (.pkg) +make release VERSION=1.0.3 +# → build/release/rmm-freebsd-1.0.3.zip +# enthält: rmm-agent + rmm-updater-freebsd + install.sh ``` ### 2. Installer-ZIP im Frontend hochladen **Frontend → Firmware → Installer-Pakete → freebsd → ZIP hochladen** -Das ZIP enthält: `rmm-agent` + `rmm-updater-freebsd` + `install.sh` - -```bash -# ZIP bauen (auf dem Build-Server) -cd /opt/rmm -make release VERSION=1.0.3 -# → build/release/rmm-freebsd-1.0.3.zip -``` +Das Frontend zeigt nach dem Upload den fertigen Installationsbefehl mit Copy-Button. ### 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 @@ -43,7 +38,7 @@ fetch --no-verify-peer --no-verify-hostname \ && cd /tmp && unzip -o installer.zip && sh /tmp/install.sh ``` -### 3. Im WebGUI konfigurieren +### 4. Im WebGUI konfigurieren **Services → RMM Agent** öffnen und eintragen: @@ -53,6 +48,102 @@ fetch --no-verify-peer --no-verify-hostname \ | API Key | API-Key aus `backend/config.yaml` | | Agent Name | Anzeigename im RMM-Frontend | +--- + +## Agent-Binary aktualisieren (OTA) + +Für Updates auf bereits installierten Agents übernimmt der `rmm-updater` Daemon die Verteilung automatisch. + +### Ablauf + +1. Neues 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 heruntergeladen und SHA256-verifiziert +5. Agent wird gestoppt, Binary ersetzt, Agent gestartet +6. Flag wird automatisch zurückgesetzt + +### Binary bauen und hochladen + +```bash +cd /opt/rmm +make agent VERSION=1.0.4 +# → build/rmm-agent +``` + +**Frontend → Firmware → Agent-Binary → Version + freebsd → Binary hochladen** + +Oder per API: + +```bash +curl -sk -X POST "https://BACKEND_IP:8443/api/v1/firmware/upload?version=1.0.4&platform=freebsd" \ + -H "X-API-Key: DEIN_API_KEY" \ + --data-binary @build/rmm-agent +``` + +### Update auslösen + +```bash +# Einzelnen Agent updaten +curl -sk -X POST "https://BACKEND_IP:8443/api/v1/agents/AGENT_ID/request-update" \ + -H "X-API-Key: DEIN_API_KEY" + +# Alle Agents updaten +curl -sk -X POST "https://BACKEND_IP:8443/api/v1/agents/request-update-all" \ + -H "X-API-Key: DEIN_API_KEY" +``` + +### Updater-Details + +- Binary: `rmm-updater-freebsd`, läuft als `rmm_updater` rc.d Service +- Liest dieselbe `config.yaml` wie der Agent +- SHA256-Verifizierung vor Ersetzung +- Automatisches Rollback bei fehlgeschlagenem Agent-Start +- Backup der alten Binary als `.bak` +- Logs: `/var/log/rmm-updater.log` + +--- + +## OPNsense-Updates (Core + Packages) + +### Normales Update (Patches innerhalb der gleichen Version) + +Über **Frontend → Firewall → Agent-Tab → Update** oder per API: + +```bash +curl -sk -H "X-API-Key: DEIN_API_KEY" -X POST \ + https://BACKEND_IP:8443/api/v1/agents/AGENT_ID/update \ + -d '{"reboot":true}' +``` + +Ablauf im Agent: +1. `opnsense-update` — Core-Update herunterladen +2. `pkg upgrade -y` — Paket-Updates installieren +3. Prüfung ob Reboot nötig (`opnsense-update -c`) + +### Major-Upgrade (z.B. 25.7 → 26.1) + +```bash +# Phase 1: Base + Kernel + Packages herunterladen, dann Reboot +curl -sk -H "X-API-Key: DEIN_API_KEY" -X POST \ + https://BACKEND_IP:8443/api/v1/agents/AGENT_ID/major-update \ + -d '{"version":"26.1","reboot":true}' + +# Phase 2: nach Reboot — Pakete finalisieren +curl -sk -H "X-API-Key: DEIN_API_KEY" -X POST \ + https://BACKEND_IP:8443/api/v1/agents/AGENT_ID/major-update \ + -d '{"version":"26.1","phase":"2"}' +``` + +### Update-Check + +```bash +curl -sk -H "X-API-Key: DEIN_API_KEY" -X POST \ + https://BACKEND_IP:8443/api/v1/agents/AGENT_ID/update-check +``` + +--- + ## Konfigurationsdatei ```yaml @@ -63,21 +154,26 @@ agent_name: "OPN.intra.kunde.de" insecure: true # false wenn gültiges TLS-Zertifikat vorhanden ``` +--- + ## Service-Management (FreeBSD) ```bash -# Status +# Agent service rmm-agent status +service rmm-agent start | stop | restart -# Start / Stop / Restart -service rmm-agent start -service rmm-agent stop -service rmm-agent restart +# Updater +service rmm_updater status +service rmm_updater start | stop | restart # Logs tail -f /var/log/rmm-agent.log +tail -f /var/log/rmm-updater.log ``` +--- + ## Gesammelte Daten (Heartbeat alle 60s) | Collector | Daten | @@ -97,6 +193,8 @@ tail -f /var/log/rmm-agent.log | Updates | Verfügbare Core + Package Updates | | Cron | System-Crontab + OPNsense Jobs | +--- + ## Remote-Commands (via WebSocket) | Command | Beschreibung | @@ -110,6 +208,8 @@ tail -f /var/log/rmm-agent.log | `wg_add_peer` | WireGuard-Peer anlegen | | `wg_delete_peer` | WireGuard-Peer löschen | +--- + ## Hinweise (FreeBSD) - Volle Pfade verwenden: `/usr/local/sbin/pluginctl`, `/usr/bin/netstat` diff --git a/docs/FIRMWARE.md b/docs/FIRMWARE.md deleted file mode 100644 index b61f791..0000000 --- a/docs/FIRMWARE.md +++ /dev/null @@ -1,195 +0,0 @@ -# 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 - -```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 - -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: - -```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/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 -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 - -```bash -# 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 -```