Backup And Recovery

Backups for Vaulthalla must cover metadata, file bodies, configuration, key protection state, and exported recovery material. A PostgreSQL dump alone is not a complete backup.

Recovery Set

A practical recovery set includes:

Item	Why it matters
PostgreSQL database dump	Users, groups, roles, vault definitions, sync policy, shares, audit state, key records, remote indexes, and metadata.
`/etc/vaulthalla/config.yaml`	Runtime ports, auth settings, pricing settings, sharing settings, cache policy, and service configuration.
`/var/lib/vaulthalla`	Vaulthalla-managed state, local vault bodies, cache/index state, and sealed key blobs.
`/var/lib/swtpm/vaulthalla`	Software TPM state when `swtpm` is used.
Vault key export	Portable recovery material for encrypted vault content.
Internal secret export	Database and JWT secrets managed by Vaulthalla.
S3/R2 bucket data	Remote object bodies for S3-compatible vaults.
Package version record	Helps restore with the same or compatible schema and runtime behavior.

No single backup command covers everything

The current operator surfaces expose key and secret export commands, but a full backup still needs database, config, state, and object-storage backups using your normal infrastructure tooling.

Recommended Backup Command Set

Create a PostgreSQL custom-format dump for a local database:

1sudo -u postgres pg_dump -Fc vaulthalla > vaulthalla-db.dump

For remote PostgreSQL, use your database host, credentials, and network path:

1pg_dump -h <host> -U <user> -Fc vaulthalla > vaulthalla-db.dump

Archive config and state:

1sudo tar -C / -czf vaulthalla-config-state.tgz \2  etc/vaulthalla \3  var/lib/vaulthalla

If using swtpm, include software TPM state:

1sudo tar -C / -czf vaulthalla-swtpm-state.tgz var/lib/swtpm/vaulthalla

Export vault keys:

1vh vault keys export all \2  --recipient <gpg-fingerprint> \3  --output vaulthalla-vault-keys.json.gpg

Export internal secrets:

1vh secret export all \2  --recipient <gpg-fingerprint> \3  --output vaulthalla-secrets.json.gpg

Record the package version:

1vh version > vaulthalla-version.txt

Local Vault Backup

For local vaults, the file bodies live in Vaulthalla-managed local state. Back up /var/lib/vaulthalla consistently with the PostgreSQL dump. If the system is active during backup, use snapshots or a maintenance window so the database and file bodies represent a coherent point in time.

S3/R2 Vault Backup

For S3/R2 vaults, back up the bucket according to your provider's tooling. If upstream encryption is enabled, the remote object bodies still require Vaulthalla keys and metadata to decrypt.

Do not rely only on the provider bucket as a complete Vaulthalla backup. You still need PostgreSQL metadata, vault key exports, internal secrets, and configuration.

Hardware TPM Recovery

Hardware TPM-sealed material is tied to the original TPM context. For host replacement, exported vault keys and internal secrets are the portable recovery material. Plan migration and restore testing before a hardware failure.

Software TPM Recovery

When using swtpm, restoring /var/lib/swtpm/vaulthalla can preserve the software TPM context. Protect this directory like key material. Restoring it to a different host should be treated as a sensitive security event.

Restore Outline

Use this as a cautious outline, not a blind script:

Install the same Vaulthalla version where possible.
Stop Vaulthalla services.
Restore /etc/vaulthalla and /var/lib/vaulthalla.
Restore /var/lib/swtpm/vaulthalla if the backup used software TPM.
Restore PostgreSQL from the dump.
Reseed or verify the database password secret if the database connection changed.
Start services.
Run vh status.
Run vh vault sync info <vault> for S3/R2 vaults.
Test read access to a known file in each vault.

Example service boundary:

1sudo systemctl stop vaulthalla.service vaulthalla-web.service vaulthalla-cli.socket2sudo systemctl start vaulthalla.service vaulthalla-web.service vaulthalla-cli.socket

Preserved Database Reinstall

If the package was removed but the database was preserved, reseed the runtime database password file before restart when needed:

1sudo install -d -m 0755 /run/vaulthalla2sudo install -m 0600 -o vaulthalla -g vaulthalla /path/to/db_password /run/vaulthalla/db_password3sudo systemctl restart vaulthalla

Test Restores

Run restore drills. A backup is not proven until an operator has restored:

Database metadata.
At least one local vault file.
At least one S3/R2 vault file.
An encrypted upstream object.
A user, group, role, and share record.
Cost-control policy state.

Document the exact Vaulthalla version, package source, database version, host TPM mode, and GPG recipient used for each recovery set.