This page explains what klav-server keeps, how to back it up without corrupting the database, how to restore it, and what happens to deleted accounts in your backups.
What is in /data
klav.db,klav.db-walandklav.db-shm: the SQLite database, in WAL mode.attachments/<vault>/<attachment>: encrypted attachments (.partwhile they upload).
The database also holds the server’s OPAQUE setup, created on the first start. If it is lost, nobody can sign in again, although the encrypted data is still safe. Always back up the whole database.
What you back up is already encrypted end to end, but keep backups as carefully as the server: they hold email addresses and metadata.
Back up
The simplest consistent backup stops the server for a moment:
docker compose stop klav
docker run --rm -v klav_klav-data:/data:ro -v "$PWD":/backup debian:bookworm-slim \
tar czf /backup/klav-$(date +%F).tar.gz -C /data .
docker compose start klavThe volume’s name starts with the Compose project’s name, which is the folder’s name by default (klav_klav-data). Check it with docker volume ls.
Don’t copy the database files while the server runs: SQLite spreads changes between klav.db and klav.db-wal, and a copy taken halfway may not open. If you can’t stop it, use SQLite’s backup command, which is consistent while the server writes, from a machine with sqlite3 that sees the volume (the image doesn’t include it). Then copy the attachments separately:
sqlite3 /path/to/volume/klav.db ".backup '/backups/klav-$(date +%F).db'"
sqlite3 /backups/klav-$(date +%F).db 'PRAGMA integrity_check'okRestore
Stop the server, empty the volume, extract the backup into it, and start the server again.
If the backup came from sqlite3 .backup, put that file in the empty volume as klav.db and the attachments you copied as attachments/, and make both owned by UID 10001, the user the server runs as (chown -R 10001:10001 on them).
Every device remembers the newest state of each vault it saw. After you restore an older backup, a device refuses what the server sends as a rollback: its commands warn and keep using the device’s own copy, unchanged, and klav sync fails with exit code 3. That copy is how you keep the newer changes:
-
Pick the device that saw the most changes, usually the one you use most.
-
On it, note or copy what changed after the backup.
klav item lslists the items on the device,klav item ls --trashthe ones deleted, andklav item get <item> --revealshows one with its secret values; the apps show them too. A passkey saved after the backup can’t be added back by hand: sign in on that site and save a new one. -
On every other device, run:
klav sync --reset-cache klav log resetBoth ask you to confirm; in a script, add
--yes. The first forgets the device’s copy of your vaults and the marks that detect a rollback. The second does the same for the activity log, which keeps its own copy: until you run it,klav logandklav log verifyfail with exit code 3. Afterwards nothing can check the entries from before the reset: run it only for a backup you restored yourself.With
klavdrunning, as it is alongside the Mac app, both also cover the Mac app and the browser extension, which go through it. The iPhone app has no such command: in its Settings, use “Sign out on this iPhone”, which deletes its copy and its Secret Key, and sign in again with your email, master password and the Secret Key from your emergency kit (klav account kitshows it again on a computer that still has the account). If passkeys or generated passwords haven’t been uploaded yet, Klav says how many before it signs out; copy them first.A device you signed in after the backup is unknown to the restored server: its commands,
klav item lsincluded, fail with “the session expired or was revoked” (exit code 1), so don’t pick it in step 1. On it, runklav logout --yesand thenklav loginwith your emergency kit instead. -
Reset the device you picked last, once you have everything you need from it.
-
Add the changes again, from any device.
Upgrades
Database migrations run by themselves when the server starts. Take a backup before you upgrade: going back to an older version may need it.
Deleted accounts and backups
Anyone with an account can delete it from the iPhone app, the Mac app or with klav account delete; there is no setting to turn that off. The server deletes the account 7 days after the request, in its regular purge (retention.purge_interval_secs, every hour by default), with all its data and its vaults’ files. The email becomes free for a new account.
What stays:
-
Your backups keep the account until you delete them. If you restore one taken before a deletion, the account comes back. To delete it again, find the
account deletedlines in the log after the backup’s date (each has the account’s ID in itsaccountfield), and with the server stopped, delete each account:sqlite3 /path/to/volume/klav.db \ "PRAGMA foreign_keys = ON; \ DELETE FROM vault_members WHERE member_type = 'account' AND member_id = '<account_id>'; \ DELETE FROM accounts WHERE id = '<account_id>';"PRAGMA foreign_keys = ONmakes SQLite delete everything that belongs to the account; on Postgres that always happens. The server’s next purge removes those vaults’ files. -
The log keeps the
account deletedlines for as long as you keep it. They hold only the account’s ID.