rmm2/README.md

OPNsense RMM System

Remote Monitoring & Management System fuer OPNsense Firewalls.

Ueberblick

Dieses System besteht aus zwei Komponenten:

• Backend (Go) - REST API Server mit TLS und SQLite-Datenbank, laeuft auf einem Linux-Server
• Agent (Go) - Laeuft auf OPNsense/FreeBSD, sammelt Systemdaten und sendet sie an das Backend

Architektur

┌──────────────────┐        HTTPS (TLS)        ┌──────────────────┐
│   OPNsense FW    │ ────────────────────────►  │   RMM Backend    │
│   (FreeBSD)      │   POST /agent/register     │   (Linux)        │
│                  │   POST /agent/heartbeat    │                  │
│   rmm-agent      │                            │   REST API       │
│   - Hardware     │                            │   SQLite DB      │
│   - CPU/RAM      │                            │   :8443          │
│   - Disk/Net     │                            │                  │
│   - Services     │                            │   192.168.85.13  │
│                  │                            │                  │
│   192.168.85.33  │                            │                  │
└──────────────────┘                            └──────────────────┘

Voraussetzungen

• Go 1.22+
• make
• OpenSSL (fuer manuelle Zertifikat-Generierung)
• SSH-Zugang zu den Zielservern

Build

# Beide Komponenten bauen
make all

# Nur Backend (linux/amd64)
make backend

# Nur Agent (freebsd/amd64)
make agent

# TLS-Zertifikate generieren (optional, Backend generiert automatisch)
make certs

Die Binaries landen in build/.

Konfiguration

Backend (backend/config.yaml)

listen_addr: ":8443"
tls_cert: "certs/server.crt"
tls_key: "certs/server.key"
db_path: "rmm.db"
api_keys:
  - "01532e5a7c9e70bf2757df77a2f5b9b9"

Parameter	Env-Variable	Beschreibung
listen_addr	RMM_LISTEN_ADDR	Bind-Adresse (default: :8443)
tls_cert	RMM_TLS_CERT	Pfad zum TLS-Zertifikat
tls_key	RMM_TLS_KEY	Pfad zum TLS-Key
db_path	RMM_DB_PATH	Pfad zur SQLite-Datenbank
api_keys	-	Liste erlaubter API-Keys

Das Backend generiert automatisch self-signed TLS-Zertifikate wenn keine vorhanden sind.

Agent (agent/config.yaml)

backend_url: "https://192.168.85.13:8443"
api_key: "01532e5a7c9e70bf2757df77a2f5b9b9"
interval_seconds: 60
agent_name: "opnsense-fw01"
insecure: true

Parameter	Beschreibung
backend_url	URL des Backend-Servers
api_key	API-Key fuer Authentifizierung
interval_seconds	Heartbeat-Intervall in Sekunden (default: 60)
agent_name	Name des Agents
insecure	TLS-Zertifikatpruefung ueberspringen

Deployment

Backend (192.168.85.13)

make deploy-backend

Dies:

1. Baut das Backend fuer linux/amd64
2. Kopiert Binary + Config nach /opt/rmm/
3. Erstellt einen systemd-Service
4. Startet den Service

Agent (192.168.85.33 / OPNsense)

make deploy-agent

Dies:

1. Baut den Agent fuer freebsd/amd64
2. Kopiert Binary + Config nach /opt/rmm/
3. Erstellt ein rc.d-Script
4. Aktiviert und startet den Service

API-Dokumentation

Alle Endpoints erfordern den Header X-API-Key mit einem gueltigen API-Key.

POST /api/v1/agent/register

Agent registrieren.

Request:

{
  "name": "opnsense-fw01",
  "hostname": "fw01.local",
  "ip": "192.168.85.33",
  "opnsense_version": "OPNsense 24.1.1"
}

Response (201):

{
  "id": "a1b2c3d4e5f6...",
  "message": "Agent erfolgreich registriert"
}

