backup-tool/docs/runbooks/recovery-bundle.md

Recovery bundle export and validation

M11 recovery exports an offline, passphrase-encrypted catalog and key bundle. Import is a local CLI operation that reconstructs only the metadata required to restore existing encrypted backups; it does not reactivate backup scheduling.

Export

Choose an absolute path in a trusted, non-symlinked directory. The destination must not already exist; export creates it with mode 0600 and never overwrites it.

read -r -s recovery_passphrase
printf '\n'
printf '%s\n' "$recovery_passphrase" | \
  backup-tool admin recovery export \
  --output /secure/offline/backup-tool-recovery.btrec \
  --passphrase-fd 0
unset recovery_passphrase

The passphrase is read from the inherited file descriptor. It is never a CLI argument. Store the resulting BTREC file away from the host and away from the live repository-key directories.

Validate

Validation authenticates and decrypts the bundle, checks the versioned Argon2id and AES-GCM format, and verifies the included catalog/key relationships. It prints only a status and repository count.

read -r -s recovery_passphrase
printf '\n'
printf '%s\n' "$recovery_passphrase" | \
  backup-tool admin recovery validate \
  --input /secure/offline/backup-tool-recovery.btrec \
  --passphrase-fd 0
unset recovery_passphrase

Wrong passphrases, tampering, malformed headers, unsupported KDF parameters, and invalid encrypted payloads intentionally produce the same validation error. Do not use a failed validation result to diagnose which of those conditions occurred.

Fresh-host import

Before importing, run migrations on the replacement host and configure its repository allowlist to include the surviving repository directory. The repository must pass normal metadata/path inspection. The replacement metadata database must be current and otherwise empty; import rejects a non-empty destination and any existing/conflicting key files.

backup-tool migrate upgrade
read -r -s recovery_passphrase
printf '\n'
printf '%s\n' "$recovery_passphrase" | \
  backup-tool admin recovery import \
  --input /secure/offline/backup-tool-recovery.btrec \
  --passphrase-fd 0
unset recovery_passphrase

Import installs signing and data keys with restrictive modes, restores the repository/source/job/execution/backup catalog needed for restore, and marks sources unavailable plus jobs archived and disabled. Reconfigure sources and explicitly create or enable new jobs before taking another backup.