christian/rmm2

Fork 0

cynfo3000 5fc46a8148 release: alle hardcodierten IPs entfernt, Konfiguration via Env-Variablen und Auto-Discovery

2026-03-07 14:31:24 +01:00

12 KiB

Raw Blame History

API-Referenz

Vollstaendige REST API Dokumentation mit allen Endpoints und Beispielen.

Base-URL: https://your-backend:8443/api/v1

Authentifizierung

Zwei Auth-Methoden (CombinedAuth Middleware):

API-Key (Header X-API-Key): Fuer Agents und automatisierte Zugriffe
JWT Bearer Token (Header Authorization: Bearer <token>): Fuer Frontend-Benutzer

Methode	Endpoint	Beschreibung
POST	`/auth/login`	Login (username + password → JWT Token, 8h Ablauf)
GET	`/auth/me`	Eigene Benutzerdaten

Default-Admin: admin / YOUR_PASSWORD (min. 6 Zeichen).

Agent-Management

Methode	Endpoint	Beschreibung
POST	`/agent/register`	Agent registrieren (mit optionaler `agent_id`)
POST	`/agent/heartbeat`	Systemdaten senden
POST	`/agents`	Firewall pre-registrieren (`{name, customer_id?}`)
GET	`/agents`	Alle Agents auflisten
GET	`/agents/{id}`	Agent + Systemdaten abrufen
GET	`/agents/{id}/system`	Nur Systemdaten
DELETE	`/agents/{id}`	Agent loeschen

Agent-Status

Status wird automatisch aus last_heartbeat berechnet:

Status	Bedingung
`online`	Heartbeat < 2 Minuten
`stale`	Heartbeat < 5 Minuten
`offline`	Heartbeat > 5 Minuten
`unknown`	Kein Heartbeat vorhanden

Pre-Registration

POST /agents mit {"name": "FW-NAME", "customer_id": 1} — legt Agent mit hostname="(ausstehend)" an. Bei Agent-Registration wird automatisch nach Name gematcht (GetAgentByName).

Beispiele

# Alle Agents auflisten
curl -sk -H "X-API-Key: YOUR_API_KEY" \
  https://your-backend:8443/api/v1/agents

# Einzelner Agent mit Systemdaten
curl -sk -H "X-API-Key: YOUR_API_KEY" \
  https://your-backend:8443/api/v1/agents/e92e87a684b20db15d8d2344583c5887

# Nur Systemdaten
curl -sk -H "X-API-Key: YOUR_API_KEY" \
  https://your-backend:8443/api/v1/agents/e92e87a684b20db15d8d2344583c5887/system

# Agent loeschen
curl -sk -H "X-API-Key: YOUR_API_KEY" -X DELETE \
  https://your-backend:8443/api/v1/agents/e92e87a684b20db15d8d2344583c5887

# Hub-Status (verbundene Agents, aktive Tunnel)
curl -sk -H "X-API-Key: YOUR_API_KEY" \
  https://your-backend:8443/api/v1/hub/status

# Remote-Command ausfuehren
curl -sk -H "X-API-Key: YOUR_API_KEY" -X POST \
  https://your-backend:8443/api/v1/agents/e92e87a684b20db15d8d2344583c5887/exec \
  -d '{"command":"uptime","timeout":30}'

Agent-Events

Methode	Endpoint	Beschreibung
GET	`/agents/events`	Alle Events (`?limit=N&type=X`)
GET	`/agents/{id}/events`	Events eines Agents (`?limit=N&type=X`)

Event-Typen: online, offline, stale, connected, disconnected

# Alle Events (letzte 10)
curl -sk -H "X-API-Key: YOUR_API_KEY" \
  "https://your-backend:8443/api/v1/agents/events?limit=10"

# Nur Offline-Events eines Agents
curl -sk -H "X-API-Key: YOUR_API_KEY" \
  "https://your-backend:8443/api/v1/agents/6beb8dfd38ecf03eab6c0f21b4ac7bee/events?type=offline"

Kunden (Customers)

