0 Fork 0

Files

T

br dd93277750 Accountant: Inventar, where, Checkmk, Abrechnung

2026-10-18 17:08:58 +02:00

104 KiB

Raw Permalink Blame History

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:

In-Service-Deklaration: Backends deklarieren ihr Routing direkt am Dienst (native Traefik-Labels in Docker oder Drop-in-Konfigurationen unter /etc/sultan.d/).
Dynamische Registrierung: Ein leichtgewichtiger Agent überträgt diese Konfiguration kryptografisch gesichert über einen langlebigen, ressourcenschonenden Keepalive-Stream an den zentralen Ingress.
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.
Integrierte Autorisierung & Monetarisierung: Mandantensichere Capability-Lizenzen via Ed25519-Kryptografie, Lease-System und automatisierte Überwachung von Lizenzfristen.

2. Netzwerkmodell (Network Model)

2.1 Topologie

[ Ö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

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.

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.

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 am Fingerprint, unabhängig von der Adresse (statt reinem TOFU, siehe 3.4):
- Erstkontakt: Der Fingerprint kommt aus der Einladung (3.2). Passt das Zertifikat nicht, wird abgebrochen.
- Danach: Der Fingerprint steht als server_fingerprint in node.json und wird bei jeder Verbindung geprüft, über welche Adresse auch immer (DNS, interne IP, NetBird). Derselbe Server hat überall denselben Fingerprint, deshalb ist ein Adresswechsel gefahrlos. Ein anderer Fingerprint bedeutet einen anderen Server und erfordert ein neues Enrollment.
- Ohne Fingerprint wird nicht verbunden (kein blindes TOFU).
- Die Prüfung erfolgt im TLS-Handshake (crypto.PinnedTLSConfig), also bevor Token, Signatur oder Body gesendet werden. Hostname und CA werden bewusst nicht geprüft; das Pinning ist strenger.
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>[.<server-url>]. Alle Teile sind Base64url; der Token ist ohne Quoting shell-sicher (~130 Zeichen mit URL).
- secret: 256 Bit Zufall. 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 ab.
- server-url (optional, nicht geheim): Adresse, unter der der Agent den Server erreicht.
  - Nur https://host[:port]: kein Pfad, keine Query, keine Zugangsdaten, max. 255 Zeichen.
  - Woher sie kommt: sultan server --public-url (wird im Store gemerkt) oder pro Einladung sultan token invite --server-url. So kann ein Knoten z. B. eine NetBird-Adresse bekommen.
  - Ohne Adresse entsteht der zweiteilige Token; der Agent braucht dann --server.
  - Eine manipulierte Adresse führt dank Pinning höchstens zu einem Verbindungsfehler, nie zum Versand des Secrets an einen fremden Server.
- Der Admin überträgt den Token auf einem vertrauenswürdigen Weg (z. B. Copy-Paste aus dem Server-Terminal). Wer den Token manipulieren kann, könnte auch den Fingerprint tauschen.
- Server-Adresse beim Agent: Beim Enrollment gilt --server/SULTAN_SERVER, sonst die URL aus der Einladung. Danach versucht der Agent in dieser Reihenfolge:
  1. --server
  2. die zuletzt funktionierende Adresse (node.json server)
  3. die Adressliste des Servers (server_urls)
  Nach jedem Verbindungsfehler wechselt er zur nächsten Adresse; eine erfolgreich genutzte wird als server gespeichert. Das ist gefahrlos, weil der Pin am Fingerprint hängt (Schritt 4).
- Umgebungsvariablen SULTAN_TOKEN/SULTAN_SERVER statt Argumenten, z. B. für curl … | sh oder Compose. Argumente wären über ps für andere Benutzer sichtbar.
- Eine in Compose stehen gebliebene, bereits eingelöste Einladung desselben Servers ist harmlos und wird ignoriert. Eine Einladung eines anderen Servers bei bestehender Registrierung wird abgelehnt.
Enrollment:

Admin erzeugt den Einladungs-Token auf dem Server (sultan token).
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.
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.
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.
(Geplant) Server signiert das initiale Berechtigungszertifikat (Capability Lease).
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 (deterministisch: nach Router-Namen sortiert, die hinteren fallen weg).

Umsetzung in pkg/policy. Jeder Verstoß entfernt nur den betroffenen Router und wird als Violation (Audit-Log) gemeldet:

Regel-Analyse statt Textsuche: Traefik-Regeln werden geparst (Matcher, &&, ||, !, Klammern).
- Jeder ||-Zweig muss durch Host(...) eingeschränkt sein. Host(`kunde.de`) || PathPrefix(`/`) würde sonst den Verkehr aller Mandanten abgreifen.
- Negierte Hosts schränken nicht ein.
- HostRegexp ist nicht erlaubt, weil sich ein Regex nicht gegen allowed_domains prüfen lässt.
Namensraum: Router, Services und Middlewares heißen in der ausgelieferten Konfiguration <tenant>__<node>__<name>.
- Mandanten können sich damit weder überschreiben noch gegenseitig referenzieren.
- IDs: alphanumerisch mit -/_, nicht am Rand, kein __.
- Das Präfix sultan__ und die Mandanten-ID sultan sind reserviert.
Fremde Provider: Referenzen mit @ (z. B. api@internal = Traefik-Dashboard) sind verboten, außer sie stehen in einer Freigabeliste des Admins (z. B. auth@file).
Middleware-Ziele begrenzen (geplant): Middlewares mit eigenem Netzwerkziel (z. B. forwardAuth, Redirects auf andere Hosts) sollen auf das eigene Backend des Dienstes beschränkt werden können.
- Grenze: das Tupel ip:port, [ipv6]:port bzw. fqdn:port, eventuell plus höchstens ein Pfadsegment.
- Redirect/Auth auf einen Host derselben Zone (z. B. acronym.meine.home.lab → acronym-service.meine.home.lab) soll möglich bleiben, um Zertifikate zu erleichtern.
- Aktivierung per Label; zunächst im Beobachtungsmodus (nur Audit-Log, keine Sperre).
- Zunächst werden nur die mitgelieferten Redirects (to-www/to-non-www) angeboten; alles andere wird geduldet.
- Umgesetzt ist die Andockstelle policy.Engine.MiddlewareTargetCheck(mwName, def, backend):
  - nil (Default): alles dulden
  - mit Prüffunktion und EnforceMiddlewareTargets = false: Verstoß nur melden (Observed)
  - mit true: Router entfernen
- Regeln und Label-Name folgen später.
Middleware-Gates:
- Ohne Feature custom_middleware sind nur Basistypen erlaubt: redirectScheme, redirectRegex, stripPrefix(Regex), addPrefix, replacePath(Regex), compress, headers.
- chain und errors sind immer verboten, weil sie per Namen auf andere Middlewares/Services verweisen und den Namensraum umgehen könnten.
Nicht referenzierte Services/Middlewares werden nicht ausgeliefert.
TCP / TLS-Passthrough (umgesetzt 2026-10-11): für Dienste mit eigener CA bzw. eigener TLS-Verwaltung (z. B. tinyCA im Kundenlabor). Traefik routet per SNI und reicht die TLS-Verbindung unverändert zum Backend durch.
- Labels: traefik.tcp.routers.<n>.{rule,entrypoints,service,priority,tls,tls.passthrough} und traefik.tcp.services.<n>.loadbalancer.server.port. TCP-Middlewares, TLS-Terminierung (certresolver/options), proxyProtocol und UDP bleiben ErrUnsupportedLabel.
- Nur mit Feature tcp_stream (in jedem Tier vergebbar, auch community).
- Nur tls.passthrough=true, nur Entrypoint websecure (wird immer gesetzt; ein anderer Entrypoint ist ein Verstoß).
- Regel: Jeder ||-Zweig muss durch HostSNI(...) beschränkt sein, nur explizite Hosts: HostSNI(`*`), Wildcards und HostSNIRegexp sind verboten. Jeder Host muss in allowed_domains stehen; eine Wildcard dort (*.lab.kunde.de) deckt einzelne Hosts darunter.
- Jeder TCP-Router zählt gegen max_routes; HTTP-Router werden zuerst vergeben, danach TCP (jeweils nach Namen).
- Gleicher Namensraum <tenant>__<node>__<name>.
- Stufen: Ohne HTTP gibt es keinen Interceptor. Mahnstufe 1/2 lassen durch; ab Paywall (auch landing) sowie bei jeder Wartung (Knoten, Dienst, Healthcheck, getrennter Knoten) wird die Route entfernt; Sperre/drain wie bei HTTP.

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 (umgesetzt, Schritt 2): Jedes Server→Agent-Event ist mit dem Master-Key signiert (signature, Präfix SULTAN-EVENT-V1, über alle übrigen Felder inkl. event_id, timestamp, node_id). Der Agent kennt den Public Key seit dem Enrollment (node.json) und verwirft Events ohne gültige Signatur. Die Echtheit von node_command hängt damit nicht mehr allein am TLS-Pin.

4. Datenmodell (Data Specifications)

4.1 Lizenz & Capabilities (`license.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"]
}

Signatur: Ed25519 mit dem Server-Master-Key.
- Signiert wird SULTAN-LICENSE-V1\n + JSON der Felder in fester Reihenfolge (tenant_id, tier, max_routes, allowed_domains, features, valid_until).
- valid_until geht als RFC 3339 in UTC mit ganzen Sekunden ein.
- Jede Änderung eines Felds, auch die Reihenfolge der Domains, macht die Signatur ungültig.
- Das Präfix trennt Lizenz-Signaturen von künftigen anderen Nutzungen desselben Master-Keys (z. B. signierte Server-Events, 3.4).
Einlesen: Unbekannte Felder werden abgelehnt; features fehlt → leere Liste.
allowed_domains: Kleinbuchstaben, ohne Punkt am Ende, IDN als Punycode (xn--…).
- shop.de deckt genau shop.de.
- *.firma.de deckt jede Subdomain beliebiger Tiefe, aber nicht firma.de selbst.
- Wildcards nur ganz vorne; *.de (Wildcard auf TLD) und * sind unzulässig.
Ablauf: Der Zeitpunkt valid_until selbst gilt als abgelaufen. „Verbleibende Tage“ (Checkmk) = abgerundete volle Tage, nach Ablauf negativ.
Routen: max_routes = -1 bedeutet unbegrenzt.

4.1a Leases (Entscheidung 2026-10-01)

Eine Lease ist eine kurzlaufende, signierte Kopie der Lizenz (gleiches Format, eigenes valid_until). Sie ist der „Ausweis“, mit dem ein Knoten Routen bekommt.
Kommerziell: Laufzeit 7 Tage, Erneuerung nach rund 2/3 (ab Tag 4–5); bei Wartung/Baustelle 10 Tage, Erneuerung ab Tag 5. Angelehnt an ACME (90 Tage, Erneuerung nach ~60). Die Lease endet spätestens mit dem bezahlten Abo-Zyklus (valid_until der Lizenz).
Community: Laufzeit max. 14 Tage, Erneuerung nach ca. 7 Tagen mit zufälliger Streuung (damit nicht alle Agents gleichzeitig erneuern). Der Server stellt Lizenz und Lease selbständig neu aus (re-license). Es gibt kein Mahnwesen.
- Eine Wartung des Servers darf damit bis zu 7 Tage dauern: Bis die Lease abläuft, wird nichts invalidiert, keine Authentifizierung, keine Policy, keine Route.
- Ist das Backend in dieser Zeit nicht erreichbar, zeigt der Lander eine 50x-Seite („geht gerade nicht …“) mit Hinweis auf den Pro-Service.
Umsetzung (Schritt 2):
- Lease-Dokument: Lizenzfelder plus node_id, issued_at, renew_after, valid_until, signiert mit dem Master-Key unter dem Präfix SULTAN-LEASE-V1 (gilt nie als Lizenz und umgekehrt).
- Community: 14 Tage, Erneuerung nach 7 Tagen ± 12 h Streuung. Kommerziell: 7 Tage (10 bei Wartung), Erneuerung nach 2/3, gekappt am Vertragsende; nach Vertragsende keine Lease.
- Der Server stellt beim Verbinden aus bzw. erneut zu und erneuert bei jedem Refresh ab renew_after (lease_renew).
- Der Agent prüft die Signatur, legt lease.json ab und protokolliert. Weitere Folgen hat das beim Agent vorerst nicht; ein Checkmk-Check auf Kundenseite ist vorgesehen.
- Wirkung serverseitig: Ein getrennter Knoten behält seine Routen als Wartungsseite, bis die Lease abläuft.
- sultan server --lease-duration (Konfigurationsfeld LeaseDuration) erzwingt eine feste Laufzeit, für Tests und Sonderfälle.
Unterbrechung jederzeit serverseitig möglich: Agent und Traefik pollen bzw. halten den Stream, also wirkt eine Unterbrechung sofort (Hub.Disconnect, keine Erneuerung, Policy-Stufe).
- Gründe: Security-Breach, DDoS, Domain-Verstoß.
- Nur kommerziell zusätzlich: Verstoß gegen Nutzungsrichtlinien (z. B. strafbare Inhalte), Zahlungsausfall, unterbrochenes Abo.
Eskalation (nur kommerziell), analog zu Mahnstufen: Karenzzeit mit Wasserzeichen → Firemark → Paywall-Landingpage („Kauf mich!“), siehe Stufen in 5.2.

4.1b Agent-Konfiguration `/etc/sultan.d/*.yaml` (umgesetzt 2026-10-02)

Format: YAML, eine oder mehrere Dateien *.yaml/*.yml (Verzeichnis per --config-dir, Default /etc/sultan.d, none = aus). Unbekannte Felder sind Fehler.

services:
  - name: kunde-a                     # a–z, 0–9, - und _ (Router-/Service-Name)
    url: https://127.0.0.1:8443/      # lokaler Dienst; sein Port gilt auch für den Ingress
    hosts: [kunde-a.de]               # keine Wildcards
    https: true                       # Router auf websecure mit TLS
    certresolver: dns-resolver        # optional
    entrypoints: [websecure]          # optional, Default websecure (https) bzw. web
    redirect_http_to_https: true      # zweiter Router auf web mit redirectScheme (nur mit https)
    redirect_www: to_non_www          # none | to_www | to_non_www
    maintenance: false                # true = Dienst in Wartung (Wartungsseite)
    maintenance_public_reason: ""     # optional, ersetzt den Standardtext
    healthcheck:                      # optional
      url: https://127.0.0.1:8443/    # Default: url des Dienstes
      interval: 30s                   # Default 30s
      timeout: 5s                     # Default 5s
      failures: 2                     # Fehlschläge in Folge bis "down", Default 2
      expect_status: 200              # Default 200
      expect_title: "KundeA - Willkommen"            # optional, exakter <title> (Leerraum normalisiert)
      expect_contains: { tag: h2, text: Impressum }  # optional, Element enthält Text
    labels:                           # optional: rohe traefik.*-Labels, überschreiben die erzeugten
      traefik.http.middlewares.kunde-a-www.redirectregex.permanent: "false"

Übersetzung in Traefik-Labels (danach gelten dieselben Regeln wie für Docker: FromLabels, Policy, Namensraum):
- Workload-Name sultan.d/<name>; Router und Service heißen <name>.
- Backend: <backend-host>:<port der url>; https-URL → loadbalancer.server.scheme=https. Ohne Port 80/443.
- redirect_www:
  - Middleware <name>-www (redirectRegex, permanent), z. B. ^https?://www\.(kunde-a\.de)(.*) → https://${1}${2}.
  - Die jeweils fehlende Variante (www./ohne) wird automatisch in die Hosts aufgenommen, sonst käme die Anfrage nie beim Router an.
  - Die Policy prüft beide Varianten gegen allowed_domains.
- redirect_http_to_https: Router <name>-http auf web mit Middleware <name>-https (redirectScheme https, permanent).
Healthcheck → Wartungsseite:
- Der Agent prüft regelmäßig Status, optional <title> und ein Element mit Text. Das ist ein einfacher Textabgleich ohne HTML-Bibliothek.
- Nach failures Fehlschlägen in Folge gilt der Dienst als down, nach einem Erfolg wieder als up (gegen Flattern).
- Ausgefallene Dienste stehen in down_services; die Policy leitet ihre Router auf maintenance um (503 über den Interceptor).
Änderungen: Das Verzeichnis wird per Polling geprüft (Default alle 5 s, Inhaltsvergleich), nicht per inotify. Polling ist zuverlässig auch bei Docker-Bind-Mounts und atomar ersetzten Dateien und braucht keine Abhängigkeit.
- Bei Änderungen werden die Dienste neu geladen, Healthchecks neu gestartet und der Zustand gesendet.
- Eine fehlerhafte Datei oder ein doppelter Dienstname wird mit Warnung übersprungen; die übrigen Dateien bleiben aktiv.
Backend-Adresse/NetBird: wie bei Docker (--backend-host, --backend-interface, sonst automatisch).

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.

{
  "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): Payload {command, reason}, feste Liste:
- resync: Agent sendet sofort seinen Zustand.
- rotate_key: Agent legt node.key.new an und meldet ihn (POST /api/v1/rotate-key). Erst nach Erfolg wird umbenannt. Ein Abbruch wird beim nächsten Start sicher abgeschlossen: Lehnt der Server den alten Schlüssel ab, wird mit dem neuen wiederholt.
- drain, maintenance, resume: Hinweise, der Agent protokolliert nur.
- config: Adressliste des Servers (server_urls), wird beim Verbinden direkt gesendet (nicht über die Warteschlange). Der Agent übernimmt nur gültige https-Adressen nach node.json.
Die CLI reiht Befehle in node_commands ein, der Server stellt sie beim Verbinden und bei jedem Refresh zu.
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 (<data-dir>/sultan.db, Default-Datenverzeichnis ./suldata).

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.
Migration v2: Tabelle settings (key TEXT PRIMARY KEY, value TEXT NOT NULL) für Server-Einstellungen, die auch sultan token braucht (derzeit public_url).
Migration v3: Wartung pro Knoten – nodes.maintenance_since, maintenance_until (NULL = unbefristet), maintenance_reason, maintenance_public_reason.
Migration v5: Tabelle notifications (key, sent_at) für „jedes Ereignis genau einmal“.
Migration v4:
- Tabelle leases (node_id, issued_at, renew_after, valid_until, document)
- Tabelle node_commands (id, node_id, command, reason, created_at, sent_at)
- tenants.features (JSON) und tenants.payment_overdue_since; daraus Lizenz-Features bzw. Mahnstufe
- enrollment_tokens.used_at

Schema (Stand Migration v1):

-- 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:

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

Umsetzung: main.go ist eine dünne Hülle (Signale → pkg/cli.Run); pkg/cli parst Befehle und Flags; pkg/server verdrahtet Store, Zertifikat, Master-Key, Hub, Verifier, Registry und Policy.

Datenverzeichnis: Default ./suldata (relativ zum Arbeitsverzeichnis), für Server und Agent; per --data-dir änderbar. Es wird mit Rechten 0700 angelegt und enthält Schlüssel. Es gehört gesichert und nie ins Git (steht in .gitignore).

sultan server – Flags und Defaults:

Flag	Default	Bedeutung
`--data-dir`	`./suldata`	`sultan.db`, `server.key`/`server.crt`, `master.key`
`--agent-addr`	`:8443`	Agent-Port, nur TLS 1.3
`--public-url` (mehrfach)	–	Adressen, unter denen Agents den Server erreichen (z. B. öffentlich und NetBird); werden im Store gemerkt (`settings.public_urls`). Die erste steckt in Einladungen; die ganze Liste bekommen Agents beim Verbinden per `config`-Befehl
`--provider-addr`	`127.0.0.1:8080`	Traefik-Provider, Klartext. Bewusst Loopback, weil die Konfiguration Backend-IPs aller Mandanten enthält. Im Container `:8080` setzen und nur auf `127.0.0.1` veröffentlichen.
`--lander-addr`	`127.0.0.1:8081`	eingebauter Lander; `none` = aus (externer Lander)
`--interceptor-url`	Adresse des Landers	URL, unter der Traefik den Lander erreicht
`--hoster-name`, `--hoster-url`, `--pro-url`	–	Texte und Links der Lander-Seiten
`--notify-slack`, `--notify-ntfy` (mehrfach), `--notify-ntfy-token`	–	Benachrichtigungsziele
`--offline-alert-after`	`15m`	Alarm/CRIT für getrennte Knoten
`--lease-duration`	`0` (je Tier)	feste Lease-Laufzeit (Tests, Sonderfälle)
`--enroll-limit`	`10`	Enrollment-Versuche pro Minute und Client-IP, gleitendes Fenster; darüber `429` mit `Retry-After`; `-1` = unbegrenzt. Geprüft vor der Signaturprüfung

Umgebungsvariablen: Jedes Flag von server, agent und token ist auch als SULTAN_<FLAG> setzbar (--public-url → SULTAN_PUBLIC_URL, --notify-ntfy-token → SULTAN_NOTIFY_NTFY_TOKEN, --data-dir → SULTAN_DATA_DIR).

Listen sind kommagetrennt.
Flags gewinnen; bei Listen ersetzt ein Flag den Wert aus der Umgebung, statt ihn zu ergänzen.
Die Hilfe (--help) nennt zu jedem Flag die Variable; fehlerhafte Werte werden mit dem Variablennamen gemeldet.
Geheimnisse wie SULTAN_NOTIFY_NTFY_TOKEN oder SULTAN_TOKEN gehören in die Umgebung statt auf die Befehlszeile (dort per ps sichtbar). | --refresh | 1m | Neubewertung aller Knoten (zeitabhängige Stufen, Mandantenänderungen) |

HTTP-Routen des Servers:

Port	Route	Zweck
Agent (TLS)	`POST /api/v1/enroll`	Body `{token, node_id, hostname}`, signiert mit neuem Schlüssel → 201 `{node_id, tenant_id, master_public_key}`; Token ungültig/verbraucht/abgelaufen → 403 ohne Details; ID/Schlüssel vergeben → 409
Agent (TLS)	`GET /api/v1/stream`	SSE-Stream (signiert); Stream offen = Knoten `online`
Agent (TLS)	`POST /api/v1/maintenance`	Body `{enabled, duration ("" = 4h, "0" = unbefristet), reason, public_reason}` → 204; wirkt sofort
Agent (TLS)	`POST /api/v1/rotate-key`	Body `{public_key, proof}`, signiert mit dem bisherigen Schlüssel; `proof` = Signatur des neuen Schlüssels über `SULTAN-ROTATE-V1\n<node_id>\n<public_key>` (an die Knoten-ID gebunden). Idempotent: ist der neue Schlüssel schon aktiv, ebenfalls 204
Agent (TLS)	`POST /api/v1/state`	vollständiger Schnappschuss `{workloads: [{name, host, labels}], down_services}`; nur bei offenem Stream (sonst 409) → 204
Provider	`GET /v1/traefik-config`	`?format=json\|yaml`
Provider	`GET /healthz`	Lebenszeichen
Provider	`GET /metrics/checkmk`	Checkmk Local Checks (6.1)

sultan token – Verwaltung (Community-Weg; kommerziell zusätzlich Admin-API, geplant): arbeitet direkt auf dem Datenverzeichnis des Servers, auch während er läuft (SQLite/WAL).

Befehl	Wirkung
`tenant add --id --name --email --domains [--tier community] [--max-routes 5] [--valid-until +1 Jahr] [--features …]`	Mandant anlegen; Domains werden wie in der Lizenz normalisiert und geprüft; Features fließen in Lizenz, Lease und Policy
`tenant list` / `tenant set-status --id --status` / `tenant delete --id`	Anzeigen, Status setzen (wirkt beim nächsten Refresh), Löschen inkl. Knoten und Einladungen
`invite --tenant [--ttl 24h\|7d] [--server-url]`	Einladung `sltn_enroll_<secret>.<fingerprint>[.<server-url>]`; Adresse aus `--server-url` oder der gemerkten `--public-url`; stdout enthält nur den Token, Hinweise auf stderr
`node list [--tenant]`	Knoten mit Status und Wartung (`bis …`, `unbefristet`, `abgelaufen`)
`node maintenance --id [--for 4h\|0] [--reason] [--public-reason]`	Wartung anmelden (wirkt beim nächsten Refresh, ≤ 1 min)
`node drain --id` / `node resume --id` / `node delete --id`	drain; `resume` beendet Wartung und drain (`online` setzt erst der Stream). drain/maintenance/resume schicken dem Agenten zusätzlich einen Hinweis
`node command --id --cmd resync\|rotate_key [--reason]`	Befehl in die Warteschlange; Zustellung beim nächsten Refresh bzw. Verbinden
`license issue --tenant`	signierte `license.json` (Master-Key) auf stdout
`purge`	verbrauchte und abgelaufene Einladungen löschen

Ein nicht initialisiertes Datenverzeichnis wird nie angelegt. Ein Tippfehler bei --data-dir würde sonst eine neue Server-Identität erzeugen, und alle damit ausgestellten Einladungen hätten einen falschen Fingerprint.
Exit-Codes: 0 ok, 1 Fehler, 2 Bedienfehler.

Wartung vom Knoten aus: sultan agent maintenance on|off [--for 4h|0] [--reason] [--public-reason] meldet die Wartung signiert beim Server an (z. B. in Patch- oder Reboot-Skripten). Der laufende Agent wird dafür nicht benötigt.

Lebenszyklus eines Knotens:

Enrollment legt ihn offline an.
Stream verbunden → online.
Stream verbunden → Lease ausstellen bzw. zustellen, ausstehende Befehle zustellen.
Stream getrennt → offline. Die Routen bleiben als Wartungsseite stehen, solange eine Wartung angemeldet ist oder die Lease gilt; danach werden sie entfernt (Prüfung bei jedem Refresh). drain entfernt sie sofort.
drained bleibt bei beidem unverändert.

Der Agent muss deshalb nach jedem (Wieder-)Verbinden seinen Zustand erneut senden.

5.1 Agenten-Subsysteme

Umsetzung (pkg/agent, pkg/docker, sultan agent), Teil 1:

Flag	Default	Bedeutung
`--server` / `SULTAN_SERVER`	–	Override der Server-Adresse; sonst aus der Einladung bzw. `node.json`
`--token` / `SULTAN_TOKEN`	–	Einladung, nur beim ersten Start
`--data-dir`	`./suldata`	`node.key` (0600), `node.json` (inkl. `server_fingerprint`)
`--node-id`	aus dem Hostnamen	z. B. `Proxmox-VM.42` → `proxmox-vm-42`
`--docker-socket`	`/var/run/docker.sock`	`none` = ohne Docker
`--backend-host` / `--backend-interface`	automatisch	siehe Backend-Adresse
`--fqdn` / `SULTAN_FQDN`	automatisch	Name des Hosts fürs Inventar (5.3), nur Information

Enrollment:
1. Der Agent erzeugt node.key und prüft den Server gegen den Fingerprint aus der Einladung.
2. Er löst die Einladung ein und speichert node.json (Adresse, server_fingerprint, Knoten-ID, Mandant, Master-Public-Key).
3. Danach ist kein Token mehr nötig.
4. Adresswechsel desselben Servers sind erlaubt und werden gespeichert. Ein anderer Server erfordert ein neues Enrollment (Datenverzeichnis leeren).
Zustand senden: vollständiger Schnappschuss an POST /api/v1/state.
- Ausgelöst wird er nach jedem (Wieder-)Verbinden des Streams (der Server hat die Routen beim Trennen entfernt) und bei jedem Docker-Event.
- Mehrere Auslöser werden über ein kurzes Sammelintervall gebündelt (Default 500 ms).
- Schlägt die Docker-API fehl, wird nichts gesendet, sonst würden alle Routen entfernt. Ohne Docker-Socket (Bare-Metal) ist der Zustand leer.
Port-Übersetzung: Der Ingress sitzt auf einem anderen Host. Deshalb wird loadbalancer.server.port (Port im Container) auf den veröffentlichten Host-Port umgerechnet.
- Fehlt das Port-Label, gilt wie bei Traefiks Docker-Provider der einzige veröffentlichte Port.
- Ohne Service-Labels entsteht ein Service mit dem Containernamen.
- Container, deren Port von außen nicht erreichbar ist (nicht veröffentlicht, nur auf 127.0.0.1/::1, nur UDP), werden mit Warnung weggelassen.
- Es werden nur Container mit traefik.enable=true gemeldet.
Gestoppt vs. entfernt: Der Agent listet auch gestoppte Container (/containers/json?all=1).
- Gestoppt (docker stop, Absturz, restarting, paused, created): Der Container wird weiter gemeldet, seine Services stehen in down_services → Wartungsseite (503) statt 404. Die Ports stammen aus HostConfig.PortBindings (die Liste nennt bei gestoppten Containern keine Ports).
- Entfernt (docker rm, docker compose down): Die Route verschwindet – bewusstes Abschalten.
- Teilt ein gestoppter Container Router- oder Service-Namen mit einem laufenden (z. B. alte Kopie), entfällt der gestoppte.
Backend-Adresse, in dieser Reihenfolge:
1. --backend-host
2. IP von --backend-interface (z. B. wt0)
3. automatisch die lokale IP, über die der Server erreicht wird
Docker: minimaler Client für die Engine API über den Unix-Socket, ohne Docker-SDK (nur GET /containers/json und GET /events). Events werden mit Backoff neu abonniert; nach jedem Neuaufbau wird der Zustand neu gesendet.
Server-Events (node_command, lease_renew) werden bisher nur protokolliert.

Watcher Engine:

Docker Engine: Lauscht am /var/run/docker.sock via Docker Events API. Filtert nach Labels mit Präfix traefik..
File Provider: liest /etc/sultan.d/*.yaml (Format 4.1b) per Polling, inkl. Healthchecks – umgesetzt (Teil 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.

Transport Engine:

Verwaltet den permanenten TLS-Stream mit 45s-Keepalive.
Führt automatischen Reconnect mit exponentiellem Backoff durch.

5.2 Server-Subsysteme

Stream Hub:

Hält offene Sockets aller Agents im RAM.
Verarbeitet State-Pushes und führt Dead-Node-Detection durch (Timeout: 90s).

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.

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).

Stufen (pkg/policy.StageFor), Reihenfolge der Prüfung:

Bedingung	Stufe	Wirkung
Status `quarantined`	`blocked`	keine Routen
Status `expired` oder Lizenz abgelaufen	`landing`	Informations-Landingpage
Tier `community`	`normal`	kein Mahnwesen
Status `suspended_payment` oder Mahnstufe ≥ 3	`paywall`	Kunde ist offline: freundliche Einladung des Hosters, den Sultan-Service und weitere Angebote kennenzulernen (402), kein Durchlass
Mahnstufe 2	`firemark`	Hinweisseite, dann Weiterleitung zum Original (längere Wartezeit)
Mahnstufe 1	`watermark`	Hinweisseite, dann Weiterleitung zum Original (kurze Wartezeit)
Healthcheck meldet Dienst down	`maintenance` (je Router)	503, `Retry-After: 60`

Sultan-Interceptor / Web-Lander (pkg/lander, läuft im Server-Prozess auf --lander-addr, Default 127.0.0.1:8081): Bei jeder Stufe außer normal leitet die Policy den Router auf den Service sultan__interceptor um. Die Interceptor-URL folgt automatisch der gebundenen Lander-Adresse; mit --lander-addr=none und --interceptor-url lässt sich ein externer Lander nutzen.
- Regel, TLS und die Middlewares des Mandanten bleiben erhalten.
- Ein headers-Middleware setzt X-Sultan-Stage, X-Sultan-Tenant und X-Sultan-Tier. Traefik überschreibt damit vom Besucher gesendete Werte.
- Der Lander liefert nur eine eigene HTML-Seite je Stufe. Er verändert keine Originalseiten und braucht deshalb kein Upstream.
Mahnhinweis mit Durchlass (watermark/firemark):
1. Der Lander zeigt den Hinweis und leitet per <meta http-equiv="refresh" content="<x>;url=<ursprüngliche URL>"> zurück. Wartezeit konfigurierbar, Default 5 s (Stufe 1) und 10 s (Stufe 2).
2. Dabei setzt er das Cookie sultan_ack=<stufe> auf der Mandanten-Domain, gültig 60 Minuten (durchschnittlicher Besuch). Der Hinweis darf also mehrmals am Tag erscheinen.
3. Die Policy erzeugt dafür einen zweiten Router sultan__<tenant>__<node>__<router> mit der Regel (<Originalregel>) && HeaderRegexp(`Cookie`, `(^|;\s*)sultan_ack=<stufe>(;|$)`). Er führt direkt zum Original, sonst würde die Weiterleitung wieder beim Lander landen (Schleife).
4. Priorität: Ohne gesetzte Priorität gewinnt der Durchlass über die längere Regel, sonst über Priorität+1.
5. Eine bestätigte niedrigere Stufe gilt nicht für eine höhere.
6. Das Cookie ist bewusst kein Sicherheitsmerkmal: Wer es selbst setzt, überspringt nur den Hinweis. paywall, landing und maintenance haben keinen Durchlass.
Eskalation in der Praxis: Bei Stufe 1 und 2 alarmiert Checkmk. Zwei Alarme genügen; spätestens mit Stufe 3 ist der Kunde offline.

Lander-Seiten (umgesetzt):

Stufe	Status	Inhalt
`watermark` / `firemark`	200	Hinweis, `meta refresh` nach 5 / 10 s, Cookie `sultan_ack=<stufe>` (60 min, HttpOnly, SameSite=Lax, Secure hinter HTTPS)
`paywall`	402	Kunde offline, freundliche Einladung des Hosters (`--hoster-name`, `--hoster-url`)
`landing`	402	Hosting abgelaufen, Einladung des Hosters
`maintenance`	503, `Retry-After: 60`	„Gleich wieder da“; Community zusätzlich mit Pro-Hinweis (`--pro-url`)

Eingebaut: je Stufe eine minimale HTML-Seite ohne CSS, Text auf Deutsch und Englisch auf derselben Seite, noindex, Cache-Control: no-store. Alle Methoden (auch POST) bekommen die Seite.
Weiterleitungsziel nur lokal: Pfad+Query des Requests. Ziele wie //fremd.example oder mit \ werden zu /; es gibt keine Hosts und keine Schemata. Grund: html/template lässt im content von meta refresh auch javascript: durch, und //host wäre eine offene Weiterleitung.
Eigene Vorlagen: <data-dir>/landing/<stufe>.html (Go html/template), optional <stufe>.css und <stufe>.svg/.webp (je ≤ 512 KiB).
- CSS und Grafik werden eingebettet ({{.CSS}}, {{.Image}} als data:-URI). Bei Mahnstufe 1/2 ist das Cookie schon gesetzt, ein separater Asset-Request ginge über den Durchlass-Router ans Kunden-Backend.
- Änderungen wirken sofort (Neuladen bei geänderter Größe/Zeitstempel).
- Eine fehlerhafte Vorlage führt zurück zur eingebauten Seite und wird protokolliert.
sultan dump-landing [--out ./suldata/landing] [--force] schreibt die eingebauten Seiten plus README.txt (alle Template-Werte) als Ausgangspunkt.

Begriffe – maintenance vs. drain (Festlegung 2026-10-02):

	maintenance – „bin gleich wieder da“	drain – „gebe meine Arbeit ab“
Routen bei Traefik	bleiben, zeigen 503 (Lander)	werden entfernt
Besucher sehen	Wartungsseite mit `Retry-After`	anderen Knoten, falls einer die Domain bedient, sonst 404
Dauer	befristet (Default 4 h, `--for`)	bis `resume`
Anlass	Patchen, Reboot, Migration, Sicherheitsupdate	Umzug, Abbau, Lastverteilung
Knoten	darf sich trennen (Reboot) – Routen bleiben als Wartungsseite stehen	bleibt verbunden, bekommt weiter Events und Leases
Auslöser	Admin (`sultan token node maintenance`) oder Knoten selbst (`sultan agent maintenance on`), pro Dienst per YAML/Label	Admin

Wie in der Cloud (kubectl drain vor der Wartung) ist die Kombination möglich: erst drain (Last auf andere Knoten), dann Wartung am leeren Knoten.
Einschränkung: Echte Lastverteilung einer Domain über mehrere Knoten gibt es noch nicht (Roadmap). Bis dahin ist bei Seiten mit nur einem Backend maintenance das Mittel der Wahl; drain bedeutet dort „Seite offline (404)“.

Wartung (umgesetzt, Schritt 1):
- Quellen: Knoten (node maintenance bzw. agent maintenance on), Dienst (Label sultan.maintenance=true + optional sultan.maintenance.public_reason, in YAML maintenance/maintenance_public_reason), Healthcheck-Ausfall.
- Vorrang: Sperre/drain (keine Routen) > Ablauf/Paywall > Wartung > Mahnhinweis > normal. Wartung unterdrückt also auch den Cookie-Durchlass der Mahnstufen.
- Header an den Lander: X-Sultan-Until (RFC 3339, nur befristet) und X-Sultan-Public-Reason (URL-kodiert).
- Lander: public_reason (max. 300 Zeichen, einzeilig) ersetzt den Standardtext; das Ende wird in der Zeitzone des Servers angezeigt; Retry-After = Sekunden bis zum Ende (60 s … 1 Tag).
- reason (max. 500 Zeichen) erscheint nur im Log und in node list, nie öffentlich.
Mahnstufen-Zeitplan (policy.DunningSchedule): Der Server berechnet die Stufe aus dem Fälligkeitsdatum der offenen Zahlung, angelehnt an Bank-Zahlungsfristen: Stufe 1 ab 8 Tagen, Stufe 2 ab 25, Stufe 3 ab 32 Tagen Verzug. Die Werte sind konfigurierbar.

5.3 Accountant: zentrales Inventar & Abrechnung (Entscheidung 2026-10-16; 6a–6c umgesetzt)

Zweck (Priorität): (1) Im Störfall sofort wissen, auf welchem Backend-Host und in welchem Compose-Stack eine URL läuft – ohne Umweg über DNS, Reverse-Proxy und VPN-Suche. (2) Inventar je Mandant (Grundlage für spätere Statusberichte an Mandanten). (3) Abrechnung markierter Services.

Rollen:

Accountant – sultan accountant (gleiches Binary, eigene Rolle): nimmt Berichte entgegen, führt Inventar und Historie. Eigenes Datenverzeichnis mit eigener accountant.db, eigenem TLS-Zertifikat (gepinnt wie beim Server) und eigenem Agent-Port (Default :8444).
Payee – ein normaler sultan server (Ingress mit Traefik), der zusätzlich an den Accountant meldet: --accountant=https://…:8444 (bzw. SULTAN_ACCOUNTANT) plus Einladung des Accountants. Nur Server melden; Agents (Docker wie systemd) sind nicht meldepflichtig, sie liefern ihrem Server lediglich Zusatzdaten.

Warum eigene DB: andere Lebensdauer (Historie über Jahre, eigene Aufbewahrung/Backups), anderes Vertrauen (Berichte sind Eingaben fremder Server und werden nie mit dem eigenen Mandanten- und Schlüsselbestand vermischt), kein Ballast und keine Migrationen auf jedem Ingress. Migrationsmechanik und Zeitformat werden aus pkg/store wiederverwendet.

Transport & Sicherheit: wie Agent → Server. Payee erzeugt lokal payee.key (Ed25519, im Datenverzeichnis des Servers), löst eine Einladung sltn_enroll_<secret>.<fingerprint>.<url> des Accountants ein (sultan accountant invite --payee=<id>), pinnt dessen Fingerprint, signiert jeden Request (pkg/auth). Nur TLS 1.3, kein Klartext.

Bericht = vollständiger Schnappschuss (POST /api/v1/report), kein Delta: sofort nach Änderungen (Knoten online/offline, service_state, Mandantenänderung; 10 s gebündelt) und stündlich als Lebenszeichen. Inhalt:

Payee: Name, Version, Zeitpunkt.
Mandanten: ID, Name, Tier, Status.
Knoten: ID, Mandant, Hostname, FQDN, IP, Status, last_seen, Betriebssystem, Docker-Version, NetBird-IP (falls vorhanden).
Routen: Router, Hosts, Mandant, Knoten, Ziel als <fqdn>:<port> und <ip>:<port>, Container, Compose-Projekt und -Verzeichnis, Startzeit, Docker-Health, Zustand (läuft / down / Wartung / Mahnstufe), Produkt aus sultan.accountant.billing.

Zusatzdaten vom Agent (umgesetzt 2026-10-16; nur Information, ändern das Routing nie; ohne zusätzliche Labels, alles automatisch erkannt):

je Container meta im Workload: compose_project, compose_service, compose_dir (aus den Labels, die Docker Compose selbst setzt: com.docker.compose.project, ….service, ….project.working_dir), state, started_at, health (aus GET /containers/{id}/json, docker.Client.Inspect). Ein Health-Wechsel löst über das Docker-Event health_status eine neue Meldung aus. sultan.d-Dienste haben kein meta.
je Knoten host_info im service_state: fqdn, os, docker_version, netbird_ip.
- FQDN: --fqdn > Hostname mit Punkt > Hostname über die Suchdomain aufgelöst (CNAME/kanonischer Name) > Reverse-Lookup der Backend-Adresse > kurzer Hostname; einmal beim Start, je Abfrage max. 2 s.
- Betriebssystem/Docker-Version: aus GET /info (das OS des Hosts, auch wenn der Agent im Container läuft); ohne Docker PRETTY_NAME aus /etc/os-release.
- NetBird-IP: IPv4 auf wt0, sonst die erste Adresse aus 100.64.0.0/10.
Der Server liest service_state tolerant: ältere Server ignorieren die Felder, ältere Agents schicken sie nicht. Die Registry speichert sie mit dem Zustand (Registry.State, Server.NodeState) für den Bericht an den Accountant.
Das Ziel <fqdn>:<port> je URL entsteht beim Bericht aus host_info.fqdn und dem (bereits auf den Host-Port umgerechneten) Service-Port.

Umsetzung Accountant, Teil 1 (6b, 2026-10-16):

pkg/accountant: New (Datenverzeichnis 0700, Default ./accdata; accountant.db; eigenes server.crt/server.key), Start/Run/Shutdown, TLS-Port Default :8444, POST /api/v1/enroll (signiert mit payee.key, auth.Verifier.VerifyUnregistered; Body {token, hostname}, Antwort {payee_id}; 403 ohne Details bei unbekannter/verbrauchter/abgelaufener Einladung, 409 bei doppeltem Schlüssel). --public-url wird gemerkt (settings.public_urls) und steckt in Einladungen.
pkg/ledger (accountant.db, Migrationen über store.OpenDB): payees (ID aus der Einladung, Hostname, Schlüssel, IP, Zeitpunkt), invites (nur Hash, einmalig, Ablauf), settings. Ein registrierter Payee bekommt keine neue Einladung, bevor er gelöscht ist.
CLI: sultan accountant [--addr --public-url --data-dir], accountant invite --payee ID [--ttl] [--server-url], accountant payee list, accountant payee delete --id ID. Verwaltungsbefehle legen nie ein neues Datenverzeichnis an (Schutz vor Tippfehlern).
Rate-Limit für /enroll wie beim Server (--enroll-limit, Default 10/min je IP, pkg/ratelimit; schützt vor Last und Log-Flut, nicht vor Raten – dafür sorgen 256 Bit Zufall). Compose-Vorlage: deploy/compose/accountant (beides umgesetzt 2026-10-18).

Umsetzung Payee & Berichte (6c, 2026-10-17):

Server: --accountant-token (SULTAN_ACCOUNTANT_TOKEN, Einladung, nur beim ersten Start) und --accountant (SULTAN_ACCOUNTANT, Adress-Override; Vorrang: Override > Adresse in der Einladung > accountant.json). Im Datenverzeichnis des Servers: payee.key (0600) und accountant.json (url, fingerprint, payee_id). Ohne Einladung und ohne accountant.json meldet der Server nichts.
Fehlerverhalten: Unbrauchbare Angaben (Einladung unlesbar, http://, Einladung ohne jede Adresse, --accountant ohne Einladung) verhindern den Start – das sind Tippfehler. Ein nicht erreichbarer Accountant hält den Ingress nie auf: Enrollment und Berichte laufen im Hintergrund und werden je Prüfintervall wiederholt; Fehler werden nur bei Änderung geloggt. Einladung eines anderen Accountants bei bestehender Registrierung: Fehler im Log, keine Berichte, Server läuft (kein stiller Wechsel).
Wann gemeldet wird: Der Server baut den Schnappschuss je Prüfintervall (Default 10 s) und sendet nur, wenn sich der Inhalt (Hash ohne Zeitstempel) geändert hat oder das Lebenszeichen fällig ist (Default 1 h). Polling statt Ereignis-Hooks: erfasst auch Mandanten-, Wartungs- und Statusänderungen ohne zusätzliche Kopplung. Fehlgeschlagene Berichte werden beim nächsten Intervall wiederholt.
Inhalt (accountant.Report): Mandanten, alle Knoten aus sultan.db (verbunden, Wartung, last_seen, Host-Infos aus dem letzten service_state), Routen aus den gemeldeten Zuständen (reportRoutes: Hosts per HostsFromRule/HostsFromSNIRule, backend, backend_fqdn = <fqdn>:<port>, Compose-Angaben, Produkt aus sultan.accountant.billing, down aus down_services, active = Router steht in der Traefik-Konfiguration, also nicht von der Policy verworfen).
Accountant: POST /api/v1/report (signiert, Schlüssel muss registriert sein, max. 8 MiB, generated_at Pflicht), speichert den letzten Bericht je Payee normalisiert (reports, Migration v2 von accountant.db). CLI: payee list mit LAST_REPORT, payee report --id (JSON).

Umsetzung Checkmk (6e, 2026-10-18):

--metrics-addr (Default 127.0.0.1:8082, Klartext, nur Loopback; none = aus), GET /metrics/checkmk. Quelle: letzter Bericht je Payee (keine Historie nötig).
Services: Sultan Payee <id> (OK; WARN ab --stale-warn 2 h bzw. ohne Bericht; CRIT ab --stale-crit 6 h) und Sultan URL <host> je Host jeder Route (OK; WARN bei „von Policy verworfen“, „gestoppt/Wartungsseite“, „unhealthy“, „Knoten getrennt“; angekündigte Wartung des Knotens bleibt OK mit Hinweis; veralteter Bericht des Payees überträgt WARN/CRIT). Derselbe Host mehrfach → Zusatz (payee/knoten/router).
Text per text/template: eingebaut (defaultCheckmkTemplate), eigene <data-dir>/checkmk/checkmk.tmpl hat Vorrang und wirkt sofort; fehlerhafte Vorlage → eingebaute greift + CRIT-Service „Sultan Accountant Vorlage“. sultan accountant dump-checkmk [--force]. Felder bereinigt (ASCII, einzeilig, |→/, "→') und HTML-escaped; .Unescaped.<Feld> nur bereinigt. Funktion status (0/1/2 → OK/WARN/CRIT).
Links: Die Standardvorlage schreibt https://<host> und http://<fqdn>:<port> als Text; ob Checkmk sie klickbar darstellt, hängt von Version/Einstellung ab – Anpassung über die Vorlage.

Historie: Der Accountant führt je (Payee, Mandant, Host, Router) Zeiträume first_seen / ended_at. Fehlt eine Route in einem frischen Schnappschuss, endet ihr Zeitraum (Offboarding). Bleibt das Lebenszeichen eines Payees aus (> 2 h), endet nichts – der Server ist weg, nicht seine Services; Checkmk meldet den Payee als veraltet.

Abrechnung – Modell (Antworten 2026-10-18; Umsetzung 6d). Der Accountant gewinnt: Das Label sultan.accountant.billing=<produkt> ist der bequeme Weg für den Hoster (viele Kunden pflegen ihre Services nicht selbst; der Hoster trägt das Label am Kunden-Container ein), Vorgaben am Accountant haben aber immer Vorrang. Alle Routen werden erfasst; nichts verschwindet aus dem Bericht.

Kunde (zentral am Accountant): trägt Zahlweise, Pauschale und Kostenverursacher-Gruppe (z. B. extern, intern, familie – zum Clustern, keine Buchhaltungs-Kostenstelle; Posten haben keine eigene) sowie eine Notiz für persönliche Nebenabreden; Gruppe und Notiz sind im Bericht sichtbar und filterbar. Mandanten werden Kunden zugeordnet – gleiche Mandanten-ID auf allen Payees = derselbe Kunde (automatisch: der Kunde entsteht beim ersten Auftauchen der Mandanten-ID mit dem Mandantennamen und Zahlweise „nicht eingeordnet“; maßgeblich ist der Mandant aus der Einladung auf dem Server, nicht eine Angabe des Agents – von Hand nur Zahlweise, Pauschale, Gruppe, Notiz und Ausnahmen); eine Zuordnung je Payee + Mandant überschreibt das (Tippfehler auf einem Nebencluster, historische Abweichungen). Mandanten ohne Kunde erscheinen im Bericht als „Kunde unbekannt“.
Pauschale ist ein Posten am Kunden (monatlich); die meisten Kunden zahlen pauschal.
Posten = URL bzw. Router: je Router ein Posten (seine Hosts werden aufgeführt); alle Posten gehören dem Kunden des Mandanten. Einem Posten kann ein „Dienst“ zugeordnet sein (z. B. OLAT) – das ist dann der abgerechnete Zusatz-Service.
Klassen eines Postens:
- included – in der Pauschale enthalten (eingepreist), nur aufgeführt;
- billable – dazugebuchter Zusatz-Service, eigene Position;
- free – Give-away, kostet derzeit nichts, wird erfasst und kann später (mit Gültig-ab-Datum) abrechenbar werden;
- internal – keine Rechnung, aber über die Gruppe des Kunden zuordenbar (z. B. Infrastruktur wie sultan.chmln.de, Familie) und mit Schattenpreis, damit Fragen wie „Was habe ich dem Neffen geschenkt?“ oder „Was müsste das Brautpaar eigentlich zahlen?“ beantwortbar sind; ein Posten kann später an einen echten Kunden übergehen.
Klasse/Produkt einer Route (erste zutreffende Regel): Zuordnung am Accountant für Route/Domain > Label sultan.accountant.billing (Produkt aus dem Katalog bestimmt die Klasse) > Kunde mit Pauschale: included > sonst „nicht zugeordnet“ (fällt im Bericht auf). Klassen- und Preisänderungen gelten ab Datum.
Laufzeit: Abrechnung immer in vollen Monaten (Stichtag Monatserster/Monatsultimo). Beginn: Der Monat, in dem ein Posten erstmals auftaucht, zählt voll ab dem 1. Liegen Go-live und Bestellung weit auseinander, setzt der Hoster den Beginn je Posten manuell auf einen späteren Monatsersten (die Zwischenzeit läuft als Einmalbetrag im Projekt, außerhalb von Sultan). Gestoppte Routen, Wartung, Mahnstufen ändern nichts – erst das Verschwinden aus dem Bericht beendet einen Posten. SLA-Verletzungen werden manuell vergütet (bleibt so). Kündigung: Standard zum Monatsultimo; zusätzlich gibt der Bericht eine tagesgenaue Gegenrechnung als Vorschlag aus (beschleunigt seltene Kündigungen).
Zahlweise je Kunde: monatlich, quartalsweise, jährlich – oder „noch nicht eingeordnet“ (Feedback der Buchhaltung fehlt). Die Monats-CSV weist bei Quartals-/Jahreszahlern den Monatsanteil aus und vermerkt, dass die Rechnung das 3- bzw. 12-Fache beträgt (bzw. führt den Periodenbetrag mit); bei „nicht eingeordnet“ steht ein Vermerk.
Preise im Accountant: optional (Katalogpreis je Produkt, Kundenpreis überschreibt, Gültig-ab). Nicht buchhaltungsrelevant – führend sind die Abos in Lexware Office; Preise dienen Summen, Plausibilität und Schattenpreisen. Ohne Preis bleibt die Spalte leer.
Ausgabe: CSV je Monat (Abrechnung erfolgt in Lexware Office). Spalten werden an der Praxis nachgeschärft; kein Templating, bis die Buchhaltungsfragen geklärt sind.
Geparkt: Abo-Revision (Abgleich mit den Lexware-Abos) bleibt vorerst manuell. Ausblick (TODO): Der Accountant als „Realität“ statt der Abopflege in Lexware – also Lexware aus dem Bestand speisen statt umgekehrt.
Offene Fachfragen vor 6d: siehe Abschnitt 9.

Abfrage:

CLI auf dem Accountant: sultan accountant where <domain> (Mandant, Payee, Knoten, <fqdn>:<port>, Container, Compose-Verzeichnis, Zustand), routes [--tenant=…], billing --month=JJJJ-MM, payee list, invite.
Checkmk (GET /metrics/checkmk auf Loopback, umgesetzt 2026-10-18, siehe unten): ein Service je URL mit Link auf https://<host> und auf das interne Ziel http://<fqdn>:<port>, dazu Frische je Payee. Text per Vorlage (Go text/template, wie beim Lander): eingebaute Default-Vorlage, eigene unter <data-dir>/checkmk/ hat Vorrang; sultan accountant dump-checkmk exportiert die Vorlage zum Anpassen. Die Default-Vorlage wird mit den Releases weiterentwickelt. Werte aus Berichten sind Fremdeingaben (Containername, Compose-Verzeichnis stammen vom Kunden-Host): Sie werden vor dem Einsetzen bereinigt (keine Zeilenumbrüche, kein |, ASCII) und HTML-escaped; rohe Werte nur über eine explizit benannte Funktion. Grund: Wer in Checkmk das HTML-Escaping abschaltet, damit Links klickbar sind, öffnet sonst Script-Injektion in die Checkmk-Oberfläche.
Später: HTTP-API als Vorstufe für den Export ins Dokuwiki; Statusberichte an Mandanten. (Uptime Kuma verworfen: keine offizielle API.)

Umsetzung Historie, where, routes (6d Schritt 1, 2026-10-18):

accountant.db v3: route_spans – ein Zeitraum je Ort (Payee, Mandant, Knoten, Protokoll, Router) mit Hosts, Backend, <fqdn>:<port>, Workload, Compose-Verzeichnis, Produkt, first_seen/last_seen/ended_at. SaveReport führt sie im selben Schritt wie den letzten Bericht fort: neue Orte öffnen, bestehende übernehmen geänderte Angaben (first_seen bleibt), fehlende enden mit dem Eingang des Berichts. Nur ein Bericht des Payees selbst beendet dessen Orte; ein schweigender Payee beendet nichts. Die Historie bleibt, wenn ein Payee gelöscht wird. Ein Umzug auf einen anderen Knoten ist ein neuer Ort; die Abrechnung fasst Orte später je Mandant + Router zum Posten zusammen.
sultan accountant where <host|mandant>: Teiltreffer im Host (ohne Groß-/Kleinschreibung) oder exakte Mandanten-ID; je Treffer URL, Mandant, Ingress (Zeitpunkt des Berichts), Backend <fqdn>:<port> (+ IP, NetBird), Container + Compose-Verzeichnis, Zustand, Knoten (verbunden, OS, Docker), seit wann am Ort, vorher (beendete Orte derselben Route), dazu passende Routen, die es nicht mehr gibt. Kein Treffer → Exit 1.
sultan accountant routes [--tenant] [--payee]: Tabelle aller aktuellen Routen (Host, Mandant, Payee, Knoten, Ziel, Zustand, seit).

Umsetzung Abrechnung (6d Schritte 2–4, 2026-10-18):

Kunden (accountant.db v4: customers, customer_map): StoreReport (Endpunkt) ruft EnsureCustomers – unzugeordnete Mandanten-IDs werden Kunden (auto, Name folgt dem Mandanten, bis der Kunde von Hand bearbeitet wird). Auflösung CustomerResolver.Resolve(payee, mandant): Zuordnung für den Payee > für alle Payees > Kunde mit gleicher ID. CLI customer add|set|list|map|unmap|delete; set ändert nur angegebene Felder; list --group, --unclassified. where zeigt den Kunden.
Katalog (v5: products, product_versions, customer_prices, assignments): Klasse und optionaler Preis je Monat (product set --from JJJJ-MM, erste Version gilt von Anfang an), Kundenpreis mit Vorrang. Zuordnung je Posten (Mandant, Protokoll, Router) mit Produkt, Klasse und/oder Beginn: assign --host … (Host → Posten über die Historie; mehrdeutig → --tenant/--router), assign --clear, assignments.
Monatsabrechnung (Billing, billing --month JJJJ-MM [--out]): Posten = alle Orte eines (Mandant, Protokoll, Router); abgerechnet, wenn der Monat zwischen Beginn (Zuordnung, sonst Monat des ersten Auftauchens, voll) und dem Monat des Endes (bis Ultimo) liegt. Klasse: Zuordnung > Produkt (Zuordnung, sonst Label) > Pauschale des Kunden → included > leer („nicht zugeordnet“; Produkt nicht im Katalog wird benannt). Beträge: billable = Preis (fehlt → Hinweis), included 0, free/internal 0 + Schattenpreis. Pauschale als eigene Zeile je Kunde mit Pauschale (Hinweis, wenn keine URL aktiv). Periodenbetrag = Monatsbetrag × 1/3/12; Hinweise für Quartals-/Jahreszahler und „noch nicht eingeordnet“; Ende im Monat → „beendet am …“ + tagesgenaue Gegenrechnung. Mandanten ohne Kunde: Hinweis „Kunde unbekannt“, am Ende der Liste.
CSV: UTF-8 mit BOM, Semikolon, Dezimalkomma; Spalten Monat, Kunde, Kundenname, Gruppe, Zahlweise, Posten, Hosts, Mandant, Klasse, Produkt, Von, Bis, Monatsbetrag, Periodenbetrag, Schattenpreis, Hinweis, Notiz; je Kunde die Pauschale zuerst. Spalten werden an der Praxis nachgeschärft.

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:

# 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

Umsetzung (Schritt 3, pkg/checkmk): GET /metrics/checkmk auf dem Provider-Port.

Service	Metrik	Zustand
`Sultan_Tenant_<id>` (nur kommerziell)	`days_left=N;30;14`	OK; WARN ≤ 30 Tage; CRIT ≤ 14 Tage, abgelaufen oder Quarantäne
`Sultan_Payment_<id>` (nur kommerziell)	`dunning_level=N;1;2`	OK ohne offene Zahlung; Mahnstufe 1 WARN; 2 und 3 CRIT (3 = „Kunde offline“)
`Sultan_Node_<id>`	`lease_hours_left=N`	online/drained OK; Wartung WARN (mit internem Grund, auch offline); offline WARN, ab `--offline-alert-after` (Default 15 min) CRIT
`Sultan_Policy_Violations`	`violations_24h=N;1`	OK ohne Verstöße; ab 1 WARN (gezählt im Speicher, nach Neustart neu)

Texte in ASCII (Umlaute umschrieben), einzeilig, sortiert. Kurze Ausfälle in Sekunden („offline seit 45 s“), sonst in Minuten. Das Wartungsende steht in der Zeitzone des Servers mit Kürzel (z. B. CEST), wie auf der Lander-Seite.
Checkmk-Agent-Plugin auf dem Ingress-Host: /usr/lib/check_mk_agent/local/sultan mit dem Inhalt #!/bin/sh und curl -fsS http://127.0.0.1:8080/metrics/checkmk.

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“.
Umsetzung (Schritt 3): Der Server-Job läuft bei jedem Refresh.
- Vertragsablauf: Kommerzielle Mandanten werden ab valid_until dauerhaft auf expired gesetzt. Community läuft nie über valid_until ab (5c), nur über den expliziten Status.
- Benachrichtigungen genau einmal pro Ereignis. Die Schlüssel enthalten das Bezugsdatum, damit nach einer Verlängerung bzw. bei einer neuen offenen Zahlung ein neuer Zyklus beginnt (Tabelle notifications).
  - Ereignisse: Vertrag 30 / 14 / 0 Tage, Mahnstufe 1 / 2 / 3, Knoten länger als --offline-alert-after getrennt (nicht bei angemeldeter Wartung oder drain), neue Policy-Verstöße (sofort, asynchron).
  - „Wieder online“ (Info) beim erneuten Verbinden, nur wenn zuvor ein Offline-Alarm verschickt wurde, je Ausfall einmal, mit Ausfalldauer.
  - Schlägt der Versand fehl, wird beim nächsten Durchlauf erneut versucht. Bei mehreren Zielen können dann einzelne Ziele eine Nachricht doppelt bekommen.
  - Ziele: --notify-slack (Slack-kompatibel: {"text": …}, Slack-Markdown, Emoji je Schweregrad) und --notify-ntfy (+ --notify-ntfy-token; Titel, Priorität default/high/urgent, Tags, Markdown), jeweils mehrfach angebbar. Ohne Ziel wird nichts vermerkt.
- Aufräumen nach 10 Tagen: eingelöste/abgelaufene Einladungen, abgelaufene Leases, zugestellte Befehle.
- Zahlungsstatus bis zur Admin-API per CLI: sultan token tenant payment --id … --overdue-since JJJJ-MM-TT | --paid; tenant list zeigt die Spalte PAYMENT.
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

Die lauffähigen Vorlagen liegen unter deploy/compose/{server,agent,accountant}; die Ausschnitte hier zeigen das Prinzip. Einstellungen nur über .env (env_file: .env): compose.yaml wiederholt keine Variablen, alle Optionen samt Defaults stehen in .env.example (SULTAN_<FLAG> je Flag, leer = Default). Das Image legt /suldata und /accdata für den nonroot-User an; WORKDIR / macht beide zu den Defaults. Image: ein distroless-Image für Server und Agent (Dockerfile, nonroot-User 65532, kein ENTRYPOINT, Arbeitsverzeichnis /, Default-Datenverzeichnis also /suldata). Ein Bind-Mount für /suldata muss vorher 65532:65532 gehören.

7.1 Compose-Setup: Ingress-Knoten

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
    # Im Container auf allen Interfaces lauschen; nach außen nur 127.0.0.1 veröffentlichen.
    command: ["sultan", "server", "--data-dir=/suldata", "--provider-addr=:8080", "--lander-addr=:8081",
              "--hoster-name=Mein Hosting", "--hoster-url=https://hosting.example"]
    ports:
      - "8443:8443" # Agent Inbound (TLS Stream)
      - "127.0.0.1:8080:8080" # Traefik Config Provider & Checkmk Metrics – Klartext, nie öffentlich
      - "127.0.0.1:8081:8081" # Lander (Hinweis-/Wartungsseiten) – Traefik ruft ihn über 127.0.0.1 auf
    volumes:
      - ./suldata:/suldata   # sultan.db, server.key/.crt, master.key – server.key und master.key sichern!

7.2 Compose-Setup: Kunden-Host (Backend mit Docker)

services:
  sultan-agent:
    image: sultan:latest
    container_name: sultan-agent
    restart: unless-stopped
    network_mode: host   # Host-IP als Backend-Adresse, Hostname als Knoten-ID (Bridge: Container-IP/-ID)
    group_add: ["${DOCKER_GID}"]   # Lesezugriff auf den Docker-Socket für den nonroot-User
    command:
      - "sultan"
      - "agent"
      - "--data-dir=/suldata"
    environment:
      # Ausgabe von `sultan token invite` – enthält Fingerprint und (mit --public-url) die Server-Adresse.
      # Nach dem ersten Start nicht mehr nötig; stehen lassen ist harmlos.
      SULTAN_TOKEN: "sltn_enroll_<secret>.<fingerprint>.<server-url>"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./suldata:/suldata   # node.key (0600) und node.json – 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_`.
2026-10-01	Lizenz-Signatur mit Versionspräfix `SULTAN-LICENSE-V1`; Wildcard `.domain` deckt alle Subdomain-Ebenen, nicht die Apex-Domain; `.<tld>` verboten.	Eindeutige, manipulationssichere Kodierung; Wildcard-Semantik entspricht der Erwartung „Mandant besitzt die Zone“, ohne versehentlich ganze TLDs freizugeben.
2026-10-01	Leases: signierte Lizenz-Kopie, 7 Tage (Wartung 10), Erneuerung nach ~2/3; kommerziell an Abo-Zyklus gebunden; Community automatisch neu ausgestellt; jederzeit serverseitig unterbrechbar.	Kurze Laufzeit begrenzt Schaden bei Missbrauch; Sperren wirken über Polling ohnehin sofort (ACME-Analogie).
2026-10-01	Eskalatives Mahnwesen nur kommerziell: Wasserzeichen → Firemark → Paywall (402); umgesetzt über einen Sultan-Interceptor, zu dem die Policy umleitet.	Mehrstufige Dringlichkeit analog zu Mahnstufen; Traefik selbst kann Seiteninhalte nicht verändern.
2026-10-01	Policy parst Regeln und verlangt Host-Einschränkung in jedem `\|\|`-Zweig; `HostRegexp` verboten; Namensraum `<tenant>__<node>__<name>`; `@`-Referenzen nur per Freigabeliste; `chain`/`errors` verboten.	Verhindert Catch-all-Übernahmen, Zugriff auf `api@internal` und Querverweise zwischen Mandanten.
2026-10-01	`/etc/sultan.d` als YAML mit Komfortschaltern + rohen Labels; Healthcheck (Status + einfache Inhaltsprüfung) im YAML; Interface/Port konfiguriert.	Für Bare-Metal-Admins lesbarer als Labels; Ports sind nicht sicher erratbar.
2026-10-01	Benachrichtigung: Community per Webhook; kommerziell SMTP an Mandanten + Ticketsystem (Zammad per Webhook/API).	Homelab braucht keinen Mailserver; kommerziell nachvollziehbare Kommunikation.
2026-10-01	Admin-Zugriff: Community nur lokale CLI; kommerziell zusätzlich Admin-API (Rechnungssystem, Ansible).	Automatisierte Lizenzpflege im kommerziellen Betrieb.
2026-10-01	Community-Lease 14 Tage, Erneuerung ~7 Tage mit Streuung; Wartung bis 7 Tage ohne Invalidierung, solange 50x-Lander mit Pro-Hinweis.	Homelab-Betrieb robust gegen Server-Wartung; Upsell statt Ausfall.
2026-10-01	Mahnstufen 8/25/32 Tage (Bank-Zahlungsfristen), vom Server berechnet. Watermark/Firemark als Hinweisseite mit `meta refresh` statt Einblendung ins Original; Durchlass per Cookie `sultan_ack=<stufe>` über einen zweiten Router.	Deutlich einfacher als Seiten umzuschreiben; Cookie verhindert die Weiterleitungsschleife.
2026-10-01	Middleware-Zielbegrenzung vorgesehen (Backend-Tupel `host:port`, per Label, erst Beobachtungsmodus).	SSRF-Risiko durch `forwardAuth` u. ä.; Regeln erst nach Beobachtung festlegen.
2026-10-01	Admin-API mit API-Token; TLS des Admin-Interfaces über ACME (öffentliches Zertifikat via Traefik), kein Pinning nötig.	Gängige Praxis für Rechnungssystem/Ansible; ACME ist auf dem Ingress ohnehin vorhanden.
2026-10-01	Mahnhinweis-Weiterleitung 5 s / 10 s, Cookie 60 min; Stufe 3 ohne Durchlass = Kunde offline mit Hoster-Einladung.	Hinweis pro Besuch statt pro Request; Eskalation endet mit Abschaltung nach zwei Checkmk-Alarmen.
2026-10-01	Lander: eingebaute minimale HTML-Seiten (de_DE/en_US, ohne CSS); optional eigene Vorlagen aus gemountetem Verzeichnis, max. 1 HTML-Vorlage + 1 CSS + 1 Grafik pro Seite.	Funktioniert ohne Konfiguration; Anpassung möglich ohne komplexen Webserver.
2026-10-01	Middleware-Zielbegrenzung als Andockstelle mit Beobachtungs-/Durchsetzungsmodus, Default dulden.	Erst beobachten, dann Regeln festlegen.
2026-10-01	Registry: `service_state` = vollständiger Schnappschuss je Knoten (Workloads mit Host + Labels, Liste ausgefallener Services); Workloads einzeln übersetzt, bei Namenskonflikt innerhalb eines Knotens gewinnt der alphabetisch erste; fail-static bei Directory-Ausfall; Verstöße nur beim ersten Auftreten melden.	Robust gegen Teilausfälle; Audit-Log ohne Wiederholungsflut.
2026-10-01	Lander-Vorlagen mit Go `html/template`; die eingebauten Seiten lassen sich als Beispiel exportieren (`dump-landing`).	Eingebaut, ohne Abhängigkeit, schützt automatisch gegen eingeschleustes HTML; Syntax erlernbar.
2026-10-01	Datenverzeichnis `./suldata` für Server und Agent; Ports `:8443`/`8080` als konfigurierbare Defaults, Provider-Port auf Loopback.	Einheitlich, einfach zu mounten; Klartext-Port nicht versehentlich öffentlich.
2026-10-01	`sultan server`: Knoten-Lebendigkeit = offener Stream; Routen beim Trennen sofort entfernt; `POST /api/v1/state` nur bei offenem Stream.	Keine verwaisten Routen; einfaches, eindeutiges Modell.
2026-10-01	`sultan token` arbeitet direkt auf dem Datenverzeichnis; legt es nie selbst an; Einladungs-Token allein auf stdout.	Kein versehentlicher Identitätswechsel durch Tippfehler; skriptfreundlich (`TOKEN=$(sultan token invite …)`).
2026-10-02	Agent Teil 1: Docker-Anbindung ohne SDK; Port-Übersetzung Container-Port → veröffentlichter Host-Port; Zustand nach jedem Verbinden neu senden; bei Docker-Fehler nichts senden.	Ingress erreicht nur veröffentlichte Ports; leichte Abhängigkeiten; keine versehentlich gelöschten Routen.
2026-10-02	Hub registriert einen Knoten vor dem Senden der Antwort-Header.	Sonst Wettlauf: Agent sendet seinen Zustand direkt nach den Headern und bekäme 409.
2026-10-02	Agent Teil 2: `/etc/sultan.d`-YAML wird in Traefik-Labels übersetzt (gleicher Weg wie Docker); Polling statt inotify; Healthcheck mit Schwelle (Default 2 Fehlschläge) → `down_services`.	Ein Prüfweg für alle Quellen; robust bei Bind-Mounts; kein Flattern der Wartungsseite.
2026-10-02	Lander im Server-Prozess (`--lander-addr`); `landing` wie `paywall` mit 402; Weiterleitungsziel nur lokaler Pfad; Assets eigener Vorlagen eingebettet; Vorlagen in `<data-dir>/landing`.	Ein Dienst weniger im Betrieb; keine offene Weiterleitung; Assets funktionieren auch mit gesetztem Durchlass-Cookie.
2026-10-02	Polling in `/etc/sultan.d` bestätigt: lokal, nur Inhaltsvergleich weniger KB alle 5 s.	inotify ist bei Bind-Mounts und atomar ersetzten Dateien unzuverlässig; immer das Verzeichnis mounten, nie einzelne Dateien.
2026-10-02	Server-Adresse in der Einladung (optionaler dritter Teil, Base64url); Quelle `--public-url` (gemerkt) bzw. `invite --server-url`; beim Agent `--server`/`SULTAN_SERVER` als Override, `SULTAN_TOKEN` als Alternative zum Argument.	Onboarding mit einem einzigen kopierbaren Token (`curl \| sh`); der Server kennt seine erreichbare Adresse nicht selbst.
2026-10-02	Pin am Fingerprint statt an der Adresse (`server_fingerprint` in `node.json`, `known_servers` entfällt); Adresswechsel desselben Servers erlaubt und gespeichert.	Adressen ändern sich (DNS, NetBird, intern/extern); die Identität des Servers nicht. Sicherheitsniveau unverändert.
2026-10-02	Reihenfolge der Roadmap: Wartung → Leases/`node_command`/signierte Events (Migration v3) → Checkmk/Fristen/Benachrichtigungen → mehrere Adressen → Betrieb.	Jeder Schritt baut auf den Daten des vorherigen auf.
2026-10-02	maintenance vs. drain trennscharf: Wartung = Routen bleiben mit 503, befristet (Default 4 h), Admin und Knoten können sie auslösen; drain = Routen weg, bis `resume`, nur Admin. Grund zweigeteilt (`reason` intern, `public_reason` ersetzt den Standardtext der Wartungsseite).	Beides ist aus Cloud-Umgebungen bekannt; unterschiedliche Wirkung für Besucher.
2026-10-02	Lease bestimmt, wie lange Routen eines getrennten Knotens als Wartungsseite stehen bleiben; Agent loggt nur. `node_command` als feste Liste ohne Fernsteuerung; lokale Hooks geparkt. Server-Events werden signiert.	Klarer Zweck der Lease; keine Remote-Code-Ausführung.
2026-10-02	Fristen & Benachrichtigung: `expired` wird gespeichert; Aufräumen nach 10 Tagen; Offline-Alarm nach 15 min; Webhooks zuerst Slack-kompatibel und ntfy, Matrix geplant.	Nachvollziehbar, wenig Aufwand, gängige Ziele.
2026-10-02	Wartung umgesetzt: eigene Dimension je Knoten (nicht Teil von `status`); Vorrang Ablauf/Paywall > Wartung > Mahnhinweis; getrennter Knoten in Wartung behält seine Routen bis Wartungsende; `undrain` durch `resume` ersetzt (beendet Wartung und drain).	Ein Knoten in Wartung kann verbunden sein oder nicht; Reboot ohne 404 für Besucher.
2026-10-02	Leases und Befehle umgesetzt: Lease mit eigenem Signaturpräfix; ungeplant getrennter Knoten zeigt die Wartungsseite bis Lease-Ende; Befehle über eine DB-Warteschlange (CLI ist eigener Prozess); alle Server-Events signiert; `rotate_key` mit Besitznachweis und abbruchsicherer Wiederaufnahme.	Kein 404 bei kurzen Ausfällen; keine Fernsteuerung ohne Server-Signatur; Schlüsselwechsel ohne Aussperren.
2026-10-02	Schritt 3 umgesetzt: Checkmk-Ausgabe als reine Funktion (`pkg/checkmk`); Job bei jedem Refresh (Ablauf, Benachrichtigung, Aufräumen); Benachrichtigungen Slack-kompatibel + ntfy mit Wiederholung bis zur erfolgreichen Zustellung; Community läuft nicht über `valid_until` ab.	Testbar, ohne zusätzlichen Prozess; keine verlorenen Alarme.
2026-10-02	Mehrere Server-Adressen: `--public-url` mehrfach; die Einladung trägt nur die erste; die Liste kommt per signiertem `config`-Befehl bei jedem Verbinden; der Agent weicht der Reihe nach aus und merkt sich die funktionierende Adresse.	Kurze Einladung; Ausfall einer Adresse (DNS, Weiterleitung) ohne Eingriff überbrückt.
2026-10-02	Build & Auslieferung: ein distroless-Image (nonroot) für Server und Agent, Multi-Arch amd64+arm64 per buildx mit Go-Cross-Compile (kein QEMU); Registry: eigener Zot-Server `zot.chmln.de`, Image `zot.chmln.de/sultan` (ohne Owner-Ebene, daher kein Rewrite-Proxy nötig); Zugangsdaten für den Push nur in `deploy/.env` (gitignored), ohne Passwort bricht `push-image.sh` ab. (Ursprünglich geplant: Gitea-Registry hinter Rewrite-Proxy – verworfen.) Binaries + `SHA256SUMS` statisch unter `sultan/releases/<version>/`, `releases/stable` als Zeiger. Agent-Container mit `network_mode: host`. Vorerst manuell über `deploy/*.sh`, später Gitea Actions bei Tags.	Kein Go-Stack beim Nutzer; ein Image für alle Architekturen; Agent meldet sonst die Container-IP als Backend; eigene Registry mit kurzen Image-Namen ohne Proxy-Tricks.
2026-10-02	Kleinere Punkte: Rate-Limit `/enroll` 10/min/IP vor der Signaturprüfung (`-1` = aus); `SULTAN_<FLAG>` für alle Flags, Flags gewinnen; „wieder online“ nur nach Offline-Alarm; Checkmk-Zeiten in Server-Zeitzone. Ein Agent, dessen Enrollment mit 429 scheitert, beendet sich; der Neustart erfolgt über systemd bzw. Docker `restart`.	Schutz vor Durchprobieren; Container-/systemd-freundliche Konfiguration; vollständige Alarmkette.
2026-10-03	Gestoppter Container = Wartungsseite, entfernter = Route weg. Der Agent meldet gestoppte Container mit (Ports aus `PortBindings`) und deren Services als `down_services`; laufende Container gewinnen bei Namensgleichheit. Leerer `--public-url`-Wert wird ignoriert; `sultan version` zeigt die Zeitzone; `TZ` kommt über Compose (distroless enthält tzdata). Server-Compose mit `network_mode: host` neben Traefik.	Erster Test gegen echtes Traefik: `docker stop` lieferte 404 statt 503. Abschalten bleibt über Entfernen möglich.
2026-10-11	TCP nur als TLS-Passthrough (Feature `tcp_stream`, auch Community): `HostSNI` mit expliziten Hosts aus `allowed_domains`, keine Wildcard-/Regexp-Router; nur Entrypoint `websecure`; zählt gegen `max_routes`. Ohne Interceptor: Mahnhinweis lässt durch, ab Paywall und bei Wartung Route entfernt. UDP und übrige TCP-Labels weiterhin abgelehnt.	Kunden mit eigener CA/TLS (tinyCA) brauchen Passthrough; DNS-Wildcard ist kein Grund für einen Wildcard-Router – host-genau bleibt prüf- und abrechenbar. Seiten lassen sich bei TCP nicht einblenden.
2026-10-16	Accountant (5.3): zentrales Inventar über eigene Rolle `sultan accountant` mit eigener `accountant.db`; nur Server (Payees, `--accountant`) melden, per signiertem, gepinntem Push eines vollständigen Schnappschusses bei Änderung und stündlich. Abrechnung: Vorgaben am Accountant (Zuordnung, Abo pauschal/einzeln, Mandantenpreis) gewinnen vor dem Label `sultan.accountant.billing`; alle Routen werden erfasst, ungelabelte gelten bei Abo als „im Abo enthalten“, sonst „nicht zugeordnet“. Abfrage zuerst per CLI (`where`) und Checkmk (Text per `text/template`-Vorlage mit eingebautem Default); HTTP-API später, Uptime Kuma verworfen.	Störfall: Backend-Host sofort finden; Kunden-Labels können Routen nicht vor der Abrechnung verstecken; bewährte Mechanik (Pinning, Signatur, Schnappschuss) statt neuem Protokoll; viele Services sind eingepreist; Vorlagen-Mechanik wie beim Lander, ohne neue Abhängigkeit.
2026-10-16	6a/6b umgesetzt: Zusatzdaten automatisch aus Docker (Compose-Labels, Inspect, `/info`), DNS und Interfaces – keine neuen Pflicht-Labels; einziges neues Label ist `sultan.accountant.billing` (statt `sultan.billing`). Accountant mit Default `./accdata` und Port `:8444`; `accountant.db` über das exportierte `store.OpenDB`; Payee-ID kommt aus der Einladung (`invite --payee`).	Kein Pflegeaufwand an Kunden-Compose-Dateien; Label-Namensraum zeigt, wer das Label auswertet; getrenntes Datenverzeichnis erlaubt Accountant und Server auf demselben Host.
2026-10-17	6c umgesetzt: Payee meldet per Polling (Prüfintervall 10 s, Senden nur bei geändertem Inhalt, Lebenszeichen 1 h) statt über Ereignis-Hooks; Konfigurationsfehler verhindern den Start, ein nicht erreichbarer Accountant nie; Einladung eines anderen Accountants wird bei bestehender Registrierung ignoriert (Log-Fehler). Accountant hält bis 6d nur den letzten Bericht je Payee. Routen tragen `active` (in Traefik) und `down`.	Ingress-Verfügbarkeit vor Inventar; Polling erfasst alle Änderungsquellen ohne Kopplung; kein stiller Wechsel der Zentrale.
2026-10-18	Compose: Einstellungen nur über `.env` (`env_file`), Defaults dokumentiert in `.env.example`; Accountant-Vorlage `deploy/compose/accountant` mit Datenverzeichnis `/accdata`.	Keine doppelte Pflege von Variablen und Defaults; neue Flags brauchen keine Compose-Änderung.
2026-10-18	Abrechnungsmodell (5.3): Posten = Router/URL; Pauschale am Kunden; Klassen `included`/`billable`/`free`/`internal` (Kostenstelle, Schattenpreis); volle Monate, Kündigung zum Ultimo mit tagesgenauer Gegenrechnung als Vorschlag; Zahlweise m/q/j je Kunde mit Vermerk in der Monats-CSV; Kunden-Zuordnung automatisch über gleiche Mandanten-ID, Ausnahme je Payee.	Spiegelt die Praxis (Lexware-Abos, meist Pauschale, Zusatz-Services je URL); interne und geschenkte Dienste bleiben bewertbar.
2026-10-18	Abrechnung, Details: Beginn = voller Monat ab dem 1. des ersten Auftauchens, manuell verschiebbar je Posten; Zahlweise je Kunde; Preise optional und nicht buchhaltungsrelevant (Lexware führt); Gruppe (Kostenverursacher) und Notiz (Nebenabreden) je Kunde, filterbar; Abo-Abgleich bleibt manuell.	Projekt- und Einmalbeträge laufen außerhalb; persönliche Kundenverhältnisse bleiben nachvollziehbar, ohne Buchhaltungsstruktur nachzubauen.
2026-10-18	6e umgesetzt: Checkmk des Accountants auf eigenem Loopback-Port `127.0.0.1:8082`, Quelle = letzter Bericht; Wartung dämpft auf OK; Rate-Limiter nach `pkg/ratelimit` verschoben und für `/enroll` des Accountants genutzt.	Unabhängig von 6d nutzbar; einheitliches Verhalten von Server und Accountant.
2026-10-18	Historie je Ort (Payee, Mandant, Knoten, Protokoll, Router) statt je Posten; Kunden entstehen automatisch aus der Mandanten-ID der Berichte.	`where` braucht den Ort (wohin springen, wo vorher); Posten für die Abrechnung lassen sich daraus ableiten; der Mandant ist durch die Einladung auf dem Server verlässlich, also keine Nachpflege.
2026-10-18	6d umgesetzt: Posten = Orte je (Mandant, Protokoll, Router) zusammengefasst; Beginn voller Monat (Zuordnung verschiebt), Ende bis Ultimo mit tagesgenauer Gegenrechnung als Hinweis; Klasse Zuordnung > Produkt > Pauschale > nicht zugeordnet; Preise optional, Schattenpreis für free/internal; Pauschale als eigene Zeile; CSV mit BOM, Semikolon, Dezimalkomma.	Deckt sich mit der Praxis (Lexware, Pauschale + Zusatz-Services); Lücken (kein Kunde, kein Produkt, keine Zahlweise) werden sichtbar statt still verschluckt.
geplant	Geordneter Zertifikatswechsel; optionale Root-CA. (Signierte Server-Events: umgesetzt.)	Zweite Sicherheitsschicht neben dem TLS-Pin; Betrieb ohne Aussperren.

9. Umsetzungsstand & Roadmap

Umgesetzt (Go-Packages, testgetrieben):

Package	Inhalt
`pkg/traefik`	Labels → Traefik-Konfiguration (HTTP, TCP-Passthrough), Merge, JSON/YAML
`pkg/stream`	SSE-Hub (Server) und Client (Agent) inkl. Keepalive, Backoff, Disconnect
`pkg/store`	SQLite: Mandanten, Knoten, Enrollment
`pkg/auth`	Ed25519-Request-Signatur, Verifier, Schlüsseldateien
`pkg/crypto`	Server-Zertifikat, TLS 1.3, Pinning, Enrollment-Token
`pkg/license`	Lizenz ausstellen, prüfen, Domain/Routen/Feature-Checks
`pkg/policy`	Regel-Parser, Domain-/Routen-/Feature-/Referenz-Prüfung, Namensraum, Stufen & Interceptor-Umleitung, Mahnstufen-Zeitplan, Andockstelle Middleware-Ziele
`pkg/registry`	Aggregator: Zustand je Knoten → Labels → Policy → Merge; `/v1/traefik-config`-Handler; Audit-Callback
`pkg/server`	`sultan server`: Datenverzeichnis, Master-Key, HTTP-Routen beider Ports, Knotenstatus, Refresh-Schleife, Graceful Shutdown, Audit-Log über `slog`
`pkg/cli`, `main.go`	Befehle `server`, `agent`, `token` (Mandanten, Einladungen, Knoten, Lizenzen), `version`, `help`
`pkg/docker`	minimaler Docker-Engine-Client (Container, Events) über Unix-Socket
`pkg/lander`	Hinweis-, Wartungs- und Einladungsseiten je Stufe; eigene Vorlagen; `Dump`
`pkg/agent`	Agent: Enrollment, Stream, Zustand senden, Docker-Watcher, Port-Übersetzung, Backend-Adresse; `/etc/sultan.d`-YAML mit Komfortschaltern und Healthchecks

Offen – Bausteine in dieser Reihenfolge (festgelegt 2026-10-02):

Schritt 1 – Wartung pro Knoten und Dienst (3a–3e) – ✅ umgesetzt 2026-10-02 (Migration v3)

Knotenstatus maintenance mit Ende: sultan token node maintenance --id … [--for 4h] [--reason …] [--public-reason …], Ende per node resume. Standard-Dauer 4 h; --for 0 = unbefristet.
Auch der Knoten selbst kann Wartung an- und abmelden: sultan agent maintenance on|off [--for] [--reason] [--public-reason] (signierter Request, z. B. aus Patch-/Reboot-Skripten).
Pro Dienst: YAML-Feld maintenance: true bzw. Container-Label sultan.maintenance=true.
Grund zweigeteilt:
- reason: intern (Log, Monitoring), nie öffentlich.
- public_reason: optional. Wenn angegeben, ersetzt er auf der Wartungsseite den Standardtext („bitte versuchen Sie es bald wieder“), z. B. „Wir spielen ein Sicherheitsupdate ein (CVE-1234) – Sicherheit nehmen wir ernst.“
- Die Wartungsseite zeigt das voraussichtliche Ende; Retry-After wird daraus abgeleitet.
Trennt sich ein Knoten in Wartung, bleiben seine Routen als Wartungsseite stehen, bis die Wartung endet. Für ungeplantes Trennen gilt künftig die Lease (Schritt 2).

Schritt 2 – Leases, node_command, signierte Server-Events (4a–4e) – ✅ umgesetzt 2026-10-02 (Migration v4)

Lease: pro Knoten, signiert mit dem Master-Key. Der Server verlängert per lease_renew, solange der Knoten verbunden und der Mandant in Ordnung ist. Laufzeiten wie 4.1a.
Wirkung serverseitig: Ein getrennter Knoten behält seine letzten Routen als Wartungsseite, bis seine Lease abläuft; erst dann werden sie entfernt. Sofort entfernt werden sie nur durch drain.
Beim Agent: nur Logging, vorerst ohne Konsequenz. Später auch für einen Checkmk-Check auf Kundenseite („Lease läuft bald ab“).

node_command, feste Liste ohne beliebige Befehle:

Befehl	Agent tut
`resync`	sendet sofort seinen Zustand
`rotate_key`	neuer `node.key`, mit dem alten signiert gemeldet
`drain`, `maintenance`, `resume`	nur Logging (Hinweis)
`config`	übernimmt Server-Adressen (Schritt 4)

Lokale Hooks (/etc/sultan.d/hooks/<befehl>) sind geparkt.

Server-Events signiert mit dem Master-Key (Agent kennt den Public Key seit dem Enrollment). Das ist die bisher „geplante zweite Schicht“ aus 3.4.
Migration v4 wie in 4.3 beschrieben. (Die Wartungsfelder kamen bereits mit v3.)

Schritt 3 – Checkmk, Fristen-Job, Benachrichtigungen (5a–5e) – ✅ umgesetzt 2026-10-02 (Migration v5)

GET /metrics/checkmk (Provider-Port, lokal), Local-Check-Format:
- pro kommerziellem Mandanten: Vertragsende (WARN 30 / CRIT 14 Tage) und Mahnstufe
- pro Knoten: online / offline / Wartung, Lease-Restlaufzeit
- Server: Policy-Verstöße der letzten 24 h
- Community-Mandanten bekommen keine Vertragsfristen (automatisch neu lizenziert).
Zwei getrennte Uhren: Vertragsende (valid_until) für Checkmk-Fristen; überfällige Zahlung (payment_overdue_since) für Mahnstufen 8/25/32. Bis zur Admin-API setzt die CLI den Zahlungsstatus: sultan token tenant payment --id … --overdue-since DATUM | --paid.
Job:
- setzt expired dauerhaft als Status (Nachvollziehbarkeit, Anzeige)
- räumt auf: Einladungen 10 Tage nach Ablauf bzw. Einlösung, abgelaufene Leases
- verschickt Benachrichtigungen
Benachrichtigungen einmal pro Ereignis, Versand in der DB vermerkt:
- Ereignisse: Fristen 30/14/0 Tage, Mahnstufen 1/2/3, Knoten länger als 15 min offline (entspricht 900 s DNS-TTL volatiler Subdomains), neue Policy-Verstöße
- Formate zuerst Slack-kompatibel ({"text": …}, Slack-Markdown; funktioniert auch mit Mattermost/Rocket.Chat/Discord) und ntfy. Danach Matrix (geplant), SMTP und Zammad (kommerziell).

Schritt 4 – Mehrere Server-Adressen – ✅ umgesetzt 2026-10-02

Die Einladung behält eine Adresse.
Der Server verteilt die vollständige Liste per config-Event (--public-url mehrfach angebbar).
Der Agent probiert sie der Reihe nach und merkt sich die zuletzt funktionierende. Gefahrlos, weil das Pinning am Fingerprint hängt.

Schritt 5 – Betrieb und Installationsskript (teilweise umgesetzt: Dockerfile, deploy/build.sh, deploy/push-image.sh, deploy/publish-static.sh, deploy/compose/)

Strukturiertes Logging (log/slog, umgesetzt), Graceful Shutdown (umgesetzt), Versionsinfo
✅ Dockerfile (statisch, distroless, Multi-Arch), Build-/Deploy-Skripte, Compose-Vorlagen
offen: systemd-Unit, install.sh, Signatur von SHA256SUMS (Ed25519, Schlüssel nur im Runner), Gitea Actions (Tests bei Push, Release bei Tag v*), Image-Digest in der veröffentlichten Compose-Vorlage, optional Spiegel auf ghcr.io
Installationsskript für curl | sh: Herkunft mit öffentlichem Zertifikat und/oder Prüfsumme bzw. Signatur. Die eigentliche Vertrauensfrage ist das Skript, nicht der Token.

Projektstand 2026-10-03: vorerst fertig. Erster Feldtest (webproxy11 + dockweb11) erfolgreich; Betriebsdoku unter docs/ (community.md, wartung.md, hoster.md). Weitere Iterationen nach Schwierigkeiten im Betrieb. Offen aus dem Abschluss:

Ungetestet im Feld: Agent als systemd-Dienst (ohne Docker); kommerzieller Betrieb (Lizenzen, Mahnwesen, Vertragsende, pro/enterprise).
tenant update (Vertragsende, Domains, Tier, Routenlimit) – Voraussetzung für zahlende Kunden; store.UpdateTenant existiert, CLI fehlt.
Lander-Vorlagen gestalten („hübsch“): die eingebauten Seiten sind bewusst minimal ohne CSS.
Registry mit Vanity-URL: zot.chmln.de ist noch nicht weiter getrieben (Image-Name unabhängig vom Registry-Host, z. B. cr.<domain>/sultan).
Geparkt: Veröffentlichung auf GitHub (Quellen, Releases, ggf. ghcr.io-Spiegel).

Schritt 6 – Accountant (5.3) – 6a/6b ✅ 2026-10-16, 6c ✅ 2026-10-17, 6d/6e ✅ 2026-10-18

✅ 6a Agent: Zusatzdaten (Compose-Projekt/-Verzeichnis, Startzeit, Health; FQDN, OS, Docker-Version, NetBird-IP) im service_state, automatisch erkannt.
✅ 6b sultan accountant: Datenverzeichnis, Zertifikat, accountant.db, Enrollment-Endpunkt, invite, payee list/delete.
✅ 6c Payee: --accountant-token/--accountant, Enrollment, Schnappschuss bei Änderung (Prüfintervall 10 s) und stündlich; Accountant speichert den letzten Bericht.
✅ 6d Accountant (2026-10-18): Schritt 1 Historie (Zeiträume je Ort), where, routes; Schritt 2 Kunden + Zuordnung (automatisch aus der Mandanten-ID); Schritt 3 Katalog + assign; Schritt 4 Monats-CSV. Inhalt: Pauschale, Klassen (included/billable/free/internal mit Schattenpreis), Gruppe + Notiz je Kunde, Produktkatalog und optionale Preise mit Gültig-ab, Zahlweise je Kunde, Monats-CSV, tagesgenaue Kündigungs-Gegenrechnung. Fachfragen geklärt 2026-10-18 (Beginn voller Monat ab dem 1., manueller späterer Beginn je Posten; Zahlweise je Kunde; Abo-Abgleich manuell; Preise optional; Kostenverursacher-Gruppe + Notiz je Kunde).
✅ 6e Checkmk-Ausgabe per Vorlage (Default eingebaut, dump-checkmk) mit Links; dazu Rate-Limit für /enroll des Accountants (2026-10-18).
Später: HTTP-API (Dokuwiki-Export), Mandanten-Statusberichte.

Weitere offene Bausteine (ohne feste Reihenfolge):

Lastverteilung einer Domain über mehrere Knoten (gemeinsamer Load-Balancer statt getrennter Router) – Voraussetzung dafür, dass drain seine Stärke ausspielt.
Admin-API (nur kommerziell): Mandanten, Lizenzen, Zahlungsstatus für Rechnungssystem und Ansible; Authentifizierung per API-Token, TLS über ACME.
(umgesetzt 2026-10-02: Rate-Limit für /enroll, Umgebungsvariablen für alle Flags, „wieder online“-Meldung, Checkmk mit Sekunden und Zeitzone)
Agent: Healthchecks auch für Docker-Container (Docker-Health-Status oder Labels sultan.healthcheck.*).
CLI: tenant update (Domains/Tier/Laufzeit ändern), JSON-Ausgabe für Skripte.
public_reason zweisprachig (klein): Die Wartungsseite ist de/en, der öffentliche Grund bisher nur ein Text. Vorschlag: --public-reason mehrfach mit Sprachpräfix (de:…, en:…; ohne Präfix = für alle Sprachen), Label analog sultan.maintenance.public_reason.<lang>; Übertragung im bestehenden Header X-Sultan-Public-Reason als URL-kodierte Form (de=…&en=…), Lander wählt je Sprachblock, fehlt eine Sprache → der andere Text.
Sicherheit (3.4): geordneter Zertifikatswechsel, optionale Root-CA.
Ausblick Monitoring: Die Zahl der Policy-Verstöße der letzten 24 h (Sultan_Policy_Violations) zählt der Server derzeit im Speicher; nach einem Neustart beginnt sie bei 0. Für Checkmk reicht das. Wird sie dauerhaft gebraucht (Auswertung, Audit), ist das eine kleine Erweiterung: Verstöße mit Zeitpunkt in einer Tabelle ablegen und im Aufräum-Job nach der Frist löschen.

Offene Fachfragen (vor Umsetzung klären):

Middleware-Zielbegrenzung: genaue Grenze (Pfadsegment? Zonen-Redirects?), Label-Name, Wechsel vom Beobachtungs- in den Sperrmodus.

104 KiB Raw Permalink Blame History Unescape Escape