florian.wildeandClaude Opus 5.5
3b28f73c95
Handbuch mit Bildern fuer alle Ablaeufe, darunter der Kern- Anwendungsfall und der Deployment-Zugang fuer Claude Code. Betriebsdoku zu Installation, authentik und Reverse Proxy sowie eine Bedrohungsanalyse mit Notfallplan fuer den Fall, dass sshkv selbst kompromittiert wird. Sicherung und Wiederherstellung als Skripte, auf einem Wegwerf-Stapel geprobt. Dabei fielen zwei Fehler auf: das Schema der Warteschlange liess sich nicht zurueckspielen, und ein Abbruch ohne Transaktion loeschte es halb. Jetzt nur Schema public, in einer Transaktion, mit Pruefwert des Master-Keys. Der Worker startet nicht, wenn der Master-Key nicht zur Datenbank passt. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
113 lines
4.7 KiB
Markdown
113 lines
4.7 KiB
Markdown
# Installation und Betrieb
|
||
|
||
SSHKeyVault läuft als Docker-Compose-Stapel aus drei Diensten plus einem einmaligen Migrationslauf:
|
||
|
||
| Dienst | Aufgabe | Netz | Geheimnisse |
|
||
|---|---|---|---|
|
||
| `db` | PostgreSQL 17 | nur intern (`internal: true`) | Datenbankpasswort |
|
||
| `migrate` | Schema einspielen, Notfall-Admin und Vorlagen anlegen (läuft bei jedem Start einmal) | intern | Notfall-Passwort beim ersten Start |
|
||
| `web` | Weboberfläche (Port 3400) | intern + nach außen zum OIDC-Anbieter | `SSHKV_APP_SECRET`, OIDC-Client-Secret – **kein Master-Key** |
|
||
| `worker` | SSH zu den Hosts, Ver-/Entschlüsselung, Zeitpläne | intern + zu den Hosts | Master-Key (Docker-Secret), `SSHKV_APP_SECRET` |
|
||
|
||
## Voraussetzungen
|
||
|
||
- Linux-Host mit Docker und Docker Compose v2, **im internen Netz bzw. nur per VPN erreichbar**.
|
||
- Der Worker muss die zu verwaltenden Hosts per SSH erreichen (Port 22 oder den jeweiligen Port).
|
||
- authentik (oder ein anderer OIDC-Anbieter) für die Anmeldung.
|
||
- Ein Reverse Proxy mit TLS vor der Weboberfläche.
|
||
|
||
## Schritt für Schritt
|
||
|
||
```bash
|
||
sudo mkdir -p /opt/sshkv && cd /opt/sshkv
|
||
git clone <repo> . # oder Release entpacken
|
||
cp .env.example .env && chmod 600 .env
|
||
```
|
||
|
||
In `.env` eintragen (Kommentare in der Datei erklären jede Variable):
|
||
|
||
- `POSTGRES_PASSWORD` – `openssl rand -hex 24`
|
||
- `SSHKV_APP_SECRET` – `openssl rand -base64 48`
|
||
- `SSHKV_APP_URL` – die Adresse, unter der Benutzer sshkv aufrufen, z. B. `https://sshkv.intern.example.de`
|
||
- `SSHKV_BREAKGLASS_PASSWORD` – mindestens 16 Zeichen; Notfall-Admin `notfall`
|
||
- `SSHKV_OIDC_*` – siehe unten
|
||
|
||
Master-Key erzeugen und nur für den Worker lesbar machen:
|
||
|
||
```bash
|
||
sudo mkdir -p geheim
|
||
sudo sh -c 'head -c 32 /dev/urandom > geheim/master.key'
|
||
sudo chown 1001:1001 geheim/master.key && sudo chmod 400 geheim/master.key
|
||
```
|
||
|
||
Starten:
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
docker compose logs -f worker # „sshkv-worker … bereit“
|
||
```
|
||
|
||
Beim ersten Start legt `migrate` das Schema, den Notfall-Admin und die eingebauten Vorlagen an; der
|
||
Worker erzeugt den **Deployment-Key** der Instanz. Danach sofort den Master-Key sichern
|
||
([sicherung.md](sicherung.md)).
|
||
|
||
## authentik einrichten
|
||
|
||
1. **Provider** „OAuth2/OpenID Provider“ anlegen: Client-Typ *confidential*, Redirect-URI
|
||
`https://sshkv.intern.example.de/api/auth/oidc/rueckruf`, Scopes `openid profile email` und ein
|
||
Scope-Mapping, das die Gruppen als Claim `groups` liefert (in authentik Standard).
|
||
2. **Application** „SSHKeyVault“ mit diesem Provider anlegen.
|
||
3. **Gruppen** `sshkv-admins`, `sshkv-operators`, `sshkv-readers` anlegen und Benutzer zuordnen
|
||
(Namen änderbar über `SSHKV_OIDC_GROUP_*`). Wer in keiner Gruppe ist, kommt nicht hinein.
|
||
4. In `.env`: `SSHKV_OIDC_ISSUER=https://authentik.example.de/application/o/sshkv/`,
|
||
`SSHKV_OIDC_CLIENT_ID`, `SSHKV_OIDC_CLIENT_SECRET`, `SSHKV_OIDC_NAME=authentik`.
|
||
|
||
Erneute Bestätigung vor kritischen Aktionen schickt `prompt=login` und `max_age=0`; sshkv prüft
|
||
`auth_time` im ID-Token. authentik liefert `auth_time` standardmäßig.
|
||
|
||
| Rolle | darf |
|
||
|---|---|
|
||
| Leser | alles ansehen, eigene Public Keys hinterlegen |
|
||
| Operator | zusätzlich Hosts verwalten, Host-Keys bestätigen, Schlüssel erzeugen, Public Keys ausrollen, abgleichen |
|
||
| Admin | zusätzlich Private Keys ausrollen/anzeigen/löschen, Zielkonten mit sudo, Massenwiderruf, Einstellungen, Vorlagen |
|
||
|
||
## Reverse Proxy (Beispiel Caddy)
|
||
|
||
```caddyfile
|
||
sshkv.intern.example.de {
|
||
tls internal # oder das interne Zertifikat
|
||
@extern not remote_ip 10.0.0.0/8 192.168.0.0/16
|
||
respond @extern 403
|
||
reverse_proxy 127.0.0.1:3400
|
||
}
|
||
```
|
||
|
||
Wichtig: `SSHKV_APP_URL` muss die Adresse mit `https://` sein – davon hängen Secure-Cookie und
|
||
OIDC-Rückruf ab.
|
||
|
||
## Hosts vorbereiten
|
||
|
||
- **Debian/Ubuntu** mit `openssh-server`, `sudo`, `runuser` (util-linux), `base64`, `sha256sum`,
|
||
`visudo` (bei Dienstbenutzer) – auf Standardinstallationen vorhanden.
|
||
- Für den Bootstrap per Passwort einmalig ein Konto mit Passwort-Login (root oder ein Benutzer mit
|
||
sudo). Danach kann Passwort-Login aus; sshkv zeigt den sshd-Befund an.
|
||
|
||
## Aktualisieren
|
||
|
||
```bash
|
||
cd /opt/sshkv
|
||
sudo bash deploy/sichern.sh
|
||
git pull
|
||
docker compose up -d --build # migrate spielt neue Migrationen ein
|
||
```
|
||
|
||
## Variablen (Auswahl)
|
||
|
||
| Variable | Bedeutung |
|
||
|---|---|
|
||
| `SSHKV_SYNC_CRON` | Zeitplan des Abgleichs (Standard `30 2 * * *`, Europe/Berlin) |
|
||
| `SSHKV_MELDUNG_CRON` | tägliche Zusammenfassung der Benachrichtigungen |
|
||
| `SSHKV_SYSLOG_HOST`/`_PORT`/`_PROTOKOLL` | Kopie des Protokolls an einen Syslog-Server |
|
||
| `SSHKV_WORKER_USER` | Benutzer des Worker-Containers, falls die Master-Key-Datei nicht UID 1001 gehört |
|
||
| `SSHKV_BIND` / `SSHKV_PORT` | Bindeadresse/Port der Weboberfläche (Standard `127.0.0.1:3400`) |
|