rmm2/agent-bsd/README.md

# RMM Agent BSD (OPNsense)

FreeBSD/OPNsense Agent für das RMM-System. Läuft als OPNsense-Plugin und liefert
Systemdaten via Heartbeat sowie Remote-Commands über WebSocket.

## Unterstützte Systeme

- OPNsense (FreeBSD, amd64)

---

## 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 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 Frontend zeigt nach dem Upload den fertigen Installationsbefehl mit Copy-Button.

### 3. Installer auf der Firewall ausführen

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

### 4. Im WebGUI konfigurieren

**Services → RMM Agent** öffnen und eintragen:

| Feld | Beschreibung |
|------|-------------|
| Backend URL | `https://BACKEND_IP:8443` |
| 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
# /usr/local/etc/rmm-agent/config.yaml
backend_url: "https://BACKEND_IP:8443"
api_key: "DEIN_API_KEY"
agent_name: "OPN.intra.kunde.de"
insecure: true   # false wenn gültiges TLS-Zertifikat vorhanden
```

---

## Service-Management (FreeBSD)

```bash
# Agent
service rmm-agent status
service rmm-agent start | stop | 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 |
|-----------|-------|
| Hardware | Hersteller, Modell, Seriennummer, BIOS |
| CPU | Modell, Cores, Threads, Auslastung |
| Memory | Total, Used, Free |
| Disks | ZFS Datasets, Belegung, Mountpoints |
| Network | Interfaces, IPs, Status, MAC, Statistiken |
| Services | Laufende OPNsense-Dienste |
| WireGuard | Tunnel, Peers, Transfer, Handshake |
| DHCP | Aktive Leases (KEA/ISC/dnsmasq) |
| Routing | Routing-Tabelle |
| Gateways | Status, RTT, Loss |
| Zertifikate | Ablaufdatum, Aussteller |
| Plugins | Installierte OPNsense-Plugins |
| Updates | Verfügbare Core + Package Updates |
| Cron | System-Crontab + OPNsense Jobs |

---

## Remote-Commands (via WebSocket)

| Command | Beschreibung |
|---------|-------------|
| `exec` | Beliebigen Shell-Befehl ausführen |
| `backup` | config.xml sichern |
| `update` | OPNsense Update (Core + Packages) |
| `major_update` | Major-Upgrade (2-Phasen) |
| `reboot` | Neustart |
| `tunnel_connect` | TCP-Tunnel öffnen (SSH, WebGUI, etc.) |
| `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`
- `daemon` statt `nohup` für Hintergrundprozesse
- `csh` hat kein `$()` — Agent verwendet `/bin/sh -c`
- OPNsense Plugin-Cache nach View-Änderungen leeren
- PHP-Fehlerlog: `/var/log/php-fpm.log`