rmm2/README.md

# OPNsense RMM System

Remote Monitoring & Management fuer OPNsense Firewalls.
Go-basierter Agent (v1.0.3) + Backend mit WebSocket-Kommunikation und Session-basierten TCP-Tunneln.

## Architektur

```
┌────────────────┐   HTTPS/WSS    ┌────────────────┐   TCP Proxy     ┌────────────┐
│  OPNsense FW   │◄──────────────►│  RMM Backend   │◄───────────────│  Browser/  │
│  (FreeBSD)     │  :8443         │  (Linux)       │  :10000-20000  │  SSH/etc.  │
│                │                │                │                └────────────┘
│  rmm-agent     │  Heartbeat     │  REST API      │                ┌────────────┐
│  rmm-updater   │  WebSocket     │  WebSocket Hub │◄───────────────│  Frontend  │
│  - Collectors  │  Binary Msgs   │  Tunnel Mgr    │  Nginx Proxy   │  (React)   │
│  - WS Client   │                │  PostgreSQL +  │  :80/443       │  .20       │
│  - Tunnel Mgr  │                │  TimescaleDB   │                └────────────┘
└────────────────┘                └────────────────┘
```

### Tunnel-Flow

```
Client ──► Backend:ProxyPort ──► WebSocket (Binary) ──► Agent ──► Zieldienst
           (TCP-Listener)        (Session-basiert)       (TCP)    (SSH/HTTPS/etc)
```

- Jeder Tunnel oeffnet einen dynamischen Proxy-Port (10000-20000) auf dem Backend
- Jede TCP-Verbindung am Proxy bekommt eine eigene **Session**
- Der Agent oeffnet pro Session eine separate Ziel-Verbindung (Lazy Connect)
- Mehrere gleichzeitige Verbindungen pro Tunnel moeglich
- Tunnel bleiben offen wenn einzelne Sessions beendet werden

## Komponenten

| Komponente | Beschreibung | Dokumentation |
|------------|-------------|---------------|
| **Backend** | REST API, WebSocket Hub, Tunnel Manager, PostgreSQL + TimescaleDB | [docs/BACKEND.md](docs/BACKEND.md) |
| **Agent** | Collectors, WebSocket Client, Command Handler, Tunnel Manager | [docs/AGENT.md](docs/AGENT.md) |
| **Frontend** | React + Vite + TailwindCSS Web-Frontend | [docs/FRONTEND.md](docs/FRONTEND.md) |
| **API** | Vollstaendige REST API mit allen Endpoints | [docs/API.md](docs/API.md) |
| **Firmware** | Multi-Plattform Firmware-Verwaltung und Update-Prozess | [docs/FIRMWARE.md](docs/FIRMWARE.md) |

## Agent-Faehigkeiten

### Datensammlung (automatisch bei jedem Heartbeat, alle 60s)

| Collector | Daten | Quelle |
|-----------|-------|--------|
| Hardware | Hersteller, Modell, Seriennummer, BIOS | `kenv`, `sysctl` |
| CPU | Modell, Cores, Threads, Frequenz, Auslastung | `sysctl` |
| Memory | Total, Used, Free | `sysctl` |
| Disks | ZFS Datasets, Belegung, Mountpoints | `zfs list` |
| Network | Interfaces, IPs, Status, MAC, Statistiken | `ifconfig` |
| Services | Laufende OPNsense-Dienste (gefiltert) | `service -e`, `configctl`, `/usr/local/sbin/pluginctl` |
| WireGuard | Tunnel, Peers, Transfer, Handshake | `wg show` |
| DHCP | Aktive Leases (KEA/ISC/dnsmasq) | Lease-Dateien, KEA JSON |
| Routing | Routing-Tabelle | `netstat -rn` |
| Gateways | Gateway-Status, RTT, Loss | `configctl interface gateways status` |
| Zertifikate | Alle Certs + CAs, Ablaufdatum, Aussteller | `config.xml` + PEM-Parsing |
| Plugins | Installierte OPNsense-Plugins | `pkg info` |
| Updates | Pending Core + Package Updates | `opnsense-update -c`, `pkg upgrade -n` |
| Cron | System-Crontab + OPNsense config.xml Jobs | `crontab -l`, `config.xml` |

### Remote-Commands (via WebSocket, on-demand)

| Command | Beschreibung |
|---------|-------------|
| `exec` | Beliebigen Shell-Befehl ausfuehren |
| `backup` | Config-Backup (`/conf/config.xml`) erstellen |
| `update_check` | Verfuegbare Updates pruefen |
| `update` | Normales Update (Core + Packages, opt. Reboot) |
| `major_update` | Major-Upgrade (2-Phasen: Base/Kernel → Reboot → Packages) |
| `reboot` | Reboot mit konfigurierbarer Verzoegerung |
| `wg_add_peer` | WireGuard-Peer anlegen (Keypair + Config) |
| `wg_list_peers` | Alle Peers einer WG-Instanz auflisten |
| `wg_delete_peer` | WireGuard-Peer loeschen |
| `tunnel_connect` | TCP-Tunnel zu lokalem Dienst oeffnen |
| `tunnel_disconnect` | Tunnel schliessen |
| `agent_update` | Agent-Binary remote aktualisieren (Legacy) |

