438 lines
26 KiB
Markdown
438 lines
26 KiB
Markdown
# Sultan: High-Performance Distributed Ingress & ZeroTrust Service Discovery
|
||
|
||
Dieses Dokument beschreibt das vollständige Architektur-, Daten-, Netzwerk- und Anwendungsmodell des Projekts **Sultan**. Es dient als Kontext und Referenz für Software-Architekten und AI-gestützte Coding-Agenten (z. B. via Continue in VSCodium).
|
||
|
||
---
|
||
|
||
## 1. Executive Summary & Problemstellung
|
||
|
||
Klassische Ingress-Lösungen wie Nginx Proxy Manager (NPM) erfordern eine manuelle, GUI-basierte Konfiguration des Routings. In verteilten Umgebungen (Mehrere Proxmox-Cluster, Docker-Hosts, Bare-Metal-LAMP/Apache-Server, Kunden-Setups hinter DS-Lite/CGNAT) führt dies zu Dokumentationsbrüchen, toten Routen und hohem Wartungsaufwand.
|
||
|
||
**Sultan** löst dies durch eine entkoppelte, zweigeteilte Architektur:
|
||
1. **In-Service-Deklaration:** Backends deklarieren ihr Routing direkt am Dienst (native Traefik-Labels in Docker oder Drop-in-Konfigurationen unter `/etc/sultan.d/`).
|
||
2. **Dynamische Registrierung:** Ein leichtgewichtiger Agent überträgt diese Konfiguration kryptografisch gesichert über einen langlebigen, ressourcenschonenden Keepalive-Stream an den zentralen Ingress.
|
||
3. **ZeroTrust & Public Reachability:** Optionale Anbindung über ein WireGuard-Mesh (z. B. NetBird), um auch Hosts ohne statische IPv4/IPv6 oder hinter NAT/Firewalls öffentlich mit TLS bereitzustellen.
|
||
4. **Integrierte Autorisierung & Monetarisierung:** Mandantensichere Capability-Lizenzen via Ed25519-Kryptografie, Lease-System und automatisierte Überwachung von Lizenzfristen.
|
||
|
||
---
|
||
|
||
## 2. Netzwerkmodell (Network Model)
|
||
|
||
### 2.1 Topologie
|
||
|
||
```text
|
||
[ Öffentliches Internet ]
|
||
│
|
||
│ HTTP (80) / HTTPS (443) / TCP-Streams
|
||
▼
|
||
┌────────────────────────────────────────────────────────┐
|
||
│ Ingress-Knoten (Zentrales Rechenzentrum / Public IP) │
|
||
│ │
|
||
│ ┌────────────────────────────────────────────────┐ │
|
||
│ │ Traefik v3 (Ingress / ACME DNS-01 Validierung) │ │
|
||
│ └───────────────────────▲────────────────────────┘ │
|
||
│ │ HTTP Poll (:8080) │
|
||
│ │ (/v1/traefik-config) │
|
||
│ ┌───────────────────────┴────────────────────────┐ │
|
||
│ │ Sultan-Server (Registry / Policy Engine) │ │
|
||
│ └───────────────────────▲────────────────────────┘ │
|
||
│ │ │
|
||
│ │ Control Plane: │
|
||
│ │ TLS-Stream (:8443) │
|
||
│ │ (45s Heartbeat, │
|
||
│ │ Instant Event Push) │
|
||
│ │ │
|
||
│ ┌───────────────────────┴────────────────────────┐ │
|
||
│ │ NetBird / WireGuard Gateway (100.64.0.1) │ │
|
||
│ └───────────────────────▲────────────────────────┘ │
|
||
└───────────────────────────┼────────────────────────────┘
|
||
│
|
||
ZeroTrust WireGuard Tunnel (Traffic)
|
||
│
|
||
┌──────────────────┴──────────────────┐
|
||
│ │
|
||
┌────────┴──────────────┐ ┌──────────┴─────────────┐
|
||
│ Client-Host A │ │ Client-Host B │
|
||
│ (Bare-Metal / LAMP) │ │ (Docker-Compose Stack) │
|
||
│ │ │ │
|
||
│ ┌───────────────────┐ │ │ ┌────────────────────┐ │
|
||
│ │ sultan-agent │ │ │ │ sultan-agent │ │
|
||
│ │ (File-Watcher) │ │ │ │ (Docker-Socket) │ │
|
||
│ └───────────────────┘ │ │ └────────────────────┘ │
|
||
│ ┌───────────────────┐ │ │ ┌────────────────────┐ │
|
||
│ │ Apache / VHost │ │ │ │ Web-Container │ │
|
||
│ └───────────────────┘ │ │ └────────────────────┘ │
|
||
└───────────────────────┘ └────────────────────────┘
|
||
|
||
```
|
||
|
||
### 2.2 Datenfluss & Verbindungstypen
|
||
|
||
1. **Control Plane (Agent -> Server):**
|
||
* **Transport:** Ausgehende Verbindung vom Agenten zum Server über TCP `:8443` (TLS).
|
||
* **Firewall-Freundlichkeit:** Reine Outbound-Verbindung; funktioniert hinter DS-Lite, Mobilfunk, Carrier-Grade-NAT und Unternehmens-Firewalls ohne Portweiterleitung.
|
||
* **Keepalive-Mechanik:** Persistenter **SSE-Stream** (Server-Sent Events, `text/event-stream`) vom Server zum Agenten. Alle 45 Sekunden ohne Event wird die SSE-Kommentarzeile `:\n\n` gesendet. Verhindert das Schließen von State-Tables in NAT-Routern (Conntrack Timeout). Der Agent gilt als getrennt, wenn 90 s lang nichts ankommt (auch kein Keepalive), und verbindet sich mit exponentiellem Backoff (1 s … 60 s) neu.
|
||
* **Rückkanal (Agent -> Server):** Nicht über den Stream, sondern als eigene, signierte HTTPS-Requests (z. B. `service_state`).
|
||
* **Event-Driven Push:** Änderungen an Containern (Start/Stop) oder Notfall-Sperren werden verzögerungsfrei (Latenz < 5 ms) über den bestehenden Stream übertragen.
|
||
|
||
|
||
2. **Data Plane (Traffic: Besucher -> Backend):**
|
||
* **Direkt:** Liegen Ingress und Backend im selben VLAN/LAN, routet Traefik direkt auf die interne LAN-IP.
|
||
* **ZeroTrust Overlay (NetBird):** Sitzt das Backend im Fremdnetz/Homelab, routet Traefik auf die WireGuard-Overlay-IP (`100.64.x.y`). End-to-End verschlüsselt.
|
||
|
||
|
||
3. **Ingress zu Traefik:**
|
||
* Traefik pollt den lokalen Sultan-Server via HTTP-Provider: `GET http://127.0.0.1:8080/v1/traefik-config`.
|
||
* Intervall: 2–5 Sekunden. Traefik verarbeitet die In-Memory-Konfiguration ohne Neustart und ohne Verbindungsabbrüche.
|
||
* **Pull, nicht Push:** Traefik holt die Konfiguration ab; Sultan schreibt nie in Traefik und emuliert keinen Docker-Socket. Freigeschaltet wird das einmalig in Traefiks statischer Konfiguration (`--providers.http.endpoint`). Router aus Sultan heißen in Traefik `<name>@http`; Mischbetrieb mit dem Docker-Provider für lokale Container ist möglich (Querverweise mit Provider-Suffix, z. B. `auth@docker`).
|
||
* Port 8080 ist Klartext und deshalb nur an Loopback bzw. ein internes Docker-Netz zu binden. Achtung: Traefiks eigenes API/Dashboard nutzt per Default ebenfalls 8080.
|
||
|
||
|
||
|
||
---
|
||
|
||
## 3. Sicherheits- und Vertrauensmodell
|
||
|
||
### 3.1 Transport-Verschlüsselung (TLS ohne CA-Zirkus)
|
||
|
||
* **Grundsatz: Kein Agent-Verkehr im Klartext.** Durchgesetzt auf mehreren Ebenen:
|
||
* Der Agent-Port `:8443` wird ausschließlich per TLS bedient, **nur TLS 1.3**.
|
||
* Der Agent signiert nur Requests an `https`-URLs; an eine `http`-URL geht weder Signatur noch Body.
|
||
* Der Server authentifiziert nur Requests, die über TLS angekommen sind (sonst `426 Upgrade Required`).
|
||
* **Server-Zertifikat:** Wird beim ersten Start selbst erzeugt (selbstsigniert, ECDSA P-256, **keine CA**) und liegt dauerhaft unter `<data-dir>/server.key` (0600) und `server.crt`. Gültigkeit 20 Jahre, weil Agents den Fingerprint pinnen. Fehlt nur eine der beiden Dateien, startet der Server nicht, statt still ein neues Zertifikat zu erzeugen (das würde alle Pins brechen).
|
||
* **Fingerprint:** SHA-256 über das DER-Zertifikat, Base64url ohne Padding (43 Zeichen).
|
||
* **Vertrauensmodell: Pinning mit geprüftem Erstkontakt** (statt reinem TOFU, siehe 3.4):
|
||
* Der Agent speichert den Fingerprint je Server (`host:port`) in `known_servers` (Format wie SSH `known_hosts`: `<server> <fingerprint>`, 0600; Einträge werden nur angehängt, nie still geändert).
|
||
* **Erstkontakt:** Der Fingerprint muss zu dem im Enrollment-Token eingebetteten Wert passen (3.2), erst dann wird gepinnt.
|
||
* **Folgekontakte:** Das Zertifikat muss zum Pin passen. Der Pin gewinnt immer, auch gegen einen später gelieferten Token-Fingerprint.
|
||
* **Ohne Pin und ohne Token-Fingerprint** wird nicht verbunden (kein blindes TOFU).
|
||
* Die Prüfung erfolgt im TLS-Handshake, also bevor Token, Signatur oder Body gesendet werden.
|
||
* **Optional (geplant):** Unterstützung für explizit gemountete Root-CA-Zertifikate.
|
||
|
||
### 3.2 Authentifizierung & Enrollment (CSR-Handshake)
|
||
|
||
* Private Keys werden **ausschließlich lokal auf dem Ziel-Host** generiert (Ed25519) und verlassen diesen niemals. `node.key` liegt als PKCS#8-PEM mit Rechten 0600 vor, wird nie überschrieben und bei offeneren Rechten nicht geladen.
|
||
* **Authentifizierung ist in jedem Tier Pflicht** – auch im `community`-/Homelab-Betrieb gibt es keinen Zugang ohne Ed25519-Signatur und keinen Schalter, der das abstellt.
|
||
* **Enrollment-Token:** `sltn_enroll_<secret>.<fingerprint>`
|
||
* `secret`: 256 Bit Zufall (Base64url). Der Server speichert nur den SHA-256 von `sltn_enroll_<secret>`, einmalig verwendbar, mit Ablaufzeit.
|
||
* `fingerprint`: Fingerprint des Server-Zertifikats (3.1). Nicht geheim; er sichert den Erstkontakt des Agenten ab.
|
||
* Der Admin überträgt den Token auf einem separaten Weg (z. B. Copy-Paste aus dem Server-Terminal) an den Agenten.
|
||
* **Enrollment:**
|
||
1. Admin erzeugt den Einladungs-Token auf dem Server (`sultan token`).
|
||
2. Agent zerlegt den Token, verbindet sich per TLS und prüft dabei den Server-Fingerprint gegen den Token (3.1). Erst danach pinnt er den Server.
|
||
3. Agent generiert lokalen Key (`node.key`) und sendet `sltn_enroll_<secret>` an den Server (`POST /api/v1/enroll`). Der Request ist bereits mit dem neuen Schlüssel signiert (Besitznachweis); der Public Key steht im Header `X-Sultan-Key`.
|
||
4. Server prüft die Signatur, löst den Token ein und legt den Knoten **in einer Transaktion** an. Der Mandant ergibt sich ausschließlich aus dem Token. Schlägt das Anlegen fehl, bleibt der Token gültig. Paralleles Einlösen desselben Tokens gelingt genau einmal.
|
||
5. *(Geplant)* Server signiert das initiale Berechtigungszertifikat (Capability Lease).
|
||
6. Alle künftigen Requests werden vom Agenten mit `node.key` signiert.
|
||
|
||
* **Request-Signatur** (jeder Agent-Request inkl. Stream-Aufbau):
|
||
* Header: `X-Sultan-Key` (Public Key, Base64), `X-Sultan-Timestamp` (Unix-Sekunden), `X-Sultan-Nonce` (16–64 Zeichen, pro Request neu), `X-Sultan-Signature` (Base64).
|
||
* Signiert wird (zeilengetrennt): `SULTAN-ED25519-V1`, Methode, Pfad+Query, Timestamp, Nonce, SHA-256-Hex des Bodys.
|
||
* **Server-Prüfreihenfolge:**
|
||
1. TLS
|
||
2. Signatur (ohne Datenbankzugriff)
|
||
3. Zeitfenster ±5 Minuten
|
||
4. Nonce (Replay-Schutz)
|
||
5. erst dann Nachschlagen des Knotens per Public Key
|
||
|
||
Gefälschte Requests kosten so keinen DB-Zugriff und können keine Nonces verbrauchen.
|
||
* Die **Knoten-ID** wird ausschließlich aus dem geprüften Schlüssel abgeleitet, nie aus einer Angabe des Clients.
|
||
* Body-Limit 1 MiB.
|
||
* Fehler-Mapping: 401 (nicht authentifiziert, Replay, Zeitabweichung), 403 (gesperrt), 413 (Body zu groß), 426 (kein TLS); Infrastrukturfehler 500.
|
||
* **Sperren:** Die Authentifizierung sperrt nur Mandanten im Status `quarantined`. Zahlungsverzug, Ablauf und gedrainte Knoten regelt die Policy-Engine über das Routing (5.2). Der Agent behält den Kanal, z. B. für `lease_renew` oder eine Reaktivierung. Für Entzug zur Laufzeit trennt der Server bestehende Streams aktiv (`Hub.Disconnect`).
|
||
|
||
|
||
|
||
### 3.3 Autorisierung & Domain-Ownership-Schutz
|
||
|
||
Jeder Payload vom Agenten an den Server muss vom Server gegen die zugewiesene Policy geprüft werden:
|
||
|
||
* **Domain Spoofing Protection:** Beansprucht ein Agent ein Label `Host('kunde.de')`, prüft der Server, ob `kunde.de` im Feld `allowed_domains` der Mandanten-Lizenz hinterlegt ist. Falls nicht: Ablehnung mit Sicherheits-Audit-Log.
|
||
* **Route Limits:** Übersteigt die Anzahl der deklarierten Routen das Limit (`max_routes`), werden überzählige Routen verworfen.
|
||
|
||
### 3.4 Bedrohungsmodell: Erstkontakt (TOFU) und Server-Events
|
||
|
||
* **Schwäche von reinem TOFU:** Beim ersten Kontakt wird ungeprüft vertraut. Ein Angreifer im Netzwerkweg (ARP-Spoofing im LAN, DNS-Manipulation, kompromittierter Router, offenes WLAN) würde dauerhaft gepinnt. Er könnte damit:
|
||
* den Enrollment-Token abgreifen und mit eigenem Schlüssel zuerst einlösen,
|
||
* sich dauerhaft dazwischenschalten (der echte Server gilt danach als „Fälschung“),
|
||
* unsignierte Server-Events (`node_command`, `lease_renew`) einschleusen.
|
||
* **Gegenmaßnahme (umgesetzt):** Der Fingerprint ist im Enrollment-Token eingebettet (3.1/3.2). Damit gibt es keinen ungeprüften Erstkontakt mehr. Ein Angreifer scheitert im TLS-Handshake und sieht weder Token noch Signatur; der Token bleibt beim echten Server einlösbar.
|
||
* **Betriebsrisiko:** Ein Verlust von `<data-dir>/server.key` erzeugt ein neues Zertifikat und sperrt alle Agents aus. Deshalb muss `server.key` gesichert werden. *(Geplant:)* geordneter Zertifikatswechsel, bei dem der Server das neue Zertifikat vorab über den gepinnten Kanal ankündigt.
|
||
* **Zweite Schicht (geplant):** Server→Agent-Events werden mit einem Server-Signaturschlüssel signiert, den der Agent beim Enrollment lernt. Die Echtheit von `node_command` hängt dann nicht mehr allein am TLS-Pin.
|
||
|
||
---
|
||
|
||
## 4. Datenmodell (Data Specifications)
|
||
|
||
### 4.1 Lizenz & Capabilities (`license.json`)
|
||
|
||
```json
|
||
{
|
||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||
"title": "SultanCapabilities",
|
||
"type": "object",
|
||
"properties": {
|
||
"tenant_id": { "type": "string" },
|
||
"tier": { "type": "string", "enum": ["community", "pro", "enterprise"] },
|
||
"max_routes": { "type": "integer", "description": "-1 für unbegrenzt" },
|
||
"allowed_domains": {
|
||
"type": "array",
|
||
"items": { "type": "string" }
|
||
},
|
||
"features": {
|
||
"type": "array",
|
||
"items": { "type": "string", "enum": ["websockets", "tcp_stream", "custom_middleware"] }
|
||
},
|
||
"valid_until": { "type": "string", "format": "date-time" },
|
||
"signature": { "type": "string", "description": "Ed25519 Signatur des Server-Master-Keys über den Payload" }
|
||
},
|
||
"required": ["tenant_id", "tier", "max_routes", "allowed_domains", "valid_until", "signature"]
|
||
}
|
||
|
||
```
|
||
|
||
### 4.2 Stream Event Protocol (Agent <-> Server)
|
||
|
||
Beide Richtungen nutzen dasselbe JSON-Event-Format. Server→Agent läuft über den SSE-Stream; jedes Event ist ein SSE-Rahmen `id: <event_id>`, `event: <type>`, `data: <JSON in einer Zeile>`, gefolgt von einer Leerzeile (max. 1 MiB). Agent→Server läuft über signierte HTTPS-Requests. `node_id` setzt der Server immer selbst aus der geprüften Identität.
|
||
|
||
```json
|
||
{
|
||
"event_id": "evt_01J8Z9X2Y3...",
|
||
"timestamp": 1727618531,
|
||
"type": "service_state | lease_renew | node_command | error",
|
||
"node_id": "node-proxmox-vm-42",
|
||
"payload": {}
|
||
}
|
||
|
||
```
|
||
|
||
* **Typ `service_state` (Agent -> Server):**
|
||
Enthält die vollständige Liste der aktuell aktiven Traefik-Labels des Knotens.
|
||
* **Typ `node_command` (Server -> Agent):**
|
||
Enthält Aktionen wie `re_enroll`, `drain`, `maintenance`.
|
||
* **Typ `lease_renew` (Server -> Agent):**
|
||
Liefert ein verlängertes Krypto-Lease an den Agenten zurück.
|
||
|
||
### 4.3 SQLite Datenbankschema (Server State)
|
||
|
||
Der Server persistiert Mandanten, Tokens und Richtlinien lokal in SQLite (`/var/lib/sultan/sultan.db`).
|
||
|
||
* **Treiber:** `modernc.org/sqlite` (reines Go, kein cgo → statisches Single Binary).
|
||
* **Pragmas:** `foreign_keys=ON` (sonst greift `ON DELETE CASCADE` nicht), WAL, `busy_timeout`, Schreib-Transaktionen `IMMEDIATE`.
|
||
* **Migrationen:** Versioniert über `PRAGMA user_version`, nur anhängen. Eine Datenbank mit neuerer Version als das Programm wird abgelehnt.
|
||
* **Zeitstempel:** Die Anwendung setzt sie selbst (keine `CURRENT_TIMESTAMP`-Defaults), als UTC-Text fester Breite (`2006-01-02T15:04:05.000000000Z`). Dadurch funktionieren Vergleiche direkt in SQL.
|
||
* **Tokens:** Gespeichert wird nur der SHA-256-Hash.
|
||
|
||
Schema (Stand Migration v1):
|
||
|
||
```sql
|
||
-- Mandanten & Abonnements
|
||
CREATE TABLE tenants (
|
||
id TEXT PRIMARY KEY,
|
||
name TEXT NOT NULL,
|
||
email TEXT NOT NULL,
|
||
tier TEXT NOT NULL DEFAULT 'community',
|
||
max_routes INTEGER NOT NULL DEFAULT 5,
|
||
allowed_domains TEXT NOT NULL, -- JSON-Array: ["*.firma.de", "shop.de"]
|
||
valid_until DATETIME NOT NULL, -- Ablaufdatum des Vertrags / Abos
|
||
status TEXT NOT NULL DEFAULT 'active', -- active, suspended_payment, quarantined, expired
|
||
created_at DATETIME NOT NULL, -- von der Anwendung gesetzt (UTC-Text)
|
||
updated_at DATETIME NOT NULL
|
||
);
|
||
|
||
-- Registrierte Agenten / Knoten
|
||
CREATE TABLE nodes (
|
||
id TEXT PRIMARY KEY,
|
||
tenant_id TEXT NOT NULL REFERENCES tenants(id) ON DELETE CASCADE,
|
||
hostname TEXT NOT NULL,
|
||
public_key TEXT NOT NULL UNIQUE, -- Ed25519 Public Key des Agenten
|
||
last_seen DATETIME NOT NULL,
|
||
ip_address TEXT NOT NULL,
|
||
status TEXT NOT NULL DEFAULT 'online' -- online, offline, drained
|
||
);
|
||
CREATE INDEX nodes_tenant_id ON nodes(tenant_id);
|
||
|
||
-- Einmalige Enrollment-Tokens
|
||
CREATE TABLE enrollment_tokens (
|
||
token_hash TEXT PRIMARY KEY,
|
||
tenant_id TEXT NOT NULL REFERENCES tenants(id) ON DELETE CASCADE,
|
||
expires_at DATETIME NOT NULL,
|
||
used INTEGER NOT NULL DEFAULT 0
|
||
);
|
||
CREATE INDEX enrollment_tokens_tenant_id ON enrollment_tokens(tenant_id);
|
||
|
||
```
|
||
|
||
---
|
||
|
||
## 5. Anwendungsmodell (Application Model)
|
||
|
||
Das gesamte System ist als **Single-Binary-Architektur** in Go implementiert:
|
||
|
||
```text
|
||
sultan
|
||
├── server # Führt Registry, Stream-Hub, Policy-Engine & Traefik-Provider aus
|
||
├── agent # Führt Docker-/File-Watcher aus und verbindet sich zum Server
|
||
└── token # CLI-Tools zur Schlüsselverwaltung, Enrollment- & Lizenzausstellung
|
||
|
||
```
|
||
|
||
### 5.1 Agenten-Subsysteme
|
||
|
||
1. **Watcher Engine:**
|
||
* **Docker Engine:** Lauscht am `/var/run/docker.sock` via Docker Events API. Filtert nach Labels mit Präfix `traefik.`.
|
||
* **File Provider:** Überwacht Verzeichnis `/etc/sultan.d/*.conf` via Inotify auf Konfigurationsdateien im INI/YAML-Format.
|
||
|
||
|
||
2. **State Serializer:**
|
||
* Extrahiert Services, Host-Ports und Routen.
|
||
* Injiziert automatisch die Ziel-IP (LAN-IP oder NetBird-IP) in die Server-URL-Definitionen für Traefik.
|
||
|
||
|
||
3. **Transport Engine:**
|
||
* Verwaltet den permanenten TLS-Stream mit 45s-Keepalive.
|
||
* Führt automatischen Reconnect mit exponentiellem Backoff durch.
|
||
|
||
|
||
|
||
### 5.2 Server-Subsysteme
|
||
|
||
1. **Stream Hub:**
|
||
* Hält offene Sockets aller Agents im RAM.
|
||
* Verarbeitet State-Pushes und führt Dead-Node-Detection durch (Timeout: 90s).
|
||
|
||
|
||
2. **Dynamic Config Aggregator:**
|
||
* Führt die flachen Traefik-Labels aller aktiven Knoten zusammen.
|
||
* Wandelt die Labels in das verschachtelte Traefik-JSON-Format um.
|
||
* Stellt `GET /v1/traefik-config` bereit.
|
||
|
||
|
||
3. **Policy & Interception Engine:**
|
||
* **Sperrung bei Zahlungsverzug:** Modifiziert den Traefik-Router auf einen internen Redirect zu einer Bezahlseite (`HTTP 402 / Payment Required`).
|
||
* **Notfall-Wartung:** Schlägt das Backend fehl oder meldet der Agent `service_down`, liefert Traefik eine statische Statusseite mit `Retry-After: 60` (`HTTP 503`).
|
||
|
||
|
||
|
||
---
|
||
|
||
## 6. Überwachung, Lizenzfristen & Alerting (Checkmk-Integration)
|
||
|
||
Um zu verhindern, dass Kunden-Instanzen bei Ablauf von Quartals- oder Jahresabonnements unerwartet in den Wartungsmodus fallen, implementiert der Sultan-Server Schnittstellen für **Checkmk** und externe Alerting-Pipelines.
|
||
|
||
### 6.1 Checkmk Local Check Protocol
|
||
|
||
Der Server stellt einen internen Management-Endpunkt bereit: `GET /metrics/checkmk` (oder auslesbar über ein lokales Checkmk-Agent-Plugin-Script `/usr/lib/check_mk_agent/local/sultan_licenses`).
|
||
|
||
Das Ausgabeformat entspricht der nativen Checkmk Local-Check-Syntax:
|
||
|
||
```text
|
||
# Syntax: <Status> <ServiceName> <Metriken> <Nachrichtentext>
|
||
# 0 = OK, 1 = WARN, 2 = CRIT, 3 = UNKNOWN
|
||
|
||
0 "Sultan_Tenant_kunde_schmidt" days_left=74;30;14 OK - Abo aktiv bis 2026-12-15 (74 Tage verbleibend)
|
||
1 "Sultan_Tenant_meier_gmbh" days_left=12;30;14 WARN - Abo laeuft in 12 Tagen ab! Verlaengerung erforderlich.
|
||
2 "Sultan_Tenant_alt_ag" days_left=0;30;14 CRITICAL - Abo seit 1 Tagen abgelaufen! Status: suspended_payment
|
||
|
||
```
|
||
|
||
### 6.2 Schwellenwerte & Alarmierungskaskade
|
||
|
||
* **30 Tage vor Ablauf:** Warnung im Checkmk-Dashboard (Monitoring-Status: `WARN`).
|
||
* **14 Tage vor Ablauf:** Kritischer Alert (`CRIT`). Automatischer E-Mail-Dispatch / Ticket-Erstellung an Kunden und Admin: *„Abo-Verlängerung erforderlich – bitte Rechnung begleichen“*.
|
||
* **Tag 0 (Ablaufzeitpunkt):**
|
||
* Status wechselt in SQLite auf `expired`.
|
||
* Traefik leitet Domain auf Informations-Landingpage um.
|
||
* Checkmk triggert Alarm: `CRITICAL - Service offline geschaltet`.
|
||
|
||
|
||
|
||
---
|
||
|
||
## 7. Referenzkonfigurationen
|
||
|
||
### 7.1 Compose-Setup: Ingress-Knoten
|
||
|
||
```yaml
|
||
services:
|
||
traefik:
|
||
image: traefik:v3.1
|
||
container_name: traefik-ingress
|
||
restart: unless-stopped
|
||
network_mode: host
|
||
command:
|
||
- "--providers.http.endpoint=http://127.0.0.1:8080/v1/traefik-config"
|
||
- "--providers.http.pollInterval=3s"
|
||
- "--entrypoints.web.address=:80"
|
||
- "--entrypoints.web.http.redirections.entryPoint.to=websecure"
|
||
- "--entrypoints.web.http.redirections.entryPoint.scheme=https"
|
||
- "--entrypoints.websecure.address=:443"
|
||
- "--certificatesresolvers.dns-resolver.acme.dnschallenge=true"
|
||
- "--certificatesresolvers.dns-resolver.acme.dnschallenge.provider=rfc2136"
|
||
volumes:
|
||
- ./acme.json:/etc/traefik/acme.json
|
||
|
||
sultan-server:
|
||
image: sultan:latest
|
||
container_name: sultan-server
|
||
restart: unless-stopped
|
||
command: ["sultan", "server", "--data-dir=/var/lib/sultan"]
|
||
ports:
|
||
- "8443:8443" # Agent Inbound (TLS Stream)
|
||
- "127.0.0.1:8080:8080" # Traefik Config Provider & Checkmk Metrics
|
||
volumes:
|
||
- ./sultan-data:/var/lib/sultan # sultan.db, server.key (0600), server.crt – server.key sichern!
|
||
|
||
```
|
||
|
||
### 7.2 Compose-Setup: Kunden-Host (Backend mit Docker)
|
||
|
||
```yaml
|
||
services:
|
||
sultan-agent:
|
||
image: sultan:latest
|
||
container_name: sultan-agent
|
||
restart: unless-stopped
|
||
command:
|
||
- "sultan"
|
||
- "agent"
|
||
- "--server=https://ingress.dein-netz.de:8443"
|
||
- "--token=sltn_enroll_<secret>.<server-fingerprint>" # Ausgabe von `sultan token`
|
||
volumes:
|
||
- /var/run/docker.sock:/var/run/docker.sock:ro
|
||
- ./agent-data:/var/lib/sultan # node.key (0600) und known_servers – persistent halten!
|
||
|
||
kunde-wordpress:
|
||
image: wordpress:latest
|
||
restart: unless-stopped
|
||
labels:
|
||
- "traefik.enable=true"
|
||
- "traefik.http.routers.wp.rule=Host(`kunde.de`) || Host(`www.kunde.de`)"
|
||
- "traefik.http.routers.wp.entrypoints=websecure"
|
||
- "traefik.http.routers.wp.tls=true"
|
||
- "traefik.http.routers.wp.tls.certresolver=dns-resolver"
|
||
- "traefik.http.middlewares.wp-www.redirectregex.regex=^https?://kunde\\.de/(.*)"
|
||
- "traefik.http.middlewares.wp-www.redirectregex.replacement=https://www.kunde.de/$${1}"
|
||
- "traefik.http.middlewares.wp-www.redirectregex.permanent=true"
|
||
- "traefik.http.routers.wp.middlewares=wp-www"
|
||
- "traefik.http.services.wp.loadbalancer.server.port=80"
|
||
|
||
```
|
||
|
||
---
|
||
|
||
## 8. Architekturentscheidungen (Entscheidungslog)
|
||
|
||
| Datum | Entscheidung | Begründung |
|
||
|---|---|---|
|
||
| 2026-09-30 | Traefik bezieht die Konfiguration per **HTTP-Provider (Pull)** von `/v1/traefik-config`; kein Docker-Socket-Nachbau. | Gleichwertiger Traefik-Provider; ein Socket-Nachbau wäre fragil. Remote-Docker-Provider scheidet aus (Root-Zugriff auf Kunden-Hosts, eingehende Ports, nur ein Endpunkt). |
|
||
| 2026-09-30 | Labels → Traefik-Konfiguration: Router/Services typisiert, **Middleware-Optionen als unveränderte Label-Strings** durchgereicht; nicht unterstützte Labels (TCP/UDP, unbekannte Attribute) werden abgelehnt statt ignoriert. Nur mit `traefik.enable=true`. | Traefik parst Middleware-Werte beim Einlesen wie Labels; Sultan muss nicht jeden Middleware-Typ kennen. |
|
||
| 2026-09-30 | Server→Agent-Stream als **SSE**; Agent→Server über eigene signierte Requests. | Das Keepalive `:\n\n` ist SSE-Syntax; SSE ist proxy- und HTTP/1.1-tauglich. |
|
||
| 2026-10-01 | Tenant-Status **`expired`** als vierter gültiger Wert. | Abschnitt 6.2 setzt ihn bei Ablauf. |
|
||
| 2026-10-01 | SQLite über **`modernc.org/sqlite`**. | Kein cgo, statisches Single Binary. |
|
||
| 2026-10-01 | **Ed25519-Request-Signatur in jedem Tier**, auch `community`. | Kein ungeschützter Homelab-Modus; einheitliches Sicherheitsniveau. |
|
||
| 2026-10-01 | Authentifizierung sperrt nur `quarantined`; übrige Sperren über Routing-Policy. | Agent braucht den Kanal weiterhin (Lease, Reaktivierung). |
|
||
| 2026-10-01 | **Kein Klartext für Agent-Verkehr**: TLS 1.3 only, Signer nur für `https`, Verifier nur mit TLS. | Signaturen und Labels dürfen nie unverschlüsselt übertragen werden. |
|
||
| 2026-10-01 | **Token-Format `sltn_enroll_<secret>.<fingerprint>`**, Pinning mit geprüftem Erstkontakt statt blindem TOFU. | Schließt die Man-in-the-Middle-Lücke beim Erstkontakt (3.4). Entscheidet zugleich den früheren Widerspruch `sltn_token_` vs. `sltn_enroll_`. |
|
||
| geplant | Signierte Server-Events; geordneter Zertifikatswechsel; optionale Root-CA. | Zweite Sicherheitsschicht neben dem TLS-Pin; Betrieb ohne Aussperren. |
|