# Vaultwarden Backup Runbook

## Purpose

Define backup expectations for the homelab Vaultwarden service before it becomes authoritative for critical secrets.

This runbook now documents the initial MVP backup implementation for VM 102 `Vaultwarden`. Follow-up work is tracked in `tickets/active/2026-06-06-vaultwarden-backup-plan.md`.

## Backup Rules

- Configure a basic backup before migrating critical secrets.
- Perform a restore test soon after the first working backup.
- Backup decryption/recovery material must not live only inside Vaultwarden.
- Do not write encryption keys, recovery codes, master passwords, admin tokens, or app passwords to git.
- Log backup configuration and verification without secret values.

## MVP Backup Configuration

- Source host: VM 102 `Vaultwarden` / `192.168.0.238`.
- Backup script: `/usr/local/sbin/vaultwarden-backup` on the Vaultwarden VM.
- Primary VM-local destination: `/var/backups/vaultwarden/`, root-owned mode `0700`.
- Secondary off-VM bootstrap copy: LXC 104 `nimrod` at `/home/piagent/backups/vaultwarden/`, mode `0700` directory and `0600` artifacts.
- Encryption method: `age` using a dedicated Vaultwarden-backup age recipient generated by the user.
- Recipient file on VM: `/etc/vaultwarden/backup-recipient.txt`; public `age1...` recipient only, no private key.
- Recovery private key: user-owned `AGE-SECRET-KEY-...` file generated on the user's Linux workstation; it must be copied to safe storage outside Vaultwarden before formatting that workstation.
- Current schedule: manual only.
- Current retention: manual/no pruning until a broader backup standard is approved.
- Offline copy expectation: user should copy the latest `.tar.age` and `.manifest.txt` from the Nimrod off-VM bootstrap copy to user-owned offline/workstation storage.
- Restore-test target: tracked in `runbooks/vaultwarden-restore-test.md` and `tickets/active/2026-06-06-vaultwarden-recovery-restore-plan.md`.

## Backup Scope

Include, as applicable:

- Vaultwarden database/data directory
- Vaultwarden configuration
- Attachments, sends, and icons if enabled
- Admin token material by storage reference only, not value
- TLS/reverse-proxy configuration
- Backup scripts/configuration
- Any compose/systemd/service definitions needed for restore
- Backup encryption metadata by reference only, not key value

## Manual Backup Checklist

Current manual procedure:

1. Confirm the user controls the private key corresponding to the dedicated Vaultwarden-backup `age1...` recipient.
2. Run the VM-local backup:
   ```sh
   sudo /usr/local/sbin/vaultwarden-backup
   ```
3. Confirm Vaultwarden restarted and is active.
4. Verify the newest artifact on the VM:
   ```sh
   cd /var/backups/vaultwarden && sudo sha256sum -c <latest>.manifest.txt
   ```
5. Copy the latest `.tar.age` and `.manifest.txt` off the VM, currently to `/home/piagent/backups/vaultwarden/` on LXC 104.
6. Verify the copied artifact checksum from the destination directory.
7. User copies the encrypted artifact and manifest to offline/workstation storage.
8. Log result in `docs/server-change-log.md` without secrets.

## Automated Backup Expectations

If a scheduled job is added later, document:

- command/script path
- service account
- schedule
- destination
- retention
- encryption method by reference only
- log path
- alert/notification path
- last successful run
- restore-test date

## Verification

Minimum backup verification:

- Backup command exits successfully.
- Expected backup artifact exists.
- Artifact is non-empty.
- Artifact is stored outside the Vaultwarden data directory.
- Encrypted artifact checksum validates on the VM.
- Encrypted artifact checksum validates after off-VM copy.
- Recovery material is accessible without logging into Vaultwarden.

Stronger verification:

- Integrity/checksum validation passes.
- Backup can be decrypted by the recovery owner.
- Restore test succeeds in an isolated target.

## Restore-Test Requirement

Do not treat Vaultwarden as authoritative for critical secrets until a restore test succeeds, unless the user explicitly accepts that risk.

Use `runbooks/vaultwarden-restore-test.md` for restore testing.

## Failure Handling

If backup fails:

1. Do not migrate additional critical secrets.
2. Identify whether failure is destination, permissions, disk space, encryption, service state, or script logic.
3. Fix and retry.
4. Preserve last known-good backup if one exists.
5. Log failure and remediation without secrets.

## Rollback

If a new backup configuration breaks service or creates risk:

1. Disable the new backup job.
2. Restore prior backup configuration if one exists.
3. Preserve backup artifacts for review unless they contain invalid/corrupt data and user approves removal.
4. Verify Vaultwarden service remains healthy.
5. Log rollback.