Methode	Endpoint	Beschreibung
GET	`/customers`	Alle Kunden auflisten
POST	`/customers`	Neuen Kunden anlegen (`{number, name}`)
GET	`/customers/{id}`	Einzelnen Kunden abrufen
PUT	`/customers/{id}`	Kunden aktualisieren
DELETE	`/customers/{id}`	Kunden loeschen
GET	`/customers/{id}/agents`	Agents eines Kunden
PUT	`/agents/{id}/customer`	Agent einem Kunden zuordnen
DELETE	`/agents/{id}/customer`	Kundenzuordnung entfernen

Benutzer (Users)

Methode	Endpoint	Beschreibung
GET	`/users`	Alle Benutzer auflisten
POST	`/users`	Neuen Benutzer anlegen
PUT	`/users/{id}/password`	Passwort aendern (min. 6 Zeichen)
DELETE	`/users/{id}`	Benutzer loeschen

Metriken (TimescaleDB)

Methode	Endpoint	Beschreibung
GET	`/agents/{id}/metrics`	Rohe Metriken (`?metric=X&from=&to=&limit=N`)
GET	`/agents/{id}/metrics/summary`	Aggregierte Metriken (`?metric=X&bucket=5+minutes&from=&to=`)

Verfuegbare Metriken: cpu_usage, memory_used_percent, memory_used_bytes, memory_total_bytes, uptime_seconds, disk_used_percent, disk_used_bytes, interface_rx_bytes, interface_tx_bytes, gateway_rtt_ms, gateway_loss_percent

Retention: 90 Tage (Raw), Compression nach 7 Tagen.

Beispiele

# CPU-Auslastung der letzten 24h
curl -sk -H "X-API-Key: YOUR_API_KEY" \
  "https://your-backend:8443/api/v1/agents/6beb8dfd38ecf03eab6c0f21b4ac7bee/metrics?metric=cpu_usage"

# RAM-Nutzung mit Zeitraum
curl -sk -H "X-API-Key: YOUR_API_KEY" \
  "https://your-backend:8443/api/v1/agents/6beb8dfd38ecf03eab6c0f21b4ac7bee/metrics?metric=memory_used_percent&from=2026-02-28T00:00:00Z&to=2026-02-28T23:59:59Z"

# 5-Minuten-Durchschnitte der CPU
curl -sk -H "X-API-Key: YOUR_API_KEY" \
  "https://your-backend:8443/api/v1/agents/6beb8dfd38ecf03eab6c0f21b4ac7bee/metrics/summary?metric=cpu_usage&bucket=5+minutes"

# Stuendliche RAM-Zusammenfassung
curl -sk -H "X-API-Key: YOUR_API_KEY" \
  "https://your-backend:8443/api/v1/agents/6beb8dfd38ecf03eab6c0f21b4ac7bee/metrics/summary?metric=memory_used_percent&bucket=1+hour"

Config-Backup

Methode	Endpoint	Beschreibung
POST	`/agents/{id}/backup`	Backup jetzt ausloesen (via WebSocket)
GET	`/agents/{id}/backups`	Alle Backups auflisten (`?limit=N`)
GET	`/agents/{id}/backups/{id\|latest}`	Backup herunterladen (`?format=xml` fuer Raw-XML)
DELETE	`/agents/{id}/backups/{id}`	Einzelnes Backup loeschen
GET	`/agents/{id}/backups/diff?a={id}&b={id}`	Zeilenweises Diff zwischen zwei Backups

Backups werden dedupliziert: gleicher SHA256-Hash = kein neuer Eintrag.

Beispiele

# Backup ausloesen
curl -sk -H "X-API-Key: YOUR_API_KEY" -X POST \
  https://your-backend:8443/api/v1/agents/6beb8dfd38ecf03eab6c0f21b4ac7bee/backup

# Alle Backups auflisten
curl -sk -H "X-API-Key: YOUR_API_KEY" \
  https://your-backend:8443/api/v1/agents/6beb8dfd38ecf03eab6c0f21b4ac7bee/backups

