Backup and Restore

Key operator baseline for backup/restore. For details and extended procedures, see the migrated AngaraBook runbook flow.

Goal

Pin the verifiable workflow:

• what backup guarantees;
• how restore is performed;
• which artifacts confirm correctness.

Contract (cold/offline)

• Backup is performed with the server stopped.
• Backup includes:
• storage.data_directory (including .adb);
• storage.transaction_log_directory;
• storage.undo_directory (if moved separately), or .aud from data_directory.
• The snapshot is consistent at the moment of stop.
• For TDE backup, restore requires valid key material (fail-closed).

What is out of scope

• No hot backup in this contract.
• No PITR.
• No incremental backup.

Pinned commands

CLI (operator-facing, preferred for packaged distribution):

angara-cli backup full --config /etc/angarabase/angarabase.conf --out /tmp/base_full.abk
angara-cli backup verify --file /tmp/base_full.abk --json

Restore via CLI:

angara-cli backup restore \
  --config /etc/angarabase/angarabase.conf \
  --file /tmp/base_full.abk \
  --target-dir /tmp/angarabase-restore \
  --overwrite

Legacy tools entrypoint (workspace/dev path):

tools/backup_restore/run.sh backup \
 --data-dir /var/lib/angarabase/data \
 --txlog-dir /var/lib/angarabase/transaction_log \
 --out /tmp/angarabase-backup.tar.gz \
 --root artifacts/backup_restore/backup

tools/backup_restore/run.sh restore \
 --archive /tmp/angarabase-backup.tar.gz \
 --dest /tmp/angarabase-restore \
 --force \
 --root artifacts/backup_restore/restore

Restore oracle (txlog-level):

tools/backup_restore/oracle.sh --root artifacts/backup_restore_oracle/run_1

Evidence surfaces

Minimum for triage:

• summary.json (top-level outcome);
• backup_manifest.json (inspect);
• verify_report.json (verify);
• oracle JSON (txlog scan/replay-pages, compare.json).

Upgrade linkage

Before a version upgrade, it is recommended to:

1. take a cold backup;
2. save the archive as a rollback point;
3. run the restore oracle on a separate directory.

Compatibility and on-disk policy: src/operations/upgrade-and-migration.md.

Remote Admin Flow (updated 2026-04-23 for TD-2026-0012)

For packaged distribution (apt install angarabase-server), angara-cli is preferred (remote admin over TCP or local). Legacy tools/backup_restore/run.sh remains only for dev/workspace.

Remote admin flow:

• angara-cli backup ... --remote-admin (or through the configured admin endpoint).
• Runbooks in angarabook/src/operations/ now point to packaged CLI instead of direct tool calls.
• Evidence: tools/ci/backup_smoke.sh + golden_db restore oracle.

last_reviewed: 2026-04-23. Drift resolved.