Backup & restore — bRRAIn Docs

Encrypted vault snapshots with brrain dr, restoring to a new path, portable copies with brrain export, and proving recovery with brrain recover verify.

Backup & restore

On a customer-run host, backups are yours to design. The brain gives you three tools:

| Tool | Purpose | |---|---| | brrain dr | Encrypted vault snapshots and restores (routine recovery) | | brrain export | A verbatim, self-contained copy of the vault (portability, escrow, exit) | | brrain recover verify | Proves a vault unlocks with its recovery phrase; changes nothing |

brrain audit verify checks the signatures on the control-plane audit log and exits non-zero on a mismatch.

Start with brrain dr status

brrain dr status

It lists each disaster-recovery capability in this build (recovery-key unlock, snapshot, restore, alternate-vendor failover, tenant migration) as AVAILABLE or DEFERRED, with notes. Read the notes. In the current release the DR store is a filesystem directory, so copying snapshots off the host is your job.

Key and store

Every snapshot, restore, failover and migrate needs:

  • A DR master key: 32 bytes as 64 hex characters, in a file passed with --master-key-file or in BRRAIN_DR_MASTER_KEY. The master key never goes into a snapshot.
  • A store: --store <dir>. It defaults to $BRRAIN_DR_STORE or ./dr-store relative to wherever you run the command, so always set it.
  • Optional: --bucket-ledger (default <store>/buckets.jsonl), --region (default local) and --tier (hosted_standard, data_resident, co_located or sovereign; default hosted_standard). On a customer-run host, sovereign is usually right.
sudo install -d -m 700 /root/dr
openssl rand -hex 32 | sudo tee /root/dr/master.hex >/dev/null
sudo chmod 600 /root/dr/master.hex

Keep a copy of the key in your secret store, and keep it out of the snapshot store.

Take a snapshot

sudo brrain dr snapshot \
  --customer=<org-id> \
  --vault=/var/lib/brrain/vault \
  --store=/srv/brrain-dr \
  --master-key-file=/root/dr/master.hex \
  --tier=sovereign

It prints the snapshot ID, sizes, content hash and algorithm. If the vault has not changed since the last snapshot, it says so instead of writing a duplicate. Add --json for scripts.

Schedule it with a systemd timer or your scheduler at the interval your recovery point objective requires, and have your backup system copy the store directory (encrypted snapshots and ledger) off the host, without the master key.

Restore

Restore writes to a directory you name; it does not touch the running service.

sudo brrain dr restore \
  --customer=<org-id> \
  --snapshot=<snapshot-id> \
  --output=/srv/brrain-restore/<date> \
  --store=/srv/brrain-dr \
  --master-key-file=/root/dr/master.hex

If the restored vault does not validate, restore fails closed with an error rather than handing you a damaged vault.

To put a restored vault into service:

  1. sudo systemctl stop brrain
  2. Restore to a new path, as above.
  3. sudo brrain recover verify --vault=<restored path> --phrase-file=<file>
  4. Move the restored directory to the configured vault path, or point BRRAIN_VAULT_ROOT at it in a drop-in (the unit's ReadWritePaths must include it).
  5. sudo systemctl start brrain, then check /healthz, /readyz and a few answers.
  6. Tell users the snapshot time: anything written after it is not in the restored vault.

brrain dr failover and brrain dr migrate restore a snapshot or a live vault onto another tier and record who requested it; run brrain dr <subcommand> -h for their flags.

Portable copies: brrain export

sudo brrain export --customer=<org-id> --vault=/var/lib/brrain/vault --output=/srv/exports/<name> --json

Export copies every file of the live vault verbatim into a new directory (it refuses to overwrite an existing one) and checks the result validates. The copy can be opened and unlocked with the recovery phrase without any bRRAIn services. Records stay encrypted exactly as in the vault. Use it for escrow or exit copies; use snapshots for routine recovery.

Prove recovery: brrain recover verify

sudo brrain recover verify --vault=/var/lib/brrain/vault --phrase-file=/root/phrase.tmp

Run it after the first install, after every restore and during drills. Prefer --phrase-file to --phrase, which exposes the phrase in the process table and shell history.

Audit log integrity: brrain audit verify

brrain audit verify -log <control-audit-log.jsonl> -pub-hex <ed25519 public key>

Use -pub-file instead of -pub-hex to read a 32-byte raw key from a file. It prints "audit log signatures verified" or exits with code 1, so it can gate a pipeline.

Hosted pods

On a hosted pod the vault lives on a network volume that survives Kill Pod, Keep Storage and a recreate, but not Kill Storage. See Hosted pods.