# 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)