POST /api/v1/agent/heartbeat

Systemdaten senden.

Request:

{
  "agent_id": "a1b2c3d4e5f6...",
  "system_data": {
    "hostname": "fw01.local",
    "opnsense_version": "OPNsense 24.1.1",
    "freebsd_version": "14.0-RELEASE-p5",
    "uptime_seconds": 86400,
    "hardware": {
      "manufacturer": "Protectli",
      "model": "VP2420",
      "serial": "ABC123",
      "bios_version": "1.0.0"
    },
    "cpu": {
      "model": "Intel(R) Celeron(R) J6412 @ 2.00GHz",
      "cores": 4,
      "threads": 4,
      "freq_mhz": 2000,
      "usage_percent": 12.5
    },
    "memory": {
      "total_bytes": 8589934592,
      "used_bytes": 2147483648,
      "free_bytes": 6442450944
    },
    "disks": [
      {
        "filesystem": "/dev/ada0p3",
        "total_bytes": 107374182400,
        "used_bytes": 5368709120,
        "free_bytes": 93736247296,
        "mount_point": "/"
      }
    ],
    "network_interfaces": [
      {
        "name": "igb0",
        "role": "WAN",
        "ip": "203.0.113.1",
        "mac": "00:11:22:33:44:55",
        "status": "up",
        "rx_bytes": 1073741824,
        "tx_bytes": 536870912
      },
      {
        "name": "igb1",
        "role": "LAN",
        "ip": "192.168.1.1",
        "mac": "00:11:22:33:44:56",
        "status": "up",
        "rx_bytes": 2147483648,
        "tx_bytes": 1073741824
      }
    ],
    "services": [
      {
        "name": "configd",
        "description": "",
        "status": "running"
      },
      {
        "name": "dhcpd",
        "description": "",
        "status": "running"
      },
      {
        "name": "unbound",
        "description": "",
        "status": "running"
      }
    ]
  }
}

Response (200):

{
  "message": "OK"
}

GET /api/v1/agents

Alle registrierten Agents auflisten.

Response (200):

[
  {
    "id": "a1b2c3d4e5f6...",
    "name": "opnsense-fw01",
    "hostname": "fw01.local",
    "ip": "192.168.85.33",
    "opnsense_version": "OPNsense 24.1.1",
    "registered_at": "2024-01-28T10:00:00Z",
    "last_heartbeat": "2024-01-28T12:30:00Z"
  }
]

GET /api/v1/agents/{id}

Agent-Details mit letzten Systemdaten.

Response (200):

{
  "agent": {
    "id": "a1b2c3d4e5f6...",
    "name": "opnsense-fw01",
    "hostname": "fw01.local",
    "ip": "192.168.85.33",
    "opnsense_version": "OPNsense 24.1.1",
    "registered_at": "2024-01-28T10:00:00Z",
    "last_heartbeat": "2024-01-28T12:30:00Z"
  },
  "system_data": { ... }
}

GET /api/v1/agents/{id}/system

Nur die aktuellen Systemdaten eines Agents.

Response (200):

{
  "hostname": "fw01.local",
  "opnsense_version": "OPNsense 24.1.1",
  "uptime_seconds": 86400,
  "hardware": { ... },
  "cpu": { ... },
  "memory": { ... },
  "disks": [ ... ],
  "network_interfaces": [ ... ],
  "services": [ ... ]
}

DELETE /api/v1/agents/{id}

Agent entfernen.

Response (200):

{
  "message": "Agent geloescht"
}

Fehlermeldungen

{
  "error": "unauthorized"
}

HTTP Status Codes:

• 200 - Erfolg
• 201 - Erstellt
• 400 - Ungueltige Anfrage
• 401 - Nicht autorisiert (fehlender/falscher API-Key)
• 404 - Nicht gefunden
• 500 - Server-Fehler

Lizenz

Intern.