## Features (v1.0.3)

### OPNsense Plugin WebGUI Fix
- **Config-Parsing**: Korrektes Parsen von `rmmagent[general][KEY]` Formular-Feldern (OPNsense MVC-Konvention)
- **Initialer config.xml Eintrag**: Automatisches Anlegen des `<rmmagent>` Knotens beim ersten Speichern

### Pre-Registration von Firewalls
- Firewalls vorab registrieren bevor der Agent installiert wird (`POST /api/v1/agents`)
- Automatisches Matching bei Agent-Registration nach Name wenn `hostname="(ausstehend)"`
- Frontend: "Firewall hinzufuegen" Dialog mit Installationsanleitung und Copy-Buttons

### Service-Filter
- Boot/Init-Scripts (`bgfsck`, `cleanvar`, `dmesg`, etc.) werden gefiltert — nur echte OPNsense-Dienste
- `pluginctl` mit vollem Pfad `/usr/local/sbin/pluginctl`

### OPNsense Business Edition Lizenz-Anzeige
- Product Name, Subscription Key, Ablaufdatum im Uebersicht-Tab
- Restlaufzeit mit visuellem Farbbalken (gruen/gelb/rot)

### Firmware Management
- Multi-Platform Upload (FreeBSD, Linux, Windows)
- Agent-Update per Button (einzeln oder alle)
- Siehe [docs/FIRMWARE.md](docs/FIRMWARE.md)

### Frontend
- Firewall loeschen (Papierkorb-Icon im AgentPanel)
- Agent-Tab mit Version, Update-Button und Remote-Befehlen
- Siehe [docs/FRONTEND.md](docs/FRONTEND.md)

## Voraussetzungen

- **Build-System**: Go 1.24+ (Cross-Compilation, kein CGO)
- **Backend-Server**: Linux (Debian 12+), PostgreSQL 17+, TimescaleDB 2.x
- **Agent-Ziel**: OPNsense / FreeBSD (amd64)

## Schnellstart

```bash
make all                    # Backend + Agent + Updater bauen
make certs                  # TLS-Zertifikate generieren
make deploy-backend         # Backend deployen
```

Agent auf OPNsense installieren → siehe [docs/AGENT.md](docs/AGENT.md)

## Dateistruktur

```
rmm/
├── Makefile
├── README.md
├── docs/                        # Detail-Dokumentation
│   ├── API.md                   # Vollstaendige API-Referenz
│   ├── AGENT.md                 # Agent + Updater + OPNsense Plugin
│   ├── BACKEND.md               # Backend Installation + Konfiguration
│   ├── FRONTEND.md              # Frontend Build + Deploy
│   └── FIRMWARE.md              # Firmware-Management + Update-Prozess
├── agent/                       # Agent-Quellcode (FreeBSD/OPNsense)
│   ├── main.go
│   ├── config/config.go
│   ├── client/client.go
│   ├── collector/               # Hardware, CPU, Memory, Disk, Network, Services, ...
│   └── ws/                      # WebSocket Client, Handler, Tunnel, WireGuard
├── backend/                     # Backend-Quellcode (Linux)
│   ├── main.go
│   ├── config/config.go
│   ├── db/postgres.go
│   ├── models/
│   ├── monitor/monitor.go
│   ├── api/                     # REST Handler, Auth, Middleware
│   └── ws/                      # WebSocket Hub, Tunnel Manager
├── updater/main.go              # Separater Update-Daemon
├── frontend/                    # React + Vite + TailwindCSS
│   └── src/
├── opnsense-plugin/             # OPNsense MVC Plugin + Installer
│   ├── install.sh
│   └── src/
└── build/                       # Kompilierte Binaries
```

## Technische Details

- **PostgreSQL 17 + TimescaleDB 2.x**: Agent-Registry, Config-Backups, Time-Series Metriken
- **Pure-Go**: pgx/v5 Driver, kein CGO noetig
- **Cross-Compilation**: Backend linux/amd64, Agent freebsd/amd64
- **TLS**: Self-signed Zertifikate (automatisch generiert)
- **WebSocket**: gorilla/websocket, Binary Messages fuer Tunnel-Daten
- **Persistente Agent-ID**: Ueberlebt Agent- und Backend-Neustarts
- **FreeBSD-kompatibel**: Volle Pfade (/usr/bin/netstat etc.), daemon statt nohup

## Zugangsdaten

```
Backend:   https://your-backend:8443
API-Key:   YOUR_API_KEY
Frontend:  http://your-backend (admin / Start!123)
```

## Lizenz

Intern.