christian/rmm2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
rmm2/README.md
cynfo3000 be7cd32d45 docs: API-Key-Henne-Ei-Problem erklaert 
Der api_key wird vom Nutzer selbst in config.yaml festgelegt und
gleichzeitig in frontend/.env eingetragen — kein laufendes System
noetig. Hinweis auf zusaetzliche Keys ueber die Settings-UI.
2026-03-08 19:33:09 +01:00

392 lines
15 KiB
Markdown
Raw Blame History

# 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
| | |
|--|--|
| ![Firewalls](screenshots/01_firewalls_uebersicht.jpg) | ![Detail System](screenshots/02_firewall_detail_system.jpg) |
| Firewall-Übersicht | System-Metriken |
| ![Netzwerk Interfaces](screenshots/03_firewall_netzwerk_interfaces.jpg) | ![HAProxy](screenshots/04_firewall_netzwerk_haproxy.jpg) |
| Netzwerk / Interfaces | Netzwerk / HAProxy |
| ![Backups](screenshots/05_firewall_daten_backups.jpg) | ![Aufgaben](screenshots/06_firewall_daten_aufgaben.jpg) |
| Daten / Backups | Daten / Aufgaben |
| ![Tunnel](screenshots/07_firewall_daten_tunnel.jpg) | ![Updates](screenshots/08_firewall_system_updates.jpg) |
| Daten / Tunnel | System / Updates |
| ![Agent](screenshots/09_firewall_system_agent.jpg) | ![Login](screenshots/10_login.jpg) |
| System / Agent | Login |
| ![Dashboard](screenshots/11_dashboard.jpg) | ![Übersicht Detail](screenshots/12_firewall_uebersicht_detail.jpg) |
| Dashboard | Übersicht / Detail |
| ![Interfaces Detail](screenshots/13_netzwerk_interfaces_detail.jpg) | ![WireGuard](screenshots/14_netzwerk_wireguard.jpg) |
| Netzwerk / Interfaces | Netzwerk / WireGuard |
| ![Routen](screenshots/15_netzwerk_routen.jpg) | ![DHCP](screenshots/16_netzwerk_dhcp.jpg) |
| Netzwerk / Routen | Netzwerk / DHCP |
| ![Caddy](screenshots/17_netzwerk_caddy.jpg) | ![Zertifikate](screenshots/18_sicherheit_zertifikate.jpg) |
| Netzwerk / Caddy | Sicherheit / Zertifikate |
| ![Logins](screenshots/19_sicherheit_logins.jpg) | |
| 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](docs/BACKEND.md) |
| **Agent BSD** | OPNsense/FreeBSD Agent — Installation, Firmware, OTA-Updates, OPNsense-Updates | [agent-bsd/README.md](agent-bsd/README.md) |
| **Agent Linux** | Linux/Proxmox Agent — Installation, Monitoring, Remote-Commands | [agent-linux/README.md](agent-linux/README.md) |
| **Updater** | OTA-Update-Daemon fuer Agent-Binaries (FreeBSD + Linux, cross-platform) | [updater/README.md](updater/README.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) |
## 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](agent-bsd/README.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
### 1. Voraussetzungen
**Backend-Server** (Linux, Debian 12+ empfohlen):
```bash
# PostgreSQL 17 + TimescaleDB
apt install -y postgresql postgresql-client
# TimescaleDB: https://docs.timescale.com/self-hosted/latest/install/
```
**Build-System** (macOS oder Linux):
```bash
# Go 1.24+
go version # muss >= 1.24 sein
```
---
### 2. Konfiguration
**Backend:**
```bash
cp backend/config.yaml.example backend/config.yaml
```
```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:**
```bash
cp frontend/.env.example frontend/.env
```
```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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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. Agent auf OPNsense installieren
Im Frontend: **Firewall hinzufügen** → Installationsanleitung mit vorbefülltem Installationsbefehl anzeigen.
Oder manuell:
```bash
# Auf der OPNsense Firewall (als root):
scp build/rmm-agent-bsd root@<opnsense-ip>:/tmp/rmm-agent
scp opnsense-plugin/install.sh root@<opnsense-ip>:/tmp/install.sh
ssh root@<opnsense-ip> 'sh /tmp/install.sh'
```
Vollständige Anleitung: [agent-bsd/README.md](agent-bsd/README.md)
---
### 8. 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
[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-donate-yellow?logo=buy-me-a-coffee)](https://buymeacoffee.com/muellerchen)
Reference in New Issue View Git Blame Copy Permalink