Entwurf: ein Terminal fuer den CluPilot-Server selbst
Ein Host-Terminal reicht auf eine Maschine, dieses auf alles. Deshalb eigene Faehigkeit, eigener Schluessel, und die Netzliste ohne ihren Schalter. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>feat/versandtakt
nexxo
parent
cfd1481797
commit
76cf3d0555
|
|
@ -0,0 +1,236 @@
|
||||||
|
# Terminal für den CluPilot-Server — Entwurf
|
||||||
|
|
||||||
|
**Stand:** 2026-08-04
|
||||||
|
**Zustand:** Vom Betreiber abschnittsweise freigegeben. Ansatz, Berechtigung,
|
||||||
|
Erreichbarkeit, Protokolltiefe und Bühne sind entschieden.
|
||||||
|
|
||||||
|
## Worum es geht
|
||||||
|
|
||||||
|
Seit v1.4.2 kann ein Betreiber aus der Konsole eine Root-Schale auf einem
|
||||||
|
Proxmox-Host öffnen. Gewünscht ist dasselbe für den **CluPilot-Server selbst**:
|
||||||
|
die Debian-VM, auf der die Steuerungsebene läuft.
|
||||||
|
|
||||||
|
Das ist nicht dieselbe Funktion mit einem anderen Ziel. Ein Host-Terminal reicht
|
||||||
|
auf **eine** Maschine. Dieses hier reicht auf **alles** — Datenbank, Tresor,
|
||||||
|
DNS-Token, jede Kundeninstanz. Wer es hat, hat die Plattform. Daraus folgt jede
|
||||||
|
Entscheidung unten.
|
||||||
|
|
||||||
|
## Was entschieden ist
|
||||||
|
|
||||||
|
| Frage | Entscheidung |
|
||||||
|
|---|---|
|
||||||
|
| Reichweite | Die Debian-VM selbst, als root — nicht der `app`-Container |
|
||||||
|
| Berechtigung | Neue Fähigkeit `server.terminal`, per Migration nur an Owner |
|
||||||
|
| Erreichbarkeit | Die bestehende `trusted_ranges`-Liste, aber ohne ihren Schalter |
|
||||||
|
| Protokoll | Wer, wann, von wo — **kein** Mitschnitt des Inhalts |
|
||||||
|
| Weg zum Wirt | Eigener SSH-Schlüssel auf die sshd des Wirts |
|
||||||
|
|
||||||
|
### Warum kein Mitschnitt
|
||||||
|
|
||||||
|
Der Inhalt einer Root-Sitzung enthält zwangsläufig Passwörter, Tokens und
|
||||||
|
Schlüssel im Klartext. Wer ihn aufbewahrt, legt ein zweites Geheimnislager an,
|
||||||
|
das niemand bewacht — und das genau die Werte enthält, die der Tresor mit einem
|
||||||
|
eigenen Schlüssel schützt.
|
||||||
|
|
||||||
|
### Warum die Liste, aber nicht ihr Schalter
|
||||||
|
|
||||||
|
`RestrictConsoleNetwork` kennt die Liste bereits, ist aber **abschaltbar**
|
||||||
|
(`console.network_restricted`, Vorgabe *aus*). Für das Server-Terminal gilt die
|
||||||
|
Liste **immer**. Sonst hinge die Root-Konsole an einem Schalter, den es für
|
||||||
|
einen anderen Zweck gibt: wer ihn aus gutem Grund umlegt — ausgesperrt, muss von
|
||||||
|
unterwegs ran —, öffnete damit still auch diese Tür.
|
||||||
|
|
||||||
|
Der Preis dieser Entscheidung ist, dass eine in der Konsole pflegbare Liste über
|
||||||
|
eine Root-Konsole mitentscheidet. Bezahlt wird er mit einem **Hinweis an der
|
||||||
|
Pflegestelle**: auf `/admin/settings`, dort wo die Liste steht, wird gesagt,
|
||||||
|
dass diese Adressen auch bestimmen, von wo aus eine Root-Schale zum Server
|
||||||
|
aufgeht. Wer sie ändert, sieht, was daran hängt.
|
||||||
|
|
||||||
|
## Die Strecke
|
||||||
|
|
||||||
|
**Gemessen, nicht vermutet:** aus dem `terminal`-Container ist die sshd des
|
||||||
|
Wirts unter **172.18.0.1** erreichbar — dem Gateway des `clupilot_default`-
|
||||||
|
Netzes. Die Antwort war `SSH-2.0-OpenSSH_10.0p2`. Die Adresse ist
|
||||||
|
installationsabhängig und steht deshalb **nicht im Code**, sondern wird beim
|
||||||
|
Einrichten festgehalten.
|
||||||
|
|
||||||
|
**Die Brücke bleibt unangetastet.** `docker/terminal/bridge.py` kennt keine
|
||||||
|
Hosts, nur Tickets: Adresse, Benutzer, privater Schlüssel, Fingerabdruck. Ein
|
||||||
|
Server-Ticket sieht für sie aus wie jedes andere. Kein neues Format, keine neuen
|
||||||
|
Schließcodes, kein zweiter Weg — und damit auch keine zweite Stelle, an der die
|
||||||
|
Fingerabdruck-Prüfung schiefgehen kann. Auch der compose-Dienst und die
|
||||||
|
nginx-Stelle `location = /terminal/ws` bleiben, wie sie sind.
|
||||||
|
|
||||||
|
**Auf der PHP-Seite** kommt ein zweiter Ausstellungsweg dazu:
|
||||||
|
|
||||||
|
- `App\Services\Terminal\TicketStore` — die Feinheiten des Ticket-Speichers
|
||||||
|
wandern hierher: rohes Redis statt Cache-Fassade, `GETDEL`, `REDIS_PREFIX`,
|
||||||
|
dreißig Sekunden, genau eine Einlösung. `TerminalTicket` delegiert daran. Eine
|
||||||
|
zweite Abschrift dieser Weisheit wäre die Stelle, an der beide Seiten später
|
||||||
|
auseinanderlaufen.
|
||||||
|
- `App\Services\Terminal\ServerTicket` — `blocker()` und `issue()` in derselben
|
||||||
|
Form wie beim Host, aber mit anderer Herkunft der vier Felder:
|
||||||
|
Adresse und Fingerabdruck aus der Einrichtungsdatei, Benutzer `root`, und der
|
||||||
|
Schlüssel aus dem Tresor unter **`server.private_key`**.
|
||||||
|
|
||||||
|
`server.private_key` ist ausdrücklich **nicht** `ssh.private_key`. Ein Schlüssel,
|
||||||
|
der beides öffnet, macht aus zwei Türen eine — und der Flottenschlüssel liegt
|
||||||
|
auf jedem übernommenen Host in `authorized_keys`.
|
||||||
|
|
||||||
|
Als `host_uuid` trägt ein Server-Ticket den Wert `server`. Damit bleibt die
|
||||||
|
vorhandene Log-Zeile der Brücke lesbar („Sitzung offen — Host server
|
||||||
|
(172.18.0.1), Betreiber 3"), ohne dass an ihr etwas geändert werden muss.
|
||||||
|
|
||||||
|
## Die Einrichtung
|
||||||
|
|
||||||
|
Ein Update läuft unter dem Dienstkonto; `deploy/update.sh` weigert sich, als
|
||||||
|
root zu laufen. Für alles, was auf dem Wirt root braucht, gibt es bereits den
|
||||||
|
gebauten Mechanismus: `deploy/install-agent.sh` schreibt die privilegierte
|
||||||
|
Hälfte per Here-Dokument nach `/usr/local/sbin/clupilot-host-step` und trägt in
|
||||||
|
sudoers *eine* feste Kommandozeile ein. Das Dienstkonto kann kein Byte davon
|
||||||
|
ändern.
|
||||||
|
|
||||||
|
Dort — und nirgends sonst — gehört der Weg zum Wirt hin.
|
||||||
|
|
||||||
|
**`CONTRACT` steigt von 2 auf 3**, neuer Schritt `install-server-terminal`. Nach
|
||||||
|
dem Muster von `apply-proxy-hosts`: der Schritt **holt sich** den Wert selbst und
|
||||||
|
prüft ihn hart; das Dienstkonto liefert keine Konfiguration, nur die Auswahl.
|
||||||
|
|
||||||
|
Fünf Schritte:
|
||||||
|
|
||||||
|
1. Öffentlichen Schlüssel aus der Anwendung holen —
|
||||||
|
`docker compose exec -T -u www-data app php artisan clupilot:server-terminal-key`.
|
||||||
|
Die Anwendung erzeugt das Paar bei Bedarf mit dem vorhandenen
|
||||||
|
`Keypair::generate()` (Ed25519, Kommentar `clupilot`) und legt den privaten
|
||||||
|
Teil im Tresor ab.
|
||||||
|
2. Strikt prüfen: genau **eine** Zeile, `ssh-ed25519 <base64>` mit optionalem
|
||||||
|
Kommentar. Alles andere → Abbruch. Dieselbe Härte wie bei der
|
||||||
|
Hostnamen-Prüfung in `apply-proxy-hosts`.
|
||||||
|
3. Eintragen in `/root/.ssh/authorized_keys`, hinter einem Markierungskommentar,
|
||||||
|
damit ein zweiter Lauf **ersetzt** statt anzuhängen. Feste Optionsliste,
|
||||||
|
nicht aus der Anwendung: `from="<compose-Netz>",restrict,pty` — nur aus dem
|
||||||
|
Container-Netz, keine Weiterleitungen, aber ein PTY (ohne das kein Terminal).
|
||||||
|
4. Fingerabdruck des Wirt-Hostschlüssels **in CluPilots Form** bilden:
|
||||||
|
`SHA256:` base64 über `"<algo> <base64-blob>"`. **Nicht** der
|
||||||
|
OpenSSH-Fingerabdruck — das ist die Falle, die in `bridge.py` bereits zwölf
|
||||||
|
Zeilen Kommentar wert war, und wer sie hier erneut tritt, bekommt bei jedem
|
||||||
|
Verbindungsversuch eine Abweichung und die Versuchung, die Prüfung für kaputt
|
||||||
|
zu halten.
|
||||||
|
5. Adresse (Gateway des compose-Netzes) und Fingerabdruck nach
|
||||||
|
`storage/app/deploy/server-terminal.json` schreiben, dem Dienstkonto lesbar.
|
||||||
|
|
||||||
|
Fehlt diese Datei, sagt die Seite es in ihrer eigenen Sprache — „einmal
|
||||||
|
`sudo bash deploy/install-agent.sh` ausführen" —, statt ein Fenster zu öffnen,
|
||||||
|
das nie verbindet.
|
||||||
|
|
||||||
|
### Was ausdrücklich dazugesagt gehört
|
||||||
|
|
||||||
|
Damit wird das Dienstkonto auf dem Wirt root-fähig: es hat `.env` und die
|
||||||
|
Datenbank, kann also den Schlüssel aus dem Tresor lesen. Das lässt sich nicht
|
||||||
|
wegbauen — es **ist** die Funktion: ein Weg aus der Anwendung heraus zu root.
|
||||||
|
Auch die beiden verworfenen Ansätze (host-seitiger PTY-Dienst, privilegierter
|
||||||
|
Container) hätten daran nichts geändert.
|
||||||
|
|
||||||
|
Verworfen wurde:
|
||||||
|
|
||||||
|
- **Ein host-seitiger PTY-Dienst über einen Unix-Socket.** Kein Schlüssel, keine
|
||||||
|
zusätzliche Netz-Tür — aber ein neuer root-Dienst, ein eigenes Protokoll und
|
||||||
|
ein zweiter Weg in `bridge.py`. Ein selbstgeschriebenes PTY-Protokoll ist
|
||||||
|
genau die Sorte Code, in der ein Fehler still zu Root wird. Nach R22 der
|
||||||
|
falsche Aufwand für diese Aufgabe.
|
||||||
|
- **Ein privilegierter Container mit `nsenter`.** Am wenigsten Code — und der
|
||||||
|
von nginx erreichbare Container wäre dauerhaft root auf dem Wirt. Ein Fehler
|
||||||
|
in `bridge.py` wäre dann die Übernahme der Plattform, nicht ein kaputtes
|
||||||
|
Fenster.
|
||||||
|
|
||||||
|
## Die Tür und die Oberfläche
|
||||||
|
|
||||||
|
**Die Fähigkeit.** `server.terminal` kommt per Migration in den Katalog, nach
|
||||||
|
dem Muster der bestehenden `add_*_capability`-Migrationen, und wird nur der
|
||||||
|
Owner-Rolle zugeteilt. Sie steht damit im Rollen-Editor — der selbst hinter
|
||||||
|
`staff.manage` liegt, also heute nur beim Owner. Weitergeben kann sie nur er.
|
||||||
|
|
||||||
|
**Das Netz.** Der Prädikat-Teil von `RestrictConsoleNetwork::allows()` wird
|
||||||
|
wiederverwendet; `isRestricted()` wird **nicht** gefragt (Begründung oben).
|
||||||
|
|
||||||
|
**Die Seite.** `App\Livewire\Admin\ServerTerminal`, `layouts.bare`, eigener Tab,
|
||||||
|
Route in `routes/admin.php`. Reihenfolge im `mount()`: Fähigkeit, dann Netz,
|
||||||
|
dann Einrichtungsdatei, dann Ticket. Und wie beim Host-Terminal: **sie wirft
|
||||||
|
nie.** Ein Stacktrace in einem Terminalfenster ist ein Bruch mitten im Produkt.
|
||||||
|
|
||||||
|
**Der Knopf** sitzt auf `/admin/settings` in einem eigenen Abschnitt. Ohne die
|
||||||
|
Fähigkeit ist er nicht da. Mit Fähigkeit, aber falschem Netz oder fehlender
|
||||||
|
Einrichtung ist er sichtbar und gesperrt, mit Begründung — wer die Fähigkeit
|
||||||
|
hat, darf erfahren, warum es gerade nicht geht, sonst sucht er eine halbe Stunde
|
||||||
|
nach einem Knopf, der nie erscheint.
|
||||||
|
|
||||||
|
**Keine Bestätigung im Modal.** R23 zielt auf Aktionen mit Folgen; das Öffnen
|
||||||
|
eines Fensters ändert für sich nichts, und das Host-Terminal öffnet ebenso
|
||||||
|
direkt. Eine Rückfrage, die man täglich wegklickt, erzieht zum Wegklicken.
|
||||||
|
|
||||||
|
**Das Protokoll**, in zwei Hälften, weil keine allein reicht: PHP schreibt beim
|
||||||
|
Ausstellen, *wer* (Name, nicht nur id) von *welcher Adresse* eine Root-Konsole
|
||||||
|
angefordert hat — das weiß nur die Anwendung. Die Brücke schreibt wie bisher
|
||||||
|
Öffnen und Schließen.
|
||||||
|
|
||||||
|
## Die Bühne
|
||||||
|
|
||||||
|
Der Vorspann des Host-Terminals — Wortmarke als Blockgrafik, Titel, Notiz,
|
||||||
|
Neu-laden-Knopf — wird zum gemeinsamen Bauteil `<x-admin.terminal-screen>` mit
|
||||||
|
den Attributen, die es schon gibt: Ticket, Bühnentitel, Bühnennotiz,
|
||||||
|
Meldungssatz, Sichtbarkeit des Knopfes.
|
||||||
|
|
||||||
|
`resources/js/terminal.js` bleibt **unverändert**: es hängt an `data-terminal`,
|
||||||
|
`data-ticket` und `data-stage-messages`, nicht an der Seite, und weiß von Hosts
|
||||||
|
ohnehin nichts. Die Server-Seite füllt dieselbe Bühne aus `server.terminal.*` —
|
||||||
|
„Verbinde mit dem CluPilot-Server" statt eines Hostnamens.
|
||||||
|
|
||||||
|
Beim Herausziehen gilt: die Host-Ansicht muss danach zeichengleich dieselbe
|
||||||
|
sein. Eine Umstellung ohne Entwurfsentscheidung (R22 §5) — kein eigener Review,
|
||||||
|
aber der bestehende Testlauf.
|
||||||
|
|
||||||
|
## Fehlerbehandlung
|
||||||
|
|
||||||
|
**Was der Server schon weiß**, steht sofort auf der Bühne, ohne dass ein
|
||||||
|
WebSocket aufgeht:
|
||||||
|
|
||||||
|
| Merkwort | Bedeutung |
|
||||||
|
|---|---|
|
||||||
|
| `no_key` | kein `server.private_key` im Tresor |
|
||||||
|
| `not_installed` | `server-terminal.json` fehlt oder ist unlesbar |
|
||||||
|
| `off_network` | die Adresse steht nicht in der Liste |
|
||||||
|
| `unknown` | der Fangzaun, mit `report()` und Neu-laden-Knopf |
|
||||||
|
|
||||||
|
**Was erst der Browser weiß**, kommt unverändert aus den Schließcodes der
|
||||||
|
Brücke: **4401** abgewiesen, **4502** kein SSH.
|
||||||
|
|
||||||
|
Eine Sache verdient eigenen Text: **erzeugt der Wirt seine Hostschlüssel neu**
|
||||||
|
— Neuaufsetzen, `dpkg-reconfigure openssh-server` —, passt der gepinnte
|
||||||
|
Fingerabdruck nicht mehr, und das Terminal ist zu. Genau so soll es sein. Die
|
||||||
|
Rückfahrkarte ist dieselbe Zeile wie bei `not_installed`, und sie gehört in den
|
||||||
|
4502-Text, ohne zu behaupten, welcher der beiden Gründe es war.
|
||||||
|
|
||||||
|
## Tests
|
||||||
|
|
||||||
|
An den Grenzen statt flächendeckend (R22 §4). `DeploymentRunsAsTheAppUserTest`
|
||||||
|
zeigt, dass Skripte und compose hier ohnehin aus PHP heraus als Text gelesen
|
||||||
|
werden.
|
||||||
|
|
||||||
|
1. **Rechte.** Ohne `server.terminal` → 403. Mit Fähigkeit, aber Adresse
|
||||||
|
außerhalb der Liste → Bühne mit `off_network` und **kein Ticket in Redis**.
|
||||||
|
Das ist die Grenze, an der ein Fehler Rechte ausweitet.
|
||||||
|
2. **Zwei Türen bleiben zwei.** Das ausgestellte Ticket trägt
|
||||||
|
`server.private_key`, nicht `ssh.private_key`, dazu Adresse und Fingerabdruck
|
||||||
|
aus der Einrichtungsdatei.
|
||||||
|
3. **Der Ticket-Speicher bleibt, was er war:** rohes JSON, ein Präfix, genau
|
||||||
|
eine Einlösung — nach dem Herausziehen derselbe Test für beide Wege.
|
||||||
|
4. **Das Einrichtungsskript** nimmt nur genau eine `ssh-ed25519`-Zeile an und
|
||||||
|
schreibt die Optionsliste unveränderlich mit; `CONTRACT` ist erhöht.
|
||||||
|
5. **Die Seite wirft nie** — kaputter Tresor oder Redis weg ergibt `unknown`,
|
||||||
|
keine Laravel-Fehlerseite.
|
||||||
|
|
||||||
|
## Offen gelassen
|
||||||
|
|
||||||
|
- Die PTY-Größe bleibt bei 80×24, wie beim Host-Terminal. Das ist ein
|
||||||
|
bestehender offener Punkt der Brücke und wird hier nicht mitgelöst.
|
||||||
|
- Ein Terminal für Kundeninstanzen bleibt zurückgestellt.
|
||||||
Loading…
Reference in New Issue