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.

Screenshots

Firewall-Übersicht	System-Metriken
Netzwerk / Interfaces	Netzwerk / HAProxy
Daten / Backups	Daten / Aufgaben
Daten / Tunnel	System / Updates
System / Agent	Login
Dashboard	Übersicht / Detail
Netzwerk / Interfaces	Netzwerk / WireGuard
Netzwerk / Routen	Netzwerk / DHCP
Netzwerk / Caddy	Sicherheit / Zertifikate
Sicherheit / Logins

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 BSD	OPNsense/FreeBSD Agent — Installation, Firmware, OTA-Updates, OPNsense-Updates	agent-bsd/README.md
Agent Linux	Linux/Proxmox Agent — Installation, Monitoring, Remote-Commands	agent-linux/README.md
Updater	OTA-Update-Daemon fuer Agent-Binaries (FreeBSD + Linux, cross-platform)	updater/README.md
Frontend	React + Vite + TailwindCSS Web-Frontend	docs/FRONTEND.md
API	Vollstaendige REST API mit allen Endpoints	docs/API.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 agent-bsd/README.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 agent-bsd/README.md

Dateistruktur

rmm/
├── Makefile
├── README.md
├── docs/                        # Detail-Dokumentation
│   ├── API.md                   # Vollstaendige API-Referenz
│   ├── BACKEND.md               # Backend Installation + Konfiguration
│   ├── FRONTEND.md              # Frontend Build + Deploy
│   └── POSTGRES_SETUP.md        # PostgreSQL + TimescaleDB Setup
├── agent-bsd/                   # 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/                     # OTA-Update-Daemon (FreeBSD + Linux)
├── 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.

---

Donate