300a0 - Vaultwarden — Passwort-Manager
Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/3-apps-workloads/300a0-vaultwarden.md
Vaultwarden — Passwort-Manager
Cluster: TECH · Ordner
argocd/apps/tech/vaultwarden/· URLhttps://vault.tech.homeserverundhttps://vault-tech.pke-lab.de.kubectl-Befehle in diesem Doc gelten für den TECH-Cluster (Zugriff je Cluster).
Vaultwarden ist eine
leichtgewichtige Rust-Implementierung der Bitwarden-Server-API. Alle
offiziellen Bitwarden-Clients (Browser-Erweiterung, Mobile-Apps, Desktop-App,
CLI) können sich gegen einen selbst gehosteten Vaultwarden-Server verbinden,
ohne die schwere offizielle Bitwarden-Server-Suite (MSSQL, mehrere
Microservices) betreiben zu müssen.
Architektur
vault.tech.homeserver → Traefik → vaultwarden (Port 80)
vault.pke-lab.de → Cloudflare Tunnel → vaultwarden (Port 80)
└── PVC: data (2 Gi, local-path)
- Datenbank: SQLite (in
/data, kein externer DB-Server nötig) - Websockets: laufen seit Vaultwarden 1.30 auf demselben Port wie die
HTTP-API (WEBSOCKET_ENABLED=true) → Live-Sync zwischen Clients ohne
zusätzlichen Service/Port - Kein ForwardAuth-Layer vor der App: Die Bitwarden-Clients
sprechen die API direkt an (Master-Passwort + eigenes 2FA übernehmen die
Absicherung). Ein ForwardAuth-Redirect würde den Login/Sync der Apps
brechen — anders als bei reinen Web-UIs ohne eigenes Client-Protokoll. - Extern erreichbar über den bestehenden Cloudflare Tunnel
(argocd/apps/tech/cloudflared/values.yaml), damit Handy-App und
Browser-Erweiterung auch unterwegs syncen können.
1. Erstdeployment
1.1 Admin-Token erzeugen (Argon2-Hash empfohlen)
Ein Klartext-ADMIN_TOKEN funktioniert, ist aber anfällig für
Timing-Angriffe. Vaultwarden empfiehlt stattdessen einen Argon2-PHC-Hash:
sudo docker run --rm -it vaultwarden/server:1.37.1 /vaultwarden hash
-itnicht vergessen — ohne TTY/stdin bricht der Passwort-Prompt mit
Os { code: 6, ... "No such device or address" }ab.
Das Kommando fragt interaktiv nach einem Passwort und gibt einen
$argon2id$...-Hash aus. Diesen Hash (nicht das Klartext-Passwort!) im
nächsten Schritt versiegeln.
1.2 SealedSecret-Ciphertext erzeugen
Über die Web-UI unter https://kubeseal-webgui.tech.homeserver:
- Öffnen und ausfüllen:
- Namespace:
vaultwarden - Secret-Name:
vaultwarden-admin - Key:
admin-token - Value: der
$argon2id$...-Hash aus 1.1
- Namespace:
- Encrypt klicken, den langen Base64-String kopieren.
Oder per CLI. Falls das lokale kubeconfig nicht auf den Home-Server zeigt
(z. B. von einer Workstation ohne Cluster-Zugriff), Public Key einmalig
vom Server holen und mit --cert an alle kubeseal-Aufrufe übergeben:
mkdir -p ~/homelab-certs
ssh -i ~/.ssh/id_ed25519 [email protected] \
'sudo kubectl -n sealed-secrets get secret \
-l sealedsecrets.bitnami.com/sealed-secrets-key=active \
-o jsonpath="{.items[0].data.tls\.crt}" | base64 -d' \
> ~/homelab-certs/sealed-secrets.pem
echo -n '$argon2id$...' \
| kubeseal --raw \
--cert ~/homelab-certs/sealed-secrets.pem \
--namespace vaultwarden \
--name vaultwarden-admin \
--from-file=/dev/stdin
Mit direktem Cluster-Zugriff (kubeconfig zeigt auf den Home-Server) reicht
stattdessen:
echo -n '$argon2id$...' \
| kubeseal --raw \
--namespace vaultwarden \
--name vaultwarden-admin \
--controller-namespace sealed-secrets \
--controller-name sealed-secrets-controller \
--from-file=/dev/stdin
1.3 Ciphertext in values.yaml eintragen
argocd/apps/tech/vaultwarden/values.yaml öffnen und den Platzhalter ersetzen:
adminSecret:
enabled: true
secretName: vaultwarden-admin
encryptedAdminToken: "AgB...langes-base64..." # ← aus 1.2
Committen + pushen (macht der Nutzer selbst):
git add argocd/apps/tech/vaultwarden/values.yaml
git commit -m "feat(vaultwarden): set sealed admin token"
git push
ArgoCD übernimmt die Änderung innerhalb von ~3 Minuten (oder Refresh in
der ArgoCD-UI bei der vaultwarden-App klicken).
1.4 Verifizieren
SRV='ssh -i ~/.ssh/id_ed25519 ubuntu@homeserver'
$SRV 'sudo kubectl -n vaultwarden get pods,svc,ingress,pvc,sealedsecret,secret'
curl -sS https://vault.tech.homeserver/alive
Erwartet:
- Pod
Running, PVCBound, dasvaultwarden-admin-Secret ist vorhanden. /aliveliefert einen JSON-Zeitstempel (z. B."2026-07-20T12:00:00...").
2. Ersten Account anlegen
- https://vault.tech.homeserver öffnen → Create Account.
- Master-Passwort setzen (idealerweise einen langen Passphrase-Satz, den
man sich merken kann — das ist der einzige Schlüssel zum ganzen Tresor). - Einloggen, im Web-Vault unter Account Settings → Security → Two-step
Login 2FA aktivieren (TOTP-App oder WebAuthn/Passkey). - Danach
SIGNUPS_ALLOWED: "false"invalues.yamlsetzen und
pushen, damit der Server nicht dauerhaft offen für neue Registrierungen
im Internet steht (der Tresor ist übervault.pke-lab.deextern
erreichbar, siehe Architektur oben).
Nutzer-Inventar: Wer einen Account hat, wird zusätzlich (verschlüsselt,
außerhalb der App-DB) in capulus-ansible/group_vars/user_inventory_vault.yml
festgehalten — make user-inventory-edit zum Bearbeiten, siehe
capulus-core/4-planung/40080-multi-cluster-entw-prod-tech.md → Baustein 7
für den Zweck (Dokumentation, kein Ersatz für die eigentliche DB).
3. Clients verbinden
Alle offiziellen Bitwarden-Clients unterstützen einen "Self-hosted"-Server:
- Browser-Erweiterung: Einstellungs-Zahnrad vor dem Login → Self-hosted
Environment → Server-URL:https://vault.pke-lab.de - Mobile-App (iOS/Android): Beim ersten Start unten Settings (Zahnrad)
→ gleiche Server-URL eintragen - Desktop-App / CLI: gleiches Prinzip (
bw config server https://vault.pke-lab.defür die CLI)
Intern im LAN funktioniert auch https://vault.tech.homeserver als Server-URL,
aber nur die pke-lab.de-Domain ist von unterwegs erreichbar.
4. Admin-Oberfläche
Unter https://vault.tech.homeserver/admin (LAN oder Tailnet) mit dem Klartext-Passwort
aus Schritt 1.1 einloggen. Auf dem öffentlichen Host vault-tech.pke-lab.de liefert
/admin 403: Ein zweiter Ingress mit einer Traefik-Middleware lässt dort nur
LAN und Tailnet zu (adminRestriction in values.yaml), Anfragen über den
Cloudflare-Tunnel kommen von der cloudflared-Pod-IP und werden abgewiesen. Alle
anderen Pfade (Web-Tresor, /api, /identity, Websocket) bleiben öffentlich.
Dort lassen sich u. a. Nutzer verwalten und Diagnosen einsehen.
Weitere Schichten für /admin:
| Maßnahme | Stand |
|---|---|
| Admin-Token als Argon2-PHC-Hash (Schritt 1.1) | umgesetzt |
| 2FA für alle Konten | aktiv |
Cloudflare-WAF-Regel „URI Path starts with /admin“ für vault-tech.pke-lab.de auf Block |
bewusst nicht gesetzt. Sie würde /admin schon am Cloudflare-Rand abweisen, bevor die Anfrage den Cluster erreicht. Die Traefik-Sperre (adminRestriction) deckt dasselbe ab. Die WAF-Regel ist eine optionale zweite Schicht, die im Cloudflare-Dashboard gesetzt wird (nicht im Repo), und gehört zur Zugangskontrolle des Tunnels (e0000) |
SMTP für E-Mail-Versand (Passwort-Reset, Organisations-Einladungen) ist
seit dem netcup-Postfach-Setup fest in values.yaml hinterlegt (siehe
Abschnitt 4a) und muss dort nicht zusätzlich in der /admin-UI
gepflegt werden — ein dort manuell gesetzter SMTP-Wert würde ohnehin bei
jedem Pod-Neustart wieder auf den Env-Var-Wert zurückfallen.
4a. SMTP-Einladungsmails
Ohne SMTP-Konfiguration erzeugt Vaultwarden zwar einen Einladungs-Token,
verschickt aber keine E-Mail — das ist Standardverhalten von
Vaultwarden ohne SMTP_HOST. Konfiguriert ist das netcup-Postfach
[email protected]:
env:
SMTP_HOST: mxe9f8.netcup.net
SMTP_PORT: "465"
SMTP_SECURITY: force_tls # implizites TLS auf Port 465 (nicht STARTTLS)
SMTP_FROM: [email protected]
SMTP_FROM_NAME: Vaultwarden
SMTP_USERNAME: [email protected]
smtpSecret:
enabled: true
secretName: vaultwarden-smtp
encryptedSmtpPassword: "AgB...langes-base64..."
SMTP_PASSWORD kommt aus dem vaultwarden-smtp-SealedSecret
(templates/sealedsecret.yaml, Key smtp-password), analog zum
Admin-Token — gleicher kubeseal-Workflow wie in Schritt 1.2, nur mit
Namen vaultwarden-smtp und Postfach-Klartext-Passwort statt Argon2-Hash:
echo -n '<netcup-postfach-passwort>' \
| kubeseal --raw \
--namespace vaultwarden \
--name vaultwarden-smtp \
--controller-namespace sealed-secrets \
--controller-name sealed-secrets-controller \
--from-file=/dev/stdin
Bei Postfach-Passwort-Rotation: neuen Ciphertext erzeugen,
encryptedSmtpPassword ersetzen, committen + pushen. Das alte
vaultwarden-smtp-Secret im Cluster löschen, falls ArgoCD es nicht
automatisch prunt.
Verifizieren: Eine Organisations-Einladung im Web-Vault verschicken
und kubectl -n vaultwarden logs deploy/vaultwarden | grep -i smtp
prüfen — bei falschem Port/Security-Kombination (z. B. starttls auf
Port 465) schlägt der Verbindungsaufbau fehl und landet dort als Fehler.
5. Konfiguration (values.yaml)
| Key | Bedeutung | Default |
|---|---|---|
env.DOMAIN |
Öffentliche Basis-URL (Links, WebAuthn-Origin-Check) | https://vault.pke-lab.de |
env.SIGNUPS_ALLOWED |
Neue Registrierungen erlauben | true (nach Account-Anlage auf false setzen) |
env.WEBSOCKET_ENABLED |
Live-Sync zwischen Clients | true |
env.SMTP_HOST / SMTP_PORT / SMTP_SECURITY |
Mailserver für Einladungs-/Reset-Mails | mxe9f8.netcup.net / 465 / force_tls |
env.SMTP_FROM / SMTP_USERNAME |
Absenderadresse = Postfach-Login | [email protected] |
adminSecret.encryptedAdminToken |
Versiegelter Argon2-Hash für /admin |
— (Schritt 1) |
adminRestriction.enabled / hosts / sourceRange |
Sperrt /admin auf den öffentlichen Hosts für alle Quellen außerhalb von sourceRange |
true / vault-tech.pke-lab.de / LAN und Tailnet |
smtpSecret.encryptedSmtpPassword |
Versiegeltes netcup-Postfach-Passwort | — (Abschnitt 4a) |
persistence.size |
Datenspeicher (SQLite + Anhänge + Icon-Cache) | 2Gi |
6. Admin-Token rotieren
docker run --rm vaultwarden/server:1.37.1 /vaultwarden hash
Neuen Hash mit kubeseal versiegeln (Schritt 1.2), encryptedAdminToken in
values.yaml ersetzen, committen + pushen. Das alte vaultwarden-admin
Secret im Cluster löschen, falls ArgoCD es nicht automatisch prunt.
7. Warum kein NAS-Storage für die Haupt-PVC
Eine Migration von persistence.storageClassName auf die NFS-nas-
StorageClass (wie beim Großteil der übrigen Apps, siehe
capulus-core/2-betrieb-hardware/20000-nas-storage.md) wurde erwogen, aber bewusst
verworfen: das NAS erzwingt inzwischen all_squash (kein
no_root_squash mehr verfügbar), was bei Vaultwardens SQLite-Datei zu
Permission-Problemen führt — siehe 60040. Die Haupt-PVC bleibt daher auf
local-path (Homeserver-System-SSD).
Stattdessen sichert ein nächtlicher backup-CronJob (eigene PVC, bewusst
storageClassName: nas, siehe backup-cronjob.yaml) die SQLite-Datenbank
per sqlite3 .backup (nutzt SQLites eigene Online-Backup-API, sicher auch
bei einer laufenden, offenen DB) auf das NAS — Details:
capulus-core/2-betrieb-hardware/20010-nas-backup.md.
Zusätzlich läuft ein verschlüsselter, versionierter restic-Backup (restic-backup.yaml, eine Backup-Ressource des capulus-operator, Einrichtung und Wiederherstellungstest: 20010). Der Spiegel oben bleibt, bis die Rolle vaultwarden_restore aus restic wiederherstellen kann.
8. Restore nach Redeploy / Disaster Recovery
Vaultwarden kennt keinen "User per API/Ansible anlegen"-Mechanismus, der
einen bestehenden Tresor mitbringt — Passwörter, Attachments und das
eigene 2FA/TOTP des Accounts ([email protected]) liegen alle
verschlüsselt in db.sqlite3 + rsa_key.pem. Der Account ist deshalb
nach einem Redeploy (z. B. verlorene local-path-PVC nach einem
Node-Wechsel) automatisch wieder vollständig da, sobald diese Dateien aus
dem NAS-Backup (siehe Abschnitt 7
und capulus-core/2-betrieb-hardware/20010-nas-backup.md) zurückkopiert sind — ein
separater Schritt, um den Nutzer "neu anzulegen", ist nicht nötig.
Dafür gibt es die Ansible-Rolle vaultwarden_restore
(capulus-ansible/roles/vaultwarden_restore/, Playbook
capulus-ansible/vaultwarden-restore.yml):
make vaultwarden-restore FORCE_RESTORE=true
Ablauf (alles automatisiert, läuft gegen den homeserver-Host, der
kubectl bereits lokal hat):
vaultwarden-Deployment auf 0 Replicas skalieren (keine parallel
schreibende Instanz während des Restores).- Ein einmaliger
Job(Manifest wird von Ansible gerendert und direkt per
kubectl apply -f -angewendet — bewusst nicht Teil des Helm-Charts,
damit ArgoCD ihn nicht als Dauerzustand verwaltet/prunt) mountet die
vaultwarden-data-PVC (rw) und dievaultwarden-backup-PVC (ro) und
spiegelt Letztere zurück auf Erstere. - Deployment wieder auf 1 Replica skalieren,
rollout statusabwarten,
/aliveprüfen.
Sicherheitsgurt: Ohne FORCE_RESTORE=true (Default false) bricht die
Rolle sofort mit einer Fehlermeldung ab. Das Playbook ist bewusst nicht
Teil von site.yml/make install — ein automatischer Lauf bei jedem
normalen Deploy könnte sonst live Tresordaten mit einem älteren Backup-Stand
überschreiben. make vaultwarden-restore also nur gezielt nach einem
echten Redeploy oder Datenverlust ausführen, nie routinemäßig.
Wichtig: Das setzt voraus, dass die vaultwarden-backup-PVC auf der
NAS noch existiert und der letzte nächtliche backup-cronjob.yaml-Lauf
erfolgreich war (kubectl -n vaultwarden get jobs). Ist auch dieser Stand
verloren (z. B. NAS-Totalausfall), bleibt nur der manuelle
restic-Restore von der externen USB-Platte, siehe
capulus-core/2-betrieb-hardware/20010-nas-backup.md → Wiederherstellung
— das NAS selbst bleibt bewusst außerhalb von Ansible verwaltet, dieser
Pfad wird nicht automatisiert.
9. Troubleshooting
| Symptom | Hinweis |
|---|---|
Pod CrashLoopBackOff nach Erstdeployment |
encryptedAdminToken ist noch REPLACE_ME_WITH_KUBESEAL_OUTPUT — Schritt 1.3 abschließen |
vaultwarden-admin-Secret fehlt |
kubectl -n vaultwarden describe sealedsecret vaultwarden-admin — Ciphertext muss gegen den Public Key dieses Clusters erzeugt worden sein |
| Browser-Erweiterung/App kann sich nicht verbinden | env.DOMAIN muss exakt zur benutzten Server-URL passen (Schema + Host), sonst schlägt der WebAuthn-Origin-Check fehl |
| Kein Live-Sync zwischen Geräten | env.WEBSOCKET_ENABLED prüfen; Traefik/Cloudflare müssen Websocket-Upgrades durchreichen (Standard bei beiden, kein Extra-Konfig nötig) |
/admin auf vault-tech.pke-lab.de liefert 403 |
Gewollt. Die Admin-Oberfläche nur über https://vault.tech.homeserver/admin aufrufen. Liefert auch der interne Host 403, kubectl -n vaultwarden get middleware,ingress prüfen |
/admin ist über vault-tech.pke-lab.de trotzdem erreichbar (200) |
Die Middleware fehlt oder der Name in der Annotation des Ingress vaultwarden-admin stimmt nicht: Traefik verwirft dann den Router stillschweigend, und /admin fällt auf den offenen /-Router zurück. kubectl -n vaultwarden get middleware vaultwarden-admin-nur-intern |
/admin liefert 404/Fehler trotz korrektem Token |
ADMIN_TOKEN env im Pod prüfen (kubectl -n vaultwarden exec deploy/vaultwarden -- env \| grep ADMIN_TOKEN) — muss aus dem Secret injiziert worden sein |
| Keine Einladungs-/Reset-Mail kommt an | kubectl -n vaultwarden logs deploy/vaultwarden \| grep -i smtp prüfen — häufigste Ursache: falsche SMTP_SECURITY/SMTP_PORT-Kombination (Port 465 braucht force_tls, Port 587 braucht starttls) oder vaultwarden-smtp-Secret fehlt (siehe Abschnitt 4a) |