# Neuestes Backup als XML herunterladen
curl -sk -H "X-API-Key: YOUR_API_KEY" \
  "https://your-backend:8443/api/v1/agents/e92e87a684b20db15d8d2344583c5887/backups/latest?format=xml" \
  -o config-backup.xml

# Diff zwischen Backup 1 und 3
curl -sk -H "X-API-Key: YOUR_API_KEY" \
  "https://your-backend:8443/api/v1/agents/e92e87a684b20db15d8d2344583c5887/backups/diff?a=1&b=3"

Tunnel-Management

Methode	Endpoint	Beschreibung
POST	`/agents/{id}/tunnel`	Tunnel oeffnen
GET	`/agents/{id}/tunnels`	Aktive Tunnel auflisten
DELETE	`/agents/{id}/tunnel/{tid}`	Tunnel schliessen
POST	`/agents/{id}/exec`	Remote-Command ausfuehren

Beispiele

# SSH-Tunnel zur OPNsense
curl -sk -H "X-API-Key: YOUR_API_KEY" -X POST \
  https://your-backend:8443/api/v1/agents/e92e87a684b20db15d8d2344583c5887/tunnel \
  -d '{"target_host":"127.0.0.1","target_port":22}'
# Response: {"tunnel_id":"xxx","proxy_port":10000,...}
# Verbinden: ssh -p 10000 root@your-backend

# WebGUI-Tunnel (OPNsense auf Port 4444)
curl -sk -H "X-API-Key: YOUR_API_KEY" -X POST \
  https://your-backend:8443/api/v1/agents/e92e87a684b20db15d8d2344583c5887/tunnel \
  -d '{"target_host":"127.0.0.1","target_port":4444}'
# Im Browser: https://your-backend:10001/

# Aktive Tunnel auflisten
curl -sk -H "X-API-Key: YOUR_API_KEY" \
  https://your-backend:8443/api/v1/agents/e92e87a684b20db15d8d2344583c5887/tunnels

# Tunnel schliessen
curl -sk -H "X-API-Key: YOUR_API_KEY" -X DELETE \
  https://your-backend:8443/api/v1/agents/e92e87a684b20db15d8d2344583c5887/tunnel/TUNNEL_ID

Updates & Reboot

Siehe FIRMWARE.md fuer den vollstaendigen Update-Prozess.

Methode	Endpoint	Beschreibung
POST	`/agents/{id}/update-check`	Verfuegbare Updates pruefen
POST	`/agents/{id}/update`	Normales Update (Core + Packages)
POST	`/agents/{id}/major-update`	Major-Upgrade auf Zielversion
POST	`/agents/{id}/reboot`	Reboot ausfuehren

Firmware / Agent-Update

Siehe FIRMWARE.md fuer Details.

Methode	Endpoint	Beschreibung
GET	`/firmware`	Alle Firmware-Versionen
POST	`/firmware/upload?version=X&platform=Y`	Binary hochladen
GET	`/firmware/download?platform=Y`	Binary herunterladen
POST	`/agents/{id}/request-update`	Update-Flag setzen
DELETE	`/agents/{id}/request-update`	Update-Flag zuruecksetzen
POST	`/agents/request-update-all`	Alle Agents updaten

WireGuard-Peer Management

Methode	Endpoint	Beschreibung
POST	`/agents/{id}/wireguard/peers`	Neuen Peer anlegen
GET	`/agents/{id}/wireguard/peers`	Alle Peers auflisten (`?server_name=X`)
DELETE	`/agents/{id}/wireguard/peers/{uuid}`	Peer loeschen

Peer anlegen — Parameter

Parameter	Pflicht	Default	Beschreibung
`name`	Ja	—	Peer-Name (z.B. "VPN_MUELLER")
`allowed_ips`	Nein	`0.0.0.0/0`	AllowedIPs fuer Client-Config
`dns`	Nein	—	DNS-Server fuer Client-Config
`server_name`	Nein	`ALWAYSON_VPN`	Name der WG-Server-Instanz
`endpoint`	Nein	WAN-IP:Port	Oeffentlicher Endpoint (Auto-Detect)

