docs: FIRMWARE.md komplett überarbeitet — Installer-ZIP vs. Agent-Binary klar getrennt, make release dokumentiert
This commit is contained in:
cynfo3000
parent
72dadf19b1
commit
f0e06a93df
@ -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
|
||||
|
||||
158
docs/FIRMWARE.md
158
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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user