RMM System — OPNsense & Linux/Proxmox

Remote Monitoring & Management fuer OPNsense Firewalls und Linux-Server (Proxmox, Debian, Ubuntu). Go-basierter Agent + Backend mit WebSocket-Kommunikation, Session-basierten TCP-Tunneln und integriertem Web Terminal.

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   │  PTY-Stream    │  PTY Bridge    │  :80           │  .20       │
│  - Tunnel Mgr  │                │  PostgreSQL +  │                └────────────┘
│  - PTY Manager │                │  TimescaleDB   │
└────────────────┘                └────────────────┘
     ▲
     │  identisches Protokoll
     ▼
┌────────────────┐
│  Linux Server  │
│  (Proxmox etc) │
│  rmm-agent     │
│  rmm-updater   │
│  - Collectors  │
│  - PTY Manager │
│  - PBS Monitor │
└────────────────┘

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)
pty_start	Interaktive Bash-Shell (PTY) starten — Web Terminal
pty_stop	PTY-Session beenden
pty_resize	PTY-Fenstergroesse anpassen

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

Docker (empfohlen)

Voraussetzung: Docker installiert (curl -fsSL https://get.docker.com | sh).

git clone <repo-url> && cd rmm
git checkout release
cp .env.example .env   # .env anpassen (IP-Adresse, Passwörter, API-Key)
docker compose up -d

Fertig. Frontend unter http://<BACKEND_HOST>.

Vollständige Anleitung mit allen Details, Troubleshooting und Backup: docs/DOCKER.md

---

Manuell (ohne Docker)

1. Voraussetzungen

Backend-Server (Linux, Debian 12+ empfohlen):

# PostgreSQL 17 + TimescaleDB
apt install -y postgresql postgresql-client
# TimescaleDB: https://docs.timescale.com/self-hosted/latest/install/

Build-System (macOS oder Linux):

# Go 1.24+
go version   # muss >= 1.24 sein

---

2. Konfiguration

Backend:

cp backend/config.yaml.example backend/config.yaml

# backend/config.yaml (wichtigste Felder)
listen_addr: ":8443"
db_dsn: "postgres://rmm:PASSWORT@localhost:5432/rmm?sslmode=disable"
jwt_secret: "ZUFAELLIGER_STRING_MIN_32_ZEICHEN"
api_key: "SELBST_GEWAEHLTER_API_KEY"

Hinweis: Den api_key legst du selbst fest — z.B. eine UUID oder ein langer zufaelliger String. Denselben Wert traegst du gleich in die Frontend-.env ein. Du brauchst kein laufendes System dafuer. Ueber die Einstellungen-Seite koennen spaeter weitere Keys (z.B. pro Agent) hinzugefuegt werden.

Frontend:

cp frontend/.env.example frontend/.env

# frontend/.env
VITE_BACKEND_HOST=192.168.1.100        # IP/Hostname deines Backend-Servers
VITE_BACKEND_PORT=8443
VITE_API_KEY=SELBST_GEWAEHLTER_API_KEY # identisch mit api_key aus backend/config.yaml

---

3. Datenbank anlegen

# Als postgres-User auf dem Backend-Server:
sudo -u postgres psql << 'SQL'
CREATE USER rmm WITH PASSWORD 'PASSWORT';
CREATE DATABASE rmm OWNER rmm;
\c rmm
CREATE EXTENSION IF NOT EXISTS timescaledb;
SQL

Die Tabellen werden beim ersten Backend-Start automatisch angelegt (Auto-Migration).

---

4. Bauen

# Alles in einem Schritt:
make all

# Oder einzeln:
make backend          # → build/rmm-backend (linux/amd64)
make agent-bsd        # → build/rmm-agent-bsd (freebsd/amd64)
make agent-linux      # → build/rmm-agent-linux (linux/amd64)
make frontend         # → frontend/dist/

---

5. Backend deployen

# Binary + Config auf den Server kopieren:
scp build/rmm-backend root@<backend-server>:/opt/rmm/
scp backend/config.yaml root@<backend-server>:/opt/rmm/

# Systemd-Service einrichten:
cat > /etc/systemd/system/rmm-backend.service << 'EOF'
[Unit]
Description=RMM Backend
After=network.target postgresql.service

[Service]
ExecStart=/opt/rmm/rmm-backend
WorkingDirectory=/opt/rmm
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now rmm-backend
systemctl status rmm-backend

Der erste Start legt automatisch einen Admin-User an (Credentials werden ins Log geschrieben).

---

6. Frontend deployen

# Build (mit .env-Konfiguration aus Schritt 2):
cd frontend && npm install && npm run build

# Auf Web-Server kopieren (z.B. Nginx):
scp -r frontend/dist/* root@<frontend-server>:/var/www/html/

# Nginx-Konfiguration (einfach):
cat > /etc/nginx/sites-available/rmm << 'EOF'
server {
    listen 80;
    root /var/www/html;
    index index.html;
    location / { try_files $uri $uri/ /index.html; }
}
EOF
ln -s /etc/nginx/sites-available/rmm /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

---

7. Erste Anmeldung & 2FA

1. Frontend unter http://<frontend-server> aufrufen
2. Mit dem beim ersten Backend-Start erstellten Admin-Account anmelden
3. Einstellungen → Zwei-Faktor-Authentifizierung → Einrichten (empfohlen)
4. TOTP-Secret in Aegis / Google Authenticator eingeben, ersten Code bestätigen

---

Troubleshooting

Problem	Lösung
Backend startet nicht	journalctl -u rmm-backend -f — häufig DB-Verbindung oder Port belegt
Agent verbindet nicht	API-Key in agent/config.yaml prüfen, TLS-Zertifikat ggf. als trusted markieren
Frontend zeigt keine Daten	VITE_BACKEND_HOST und VITE_API_KEY in .env prüfen, neu bauen
TimescaleDB fehlt	CREATE EXTENSION timescaledb in der rmm-Datenbank ausführen

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 (nach Installation)

Backend:   https://<backend-ip>:8443
API-Key:   in backend/config.yaml → api_key
Frontend:  https://<frontend-ip>   (Login: admin / Passwort beim ersten Start gesetzt)

Lizenz

Intern.

---

Donate