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
Agent	Collectors, WebSocket Client, Command Handler, Tunnel Manager	docs/AGENT.md
Frontend	React + Vite + TailwindCSS Web-Frontend	docs/FRONTEND.md
API	Vollstaendige REST API mit allen Endpoints	docs/API.md
Firmware	Multi-Plattform Firmware-Verwaltung und Update-Prozess	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

Frontend

• Firewall loeschen (Papierkorb-Icon im AgentPanel)
• Agent-Tab mit Version, Update-Button und Remote-Befehlen
• Siehe 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

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

Agent auf OPNsense installieren → siehe 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 / YOUR_PASSWORD)

Agent-IDs:
  6beb8dfd38ecf03eab6c0f21b4ac7bee  OPN-PROD.intra.weidenhaupt.net  (your-backend, READ-ONLY)
  e92e87a684b20db15d8d2344583c5887  OPN-REP.intra.weidenhaupt.net   (your-backend)
  1697d28e57bc126534afc282b5de8ee0  OPN-TEST-UPDATE                 (your-backend)

Lizenz

Intern.