Backup and restore
What a backup holds
bunker backup writes one encrypted archive while the bunker keeps running. It holds:
- a consistent snapshot of the database,
./data/bancwr.db: the team and their roles, connection tokens (only a hash of each secret) and connected apps, the signing log, every identity, and the bunker relays chosen under Config, - the encrypted key file,
./data/bunker-key.enc, exactly as it is on disk.
It does not hold the root credential, the backup passphrase, the proxy secret or anyone's session.
The archive is encrypted under the backup passphrase in ./secrets/bancwr_backup_key. Inside it, the bunker's key is still encrypted under the root credential, so an archive and its passphrase together are not the key. The archive is also authenticated under the root credential (with an HMAC), so a restore can tell it was made by this bunker and not altered since.
What you need to recover
To recover a bunker you need 3 things. Keep each apart from the others:
- an archive,
- the backup passphrase,
./secrets/bancwr_backup_key, - the root credential,
./secrets/bancwr_root_key.
The database names every member and every connected app, so keep archives as private as the server.
Take a backup
mkdir -p -m 700 backups
(umask 077; podman exec bancwr-bunker bunker backup > "backups/bancwr-$(date +%F).bcwr")
With Docker, use docker exec.
The archive goes to standard output, and a short summary to the terminal: the bunker's npub, and how many members, connections and signing log entries it holds.
If the command fails, it exits with an error and says why, and the file it was written to is empty or incomplete. Delete that file.
Bancwr does not copy archives anywhere. Copy them off the server yourself, to somewhere the backup passphrase is not.
Scheduled backups
A small script, run daily, keeping 30 days of archives.
Save this as bancwr-backup.sh beside compose.yaml, and make it executable with chmod 700 bancwr-backup.sh:
#!/bin/sh
set -eu
umask 077
cd "$(dirname "$0")"
mkdir -p backups
name="backups/bancwr-$(date +%F-%H%M).bcwr"
podman exec bancwr-bunker bunker backup > "$name.part"
mv "$name.part" "$name"
find backups -name 'bancwr-*.bcwr' -mtime +30 -delete
With Docker, use docker exec. An archive only gets its final name once the backup succeeds, so a failed run leaves a .part file, never an archive that looks complete.
With a systemd timer
With rootless Podman, run it as a systemd user timer. Adjust %h/bancwr to the directory that holds your compose.yaml.
~/.config/systemd/user/bancwr-backup.service:
[Unit]
Description=Back up the Bancwr bunker
[Service]
Type=oneshot
ExecStart=%h/bancwr/bancwr-backup.sh
~/.config/systemd/user/bancwr-backup.timer:
[Unit]
Description=Back up the Bancwr bunker daily
[Timer]
OnCalendar=*-*-* 03:15:00
Persistent=true
[Install]
WantedBy=timers.target
Then turn it on:
systemctl --user daemon-reload
systemctl --user enable --now bancwr-backup.timer
loginctl enable-linger "$USER"
enable-linger keeps the timer running while you are logged out. Check the last run with:
systemctl --user status bancwr-backup.service
With Docker, put the same two units in /etc/systemd/system/, and use systemctl without --user.
With cron
Or run it from cron, with crontab -e:
15 3 * * * $HOME/bancwr/bancwr-backup.sh
Test your backups
Now and then, restore one of these archives into a spare directory, to check you can. See Restoring the bunker.
A cold copy of ./data
bunker backup is the supported way. If you cannot use it, copy ./data with the bunker stopped. Apps cannot sign while it is stopped.
podman compose stop bunker
mkdir -p -m 700 backups
mkdir -m 700 "backups/$(date +%F)"
podman unshare cp -a data/. "backups/$(date +%F)/"
podman compose start bunker
With Docker, use docker compose, and sudo cp -a in place of podman unshare cp -a.
Never copy bancwr.db on its own from a running bunker. It runs in WAL mode, and recent changes are in bancwr.db-wal.
A cold copy is not encrypted, apart from the key file. Restoring it is copying it back, and that brings back every connection and token as it was, including any revoked since. After restoring a cold copy, revoke under Connections every app and token you had shut out.
Restoring the bunker
bunker restore reads an archive from standard input. Before it writes anything, it checks that:
- the backup passphrase decrypts the archive,
- the key file in it matches the archive's public key,
- the root credential decrypts that key, so the restored bunker will unlock,
- the archive was made under the same root credential, and not altered since,
- the database in it is sound, and not from a newer Bancwr,
- the data directory holds no database and no key file.
So a restore needs the same root credential that made the backup. If any check fails, it says why and writes nothing.
On a clean server
- Put
compose.yamland.envin place, as for a new installation. Put back the two secrets from where you kept them,secrets/bancwr_root_keyandsecrets/bancwr_backup_key. Give them, an empty./dataand./sessionsto user ID 65532, as Hand the files to the bunker's user shows. There is no plain key to import. - Restore:
podman compose run --rm --no-deps -T bunker restore < backups/bancwr-2026-11-13.bcwr
With Docker, usedocker compose. It prints the bunker'snpub, how many members are back, and how many connections and tokens it revoked. Check thenpubis the bunker's. - Start the bunker and check it:
podman compose up -d podman exec bancwr-bunker bunker healthcheck
Replacing a bunker's data
A restore never writes over existing data. To roll a bunker back, stop it and move its data aside first, then restore into a new, empty ./data.
With rootless Podman:
podman compose stop bunker
mv data data.before-restore
mkdir -m 700 data
podman unshare chown 65532:65532 data
With Docker:
docker compose stop bunker
mv data data.before-restore
mkdir -m 700 data
sudo chown 65532:65532 data
Then follow steps 2 and 3 above. Once you are sure the restore is good, delete data.before-restore.
What a restore keeps, and what it revokes
A restore revokes every connected app and every unused connection token before the bunker starts again. So an app or token you shut out after the backup cannot come back with it.
Kept, as they were at the backup:
- members and their roles,
- the identities and their grants,
- the signing log and the audit events. The restore adds one, saying what it revoked and when the backup was taken,
- the bunker relays and the log retention policy.
Revoked:
- every connected app. Each shows under Connections as ended with The bunker was restored from a backup, and needs a new connection token to connect again,
- every connection token not yet used.
Lost: anything since the backup, such as members added, roles changed and signatures made.
Sessions are not in the database, so a restore does not sign anyone out. Each signed-in member's role is read from the restored database on their next request.
Older archives
Archives are in format version 2. A version 1 archive, made before archives were authenticated under the root credential, is refused. Take a new backup.
A copy of ./data made by a build from before the key was kept out of the database may hold the nsec in plain text. Treat such a copy as a copy of the key, or delete it.