Off-site & recovery¶
Off-site copies wait after a rebuild
When the Emergency wizard or Discover backups rebuilds entries without the old settings, off-site copies of those sections wait until you take their backups as this server's own. See After a rebuild.
Local backups protect you from a lost container or a bad update. Off-site copies and a tested recovery kit protect you from the whole box, ransomware, or a fire. This page covers storage locations and off-site copies, making a copy tamper-proof, proving you can restore, pairing several servers, and getting everything back when BombVault itself is gone.
Off-site copies¶
Keep the fast local backup and add one or more storage locations off the premises. BombVault copies new snapshots there with restic copy on a best-effort basis, so an off-site hiccup never fails the local backup. In this shape each section writes to its own folder first and the off-site repo is a copy. The own folder does not have to be on this server: see A section's own folder for keeping it in a storage location such as S3 or a rest-server.
- Several storage locations per section. Each section (containers, VMs, flash, self-backup, folders and ZFS datasets) can copy to several off-site storage locations at once, so you can keep, for example, a rest-server on a friend's box and an S3 bucket in parallel. The Storage locations per section card on the Storage locations page switches every line from a section to a location on or off.
- When copies run. A location's Copy card sets When to copy: After every backup, or on a plan of its own that collects the snapshots and copies at fixed times. Under Settings, Schedule, Off-site copies per section, Exception gives one section its own copy plan.
- The Off-site copies card. Under Settings, Storage locations every section with an off-site copy has a row in Off-site copies, with Test connection, Replicate now to start a copy on demand, and Set up or Edit. The rest of the section's copy settings open in its window from there.
- No off-site copies. If your backups should stay on the premises, switch this on at the end of the Off-site copies card. The overview then shows the missing copy in grey instead of red, so a failed or overdue backup still stands out. While it is on, the section rows, Off-site bandwidth, the Streaming card and the off-site plans under Settings, Schedule step aside, and switching it off brings them back. It counts only while no section copies off-site, and the switch goes away once one does.
- Retention is set per storage location under How long to keep, so you can keep off-site copies longer as an archive. The copy in a section's off-site field follows it like every other copy, and a section can keep its own values under Rules per section. All zero never trims off-site snapshots. See How long to keep.
- Bandwidth limits (Off-site bandwidth under Settings, Storage locations, or a location's Copy card) cap the restic upload/download rate so copies do not saturate your WAN. They are entered in KiB/s, the unit restic takes, and each field shows the same rate in MB/s and Mbit/s while you type: 2048 reads as about 2.0 MB/s (16.8 Mbit/s).
- Compression is Off, Automatic (restic's default) or Maximum, set on each storage location and, for one section, under its rules there. Backups, copies and prune write with it, and the recovery kit names it, so plain restic can keep writing the same way.
- Streaming first. While a media server such as Plex, Jellyfin or Emby streams, copies upload at a lower limit and return to the normal one a few minutes after the stream ends. The Streaming card on the Storage locations page has Slow off-site copies while streaming, Media servers (containers with Plex, Jellyfin or Emby in the image name until you choose), Stream above (Mbit/s), Upload limit while streaming (KiB/s) and Back to normal after (min). BombVault reads the traffic from Docker, so a media server on the host network cannot be measured. REST, S3, B2, Azure, Google Cloud, Swift and rclone over HTTP slow down in the middle of a copy. SFTP and local or mounted folders take the lower limit at their next copy step.
- Cold storage (S3). An S3 location can use a cheaper Storage class that restic can still read at once, such as Standard-IA, One Zone-IA, Intelligent-Tiering or Glacier Instant Retrieval. Glacier Flexible Retrieval and Deep Archive are left out, because restic cannot restore from them. An rclone remote sets its class in the rclone configuration.
- Simultaneous connections. On an S3, B2, Azure, Google Cloud, Swift, rest-server, SFTP or rclone location, Simultaneous connections on its Connection card sets how many connections restic opens at once, from 1 to 32. Left empty, restic keeps its default of 5. More can speed up a distant or slow line, fewer go easier on a provider that throttles. Backups, copies, checks, pruning and restores at the location all use it, and a settings export carries it. A local or mounted folder has no such setting.
- Growth budget. Growth budget (GB, 0 = off) in a section's copy window raises an alarm when the repository grows past that size. It never deletes anything, so it suits an append-only copy that nothing prunes from here.
- While a copy runs, the overview's status head says Off-site copy running. It is an active indicator, not a percentage bar, because
restic copyexposes no machine-readable progress.
Restore from any place
Every entry lists its backups as one timeline across all places a backup lies, on its Backups tab. A backup copied to B2 appears once, marked with each place that holds it. A restore takes the first place it can reach, starting with the repository the entry is written to, and you can pick another place per snapshot. Off-site storage locations are read only when you click Check, because listing cloud storage takes a while. Deleting at one place first checks the others and says whether it was the last copy. See Restore.
Storage locations¶
A storage location is a place backups go: a local folder, a share, a server of your own or a cloud service. It is set up once and then serves every section. Open Storage locations from its settings tile, or switch on Also show in the sidebar there to pin it.

Add storage location opens a window in four steps:
- Provider. Every service is listed with its logo, with a search at the top right of the window, in groups: Local for a disk or share attached to this server, NAS or server (rest-server, Hetzner Storage Box, SFTP, SMB, WebDAV and others), S3 service (Backblaze B2, Wasabi, Cloudflare R2, Hetzner Object Storage, Amazon S3 and others), your own S3 server (Garage, SeaweedFS, RustFS, Silo, Ceph, JuiceFS, Versity S3 Gateway), Cloud storage (OneDrive, Google Drive, Dropbox, pCloud, Nextcloud and the rest rclone supports) and From your group, the receiving servers of your group. Each one says how well it suits backups: cloud drives slow down under many requests, so the first backup and pruning take longer there. For a service no tile covers, the Rclone tile under Own rclone configuration takes remotes pasted from an rclone.conf.
- Sign in. The fields depend on the service: an access key for S3, a user and password for WebDAV and SMB, an app password where two-factor sign-in blocks the normal one, BombVault's public SSH key for SFTP and the Storage Box, or a token for services that sign in through a browser. For those, the window shows an
rclone authorizecommand to run on a computer with a browser, and the token it prints goes into the field. Where you already have a saved sign-in for the service, Saved sign-in picks it instead of New keys. Test connection checks the sign-in before anything is saved. The window then lists the folders on the storage location, with New folder to create one and the free space where the service reports it. An empty folder is safest. BombVault puts one folder per section in it. - Protection. The window says plainly what the service can do. A rest-server in append-only mode refuses deletion, and the tamper test checks that. An S3 bucket can keep old versions with versioning and object lock, which BombVault cannot check yet. A cloud drive cannot refuse deletion at all: whoever gets into the server gets into that copy too. Switch Delete protection (append-only) on only where the far side really refuses deletion. BombVault then never prunes there. For an emergency says what the recovery kit holds for this location.
- For which sections. Pick the sections that back up here. The first copy brings the whole history along. Entries that chose their own storage locations do not get the new one on their own, and the window names them.


Some services ask for a little more at the sign-in:
- SFTP and the Storage Box. Add key puts BombVault's public key on the server with the Account password, which is used for that one sign-in and kept nowhere. The command for doing it by hand is shown below it. The test shows the Server key with its fingerprint. BombVault remembers it and refuses the server if it later shows a different one.
- S3 keys for a single bucket, such as a Cloudflare R2 object token or a scoped AWS key, may not list the other buckets. Type the bucket into Bucket, and the test and the folder list open that bucket.
- S3 regions and addresses. The region is read from an endpoint that names it (AWS, Backblaze B2, Hetzner, Scaleway, OVH, Wasabi), Garage starts with its own default region, and IDrive e2 asks for the endpoint its dashboard shows. An address pasted with the bucket on it, the way the R2 dashboard shows it, fills in the server and the bucket. A bucket made from the folder browser goes into the region the form names.
- Storage class. The picker offers only the classes the service takes, and More settings shows only the options that shape a new bucket.
- Google Drive and OneDrive. Pruned data is deleted for good instead of going to the trash or recycle bin, where it would still count against the quota. A Google shared drive goes under More settings.
- SMB servers that do not list their shares take the name of one under Share, and the test opens that share directly.
- FTP asks for its Encryption: None, Explicit TLS (FTPES) or Implicit TLS (FTPS, port 990).
- OneDrive and Zoho WorkDrive. When a sign-in opens several drives or workspaces, the window asks which one the backups go to.
- A rest-server with a self-signed certificate. Put the certificate as a PEM file into the
certsfolder of BombVault's data folder (/config/certsin the container,appdata/bombvault/certson Unraid). Backups, copies and the delete protection test trust it without a restart.
S3 services run through restic's own S3 backend, which is what lets a storage class and object lock apply. A rest-server is reached by restic directly. Every other service runs through the rclone BombVault ships, and its section of the rclone configuration shows in the rclone.conf card on the location's page, with the secrets hidden. A settings export carries the storage locations, and with credentials included it carries their sign-ins as well.
Saving a storage location that already holds backups of containers, VMs or folders, for example one you removed and add again, adds it to those sections as an unticked copy. Nothing is copied there until you tick it, but Restore offers the old backups right away.
The folder on this server is called Local everywhere: on the storage pages, in the flow, on an entry and on Restore. With several folders on this server, each goes by its own name. A storage location that a section's off-site field sets up is named after its place, the last folder of its address or, without one, its server, and gets a number when another location already goes by that name. Every location can be renamed in the Name field of its Connection card, also a bucket folder that several sections share and the copy a section's off-site field describes, and a name you give it stays. Where two locations with the same name stand side by side, each carries its server or folder.
The page of a storage location¶
Every storage location has a page of its own. It shows only the cards that apply to that location, in this order:

- Own folders: the sections that write their backups here first. The sign-in, protection and limits of this location apply to them. Use as own folder moves the own folder of more sections here, and Change moves one away again. See A section's own folder.
- Backs up straight here: each section whose entries back up straight to this place instead of their own folder, and how many entries do. Such a direct repository takes all its settings from this location. One that nothing backs up to any more says so, and Remove takes it off the list. The backups at its place stay. See Direct repositories.
- Connection: the Name, the switch Available (off means BombVault no longer writes here, and entries that back up here fail with a clear message instead of landing somewhere else), the folder, Compression, Storage class, Simultaneous connections and Off the premises. On the Local location it lists the folder of each section under Own folders here. Change connection tests and saves a new address or sign-in. When other places sign in with the same saved sign-in, the window says so, and a change here gives this location a sign-in of its own instead of rewriting the shared one.
- Sign-in: which saved sign-in it uses (Signs in with), which other locations use it too (Also used by), and Edit, which opens the sign-in window. See Sign-ins.
- rclone.conf: this location's section of the rclone configuration, for a location that runs through rclone.
- Delete protection, with Delete protection (append-only), Accept without delete protection, Test delete protection now and Who prunes, which says whether BombVault prunes the copy and the own folders here, by this location's How long to keep card or a section's own values under Rules per section, or leaves that to the far side. A local folder shows this card only when it has a protection you can switch off. See Delete protection.
- Copy: When to copy, and the Upload limit (KiB/s) and Download limit (KiB/s). A location that holds only own folders and no copies shows the limits as a card called Bandwidth.
- How long to keep: Short, Balanced, Long or Custom values, with a timeline of which backups the rule keeps. See How long to keep.
- Already under this storage location: sections whose hand-typed address lies in a folder of this location. Taking one over leaves the repository where it is. Sign-in, storage class and delete protection then come from the location. BombVault first checks that the location's sign-in opens the repository, and it refuses to put an append-only repository under a location that is not append-only.
- Rules per section: one section's own repository, retention or compression at this location. Change rules opens them, and Reset to the storage location brings a section back. Sign-in, bandwidth and when copies run always come from the location.
- A vessel that shows how full the location is, with the mark where it is full and how many weeks are left at the growth of the last weeks. A location that does not report its size says Size unknown.
Move and Remove storage location stand among the page's actions, described under Moving and removing.
A remote storage location that held backups and suddenly holds no repository, such as a rest-server whose disk did not mount, does not get a new, empty one on its own. Its page says so as soon as a backup or copy finds the repository gone. Mount the disk again. If you emptied the old repository on purpose, Start a new repository here starts over, for every section of the location and its repositories at once. The guard is for a location that stayed in place. A storage location you add, or a section you tick at one, starts clean: with no repository at that address, the first copy creates one, even where a location removed earlier had one.
Two refusals name what to put right, on the copy's run and on the location's page. This bucket does not exist on the server comes as soon as an S3 server says so, and BombVault creates nothing there, so a bucket name typed wrong stays visible. A server that does not answer at all is a different case: restic keeps retrying for about 15 minutes per call, in case it comes back. There is already a restic repository here, and this instance's key does not open it means the backups there belong to another APP_KEY.
A receiving server that another instance of your group runs appears among the providers as From your group. See Receiving server.
BombVault checks its storage locations at every start. It puts right what needs no decision from you, such as a link to a copy or repository that is gone, a copy on a section's own folder, or a direct repository whose copy is gone, and writes a line in the log for each fix. What has no safe fix is only logged.

How long to keep¶
How long backups are kept is set per storage location, in its How long to keep card. The rule covers the copies at that location and the own folders that lie there, the Local location included. A section can keep its own values at one location under Rules per section, and those win over the location's card for that section.
A rule keeps one backup per day, week, month and year, as far back as you set, and clears out the rest after each backup or copy:
| Preset | Latest backups | Days | Weeks | Months | Years |
|---|---|---|---|---|---|
| Short | 0 | 7 | 4 | 3 | 0 |
| Balanced | 0 | 7 | 4 | 6 | 2 |
| Long | 0 | 14 | 8 | 12 | 3 |
Custom values sets the five counts yourself. A 0 switches that count off, and a rule with every count at 0 keeps everything. The dots in the card show which of 40 sample backups a rule keeps, the newest on the far right. The sample is the same for every location, since the picture is drawn before BombVault has read the backups there. It counts back from today, so how many dots stay changes with the date.
A folder on this host and a remote folder typed by hand have a card of their own too, which covers the own folders in that folder and no other. Until you save it, such a folder ages by the rule BombVault already had for it.
Ask before keeping less, on by default, asks before a change that keeps fewer backups is saved, and says how many of the 40 sample backups the new rule removes. It applies to every storage location. Reset to the storage location under Rules per section asks the same question.
A location with delete protection is never pruned from this box. Its far side keeps or drops old backups by its own rules. While an entry has an open critical anomaly about lost data, retention keeps that entry's old backups until you acknowledge it. See Anomalies.
A backup that holds less than it should never ages out the ones before it. That is a backup that reads no files where earlier ones held some, misses a selected folder, or could not read some files. Its run ends with a warning that names what is missing and says the older backups were kept, you get the same message on your notification channels, and no prune, at the entry's own folder or at its copies, touches that entry's old backups until a complete backup comes through. A first backup, and a selected folder that was always empty, count as complete.
To see what the next run would really delete, open Preview under Settings, Storage locations. It lists What the next run would remove for the section's own folder and for each of its copies, per repository and per entry with the restore points named. It takes no lock and changes nothing.

Example: what Balanced keeps¶
A container has been backed up every night at 03:00 since 1 October 2024, so on Wednesday 4 November 2026 it has had 765 backups. Its storage location is set to Balanced: 7 days, 4 weeks, 6 months and 2 years.
Each count keeps the newest backup of its day, week, month or year, and a backup that several counts pick is kept once. Weeks run from Monday to Sunday:
| Rule | Backups it picks | New ones it adds |
|---|---|---|
| 7 days | 4 Nov, 3 Nov, 2 Nov, 1 Nov, 31 Oct, 30 Oct, 29 Oct | all 7 |
| 4 weeks | 4 Nov, 1 Nov, 25 Oct, 18 Oct | 25 Oct, 18 Oct |
| 6 months | 4 Nov, 31 Oct, 30 Sep, 31 Aug, 31 Jul, 30 Jun | 30 Sep, 31 Aug, 31 Jul, 30 Jun |
| 2 years | 4 Nov, 31 Dec 2025 | 31 Dec 2025 |
That leaves 14 backups out of 765. The oldest is from 31 December 2025, so today you can go back a little over ten months. Thanks to deduplication they take little more room than one full backup plus what changed in between.
Years is worth a second look. It counts calendar years with a backup in them, starting with the current one, and the newest backup of this year is today's. So the first year adds nothing to the other counts, and the second adds the last backup of the previous year. That is why the reach of a rule varies through the year. The same backups under each preset:
| Preset | Backups kept today | Oldest backup today | Reach through the year |
|---|---|---|---|
| Short | 10 | 30 September 2026 | 1 to 2 months |
| Balanced | 14 | 31 December 2025 | about 4 months in early spring, a full year on 31 December |
| Long | 30 | 31 December 2024 | 1 year on 1 January, 2 years on 31 December |
Going from Balanced to Short asks first, because of Ask before keeping less. The question says how many of the 40 backups in the picture the new rule removes. That number comes from the sample, so it changes with the date and does not count your own backups. Of the backups in this example, 31 August, 31 July, 30 June and 31 December 2025 would go. Save anyway applies the rule, and the next prune deletes them from that location for good.
To keep the containers longer than the rest at this location, press Change rules under Rules per section, pick Containers, and set Custom values in Rules for Containers, for example 14 days, 8 weeks, 12 months and 2 years. The other sections keep following the location's card, and Reset to the storage location brings Containers back.
Sign-ins¶
A sign-in is the key or password BombVault uses for an S3 service or a rest-server. Sign-ins are one list, the Sign-ins card under Settings, Storage locations, and each row says which storage locations use it (Used by).
- Saved when you add a location. Add storage location saves the keys you type as a sign-in. The next location at the same service can pick it under Saved sign-in instead of New keys, and a change to it later applies to every location that uses it.
- The default. A star marks the default sign-in. It is used wherever no sign-in is picked, such as an address typed in by hand or a recovery on a fresh install. A pull source does not borrow it. Make default gives the star to another one.
- Edit and Test. Edit, here or in the Sign-in card of a location, opens one window for the sign-in. Test signs in to every location that uses it with what you typed, before anything is saved. Save stores it.
- Removing. A sign-in can be removed only when no storage location, pull source or received repository uses it and no old backups need it, and the default goes only as the last one. Old backups need it when an own folder moved away from a place that signs in with it and left them there. BombVault then says which place it is.
- Changing a location's connection never rewrites a sign-in other places share. The location gets a sign-in of its own instead, and the window says beforehand that its sign-in is shared. To change the shared one everywhere, edit it in the Sign-ins card.

A folder on this server needs no sign-in. SMB, WebDAV, SFTP, the Storage Box and the cloud drives keep theirs in the rclone configuration, which the location's rclone.conf card shows, so they do not show up in this list.
SMB, WebDAV and other rclone remotes¶
A Windows or Samba share and a WebDAV server (Nextcloud, ownCloud, SharePoint or any other) are provider tiles in Add storage location, under NAS or server. Fill in the host and share (SMB) or the address and server type (WebDAV), the user and the password, and BombVault writes the rclone section for you. rclone obscures the password before it is stored.
For a service no tile covers, the Rclone tile under Own rclone configuration takes remotes pasted from an rclone.conf. They are added to the remotes BombVault already has and never replace them, and they are stored encrypted. To back up a section to one of them, enter rclone:<remote>:<folder> as that section's off-site repository, for example rclone:nas:backups/bombvault. The share or bucket is the first path segment, not part of the name.
This is the better route than mounting the share on Unraid: restic advises against keeping a repository on a mounted CIFS share, and here nothing is mounted. NFS has no tile because neither restic nor rclone has an NFS backend. For NFS, mount the export on the host and use it as a local folder.
Moving and removing¶
- Move takes the copy of one section to another storage location, with its whole history. Everything stays in the old place. BombVault deletes nothing there. The move runs in the background and can take long: about 9 minutes per 100 GB between local disks, hours over a slow link. The overview shows it while it runs.
- Remove storage location offers two ways. Remove storage location, keep the backups stops writing there and leaves the backups in place. You can read them later under Restore, From an old backup folder. Remove storage location and delete the backups there first reads what is stored there and lists it: which backups go, which of them are nowhere else, and which repositories stay because delete protection refuses, entries still back up straight to them, another location or section keeps its copies there, or they could not be read. Entries that would lose their only backup are listed separately and are kept unless you switch on Delete these as well. You confirm by typing the location's name, and the deletion runs in the background.
- This works for every kind of storage location: one that several sections use, a target set up for one section, a repository you set up, and the folder a section writes its own backups to. Entries that back up to a removed repository follow their section again, and so does a section default that pointed there. A section's folder cannot just go, because every section needs one. The window asks for the folder the sections move to, and each section keeps its folder name under it.
- Deleting the backups at a storage location works without a login password too. With one set, it needs a sign-in at the instance itself.
Example: an off-site copy on Backblaze B2¶
The containers and the self-backup should also live at Backblaze B2, so a dead server does not take them along. The same steps fit Wasabi, Hetzner Object Storage and most other S3 services.
- In B2, create a private bucket, such as
tower-backups, in a region near you. Under Application Keys, create a key with read and write access, limited to that bucket, and note its key ID and application key. B2 shows the application key once. Set the bucket's lifecycle to keep only the last version, or B2 keeps pruned data as hidden versions and bills you for them. - Provider. In BombVault, open Storage locations, press Add storage location and pick Backblaze B2 under S3 service.
- Sign in. Enter the key ID as Access key ID and the application key as Secret access key. Enter the bucket's endpoint under Endpoint, such as
s3.eu-central-003.backblazeb2.com, and BombVault reads the region from it. Typetower-backupsinto Bucket, because this key opens only one bucket. - Test connection. It should say Connection established and list the bucket's folders. Press New folder and name it
bombvault. BombVault puts one folder per section in it, such asbombvault/containers. - Protection. The window explains that B2 can keep old versions with object lock and that BombVault cannot check this. Leave Delete protection (append-only) off unless the bucket really refuses deletes, so BombVault can prune by the location's keep rules.
- For which sections. Tick Containers and Self-backup. The self-backup carries your settings, so a new install can bring them back. The window says how many entries and, where known, how much history the first copy brings along.
- Press Save storage location.
The first copy runs after the next backup. To start it now, open Settings, Storage locations and press Replicate now in the section's row of Off-site copies. The status head says Off-site copy running. The first copy brings the whole history, so 200 GB over a 100 Mbit/s uplink takes about four and a half hours. Later copies send only what is new.
To keep your line free, open the location's page and set Upload limit (KiB/s) in the Copy card, for example to 5120, which reads as about 5.0 MB/s (41.9 Mbit/s). Check How long to keep on the same page while you are there.
To see that it worked, look at Protection status on the overview, where Off-site turns to copy up to date, and at a container's Backups tab, where its snapshots now name tower-backups as a second place. Then press Download recovery kit again under Settings, Restore, because the kit lists the new location and its sign-in.
Cloudflare R2 works the same way, with an object token instead of a key. Paste the S3 address the R2 dashboard shows, with the bucket on it, and BombVault fills in the server and the bucket.
Example: a rest-server you run yourself¶
A rest-server in append-only mode refuses deletes, so a copy on it survives even if someone takes over your server. A second box, at a friend's place or in the garage, is enough. A paired BombVault can set this up for you, see Receiving server. To run it by hand on any Docker host:
docker run -d --name rest-server --restart unless-stopped \
-p 8000:8000 \
-v /mnt/user/backups/rest-server:/data \
-e OPTIONS="--append-only --private-repos" \
restic/rest-server
docker exec -it rest-server create_user bombvault
The last line asks for a password and writes the user to the .htpasswd file in the data folder.
- In BombVault, press Add storage location and pick rest-server under NAS or server.
- Enter the address with the user as its folder, such as
http://192.168.2.20:8000/bombvault, and the User name and Password. Press Test connection. - In Protection, switch on Delete protection (append-only). BombVault then never prunes there and leaves that to the far side.
- Tick the sections and press Save storage location.
- Once the first copy is there, open the location's page and press Test delete protection now. BombVault tries to delete a test object. The card should say Last: delete refused, and Delete protection on the overview turns to checked. If it says Last: delete not refused,
--append-onlyis missing.
Since nothing prunes this copy from here, set Growth budget (GB, 0 = off) in the section's window, opened with Edit in its row of Off-site copies, so you hear about it before the disk fills up. With a self-signed certificate, see the note on certs above.
A section's own folder¶
Every section has an own folder: the repository its backups are written to first. Copies to other storage locations go out from there. A new install keeps the own folders on this server, below /mnt/user/bombvault, and together they form the Local storage location.
An own folder can also lie in a storage location you already have, such as a NAS, a rest-server or an S3 bucket. The section then backs up there directly, with no local copy in between, and the own folder follows that location's sign-in, delete protection and bandwidth limits. BombVault prunes it after each backup by the location's How long to keep card, and a section's own values under Rules per section win over the card. The location lists the section in its Own folders card, and Storage locations per section shows the location as the section's home.
Moving an own folder¶
- Open the storage location that should hold the own folder and choose Use as own folder, or Add sections in its Own folders card. To move several sections at once, choose Move own folders beside Own folders here in the Connection card of the Local location.
- Pick the sections under Sections and the place under Move to. Another place takes a folder on this host or the address of a remote repository typed by hand, with a sign-in from your saved sign-ins.
- Read What happens. For each section it says where new backups go, whether a copy that is already at the new place becomes the own folder, and which backups are copied over first.
- Copy the backups already made is on by default. Switched off, the old backups stay where they are, but the entry no longer lists them. From an old backup folder on the Restore page still reads them with the folder's address and, for a remote folder, its login.
- Choose Switch. When the new place's How long to keep card keeps less than the section's rule today, BombVault first asks Keep less? There, Keep the current values for that section under Rules per section carries today's values along, Save anyway goes ahead, and Back leaves everything as it was. When backups have to be copied first, BombVault copies them and then switches the own folder. When they are there already, it checks them before the switch.
After the move, new backups go to the moved own folder, also for a section that had Local switched off and backed up straight to a copy. A copy that already sat at the new place becomes the own folder, and copying there ends. Where that copy kept some backups longer than the section's keep rules, the section keeps whatever either rule keeps, so none of them is lost.
When the move cannot go ahead, the window says why in a box under What happens. When only copying the old backups is in the way, switching off Copy the backups already made lets the own folder move without them.
A section always needs an own folder. Removing the storage location that holds it asks for the folder the section moves to, see Moving and removing. An own folder that new backups go past, because the section backs up straight to a copy, is marked (off) where a location lists who uses it.

Example: Containers move to a NAS¶
The cache pool is filling up, and you have a storage location called nas, an SMB share on a second box. The Containers section has 61 backups in its own folder on this server and copies to Backblaze B2.
- Open Storage locations, then
nas, and press Use as own folder. - Tick Containers under Sections.
- Read What happens. It says that new backups of Containers go to the folder on
nas, that the 61 backups in Local are copied there first, that copies keep going to Backblaze B2, and that protection, bandwidth limits and the growth alarm come fromnas. - Leave Copy the backups already made on and press Switch.
BombVault copies the backups in the background and then switches the own folder. The nas page lists Containers under Own folders, an entry that follows its section names nas as its home, and the next backup lands there, with the copy to B2 going out from nas. From now on the How long to keep card of nas prunes the folder. The old folder on this server stays where it is, and BombVault deletes nothing there.
Typing a remote address by hand¶
The Connection card of the Local location still takes a remote address for a section's own folder: Change beside the section opens a window with a Local / Remote switch. Remote takes a restic address such as s3:..., rest:http://host:8000/repo, sftp:user@host:/repo or rclone:remote:bucket/path, and Remote primary safety settings add a connection test, upload and download limits, append-only protection with the same tamper test an off-site location gets, and a growth-budget alarm.
Such an address signs in with the default sign-in. When it is exactly the folder a storage location you have keeps for the section, it follows that location by itself, the location's card and its Available switch included, unless it signs in differently or is append-only where the location is not. A rule that pruned the folder until then stays as the section's own under Rules per section. When it lies in another folder of that location, the location's page lists the section under Already under this storage location, and taking it over gives it the location's sign-in, storage class and delete protection. Moving the own folder into a storage location with Use as own folder is the simpler way, because the window checks the backups already made before anything changes.
Placement per entry¶
The Schedule and storage location card on an entry's Settings tab has a row of buttons: Local and one button per off-site storage location of the section. Lit buttons get the entry's backups.
- With Local lit, the entry is written to the repository shown under Stored on and copied to every other lit location. Darken a location and it gets nothing new from this entry. Local alone copies nowhere, which suits data that already has a second copy, for example a share that lives on a NAS.
- With Local dark, the entry is written straight to the direct repository of the first lit location and copied from there to the other lit ones. The first time, a dialog creates that direct repository.
- One button stays lit, because a backup needs a place to go. To leave an entry out of backups, use Don't back up.
BombVault never moves backups between repositories. An entry that follows its section goes along when the section's default changes: its next backup lands in the new place, and the backups it has stay where they are. A location chosen on the entry itself stays fixed from its first backup on. The Repository card on the Settings tab names it. The copies can change at any time. A location that no longer gets an entry keeps the copies it has and trims them to its own retention at the next off-site run of the section. Append-only locations cannot be deleted from.
The place an entry left keeps its backups. On the entry's Backups tab and on Restore it stands as Earlier backups only, a restore can still read from it, and a prune there leaves those backups alone.
Follow the default brings an entry with a choice of its own back to its section. It asks first, says where new backups go then, and names what each location stops getting and what the next run would upload.
Under the row the card says where the entry goes and what is actually there: how many sites hold it, when each location was last seen, and whether 3-2-1 is met. A site is the server with the original data, each off-site location and each repository marked Off the premises. BombVault checks copies and sites. It does not check the "two media" part of 3-2-1.
Defaults per section¶
The Storage locations per section card on the Storage locations page draws the default of every section as a 3-2-1 flow. Every line from a section to a storage location is a switch, Local included, for every section, the flash drive, ZFS datasets and the self-backup as well. A click on a line or a dot switches it at once, and dashed lines are off. Only switching a section's Local off asks first, in the same dialog as the default card, because the section then backs up straight to a copy. Cancel leaves everything as it was. Graph / Switches shows the same as rows of buttons. A switch decides where new backups go. Entries without a choice of their own, and the project folders of Compose stacks, follow at once, so their next backup goes to the new places. Backups already stored stay where they are and can still be restored from there. Flash, ZFS datasets and the self-backup back up to their local folder and copy off-site from that backup. Their line to Local can be switched off too. Their backups then go straight to their off-site locations, and a ZFS entry with a replica and no location at all only sends its replica.
With Local off and only off-site locations on, a section backs up straight to them, and BombVault picks the repository there itself. Containers, VMs and folder sets go to the direct repository of the first location that is on, described below, and are copied from there to the others. The flash drive, ZFS datasets and the self-backup write each backup to every location that is on, and each location keeps them by its own retention.
A section with every line off says Not backed up. Its entries get no backups and count as not protected.
Entries that chose their own storage locations on their page keep them. The flow says how many there are in a section, for example 2 entries differ, and leads to them: to the entry's Settings tab when there is one, to a list with where each backs up when there are several. Follow the default there brings an entry back.
A new off-site location receives every entry that is not set to Local. The window that adds it says how many entries and, where known, how much history that is.
Direct repositories¶
A direct repository is where entries back up straight to an off-site location. BombVault puts it beside the location's folder with -direct added to the name, or, when the location sits at the root of its bucket, its remote or a rest-server user, in a folder inside it named after the section, such as containers-direct. In the flow on the Storage locations page it is created without a question. Turning Local off for a single entry, so that a location without a direct repository becomes its home, opens a dialog with the suggested location, for example s3:https://s3.eu-central-003.backblazeb2.com/bucket/containers-direct, and a connection test that creates nothing. Create and use creates the repository and points the entry at it. A direct repository has no settings of its own. It follows its location's switch, sign-in, storage class, limits, append-only setting and retention, and changes with them. The location's page lists it under Backs up straight here, with each section that backs up straight to it and how many entries do. One that nothing backs up to any more says so there and can be removed, and the backups at its place stay. When a new key for the location cannot open it, the direct repository keeps the key it has and the save says so. An entry on a direct repository is copied from there to the other lit locations, never to the location the repository belongs to. Its snapshots carry the tag bv:direct, and every other retention pass keeps them, so a direct repository that lost its link to its location never ages by the local rules. B2 is reached through its S3 endpoint, with the key ID and application key entered as the S3 keys. A key limited to the location's own folder cannot reach the folder next to it, so limit the key to the folder above instead.
Off the premises¶
A storage location or a repository can be marked Off the premises. Remote ones start marked. Switch it off for a rest-server in the same building. The mark only counts sites and 3-2-1 on the cards. It changes no copy.
A ZFS replica is a copy off the premises, but not a backup with history. It keeps only the snapshots you set, and old versions and single files still come from the backups. It goes from one ZFS server straight to the other, over SSH to a ZFS server or to the receive endpoint of a paired instance. The pairing group only carries the request. See Replica.
After a rebuild¶
Copy choices live in BombVault's own settings. After a rebuild through Discover backups or the Emergency wizard without restored settings they are gone, and copying everything would send the entries you had left out to B2 again. The same holds when a section that never copied off site from this database finds backups of its own at a storage location, or older ones in its own folder, for example after a location was added over the backups of an earlier install with the same APP_KEY. Off-site copies of that section then wait for your decision.
Needs you on the overview and the page of each storage location the section copies to ask whether the backups are this server's own. Take them as this server's own confirms the section's default, and its copies run again from the next pass. Check the rules first leads to the section's line in Storage locations per section, where you see where each entry goes and can set a lost rule again on the entry's page. Copying keeps waiting there until you press Take them as this server's own, which first shows what the next run copies and the names in the backups that have no entry, which you can leave out. The newest backup of each entry that waits says so in its run, with a link to the decision, and a notification goes out when those are on. Importing a settings file brings back rules and defaults but does not take the decision for you.

Delete protection (append-only)¶
Switch on delete protection for an off-site storage location so ransomware, or a compromised host, cannot delete or rewrite your backups. The far side (a restic/rest-server running in --append-only mode) enforces it. BombVault only ever verifies it and never shows green on a configuration claim alone. A folder on this server cannot refuse deletion, because whoever controls BombVault controls the folder too, so local locations do not offer the switch.
The switch belongs to the storage location: a section that copies there takes it from the location, so turn it on from the location's page under Storage locations. The scheduled Check delete protection runs only while a section copies to a location with the switch on. The far side has to be started with --append-only. With the restic/rest-server image, on TrueNAS as on any other Docker host, that goes into the OPTIONS variable.
Some places cannot refuse a delete at all, a cloud drive such as OneDrive for example. If you keep copies there on purpose, switch on Accept without delete protection on the location's page. The overview then shows the missing delete protection of a section that copies only to accepted locations as an accepted risk, a grey ring instead of an amber dot, and the section's colour follows its other checks. Nothing else changes: the backups there can still be deleted, BombVault still prunes them by the location's keep rules, and the switch goes away once delete protection is on. A copy that moves to another place loses the acceptance. Switching delete protection on clears it as well.
The fastest way to an append-only copy is a paired BombVault with a receiving server: it runs the rest-server for you, in append-only mode.
In a shared repository this holds for the members and not for the server that holds it. That server reaches the folder directly and forgets and prunes there.
A successful delete under /locks/ is expected
Append-only does not mean nothing can ever be removed. restic has to take and release its own locks, so /locks/ stays writable and deletable by design. Snapshots and the data behind them, which is what ransomware would go after, cannot be removed. If you probe the far side yourself, a delete that succeeds under /locks/ is correct behaviour and not a hole in the protection.
Append-only repos are never pruned from this box
An append-only location never prunes old snapshots from here. Pruning is the far side's job. Set a growth-budget alarm for it so you are alerted before the repo size runs away.
Tamper test¶
BombVault periodically proves the append-only guarantee by actually attempting a delete against the off-site repo, aimed at a non-existent object. Test delete protection now on a location's page runs it on demand, and Check delete protection under Settings, Verify, Automatic checks runs it on a schedule.
Switching Check delete protection off does not hide a gap. A location with delete protection that was never tested then reads "not proven, its check is off", and a location without delete protection reads "none" either way.
A copy that is switched off is not tested, and the location says so. The connection test still runs on it, because it only reads, so a copy can be checked before it is switched on.
- Refused means protected.
- Accepted means not protected.
- An inconclusive result (server unreachable, auth error) never flips the stored verdict.
A real protected-to-unprotected flip fires a single alert.
DR drills¶
BombVault offers two levels of proof that your backups are actually restorable, not just present.
- Restore-verification drills (local). BombVault periodically runs
restic check --read-data-subset(bounded, never a disk-filling full restore). The cadence lives under Settings, Verify, Automatic checks, and the Check backups card on the same tile shows the result. - Trial restore (off-site). BombVault restores a real target from the off-site repo into a sealed-off sandbox, verifies it file-for-file and byte-for-byte, then cleans up. This proves you can recover from off-site, not just that the repo answers.
The Protection status card on the overview rolls this up per section into four checks: a current backup on this server, a copy off-site, delete protection there and a trial restore from there. A click on a section shows the details, and the card only goes green on verified facts. A location you accepted without delete protection counts there as an accepted risk, not as a warning.
Pairing instances¶
Several BombVaults work together as one group: they show each other's protection status, take on roles for each other and can keep each other's key. An instance joins the group with twelve words.

On the first instance open Settings, Pairing and press Generate phrase. Three step cards show how it goes. Twelve words appear in a window with a Copy button. On every other instance open the same place, press Enter phrase and paste or type them, or press Paste in that window. A word that is not on the list is named with its position as you type, and the last word carries a checksum, so a mistyped or swapped word is caught before anything pairs. Generate the phrase on one instance only: two instances that both generate one form two separate groups. If nobody shows up for a minute, the card says to enter the words over there, which Show phrase brings back, and offers to enter the other instance's words instead. Pairing works without a login password, but set one: without it anyone who can open the web interface can read the words and, through the group, ask for roles that hand out the restic password of the instances in it. The pairing card says so until a password is set. With a password, showing the phrase again asks for it. Leave takes an instance out of the group and the fortress together. Below the card of the phrase the members stand as the cards of the Instances page, and a line says that the instance waits for one with this phrase while nobody has come yet. The picture of who does what for whom is on the Instances page.
The words alone do not let anybody in. A new instance or phone waits in the Waiting for approval card until you press Approve on an instance already in the group, and your decision reaches every instance in reach. Compare the key shown beside it with the one the new instance shows on its own pairing page. Refuse turns it away for good. When two new instances pair, each lists the other as waiting, so approve it on both. Members that were paired before all this stay approved. Still treat the words like a password: whoever has them can ask to join.
How members reach each other. Each instance learns its own address on the network from your browser the moment you sign in. On the same network members announce that address by multicast and talk directly, and where multicast cannot cross a container network, such as Docker's default bridge, an instance instead searches its own subnet for the others with a signed call only a group member can answer, so pairing still finishes in seconds without a relay. Pairing always goes by the twelve words, and there is no field for an address. Instances on different networks go through a relay, picked in one row of four in the Relay card on the same page. Each form comes with a picture:
- Project relay (the default):
parleyport.halleluja.design, the relay KnightLoader uses as well. Nothing to set up. - Own relay: the ParleyPort container from the Unraid Community Apps (also under Settings, Apps). Enter its address on every instance that should use it.
- BombVault instance: one of your instances that is already reachable from outside, with Serve as relay switched on. That instance then answers at
/relay/connecton its own address, behind the reverse proxy and certificate it already has, and lets in your group only. Enter its address on every instance that should use it. - No relay: members find each other automatically on the same network, and nowhere else.
What the relay sees. A button of the same name beside the four forms shows this for the form you picked. Every call between members is sealed with AES-256-GCM under a key derived from the twelve words, and that key never leaves your instances. The relay learns a hash that groups the connections, which instance a message is for, how big it is and when it passes. A direct call on the local network is sealed the same way and signed as well, so nothing depends on the self-signed certificate an instance serves. Calls that hand something out (role answers, a restic password, receiver logins, key deposits) are also signed with a key of the member that sends them, pinned on first sight. See Security model.
What travels over the group. The protection status on the Instances page, a request to check one section now, role requests and their answers, storage offers, and what a receiver or fetcher needs once its role is allowed: the other instance's repository locations and its restic password. Backup data never does. It still goes straight to the restic backends. Nor does the APP_KEY: the restic password opens that instance's repositories and nothing else, not its stored secrets, sessions or recovery codes.
Entries from before pairing. Instances added with a fleet token, and received repositories and pull sources set up with the other instance's APP_KEY, stay after the update and are marked Pair again. They keep working: at its first start BombVault replaces each stored APP_KEY with the restic password derived from it. Pair both instances, then edit the entry and choose its instance. Until then such entries stand in the Without an instance card on the Instances page.
The one place that still takes an APP_KEY by hand is From an old backup folder, for the case where the other instance is gone and cannot answer in a group.
The fortress¶
A fortress brings BombVault together with the other apps of the family, such as ShipLog, TowerTorch, FireSquire and TollRoll, under one phrase of twelve words. It is the phrase on the Pairing page: the words that pair your instances and phones bring the other apps in as well. Enter BombVault's words in the other app, or enter the words another app shows with Enter phrase on a BombVault that is in no group yet. When the phrase changes, the instances and phones BombVault is paired with come along without a new pairing, and one that was away follows once it is back. The old phrase stays open until every device has followed, for 30 days at most. A device still missing after that is named on the Pairing page and in the app, so you can enter the phrase on it or remove it.
- Instance name: the one name this instance goes by at its other instances, on its phones and at the other apps. Left empty, it is the Unraid server's name.
- The other apps: with Show the other apps of the fortress switched on, they stand below the members in the same cards, each with its logo where the app publishes one.
- Permissions: everything one app may do at another has its own switch, such as seeing when the last backup worked, asking for a container backup or looking through the backups. They all start switched on.
- Show phrase shows the words beside a QR code once you enter your password. Change gives the fortress a new phrase, which reaches every app and instance in reach. The old phrase keeps working for 30 days, and the Pairing page names any device the change missed. Leave takes BombVault out of the fortress and out of its group.
What the other apps do. ShipLog asks for a backup of a container before it updates it, and BombVault leaves the update of ShipLog's own containers to it, so their Update after a successful backup switch stays off. TowerTorch asks for a backup before a maintenance run, and FireSquire checks when the flash was last backed up. A request waits while another backup runs. TollRoll shows BombVault in its tile on the Unraid Dashboard. The other apps read BombVault's state at GET /api/fortress/v1/status and GET /api/fortress/v1/log, which an API token or a signed-in browser can read as well.
An app's own backup. Before BombVault backs up the container of an app that can back itself up, it fetches that app's own backup and keeps it in the container's repository, but only when that repository is encrypted. It shows in the container's list of backups with the app's name and a download, ages with the container's backups, goes off-site with them and is deleted with them. With Give backups back to apps switched on, Give back to hands it to the app again, which replaces what the app holds now. That switch is off until you turn it on.
Instances and roles¶
The Instances page (a settings tile that can be pinned to the sidebar) shows the group as a net of who does what for whom, a card for this instance and a card for every other member, the Android phones, the ZFS servers and this instance's nodes. Pairing at the bottom right leads to the pairing page, and Add node beside it adds a node. Which parts are on is set under Settings, Instances, Multiple servers: Instances, Receiver and Pull.

Each card shows the member's protection status and its roles as tiles. A role is something one instance does for another:
- Receiver keeps this server's off-site copies in a rest-server in append-only mode. This server sends after every backup and cannot delete anything there, even if someone takes it over.
- Fetcher fetches this server's backups on its own schedule. This server does not have to be awake for it. The instance that fetches needs Pull switched on before it can allow the request.
- ZFS server takes this server's ZFS replicas. Each ZFS entry picks it under Replica in its settings.
- Key keeper keeps a sealed copy of this server's recovery kit. See Key keeper.
Switching a role on sends a request, and nothing starts until someone on the other instance presses Allow. The request shows on that instance's card as a badge, and its Details list it with Allow and Decline. An allowed role can be revoked there at any time. A dashed line in the net is a role still waiting. An instance on BombVault 9.x cannot answer a request, so a role is active there as soon as you switch it on, and a request from a 9.x instance waits for Allow here.
Details on a card opens the rest: the received repositories and pull sources of that member, storage offers, monitoring, Remove and Forget key.
Below the cards, the Shared repository card on a box with a receiving server and the Shared repositories card on a member belong to the shared repository.
A member can offer its own off-site storage to another member over the group. The other admin sees the offer in the member's Details and accepts or declines it. Accepting creates a saved sign-in and an ordinary storage location, after the same checks as a location you type in. The location comes with delete protection switched on, since the recipe the offer shows is an append-only rest-server, so How long to keep does not apply there. Every offer has a login and a folder of its own, so offering a section again, to the same member or another one, leaves the first partner's copies alone: add the new line to .htpasswd and keep the server running. Only connection details travel this way, never backup data. Check now asks a member to verify one section's repository. Members leave each other's backups alone: nothing on the page starts a backup on another member, restores there or deletes anything there.
Nodes are different, since they are not members. A node is a BombVault without a web interface that takes its orders from this instance, so this instance starts its backups and restores on it and tidies up its old backups. Each node has a card with its state, its version, where its backups go and when each section backs up, with Edit placement, Replace and Release. A new node says Waiting for the node until it first answers, and a released one that is away says Being released. See Nodes.

Instances that are shut down and phones with the app closed keep their card as Inactive, in grey, with when they were last seen, and stand dimmed in the net until you Remove them. Right after this server starts, such a card says Checking until the group is back. Remove works on such a card whichever parts are switched on, and it also ends the member's open requests, its idle ZFS receive slots and its waiting key requests. The Instances card on the pairing page lists these members as Inactive too.
Receiver and fetcher¶
On the box that receives append-only copies from another BombVault, the received repositories give you independent, read-only monitoring on the receiving hardware, so a silent failure at the far end does not go unnoticed. Switch on Receiver under Settings, Instances, then open the sending instance's Details on the Instances page and add the received repository (read-only, opened with the sending instance's restic password, which it gets over the pairing group). You get:
- An inventory by source, so you can see exactly which containers, VMs and folder sets have landed. Backups the sender made before it had a host of its own count towards the same source.
- Last received per source, so you know how fresh each one is.
- An independent
restic checkrun on the receiving hardware, so integrity is verified where the data actually sits, not only on the sender. - A dead-man's switch: an alert when a source stops sending within a window you set. It looks once a day, at 09:15. You get one alert as well when the repository cannot be read at all, whatever the check schedule says, and when nothing has arrived a full window after you added it. A repository you add before the sender's first copy is fine until then.
- Integrity alerts: an alert when a check on the receiving side fails. A check that could not open the repository says nothing about integrity, so it leaves no verdict and tries again the next day at the same time.
A repository on another server needs that server's login: save it as a sign-in and pick it under Credentials in the dialog.
The receiver is strictly read-only. It never writes to the received repository, so it can never break the append-only guarantee the sender relies on.
A fetcher works the other way round: with Pull switched on, an instance reads another member's backups on its own schedule, into a repository of its own for each source, so they never count as this box's own backups. Its sources stand in that member's details as well: the repository location, which kind of backup it holds and how often to fetch. The restic password comes over the group, never the APP_KEY, and the far side has nothing more to set up and does not have to be running. The source is only ever read, and each side keeps its own sign-in. A pull runs at the day and time its schedule says, and a new source waits for that time too; Pull now does not wait. A pull missed because this box was off runs once it is back. One that failed tries again the next day at the same time, also on a weekly schedule, and a failed pull shows in the activity log and sends one alert until a pull works again. An rclone: source is refused, because rclone would reach it with this instance's remotes.
A fetched copy only grows. BombVault adds to it and neither prunes it nor checks it, so what the source has long forgotten stays here until you delete the folder, and the Storage locations page does not count it. It lies in pulled/<source id> inside the section's own folder, and when that folder moves, the copy stays where it is and later fetches go on there instead of copying everything again. If you delete it, the next fetch starts over in the own folder the section has by then.
Receiving server¶
The receiving box can also run the rest-server the others copy to. It is set up the first time you allow a Receiver request that asks for it: the window says the server needs a receiving server and asks for a folder on a share, with New folder to create one, and a port (8000 unless another container uses it). BombVault then:
- refuses if a container called
rest-serveralready exists or another container holds the port, - pulls
restic/rest-serverand starts it through the Docker socket in append-only mode with private repositories and a login file in the folder, - writes its Unraid template to the flash drive, so the container stays editable in the Docker tab, or offers the template as a download when the flash drive is out of reach,
- runs the tamper test against it and shows whether it refuses deletes.
The instances in your group then find the server among the providers under From your group, named after the receiving box, and the Receiver role offers it as the safe choice. Each instance gets a login of its own the first time it uses the server, and writes only into its own folder there. With Receiver switched on under Settings, Instances, Receiving server on this instance's card opens the server again. Its window lists the logins under Partners with a login, and Revoke login takes one away. What that instance already copied stays in the folder. Setup also creates one Login outside the group, whose password the window shows once.
An instance that reaches the receiving box only through the relay cannot use the server, because the relay carries no backups. Add the receiving box's address on the pairing page first. When BombVault runs on an IP address of its own (on br0, for example), fill in Address for partners, because the server listens on the host's address.
A receiving box can also hold a shared repository for the group, and take the backups of this instance's nodes at its Address for nodes.
Shared repository¶
Several servers of a group can copy into one restic repository together. Data they have in common, such as the same folder set or the same appdata, is stored there only once, so together they need less room than with a repository each.
One server of the group holds the repository. It is the only one that forgets old backups and prunes there. The others are members: they reach the repository through a second rest-server in append-only mode and can only add to it. Each server writes under a host of its own, so the backups stay apart even where two servers have an entry of the same name.
What it needs:
- a pairing group,
- Encrypt backups switched on, on the holder and on every member, because each server gets a restic key of its own,
- a receiving server on the holder that the members can reach. When BombVault runs on an IP address of its own, fill in Address for partners in the receiving server's window first.
A server holds at most one shared repository.
Setting it up¶
Once the receiving server runs, the Instances page of its box has a Shared repository card below the instances. Press Set up shared repository, pick a Folder for the shared repository on a share with plenty of room, keep the Port at 8001 unless another container uses it, and press Set up and start. BombVault then:
- refuses if a container called
rest-server-sharedalready exists or another container holds the port, - creates the repository in a folder
sharedinside it, with this server's password, - starts
restic/rest-serverasrest-server-shared, in append-only mode with a login file in the folder, - on Unraid writes its template to the flash drive, so the container stays editable in the Docker tab,
- runs the tamper test against it. Check again on the card runs it once more.
The card lists the Members, each with its keys and its last backup, the asks to join, and Remove for each member.
Joining¶
On the server that wants to join, open Add storage location. Under From your group the holder shows up a second time, as Shared repository on and its name. Picking it sends an ask to the holder, where it stands on the Shared repository card with Allow and Decline.
After Allow the holder hands out a one-time key and a login on its second rest-server over the group. The member adds a restic key of its own with it, and the holder then removes the one-time key. A member that has not finished within a day loses the one-time key and the login again and can ask once more. When the holder could not reach the member with its answer, the card offers Tell it again.
The holder turns a server away while it still writes no host of its own, which means it runs an older release, and when another member already writes under the same host. Two servers share a host when they share an APP_KEY.
Once the member is in, a storage location called Shared with and the holder's name appears under Storage locations, with every section switched off. Switch on the sections that should copy there on the location's page. The location has delete protection and no keep rules of its own, because only the holder forgets there. Only backups under the member's own host go there, so older backups under the host bombvault stay where they are.
The holder can copy its own backups in as well: Copy this server's backups in too on its card adds the location there too. For the holder that copy lies on its own disks and nothing keeps it from deleting there, so it is no copy away from home.
Who tidies up, and when¶
Only the holder forgets and prunes. Its settings are in the Shared repository part of the Receiving server window, which opens from the holder's own card on the Instances page:
- Tidy-up window sets when the prune runs, daily or weekly. It starts on Sundays at 03:00 until you change it, and Window length in hours is 6.
- Unused space a prune may leave, in % is 5 unless you change it. A higher value repacks less, so the prune finishes sooner.
- Data read back after a prune, in % is 5 unless you change it. After every prune the holder checks the repository and reads this share of the data back.
- How long to keep follows the holder's off-site rules for each section, and Set a rule of its own gives the shared repository its own. The backups of each server age on their own.
- Tidy up now forgets, prunes and checks right away, after telling the members.
Outside the window the holder forgets once a day, and the space comes back with the next prune. Before a prune it tells the members, and they copy nothing into the repository until the window closes. A member that is still copying gets up to half an hour to finish, otherwise the prune moves to the next window. A copy that falls into the window waits, shows as deferred in the activity log and on the member's card, and the next pass catches up.
Where the holder is unsure, it keeps more. An entry that a member holds on to because of an anomaly keeps all its backups, a member that cannot say what it holds on to keeps all its backups that time, and backups under a host that no server of the group writes are never forgotten. The window also shows the space: what the repository holds, what the servers would need apart, and what that saves. The numbers come with each tidy-up.
What members see¶
On a member, the Instances page has a Shared repositories card with each shared repository the server copies into or asked to join, and where its ask stands: Waiting for a yes, Joining, Joined, Turned down, Expired or Not a member. For a repository it is in, the card shows Who prunes, Next tidy-up, Together with for the other members, Last copy here, and how much space the repository holds and saves.
Leaving¶
Leave on the member's card takes the server out: the holder removes its key and login, and its storage location there is switched off. Remove on the holder's card takes a member out from the other side. Either way the server's backups stay in the repository and age by the holder's rules. On the holder they stand under Servers that left, where Forget backups forgets all of them once you type the server's name. The next tidy-up window gives the space back.
The backups of other servers¶
Each server finds its own backups in the shared repository on the Backups tab of its entries, like any other copy. The backups of the other members are on the Restore page under Other servers.
After an emergency¶
The recovery kit has a chapter Shared repositories. It names each shared repository with its holder, the sections that copy there, the other members with their hosts, and a restic snapshots command with this server's host. The holder's kit also names the port, folder and login of its rest-server.
In the Emergency wizard the repository shows among the places as Shared repository at and the holder's name. A new install that takes a member's key over writes under the same host, because the host comes from the key. It gets its storage location in the shared repository back and lists and restores only its own backups there.
A new install that takes the holder's key over holds the repository in its place. It ages and tidies it up as before and starts the rest-server again on the same folder. Pair it with the group again, set up its receiving server under Instances, and set the rules in the receiving server's window again, because they are not in the kit. Once the group reaches the members, the new holder tells them itself. Each member checks first: it adds a throwaway key to the repository that only a server at the repository's folder can remove, and follows the new holder once that key is gone. If the new holder answers at another address, each member runs this check there with its own key and login, makes sure it finds the same repository, and only then moves its storage locations to the new address. Until then it keeps copying to the old address, and its card says why. The holder removes keys left over from such checks at its next tidy-up.
If the old holder still runs, its card says that the other server holds the repository now. Take it back makes it the holder again, for when a kit was taken over on a second server by mistake.
Limits¶
- Every key reads everything. All keys of a restic repository open the same master key, so every member can read the backups of the others. Container and VM definitions stay sealed with each server's own key, so another server's containers and VMs come back as files only. A server that once had access could have read the master key, so removing it does not shut it out for good. Only a new repository does.
- The holder can delete. No member can delete anything there, but the holder reaches the folder directly and forgets and prunes the backups of every member. A mistake or a takeover on the holder reaches them all.
- Damage reaches every server. A broken pack is missing for every server whose backups use it, so a shared repository does not replace a second copy.
- Only on a receiving server. S3, SFTP and other places cannot keep a member to adding, so BombVault offers a shared repository only on a receiving server.
- Only as a copy target. A section's own folder cannot lie in a shared repository, because every prune would hold up the backups of all servers.
- Older history stays put. Only backups under each server's own host go in, and nothing is moved over from other repositories.
Example: pairing two Unraid boxes¶
This is one complete setup of the parts above, because they are easier to assemble once you have seen them assembled.
Two boxes: TOWER runs the containers and pushes backups. VAULT receives them and enforces append-only. Substitute your own names, addresses and share paths.
1. Pair the two boxes. On TOWER open Settings, Pairing, press Generate phrase, and enter the twelve words on VAULT under Enter phrase. Set a login password on both first.
2. On TOWER, ask VAULT to be the receiver. On the Instances page, switch on Receiver on VAULT's card, pick the sections and VAULT's receiving server as the place, and send the request.
3. On VAULT, allow it. VAULT's Instances page shows the request on TOWER's card. Press Allow. The first time, VAULT asks for a folder for its receiving server, such as user/appdata/rest-server, starts the rest-server in append-only mode and runs the tamper test against it.
4. Back on TOWER. From then on TOWER copies to VAULT after every backup, and the new storage location appears on TOWER's Storage locations page with its delete protection.
What the tamper test answers:
| Result | What happened |
|---|---|
| protected | VAULT refused the delete. This is the only passing state. |
| not protected | VAULT accepted a delete. --append-only is missing or was removed. |
| inconclusive | Neither. Usually the URL is not the one restic itself uses, or the credentials changed. Nothing is recorded and no alert fires. |
5. Watch what arrives, if you want. Switch on Receiver under Settings, Instances on VAULT, open TOWER's Details and add the received repository: click one of the locations the dialog lists. VAULT gets TOWER's restic password over the group, and because the location lies on VAULT's own receiving server it reads the folder directly. Nobody types a key or a login.
6. Make it mutual. Repeat the steps in the other direction: VAULT asks TOWER to be its receiver. Each box then enforces append-only for the other, and neither can delete the other's backups.
A rest-server you run by hand works too: add it with Add storage location as a rest-server, with the user and password from its .htpasswd, and switch on delete protection. Keep --append-only in its options. Without it the far side is an ordinary share again.
A local path is a path inside the container
Where BombVault asks for a folder on this server, enter it relative to the host mount, such as user/appdata/rest-server/bombvault-containers, not /mnt/user/appdata/.... BombVault runs in a container, where the host's /mnt is mounted elsewhere. An absolute host path does not exist inside it. If you paste one, BombVault tells you the relative path to use instead.
Emergency wizard¶
The Emergency wizard brings back a server that is gone or was set up again. It starts on the Restore page under Emergency, and from Restore from a backup on the welcome page of a new install. It runs in four steps: Access, Settings, Selection and Restore.
-
Access. Show BombVault the key of the old backups, in one of three ways:
- Upload recovery kit: the file you downloaded during setup. It holds the key and every storage location, and BombVault fills in the rest from it. A kit sealed with age asks for the identity it was sealed for. It is used once and not stored.
- Through the group: an instance of your group keeps the key as a deposit. You need the group's twelve words, your recovery code and someone at that instance. See Key keeper.
- Type the key: the old server's
APP_KEY, and where its backups are.
BombVault then tries the key on every storage location and says for each one whether it is readable, not found, locked with another key, not reachable or still missing its sign-in. Nothing has been saved yet, and the key stays in memory for a limited time. Take the key over makes this server write its backups with that key from now on. Undo the takeover goes back to its own key until the first backup has run. A server that already has backups of its own refuses the takeover and points to From an old backup folder instead. Save sign-ins stores the sign-ins the kit carries for remote storage locations, and asks before it replaces sign-ins this server already has. 2. Settings. Bring back settings restores BombVault's own settings from the newest self-backup: storage locations, sign-ins, schedules and rules. BombVault restarts to apply them, through the Docker socket, so the live settings database is never overwritten under an open handle, and the wizard carries on by itself afterwards. This server's login stays: you keep signing in with the password you use now. Secrets the old server had stored that cannot be taken over are listed, so you can enter them again. The restore ends every session and removes the passkeys, so set them up again afterwards. 3. Selection. BombVault looks through your backups and lists the containers, VMs, folder sets and ZFS datasets it finds. The newest snapshot is preselected everywhere. What this server still has starts switched off, because a restore would replace it. Folder sets no longer know where they came from after a rebuild, so they go into a folder you choose. 4. Restore. Everything selected comes back in one go, left stopped if you want to start each container and VM yourself, which is safest after a total loss. Afterwards download a new recovery kit: the old one belongs to the previous install.
A shared repository from the kit shows among the places as Shared repository at and the name of the server that holds it, and the wizard lists only this server's own backups there. See After an emergency.

Example: a new server from the recovery kit¶
The server TOWER died with its disks. It kept 23 containers and 2 VMs, and copied them and its self-backup to Backblaze B2. You have bombvault-recovery-kit.md from your password manager and a new box with Unraid on it. Its old APP_KEY is gone, and you do not need it.
- Install BombVault on the new box and give it a new
APP_KEY, as on any new install. Set the VM link up under Settings, Integrations, Host SSH if you want the VMs back, because a VM restore needs it. - Start the wizard. On Welcome to BombVault, choose Restore from a backup. On the Restore page, choose Start the emergency wizard under Emergency.
- Access. Choose Upload recovery kit and drop the file. BombVault tries its key on every storage location and says, for example, Recovery kit read. Its key opens 0 of 2 storage locations. The local folder says not found, since the disk died, and Backblaze B2 says sign-in missing.
- Save sign-ins. The kit carries the sign-in of every location. Press Save sign-ins, and the locations are tried again, so Backblaze B2 now says readable. A kit written before 10.5 holds only the default sign-in. Where a location still says sign-in missing, enter its sign-in under Enter a missing sign-in and press Try the storage locations again.
- Take the key over. This server now writes its backups with the old key, so the new backups fit the old ones. It keeps its own
APP_KEYin the template. Undo the takeover works until the first backup has run. - Settings. The step opens on the place where the key found the self-backup, here B2, with its address filled in. Choose Bring back settings, which reads the newest self-backup from there. BombVault restarts to apply it, and the wizard carries on by itself. Your storage locations, schedules and rules are back, and you keep signing in with this server's password. Enter the secrets the wizard lists again, such as notification settings.
- Selection. Where are the backups? opens on the off-site copies when nothing local is left. BombVault reads every location, so a dead one does not hide the others, lists the 23 containers and 2 VMs and restores each from the location that holds its newest snapshot.
- Restore. Switch on Leave stopped afterwards, which is safest after a total loss, and start. What happens says what comes back. The result line reads, for example, 25 restored, 0 failed. Start them under Backups when needed.
- Finish. Start your databases first, then the apps that use them. Open Settings, Restore and download a new recovery kit, because the old one belongs to the previous install. Check Needs you on the overview, and run Back up everything now once everything works.
If the self-backup is missing too, the step opens on Skip: I don't have a settings backup and says so. The storage locations then come from the kit alone, you set up schedules and rules again, and off-site copies wait until you take their backups as this server's own, see After a rebuild. Selection still lists what the off-site copies hold. Folder sets go into a folder you choose. Containers and VMs come back as plain files in a folder under Only the files can come back, because their definitions live beside the local repository and in the self-backup, and an off-site copy holds neither.
Planned migration versus disaster
The Emergency wizard restores BombVault's own settings from a backup. For a planned move to a new box, you can instead carry your configuration over directly with the Export / import settings card (a portable JSON file). See Configuration.
From an old backup folder¶
From an old backup folder under Other sources on the Restore page opens a different BombVault instance's repository (a share mounted under /mnt, or a remote address) with that instance's recovery kit or its typed APP_KEY, in a one-time, read-only session. Browse the containers, VMs, folder sets and ZFS datasets stored there, pick a snapshot and restore it, and the restored object becomes a normal local container, VM or folder set. Nothing is ever written to the other repository, and your own backup settings stay untouched (the session lives in memory and expires by itself). Moving a container from server A to server B does not mean repointing your settings and reverting them afterwards. This window is a one-shot: it opens a session, restores what you pick, and forgets the other instance. If you want a standing arrangement instead, where this box fetches another instance's snapshots into its own repository on a schedule, that is the Fetcher role on the Instances page.
What this server fetched¶
Each source this server has fetched from has its own Fetched from line under Other sources on the Restore page. A fetched copy is locked with this server's own key, not the source's, so nothing is asked for: the key of the source does not open it. Folder sets and ZFS datasets go into a folder you choose. Containers and VMs come back as plain files in a folder, because a fetch carries the snapshots and not the definitions. To recreate them, use the recovery kit and the self-backup of the source in the Emergency wizard.
A container whose network does not exist on this server, such as an Unraid br0 network on a plain Docker host, shows a network picker under its row. BombVault creates it on the network you pick, together with its other networks. The fixed IP and MAC address belonged to the old network and are dropped, so the new network assigns them.
Key keeper¶
A key keeper is an instance of your group that holds a sealed copy of this server's recovery kit. It cannot open the copy itself. If this server is ever lost, a new install that joins your group asks the keeper for the copy and opens it with your recovery code.

- On the Instances page, switch on Key keeper on the card of the instance that should keep it, and choose Make deposit. Making a deposit needs a login password.
- This server shows the Recovery code once: twenty letters and digits in four groups of five. Write it down and confirm with I wrote the code down. This server does not store the code, only what it needs to seal a deposit for it.
- The keeper now holds the deposit, and this server renews it when the kit changes. Key deposit on this instance's card lists This server's deposit with each keeper and its state, and Deposits this server keeps for the others. Make a new code replaces the code. Each keeper switches to the new one when it gets the new deposit.
On that day you need three things: the twelve words of your group, the recovery code, and access to the keeper's interface, where someone has to press Allow. In the Emergency wizard choose Through the group, pick the deposit, ask for it and type the recovery code. The code is used on the new server and is not sent to the keeper. On the keeper, the request shows under Key deposit with who asks, whether that instance was ever seen there before and how often it asked. Allow hands out the sealed copy, and allowing needs a login password. The new install has 30 minutes to collect it after the Allow, a request nobody answers runs out after a day, and an instance that asks too often has to wait an hour.
The deposit carries the APP_KEY of each of this server's nodes as well, since the kit does. With the code a keeper could open their repositories, but it can never command a node, because that takes this server's signature.
Without the code nobody can open the copy, the keeper included. If the code is lost, make a new one while this server still runs. If the server is already gone, the recovery kit and the typed APP_KEY still work. The keeper can delete a deposit at any time, and the owner then has to ask again.
Recovery kit¶
This is the piece that makes disaster recovery possible even when there is no running BombVault.
Download recovery kit in the For emergencies card under Settings, Restore gives you the key, the derived restic password, every storage location with the repository of each section, the sign-ins a new install needs to reach them, and the exact restic commands, so you can restore straight with the restic CLI on any machine. It needs a login password. The kit prints the key also with encryption switched off, because the container and VM definitions are always sealed with it. After a takeover it prints the taken-over backup key and this server's APP_KEY, which a new install needs only to bring back the settings. A Save your recovery kit card on the overview reminds you until you have stored it.
A server with nodes gets a chapter Nodes in its kit. It names each node with its id, its APP_KEY, the restic password worked out from that key and the repository of each section. The node's own password opens them, and so does this server's, because this server adds its key to every repository of a node. Download the kit again after you add a node or change where its backups go. With the node's APP_KEY and its NODE_HOME a new server becomes the same node again, see Replacing and releasing.
Store the recovery kit off the server
The kit contains the secret that decrypts your backups. Keep it somewhere safe and separate from the server (a password manager, a printed copy in a safe). If you lose both BombVault and APP_KEY with no recovery kit and no key deposit, your encrypted backups cannot be recovered.
The newest snapshot is not always the one to restore
Since restic 0.17, restic snapshots shows each snapshot's size. After data loss the newest snapshot can be the emptied one, so do not restore a snapshot that is far smaller than the ones before it. After ransomware it can be the encrypted one at the usual size. If BombVault still runs, check its Anomalies page first: it names the last good backup, and the restore window preselects it. A restore does not need any of BombVault's anomaly data, and the retention pause only ever keeps more snapshots.
The host of a server's backups¶
Each server writes its backups under a restic host of its own: bv- and twelve characters worked out from the key of the backups, such as bv-3f9a0c41d2e7. Backups from before a server had one carry the host bombvault. The kit names this server's host, and its commands pass both with --host, so latest never picks a backup another server wrote to the same repository. A server that takes over another one's backups goes on under that server's host, because the host comes from the key. For each shared repository the server copies into or holds, the kit's chapter Shared repositories names the other servers there with their hosts.
Sealing the kit¶
If you have switched on Encrypt exports with age under Settings, System, the kit is sealed with it too and downloads as bombvault-recovery-kit.md.age. It is ASCII-armored rather than binary, so it is still plain text: pasting it into a password manager or printing it works exactly as before, the contents are unreadable without your key.
Do not store the age key inside the kit
You need your age private key to open a sealed kit. Keep it somewhere that does not depend on the kit itself, or you will have two things to recover instead of one. Sealing is worth it when the kit is stored somewhere you do not fully control (a shared password manager, cloud notes, a printout in an office). A kit in your own safe is already protected by the safe.
With encryption on and no usable recipient configured, the download is refused outright. BombVault never falls back to handing out the master key in the clear.
If you do not have the kit to hand¶
The password is not stored anywhere, it is computed from the key of the backups, so you can reproduce it yourself with nothing but the key and a shell:
printf 'bombvault:restic-repo' | openssl dgst -sha256 -mac HMAC -macopt hexkey:$APP_KEY -r | cut -d' ' -f1
That is HMAC-SHA256 over the fixed string bombvault:restic-repo, keyed with the raw bytes of the hex APP_KEY, printed as 64 lowercase hex characters. The same value is in the kit, listed as the derived restic password. This is for the day the kit is somewhere you are not. On a server that took over another one's backups, use the taken-over backup key, which is that server's old APP_KEY.
The host comes from the same key and the string bombvault:host: bv- and the first twelve of those characters.
echo "bv-$(printf 'bombvault:host' | openssl dgst -sha256 -mac HMAC -macopt hexkey:$APP_KEY -r | cut -c1-12)"
For a received repository, use the SENDING instance's key
A repository that arrived here through an off-site copy was created by the machine that sent it, with its key. Deriving from the receiving box's key produces a password restic will reject, which reads exactly like a corrupt repository and is not. This is the usual reason restic check on a received repo asks for a password over and over.
Because recovery definitions live inside each repo (<repo>/def, <repo>/vm-def), a copied repo folder is fully self-contained, so the kit plus the repo is everything a bare-metal restore needs. An off-site copy and a fetched copy hold the snapshots without the definitions: they give back files, and a container or VM is recreated from the self-backup.
Getting a database dump back¶
A database dump is a restore point of its own in the containers repository, tagged dbdump:<container>, holding the single file /dbdump/<container>.sql. BombVault lists, downloads and imports them on the container's Backups tab. Below are the same steps with restic alone, for the day BombVault is not there.
restic -r <repo> snapshots --host <host> --host bombvault --tag dbdump:<container>
restic -r <repo> dump --host <host> --host bombvault --tag dbdump:<container> latest /dbdump/<container>.sql > <container>.sql
<host> is the server's host from the recovery kit.
The tags dbversion: and dbname: on each dump say which server version it came from and which databases it holds. A complete file ends with -- PostgreSQL database cluster dump complete or -- Dump completed.
Import it into a container of the same or a newer version (PostgreSQL), or the same major version (MySQL and MariaDB), started once with an empty data folder so it initialises. The host needs no database client, the container has one:
docker exec -i <container> sh -c 'exec psql -X -U "${POSTGRES_USER:-postgres}" -d postgres' < <container>.sql
docker exec -i <container> sh -c 'exec mariadb -uroot -p"$MARIADB_ROOT_PASSWORD"' < <container>.sql
docker exec -i <container> sh -c 'exec mysql -uroot -p"$MYSQL_ROOT_PASSWORD"' < <container>.sql
For a single database out of a full dump, MySQL and MariaDB take --one-database <name> on the client command. A PostgreSQL dump has one section per database, each starting with a \connect <name> line: copy that section into its own file and import it with -d <name> after creating the database.
A root dump carries the server's users
A full MySQL or MariaDB dump taken as root contains the mysql system database, so importing it replaces the new server's accounts, including root's password, with the ones from the dump. On PostgreSQL, role ... already exists for the user the container created is expected and harmless.