christian/rmm2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
rmm2/docs/API.md

352 lines
12 KiB
Markdown
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
```bash
# 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`
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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](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](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
1. Keypair wird auf der Firewall generiert (`wg genkey`/`wg pubkey`)
2. Naechste freie IP aus dem Tunnel-Subnetz wird automatisch vergeben
3. Peer wird in `config.xml` eingetragen und dem Server zugewiesen
4. `configctl wireguard configure` laedt die Aenderung
5. Response enthaelt die komplette Client-Config (ready for import)
### Beispiele
```bash
# 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)
```json
// 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).
Reference in New Issue View Git Blame Copy Permalink