Ablauf beim Anlegen

Keypair wird auf der Firewall generiert (wg genkey/wg pubkey)
Naechste freie IP aus dem Tunnel-Subnetz wird automatisch vergeben
Peer wird in config.xml eingetragen und dem Server zugewiesen
configctl wireguard configure laedt die Aenderung
Response enthaelt die komplette Client-Config (ready for import)

Beispiele

# Peer anlegen
curl -sk -H "X-API-Key: YOUR_API_KEY" -X POST \
  https://your-backend:8443/api/v1/agents/6beb8dfd38ecf03eab6c0f21b4ac7bee/wireguard/peers \
  -d '{"name":"VPN_MUELLER","allowed_ips":"0.0.0.0/0","dns":"<DNS-SERVER>"}'

# Peer mit eigenem Endpoint
curl -sk -H "X-API-Key: YOUR_API_KEY" -X POST \
  https://your-backend:8443/api/v1/agents/6beb8dfd38ecf03eab6c0f21b4ac7bee/wireguard/peers \
  -d '{"name":"VPN_EXTERN","allowed_ips":"0.0.0.0/0","endpoint":"vpn.kunde.de:8080"}'

# Alle Peers auflisten
curl -sk -H "X-API-Key: YOUR_API_KEY" \
  https://your-backend:8443/api/v1/agents/6beb8dfd38ecf03eab6c0f21b4ac7bee/wireguard/peers

# Peer loeschen
curl -sk -H "X-API-Key: YOUR_API_KEY" -X DELETE \
  https://your-backend:8443/api/v1/agents/6beb8dfd38ecf03eab6c0f21b4ac7bee/wireguard/peers/89c10e2d-148e-11f1-a7af-7c5a1c6c7b73

WebSocket

Methode	Endpoint	Beschreibung
GET	`/agent/ws?agent_id=X&api_key=X`	WebSocket-Verbindung (Agent)
GET	`/hub/status`	Hub-Status (connected agents, aktive Tunnel)

WebSocket Commands (Backend → Agent)

// Remote-Befehl ausfuehren
{"type":"command","id":"cmd1","command":"exec","params":{"command":"uptime","timeout":30}}

// Update-Check
{"type":"command","id":"cmd2","command":"update_check"}

// Normales Update
{"type":"command","id":"cmd3","command":"update","params":{"reboot":false}}

// Major-Update
{"type":"command","id":"cmd4","command":"major_update","params":{"version":"26.1","reboot":true}}

// Reboot
{"type":"command","id":"cmd5","command":"reboot","params":{"delay":5}}

// Config-Backup
{"type":"command","id":"cmd8","command":"backup","params":{}}

// Tunnel-Session oeffnen
{"type":"command","id":"cmd6","command":"tunnel_connect","params":{"session_id":"xxx","tunnel_id":"xxx","target_host":"127.0.0.1","target_port":22}}

// Tunnel-Session schliessen
{"type":"command","id":"cmd7","command":"tunnel_disconnect","params":{"session_id":"xxx"}}

Binary WebSocket Messages (Tunnel-Daten)

Format: [session_id_length:1][session_id][tcp_payload]

Tunnel-Daten werden als Binary WebSocket Messages uebertragen (kein Base64-Overhead).

12 KiB Raw Blame History

API-Referenz

Authentifizierung

Agent-Management

Agent-Status

Pre-Registration

Beispiele

Agent-Events

Kunden (Customers)

Benutzer (Users)

Metriken (TimescaleDB)

Beispiele

Config-Backup

Beispiele

Tunnel-Management

Beispiele

Updates & Reboot

Firmware / Agent-Update

WireGuard-Peer Management

Peer anlegen — Parameter

Ablauf beim Anlegen

Beispiele

WebSocket

WebSocket Commands (Backend → Agent)

Binary WebSocket Messages (Tunnel-Daten)

12 KiB

Raw Blame History