# Vaultwarden Operations Runbook

## Purpose

Document routine operation of the homelab Vaultwarden service without recording secret values.

This runbook is actionable for routine checks after the bootstrap deployment. Do not treat the service as approved for critical secrets until backup/restore and hardening gates are complete.

## Operating Rules

- Do not store vault master passwords, admin tokens, recovery codes, API keys, app passwords, or backup encryption keys in git.
- Use credential references and metadata only.
- Assistant vault access requires a dedicated/scoped assistant identity and documented authorization/revocation; do not share the user's personal vault credentials with the assistant.
- Public exposure requires a separate security review.
- Backups and restore tests are part of normal operation, not optional extras.

## Service Metadata

Current bootstrap metadata:

- VM hostname/name: `Vaultwarden`
- VMID: `102`
- IP/DNS: DHCP observed at `192.168.0.238`; intended FQDN `vw.dropcutstud.io`
- Access boundary: LAN/Tailscale only; no public exposure approved
- Deployment method: Docker container managed by systemd inside dedicated Debian 13 VM, with Nginx HTTPS reverse proxy
- Service path/config path: `/etc/vaultwarden/env`, `/etc/systemd/system/vaultwarden.service`, Nginx site config on the VM
- Data path: `/opt/vaultwarden/data`
- Backup runbook: `runbooks/vaultwarden-backup.md`
- Restore-test runbook: `runbooks/vaultwarden-restore-test.md`

## Routine Checks

Run after deployment and during maintenance windows:

- Confirm VM is running in Proxmox.
- Confirm Vaultwarden service/container is running.
- Confirm HTTPS endpoint responds from approved LAN/Tailscale path.
- Confirm no public exposure has been added accidentally.
- Confirm disk usage is healthy.
- Confirm backup artifacts exist and are recent.
- Confirm TLS certificate is valid and not near expiry.
- Review failed-login/security events if available.

## Start / Stop / Restart

Final commands depend on deployment method.

Docker Compose placeholder:

```sh
# Run from approved Vaultwarden compose directory after deployment details are known.
docker compose ps
docker compose up -d
docker compose restart
docker compose logs --tail=100
```

Systemd placeholder:

```sh
systemctl status <vaultwarden-service>
systemctl restart <vaultwarden-service>
journalctl -u <vaultwarden-service> -n 100 --no-pager
```

Do not run destructive commands without an approved rollback path.

## Update Procedure

Before updating:

1. Confirm current backup exists.
2. Take a Proxmox snapshot if approved for this maintenance.
3. Review release notes if practical.
4. Confirm rollback path.
5. Announce expected downtime if other users rely on the vault.

After updating:

1. Verify service health.
2. Verify login from an approved client.
3. Verify backup still runs.
4. Log update in `docs/server-change-log.md`.

## User/Admin Account Management

Metadata to record for vault users, without secrets:

- User/account reference
- Role: admin/user/emergency/recovery owner
- 2FA enabled: yes/no/unknown
- Recovery owner
- Date added
- Date removed, if applicable

Revocation checklist:

1. Disable/remove the vault account.
2. Rotate any shared credentials the user may have seen.
3. Verify access is removed.
4. Log metadata only.

## Credential Migration Checklist

Use for small, controlled migration batches only:

1. Confirm credential owner and purpose.
2. Confirm credential scope/permissions.
3. Store the value in Vaultwarden only, not git or chat.
4. Record metadata in repo only if useful and safe.
5. Record revocation path.
6. Confirm backup coverage before migrating critical credentials.
7. Verify dependent service still works if the credential changed.
8. Log server-side changes without values.

Recommended first migrations:

- low-risk credential metadata records
- non-critical app passwords/tokens that can be rotated easily
- recovery notes that do not make the vault a single point of lockout

Do not mass-migrate critical credentials until backup and restore testing are complete.

## Token/App Password Rotation Expectations

For each token or app password:

1. Create replacement credential in the source service.
2. Store the replacement value in Vaultwarden only.
3. Update dependent service/config if needed.
4. Verify replacement works.
5. Revoke old credential.
6. Verify old credential fails where safe.
7. Log metadata and verification only.

## Lockout / Incident Response Pointers

If vault access is lost:

1. Do not make multiple blind recovery attempts.
2. Use the out-of-vault recovery kit.
3. Confirm whether issue is account, 2FA, service outage, TLS/DNS, or data corruption.
4. If service outage, check VM/service status and logs.
5. If data corruption or failed upgrade, use backup/restore runbooks.
6. After recovery, rotate credentials if compromise is suspected.
7. Log incident actions without secret values.

If compromise is suspected:

1. Preserve evidence/logs where practical.
2. Disable exposed access paths.
3. Rotate high-risk credentials in priority order.
4. Review vault users/sessions/tokens.
5. Verify backups are clean before restoring.
6. Create follow-up tickets for root cause and hardening.

## Change Logging

Log the following in `docs/server-change-log.md`:

- deployments and upgrades
- backup job creation/changes
- restore tests
- network/TLS exposure changes
- user/admin changes that affect access
- service credential rotations affecting servers
- incidents and rollback actions

Never log secret values.