christian/rmm2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: FIRMWARE.md in agent-bsd/README.md zusammengeführt und gelöscht

Browse Source
This commit is contained in:
cynfo3000 2026-03-06 09:58:50 +01:00
parent afed19724d
commit 8e831e241a
2 changed files with 119 additions and 214 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

138
agent-bsd/README.md
View File

@ -7,33 +7,28 @@ Systemdaten via Heartbeat sowie Remote-Commands über WebSocket.
- OPNsense (FreeBSD, amd64) - 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 ```bash
git clone https://git.cynfo.net/christian/rmm2.git /opt/rmm git clone https://git.cynfo.net/christian/rmm2.git /opt/rmm
cd /opt/rmm cd /opt/rmm
make agent # Baut das FreeBSD-Binary make release VERSION=1.0.3
make plugin # Paketiert das OPNsense-Plugin (.pkg) # → build/release/rmm-freebsd-1.0.3.zip
# enthält: rmm-agent + rmm-updater-freebsd + install.sh
``` ```
### 2. Installer-ZIP im Frontend hochladen ### 2. Installer-ZIP im Frontend hochladen
**Frontend → Firmware → Installer-Pakete → freebsd → ZIP hochladen** **Frontend → Firmware → Installer-Pakete → freebsd → ZIP hochladen**
Das ZIP enthält: `rmm-agent` + `rmm-updater-freebsd` + `install.sh` Das Frontend zeigt nach dem Upload den fertigen Installationsbefehl mit Copy-Button.
```bash
# 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 ### 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): Auf der OPNsense-Firewall (SSH als root):
```bash ```bash
@ -43,7 +38,7 @@ fetch --no-verify-peer --no-verify-hostname \
&& cd /tmp && unzip -o installer.zip && sh /tmp/install.sh && cd /tmp && unzip -o installer.zip && sh /tmp/install.sh
``` ```
### 3. Im WebGUI konfigurieren ### 4. Im WebGUI konfigurieren
**Services → RMM Agent** öffnen und eintragen: **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` | | API Key | API-Key aus `backend/config.yaml` |
| Agent Name | Anzeigename im RMM-Frontend | | 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 ## Konfigurationsdatei
```yaml ```yaml
@ -63,21 +154,26 @@ agent_name: "OPN.intra.kunde.de"
insecure: true # false wenn gültiges TLS-Zertifikat vorhanden insecure: true # false wenn gültiges TLS-Zertifikat vorhanden
``` ```
---
## Service-Management (FreeBSD) ## Service-Management (FreeBSD)
```bash ```bash
# Status # Agent
service rmm-agent status service rmm-agent status
service rmm-agent start | stop | restart
# Start / Stop / Restart # Updater
service rmm-agent start service rmm_updater status
service rmm-agent stop service rmm_updater start | stop | restart
service rmm-agent restart
# Logs # Logs
tail -f /var/log/rmm-agent.log tail -f /var/log/rmm-agent.log
tail -f /var/log/rmm-updater.log
``` ```
---
## Gesammelte Daten (Heartbeat alle 60s) ## Gesammelte Daten (Heartbeat alle 60s)
| Collector | Daten | | Collector | Daten |
@ -97,6 +193,8 @@ tail -f /var/log/rmm-agent.log
| Updates | Verfügbare Core + Package Updates | | Updates | Verfügbare Core + Package Updates |
| Cron | System-Crontab + OPNsense Jobs | | Cron | System-Crontab + OPNsense Jobs |
---
## Remote-Commands (via WebSocket) ## Remote-Commands (via WebSocket)
| Command | Beschreibung | | Command | Beschreibung |
@ -110,6 +208,8 @@ tail -f /var/log/rmm-agent.log
| `wg_add_peer` | WireGuard-Peer anlegen | | `wg_add_peer` | WireGuard-Peer anlegen |
| `wg_delete_peer` | WireGuard-Peer löschen | | `wg_delete_peer` | WireGuard-Peer löschen |
---
## Hinweise (FreeBSD) ## Hinweise (FreeBSD)
- Volle Pfade verwenden: `/usr/local/sbin/pluginctl`, `/usr/bin/netstat` - Volle Pfade verwenden: `/usr/local/sbin/pluginctl`, `/usr/bin/netstat`

195
docs/FIRMWARE.md
View File

@ -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 <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
```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
```