125 lines
4.8 KiB
Markdown
125 lines
4.8 KiB
Markdown
# Agent — Installation & Konfiguration
|
|
|
|
Der RMM-Agent laeuft auf OPNsense (FreeBSD) und wird als OPNsense-Plugin mit WebGUI-Konfiguration installiert.
|
|
|
|
## Komponenten
|
|
|
|
- **Collectors**: Hardware, CPU, Memory, Disk, Network, Services, WireGuard, DHCP, Routing, Gateways, Zertifikate, Plugins, Updates, Cron
|
|
- **WebSocket Client**: Persistente Verbindung zum Backend, automatisches Reconnect mit Backoff
|
|
- **Command Handler**: Remote-Befehlsausfuehrung, Tunnel-Connect/Disconnect
|
|
- **Tunnel Manager**: Session-basierte TCP-Verbindungen zu lokalen Diensten
|
|
|
|
## 1. Agent bauen
|
|
|
|
```bash
|
|
make agent # Erzeugt build/rmm-agent (freebsd/amd64)
|
|
```
|
|
|
|
## 2. Plugin installieren
|
|
|
|
```bash
|
|
# Binary + Installer auf die Firewall kopieren
|
|
scp build/rmm-agent root@OPNSENSE:/tmp/
|
|
scp opnsense-plugin/install.sh root@OPNSENSE:/tmp/
|
|
|
|
# Installer ausfuehren
|
|
ssh root@OPNSENSE '/bin/sh /tmp/install.sh'
|
|
```
|
|
|
|
Der Installer richtet alles ein:
|
|
- Binary nach `/usr/local/rmm/rmm-agent`
|
|
- rc.d Service (`/usr/local/etc/rc.d/rmm_agent`)
|
|
- OPNsense MVC Plugin (Model, Controller, View)
|
|
- configd Actions (start/stop/restart/status/reconfigure)
|
|
- Plugin-Hook fuer Service-Integration
|
|
- Setup-Script das Config aus dem Model generiert
|
|
|
|
## 3. WebGUI konfigurieren
|
|
|
|
1. OPNsense WebGUI oeffnen
|
|
2. **Services > RMM Agent**
|
|
3. Felder ausfuellen:
|
|
- **Aktiviert**: Ankreuzen
|
|
- **Backend URL**: `https://BACKEND_IP:8443`
|
|
- **API Key**: Backend API-Key eintragen
|
|
- **Agent Name**: Optional (Standard: Hostname)
|
|
- **Heartbeat Intervall**: 60 (Sekunden)
|
|
- **Self-Signed Zertifikate**: Ankreuzen bei self-signed Backend-Certs
|
|
4. **Speichern & Anwenden** klicken
|
|
|
|
Der Agent startet automatisch und meldet sich am Backend an.
|
|
|
|
### OPNsense Plugin WebGUI Fix (v1.0.3)
|
|
|
|
Der `SettingsController` wurde gefixt:
|
|
- **Config-Parsing**: Korrektes Parsen von `rmmagent[general][KEY]` Formular-Feldern (OPNsense MVC-Konvention)
|
|
- **Initialer config.xml Eintrag**: Beim ersten Speichern wird automatisch der `<rmmagent>` Knoten in der `config.xml` angelegt
|
|
|
|
## 4. Verifizieren
|
|
|
|
```bash
|
|
# Status in der WebGUI: Badge zeigt "Running"
|
|
|
|
# Oder per SSH:
|
|
ssh root@OPNSENSE 'service rmm_agent status'
|
|
|
|
# Auf dem Backend: Agent sollte erscheinen
|
|
curl -sk -H "X-API-Key: DEIN_API_KEY" https://BACKEND_IP:8443/api/v1/agents
|
|
```
|
|
|
|
## Pre-Registration
|
|
|
|
Firewalls koennen vorab im System registriert werden, bevor der Agent installiert wird:
|
|
|
|
1. Im Frontend auf "Firewall hinzufuegen" klicken (oder `POST /api/v1/agents`)
|
|
2. Name und optionalen Kunden angeben
|
|
3. Agent wird mit `hostname="(ausstehend)"` angelegt
|
|
4. Bei der eigentlichen Agent-Registration wird automatisch nach Name gematcht (`GetAgentByName`)
|
|
5. Der pre-registrierte Eintrag wird mit den echten Agent-Daten aktualisiert
|
|
|
|
## Agent-Update (via Updater — empfohlen)
|
|
|
|
Der **rmm-updater** ist ein separater Daemon, der auf jeder Firewall neben dem Agent laeuft.
|
|
Er prueft alle 60 Sekunden ob ein Update ansteht und fuehrt es automatisch durch.
|
|
|
|
**Flow:**
|
|
1. Neue Agent-Binary im Frontend hochladen (Firmware-Seite)
|
|
2. Update-Button bei einzelnem Agent oder "Alle updaten" klicken
|
|
3. Updater erkennt den Flag, laedt die Binary vom Backend, stoppt Agent, ersetzt Binary, startet Agent
|
|
4. Flag wird automatisch zurueckgesetzt
|
|
|
|
**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)
|
|
- 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`
|
|
|
|
**Manuelles Update (Fallback):**
|
|
|
|
```bash
|
|
make agent
|
|
scp build/rmm-agent root@OPNSENSE:/tmp/
|
|
ssh root@OPNSENSE '/bin/sh -c "service rmm_agent stop; cp /tmp/rmm-agent /usr/local/rmm/rmm-agent; chmod +x /usr/local/rmm/rmm-agent; service rmm_agent start"'
|
|
```
|
|
|
|
Oder Plugin komplett neu installieren (`install.sh` ist idempotent — installiert Agent + Updater).
|
|
|
|
## Service-Filter (v1.0.3)
|
|
|
|
Boot- und Init-Scripts werden nicht mehr in der Dienste-Liste angezeigt:
|
|
- **Gefiltert**: `bgfsck`, `cleanvar`, `dmesg`, `hostid`, `ldconfig`, `motd`, `newsyslog`, `ntpd`, `resolv`, `syslogd`, `var` und andere System-Boot-Scripts
|
|
- **Angezeigt**: Nur echte OPNsense-Dienste (OpenVPN, Unbound, DHCPd, WireGuard, etc.)
|
|
- `pluginctl` wird mit vollem Pfad `/usr/local/sbin/pluginctl` aufgerufen (FreeBSD-Kompatibilitaet)
|
|
|
|
## Hinweise
|
|
|
|
- **Agent-ID** wird persistent in `/usr/local/rmm/agent_id` gespeichert — ueberlebt Neuinstallationen
|
|
- **Config** wird bei "Speichern & Anwenden" aus dem OPNsense-Model nach `/usr/local/rmm/config.yaml` generiert
|
|
- **Logs**: `/var/log/rmm-agent.log`
|
|
- **PID-File**: `/var/run/rmm_agent.pid`
|
|
- Agent braucht **root** auf OPNsense (fuer Hardware-/Service-Daten)
|
|
- OPNsense WebGUI typischerweise auf **Port 4444** (nicht 443)
|