Skip to content

ZFS datasets

ZFS datasets are entries in the Backups list, like containers and VMs. An entry is one dataset together with every dataset below it. For each backup BombVault takes one ZFS snapshot of the whole tree, so every dataset in it is captured at the same instant. It then reads each dataset's files from that snapshot and stores them with restic, the same way it stores a folder, and removes the snapshot right after. The backups are deduplicated, you can browse every one of them, and single files can be restored.

The backup never sends a stream into restic and never rolls a dataset back. BombVault destroys only snapshots it created itself. The optional replica is the one place that uses zfs send: it copies the datasets to a second ZFS server and does not touch the backup.

Requirements

  • The SSH link to this server. ZFS datasets use the same key, host and user as VM backups. If VM backups already work, so does this. Otherwise follow the VM backup over SSH guide. The template fields are called Host SSH: Address, Host SSH: Port and Host SSH: User.
  • The zfs command on that host. Unraid 6.12 and newer and TrueNAS SCALE have it.
  • Host Data mapped as /mnt with Access Mode Read/Write - Slave. That is the template default. The snapshot of a dataset shows up inside the dataset's .zfs/snapshot folder only after BombVault has started, so the container has to receive mounts the host makes later.
  • The datasets mounted below /mnt. On Unraid pools live at /mnt/<pool>, so that is already the case.

Switch the section on under Settings, General (ZFS datasets). ZFS connection to this server under More on the Backups page then opens Connection to this server. It tests the SSH link, names the user and host it connects to, and says what is missing when something is. When the link is down, the Backups list says so with View connection, and the Host Integration card on the overview shows the same result.

Entries and child datasets

Choose Add on the Backups page, then A ZFS dataset. The list comes from the server. Pick the dataset at the top of what you want backed up, for example cache/appdata, and the entry covers it and every dataset below it.

  • New child datasets join on their own. A dataset created below the entry later is backed up with the next run, and that run names it as new. Its first backup reads it in full once. After that only changes are read.
  • You can leave single children out. Switch a child off on the entry's Settings tab and it is left out together with everything below it. A left-out child that no longer exists on the server is marked as such and can be removed from the list.
  • Children that cannot be read are skipped, never silently. The run lists them, the entry shows how many were skipped, and the overview's Not backed up card counts each one as not protected. The run still backs up everything else and does not fail because of a skipped child. The reasons are in the table of reason codes: a dataset that is not mounted, has canmount=off, a legacy or no mountpoint, an encryption key that is not loaded, snapshot access switched off, or a mountpoint BombVault cannot see.
  • A skipped dataset does not take its children with it. A canmount=off dataset that only holds other datasets is skipped (shown as "structure only") and its mounted children are backed up. An encrypted dataset whose key is not loaded is skipped together with the children that share its key.
  • Children that are VM disks or system data start switched off in the add dialog, with the reason next to the switch. Adding a whole pool asks for a confirmation that lists what it contains.

Volumes

A volume (zvol) holds a virtual disk instead of files, and a ZFS entry never backs one up.

  • A volume that a VM uses is backed up with that VM.
  • A volume that no VM uses (an iSCSI extent, a disk you detached) is not backed up by BombVault. The add window and the Backups page count these volumes and say so. A later version will back them up.

Volumes inside an entry's tree are skipped and named on every run.

Docker's storage

With Docker's ZFS storage driver, every image layer is a dataset with a legacy mountpoint. The add dialog folds these into one line per parent. A tree that holds more than 20 such datasets cannot become an entry: while a snapshot of it exists, Docker cannot remove image layers. Add the datasets below it instead, for example appdata.

Entries never overlap

A dataset can belong to one entry only. BombVault refuses a new entry that lies inside an existing one, or that would contain one. To merge several child entries into one parent entry, delete the child entries first and choose to keep their backups, then add the parent. Every dataset keeps its history under its own name, so the next backup continues where the old entries left off and does not read everything again.

Stopping containers and commands around the snapshot

A snapshot of a running database is like a sudden power cut: the database will usually recover, but it has to. Each entry can do two things about that, and both only cover the instant of the snapshot, not the whole backup.

  • Stop these containers for the snapshot. BombVault stops the listed containers, takes the snapshot and starts them again right away. Containers of one level of dependencies stop in parallel, dependents first, so the whole window is usually a few seconds. The run shows how long it was. The backup then reads the frozen snapshot while the apps are already running again. Only containers that were running are stopped.
  • A command before and after the snapshot. It runs inside a container you choose, for example to dump a database into the dataset right before the snapshot, without stopping anything. If the command before the snapshot fails, the backup fails and no snapshot is taken. A failing command after the snapshot is shown on the run but does not fail the backup.

What happens when something goes wrong:

  • If a container cannot be stopped, BombVault starts the ones it already stopped and the backup fails, naming the container. It never falls back to a snapshot of running apps.
  • The stop waits for a running container backup to finish (up to 30 minutes for a manual run, up to the backup time limit for a scheduled one), so the two never stop and start the same container at once.
  • Before the first container stops, BombVault writes down which ones it stops. If BombVault is killed inside the window, it starts those containers again the next time it starts, sends a notification, and the entry shows a red note for any container it could not start.

The automatic database dumps run with a container's own backup, not with a ZFS entry. A database whose container is backed up only through its dataset gets no dump, so give it a command here.

A container can be on this list and be backed up as a container at the same time. Its data is then stored twice, in two repositories, and the full backup stops it twice. The entry says so.

Restoring

Open the entry and choose Restore, or pick it on the Restore page. The restore window asks for the backup, then the Dataset. By default that is the entry's top dataset. Under What you restore everything or only the files and folders you pick. Where to offers:

  • Restore into the dataset. Files from the backup are written into the dataset's mountpoint. Files with the same name are overwritten, other files stay. The dataset is never rolled back or replaced. BombVault checks that the dataset is mounted, visible and writable, once before it starts and again right before it writes. Where a child dataset is mounted inside it, nothing is written: the child keeps its files, owner and permissions, and is restored from its own backup.
  • To a folder. Pick a folder below /mnt. BombVault checks that the folder is on a mounted pool or share and that there is enough free space. This works without the SSH link and for datasets that no longer exist.
  • Into a new dataset. Name a dataset that does not exist yet. The window suggests <dataset>-restored. BombVault creates it with the ZFS properties stored in the backup and restores into it, see Restoring as a new dataset.

Picking All datasets of this backup as the dataset writes every dataset of the tree into its own subfolder of the folder you pick. Datasets that were skipped in that backup are named. To restore from another BombVault's repository, use From an old backup folder on the Restore page. It always restores into a folder: all datasets of one backup, each into its own subfolder, or one dataset of the tree, whole or selected files.

The entry's list of containers to stop is offered for a restore into the dataset as well. Those containers stay stopped for the whole restore, and container backups wait meanwhile.

The safety snapshot

Before it writes into a dataset, BombVault takes a ZFS snapshot of that one dataset, named bombvault-prerestore-<time>. Keep a ZFS snapshot of the current state first is on by default. Switching it off needs a second confirmation. If the snapshot cannot be taken, nothing is restored.

BombVault never deletes a safety snapshot by itself. The entry lists them with their age and size, each with a Delete action, and warns when the oldest one is more than 30 days old, because it keeps deleted and changed data on the pool.

To go back after a restore, copy single files from .zfs/snapshot/bombvault-prerestore-<time> inside the dataset. zfs rollback <dataset>@bombvault-prerestore-<time> only works while it is the newest snapshot of that dataset. zfs rollback -r deletes every newer snapshot, automatic ones included.

Restoring as a new dataset

BombVault stores the locally set ZFS properties of every dataset with each backup: compression, record size, quota, reservation, atime, xattr, acltype, case sensitivity and your own user properties. Inherited and read-only values are left out, because they come back on their own. Backups from before BombVault stored them have none.

  • Into a new dataset runs zfs create with every stored property. Case sensitivity, normalization and utf8only can only be set this way. Quotas and reservations are set after the files, so they cannot refuse them. The mountpoint is left out, so the copy does not collide with the original, and so are canmount, readonly and the encryption settings, so the restore can write. A new dataset below an encrypted one takes over its encryption. The dataset above the new one has to exist. If something fails after the new dataset was created, it stays on the server, because BombVault never destroys a dataset.
  • Restore into the dataset lists the stored properties next to the restore. Also set these properties sets the ones an existing dataset can still take, before any file is written. Quotas and reservations are set after the files, so they cannot refuse them. Without that switch the dataset keeps its settings.

What is in the backup

In the backup: the files and folders of every backed-up dataset, with their ownership, modes, timestamps and extended attributes as restic stores them, and the locally set ZFS properties of each dataset.

Not in the backup:

  • the owner and mode of each dataset's top folder itself (everything below it is included). A restore into the dataset leaves the existing top folder as it is, a restore to a folder creates it with mode 0755,
  • existing ZFS snapshots,
  • children that were skipped or left out,
  • volumes.

To restore onto a new pool, create the pool and restore each dataset into a new dataset. Whether NFSv4 ACLs, as TrueNAS uses them on SMB datasets, come back the way you expect has not been verified yet, so check a restore on your own data before you rely on them.

Encrypted datasets

An encrypted dataset is backed up only while its key is loaded. Otherwise it is skipped with a warning. Load the key with zfs load-key and mount the dataset. BombVault reads the data decrypted and stores it in restic's repository, which is encrypted. If you switched encryption off in BombVault, that repository is not.

Replica

A replica is a copy of an entry's datasets on a second ZFS server. BombVault keeps it current with zfs send and zfs receive. The first run sends everything, after that only the changed blocks travel. On the other server you can mount the copy right away.

A replica never replaces the backup. Older versions, single files and the check still come from the backups, and the replica keeps only as many snapshots as you set. A current replica counts as a copy off the premises, but not as a backup.

The replica does not wait for the backup. After every backup means after the entry's backup run, whether that run worked, failed or found nothing to do. When the ZFS section has no storage location switched on and the entry has no repository of its own, a backup run of the entry only sends the replica, and the Replica card says so in the bubble beside When. The Backups list, the entry's header and the run history show the replica: Replicating while it runs, and Replicated with the time once it has.

Replica only, no backup on the Replica card makes the whole ZFS section send replicas and take no backups. The own folder and the off-site storage locations keep their switches, so turning it off backs up to them again, and every ZFS entry's card shows the section's switch as it stands. Such an entry waits for its first replica instead of a backup, Back up now is offered as Replicate now, and the entry's containers stop and its commands run around the snapshot as for a backup. Its replicas count for an every-few-days schedule, the overdue alert and the coverage.

Switch it on in the Replica card on the entry's Settings tab. The card lists every dataset and volume with its state, and Replicate now starts a run. A replica run has a lock of its own, so a long first transfer never holds up the backups.

Field What it sets
Replicates to The target: a ZFS server (marked over SSH) or a paired instance. Add ZFS server sets up a new one.
When After every backup, which means after the entry's backup run, or Own plan.
Keep on the target How many snapshots stay on the ZFS server: Short, Balanced, Long or Custom values. A paired instance decides this itself.
Keep on this server How many of the newest replica snapshots stay on this server too. 0 or 1 keeps only the latest.
Replica only, no backup The whole ZFS section sends replicas and takes no backups.

The Replica card of a ZFS entry. The Replica card of a ZFS entry.

Replicate all now, beside the backup actions when the ZFS tile is picked on the Backups page, sends the replica of every ZFS entry, one after the other. The server runs the batch, so it goes on when you leave the page, and an entry that cannot replicate is named and skipped.

Push to a ZFS server

Any machine with ZFS and SSH can receive, for example a second Unraid or a TrueNAS. BombVault does not have to run there.

  1. Under Settings, Pairing, choose Connect over SSH in ZFS server without BombVault, or Add ZFS server in the entry's Replica card.
  2. Enter address, user and port. The dialog shows BombVault's public key. Add it to the user's ~/.ssh/authorized_keys on the server. On Unraid that is under Users, root, SSH keys. Depending on Display Settings, Users sits in the header menu or under Settings. On TrueNAS, edit the user under Credentials, Users. This is the replica key. It differs from the key of the VM and host SSH link, so add it even if that one is already authorised.
  3. Test the connection. The dialog then lists the pools of the server. Pick one and set the root, which defaults to <pool>/bombvault-replica.
  4. Pick the new server in the Replica card of the entry. The server then has a card of its own on the Instances page, and Open leads to its page.

With root nothing else is needed. A user of their own needs these permissions on the pool of the target, which the dialog also shows:

zfs allow <user> receive,create,mount,rollback,destroy,userprop,readonly,canmount <pool>

On the source the same kind of user needs these on the entry's top dataset:

zfs allow <user> send,snapshot,hold,release,bookmark,destroy,mount <dataset>

In this direction the BombVault that holds the entry also holds a key that can write on the server.

BombVault pins the host key the server shows on the first connection and refuses a different one later. If the server was reinstalled, press Forget host key on the server's page, and the next connection pins the new key.

When this server's host can reach the ZFS server itself, it pipes zfs send straight into its own ssh to the server, with the replica key and the pinned host key, so the stream does not pass through BombVault. Otherwise the stream goes through BombVault.

Send to a paired instance

A paired BombVault can receive the replica itself. Nobody gets SSH access to the other host, and no key goes into an authorized_keys file.

  1. In the Replica card of the entry, pick the paired instance as the target, or switch on the ZFS server role on that instance's card on the Instances page and pick the ZFS entries there. The card shows Waiting for approval until it answers.
  2. On the receiving instance, open Instances. The request shows on the sending instance's card as a badge, and its Details list it. Pick the pool and root on that server and how many snapshots stay, then press Allow or Decline.
  3. After Allow the source sends by its own plan, like for any other target.

The receiving instance accepts only what the approval covers: the entry's datasets, into its own root. It runs zfs receive itself, and the source has no way to delete or roll back anything there. So the copy survives a source that someone has taken over. The receiving instance keeps its own retention. The source only suggests a rule when it asks. Such a source can still send new snapshots, and over time they push older ones out under the rule like any others. A snapshot name dated ahead of the receiving instance's clock does not count towards the rule until that time has come.

Revoke access on the receiving instance ends the approval at any time and tells the source, which then shows that the approval was withdrawn and stops. What the receiving instance already holds stays there. A declined request stays declined. More datasets, or a request after a revoke, ask again.

The receiving instance has to answer over HTTPS. The source sends nothing to a plain http address, since the token and the data would cross the network unencrypted. Each transfer also leaves a tenth of the receiving pool free and stops before it would eat into it, so one source cannot fill the pool of the receiving server.

Where the data lands

Each dataset lands at <root>/<server>/<pool>/<path>. The server folder is the name of the source instance, fixed at the first transfer, so two servers with the same pool name never get in each other's way. For example, cache/appdata of a server called tower ends up at backup/bombvault-replica/tower/cache/appdata.

After BombVault is set up again, the target refuses the folder this BombVault filled before. The Replica card then offers Take over the folder, and the next replica carries on from the copies in it. Take it over only when no other BombVault still replicates into that folder.

The copy on the target is read-only. By default it is not mounted, so it never covers anything on that server. A ZFS server connected over SSH has a switch Mount read only on the server on its page: with it on, BombVault mounts the copies there read only after each run, so you can read and copy their files on the target. Encrypted copies stay locked until their key is loaded, and switching it off unmounts nothing. A paired instance that receives the replica keeps it unmounted. ZFS properties travel along, except the mountpoint and sharenfs and sharesmb. The reservations reservation and refreservation stay behind as well, so the copy only takes the space its data needs.

What goes in

Everything the entry backs up goes in, and the volumes below it too, which the backup skips. A child dataset you switched off in the entry stays out. All datasets of a run come from one snapshot, as in the backup.

A copy that another BombVault replicates to this server is not sent on, because that would thin the history its source still needs. When an entry's tree holds one, the run fails for that dataset and says why, until you switch it off in the entry. An entry that is such a copy itself cannot replicate at all. Deleting an entry or switching its replica off leaves those copies and their snapshots alone. Once you take a copy over, as described under Using the replica, it counts as a normal dataset.

How long snapshots stay

On the target, a new replica keeps 7 daily and 3 weekly snapshots. Pick Short, Balanced or Long instead, or set Custom values. Custom values of all zeros keep every snapshot, and the card says so. Only snapshots named bombvault-replica-<14 digits> are ever removed there, and never the newest one that both sides share.

On the source, BombVault keeps the latest replica snapshot, plus a bookmark for every state it has sent. Bookmarks cost no space. The next transfer starts from them.

To keep more on the source as well, set Keep on this server on the Replica card, for example to 7. That many of the newest replica snapshots then stay on this server after every replica, next to what the target keeps. 0 or 1 keeps only the latest. The latest carries a hold, so the base of the next transfer is not destroyed by accident. The older ones have none. Each snapshot holds on to the blocks that changed after it, so every one you keep takes space on the pool. Switching the replica off or to another target, or deleting the entry, removes them from this server too. Snapshots of another entry nested below it stay. If the host cannot be reached while you delete the entry, the snapshots stay too and the page says so. Remove them by hand: zfs release -r bombvault-replica <dataset>@<snapshot>, then zfs destroy.

The files of a kept snapshot can be read or copied right away, from the .zfs/snapshot folder inside the dataset or from a clone, without touching the dataset or the replica:

ls /mnt/cache/appdata/.zfs/snapshot/bombvault-replica-20261006014100
zfs clone cache/appdata@bombvault-replica-20261006014100 cache/appdata-20261006

A clone takes no space until something in it changes. Destroy it with zfs destroy cache/appdata-20261006 when you are done, since a snapshot that has a clone cannot be removed.

Going back to the latest replica snapshot needs only zfs rollback cache/appdata@<latest> here, and nothing on the target. Rolling the whole dataset back to an older one destroys every snapshot after it, on this server and on the target. The latest is held, so lift its hold first, then roll the dataset back here:

zfs release -r bombvault-replica cache/appdata@bombvault-replica-20261008014200
zfs rollback -r cache/appdata@bombvault-replica-20261006014100

The copy on the target has to go back too, but not always to the same snapshot, since its own keep rules may have dropped that one. Run the replica once. It stops for that dataset because the target holds newer snapshots, and the Replica card and the run history name the snapshot to roll the target back to: the newest one both sides still share. Roll the copy back to it on the ZFS server, or on the host of the paired instance that receives the replica, for example:

zfs rollback -r backup/bombvault-replica/tower/cache/appdata@bombvault-replica-20261005014000

zfs rollback works on one dataset, so repeat the rollbacks for each child dataset you want back as well. After that, Replicate now carries on from the shared snapshot.

Encrypted datasets in a replica

An encrypted dataset is sent raw. It stays encrypted on the target, and the target never sees the key. Keep the key safe: you need it to open the copy after a restore, and a replica without it is unreadable.

Using the replica

Open the entry's Backups tab and click the ZFS replica row among the places that hold its snapshots. The sheet lists the snapshots on the target and shows the commands with your real names.

To look at an old state, clone a snapshot on the target. A clone takes no space until something changes, and the replica stays untouched:

zfs clone backup/bombvault-replica/tower/cache/appdata@bombvault-replica-20261006014100 backup/bombvault-replica/clone-appdata

If the source fails, turn the copy into a normal, writable dataset on the target:

zfs inherit -r readonly backup/bombvault-replica/tower/cache/appdata && zfs list -rH -o name -t filesystem backup/bombvault-replica/tower/cache/appdata | xargs zfs set canmount=on && zfs mount -a

BombVault stops replicating to that dataset and its children afterwards. The next run fails with a reason, and what you wrote stays. The same goes for anything else written to the copy since its newest snapshot: BombVault never rolls a copy back. To replicate there again, move what you need off the copy and destroy it on the target. The next run then sends everything anew.

To get a state back to the source, press Bring back as a new dataset in the sheet. BombVault sends the snapshot into a new dataset next to the original, named <dataset>-bombvault-restore- plus a timestamp. It never writes over the original. A child dataset lost on the source comes back too, as long as the copy still holds that snapshot. A child that does not hold it is left out, and the run says so.

Example: a replica to a second Unraid box

The server tower backs up the dataset cache/appdata as a ZFS entry. A second Unraid box at 192.168.1.20, without BombVault, has a pool called backup and should hold a copy that you can read at any time.

  1. Open Backups, then cache/appdata, then its Settings tab. In the Replica card, choose Add ZFS server under Replicates to.
  2. Enter 192.168.1.20, the user root and port 22. The dialog shows the replica key. On the second box, paste it under Users, root, SSH keys and press Apply. This key differs from the Host SSH key, so add it even if that one is already there.
  3. Test the connection. Pick the pool backup and keep the root it suggests, backup/bombvault-replica.
  4. Back on the card, the new server is picked under Replicates to. Leave When at After every backup, leave Keep on the target at its 7 daily and 3 weekly snapshots, and set Keep on this server to 7.
  5. Press Replicate now. The first run sends everything, so 300 GB over a 1 Gbit/s line takes at least 40 minutes. The card and the Backups list say Replicating, then Replicated with the time. Later runs send only the blocks that changed.

The datasets now lie at backup/bombvault-replica/tower/cache/appdata on the second box, read-only. On the overview, Off-site of the ZFS section counts the replica as a copy off the premises.

To get one file from last Tuesday, you have three ways:

  • On this server, because Keep on this server holds seven snapshots:

    cp /mnt/cache/appdata/.zfs/snapshot/bombvault-replica-20261103014100/plex/Preferences.xml /mnt/user/restore/
    
  • On the second box, with a clone of a snapshot on the target. The entry's Backups tab shows the commands with your real names when you click the ZFS replica row. Remove the clone with zfs destroy when you are done.

  • With a mount, by switching on Mount read only on the server on the ZFS server's page. After the next run the copies stand mounted and read only on the second box.

Versions older than the replica keeps still come from the backups, as the next example shows.

Example: one file from a ZFS backup

  1. Open Restore, pick the ZFS tile and click cache/appdata.
  2. Pick the backup, and under Dataset the dataset that holds the file.
  3. Under What, choose Individual files and tick the file.
  4. Under Where to, choose To a folder and pick a folder below /mnt, such as user/restore. This needs no SSH link and also works for a dataset that no longer exists.
  5. Press Restore. The file lands directly in that folder, without the path above it.

Leftover snapshots

The snapshot of a backup is named <dataset>@bombvault-<14 digits>, for example cache/appdata@bombvault-20260924021500 (UTC). BombVault removes it right after the backup. If that fails, for example because the dataset is busy or BombVault was stopped, BombVault removes it:

  • before the next backup of that entry,
  • when BombVault starts, for every entry, also with the domain switched off,
  • when you delete the entry,
  • when you press Remove now on the entry, which shows how many are left.

Only names that match exactly bombvault- plus 14 digits are removed. Safety snapshots, your own snapshots and automatic snapshots are never touched. To remove one by hand:

zfs destroy -r cache/appdata@bombvault-20260924021500

The snapshot of a replica is named <dataset>@bombvault-replica-<14 digits> and is not a leftover. It stays on the source until a newer replica run replaces it, or as long as Keep on this server keeps it, and on the target as long as the retention keeps it. The sweeper never touches it, because it only matches bombvault- followed by exactly 14 digits.

Anomalies

A child that was emptied barely changes the total of a large tree, so anomaly detection watches every dataset of an entry on its own: its size, file count, new data and restic time each have their own history. That history belongs to the dataset's name, so it stays when the tree is later backed up by another entry.

A dataset that the previous run backed up and this run could not read counts as emptied, as long as the entry's selection did not change. That covers a key that is not loaded, a dataset that is not mounted and one that is gone from the tree. A child you exclude yourself changes the selection, so its history starts afresh instead. While a finding about lost data is open, retention keeps the old backups of that one dataset and prunes the rest of the tree as usual.

Every dataset has a line of its own in the entry's monitoring, which opens with Monitoring on the Anomalies page and stands on the entry's Verify tab. The open findings show next to each dataset. The link in a finding opens the restore window on the dataset's last good backup. Whether a run finishes is judged for the whole entry, because a run succeeds or fails as a whole.

The checks themselves are described under Anomalies. An assistant connected through the MCP server can list a ZFS entry's restore points, start its backup and read the findings, but acknowledging one happens on the Anomalies page.

Reason codes

The entry's page, the run history and the notifications name a problem with one of these codes. Most have the fix next to them on the page as well.

Code Meaning What to do
ssh-missing The SSH connection is not set up in this container. Set up the SSH link as for VM backups.
host-placeholder Host SSH: Address is still the placeholder, and host.docker.internal did not answer either. Set Host SSH: Address to this server's LAN IP.
host-fallback Host SSH: Address is still the placeholder, and host.docker.internal works. Nothing, or set the LAN IP.
ssh-unreachable The server cannot be reached over SSH. Check address and port, and that SSH is switched on.
ssh-auth The server refused BombVault's key. Run the command shown under Connection to this server once on the server.
zfs-not-found The SSH host has no zfs command. Point Host SSH: Address at the machine that owns the pools.
zfs-permission The SSH user may not run this zfs command. Use root, or see TrueNAS SCALE.
uri-mismatch LIBVIRT_URI names a different host or user than the SSH fields. Make them agree, or clear the SSH fields so both come from the URI.
zfs-error zfs reported another error. The details show its message.
propagation-missing New mounts on the host do not reach the container. Set the Access Mode of Host Data to Read/Write - Slave and restart BombVault.
invalid-name A dataset name BombVault does not accept. Rename the dataset.
name-too-long A dataset in the tree is too long for a snapshot name. Rename it, or add a dataset below it as the entry.
invalid-exclude An exclude pattern or a left-out child does not fit the entry. Fix the entry the message names. To leave out a whole child dataset, switch it off instead of writing a pattern.
not-found The dataset does not exist on the server. Remove the entry, or recreate the dataset. Its backups stay restorable.
not-filesystem This is a volume, not a filesystem. See Volumes.
overlaps-item The dataset overlaps an existing entry. See Entries never overlap.
docker-storage The tree holds Docker's image storage. See Docker's storage.
nothing-readable No dataset in the entry can be read right now. Look at the skipped datasets' codes.
snapshot-failed The snapshot could not be created. The details show zfs's message.
containers-busy A container backup was still running when the containers had to stop. Start again later. Scheduled runs wait on their own.
consistency-stop-failed A container could not be stopped, so no snapshot was taken. Check the container, or take it off the list.
pre-snapshot-failed The command before the snapshot failed. The run details show its output.
container-unknown A listed container does not exist. Remove it from the list.
container-is-self BombVault cannot stop its own container. Remove it from the list.
leftover-snapshots Snapshots BombVault could not remove are still on the server. Press Remove now, see Leftover snapshots.
zvol A volume in the tree, skipped. See Volumes.
canmount-off Never mounted (canmount=off), skipped. If it holds data, mount it or move the data into a child dataset.
legacy-mount Legacy mountpoint, skipped. Give it a mountpoint below /mnt.
no-mountpoint No mountpoint, skipped. Give it a mountpoint below /mnt.
not-mounted Not mounted on the server, skipped. zfs mount it, or set canmount=on.
key-not-loaded Encrypted and the key is not loaded, skipped. zfs load-key, then mount it.
snapdir-disabled Snapshot access is switched off, skipped. zfs set snapdir=hidden <dataset>. The .zfs folder stays hidden.
not-visible BombVault cannot see the dataset's mountpoint. Move the mountpoint below the Host Data path, or map it into the container at the same path with Read/Write - Slave.
shfs-only The dataset is only visible through /mnt/user, which hides snapshots. Map /mnt, not /mnt/user, as Host Data.
snapshot-not-visible The snapshot was created but did not appear inside BombVault. Run Test snapshot access. See below.
snapshot-loop The snapshot did not reach BombVault because Host Data does not pass new mounts through. Set the Access Mode of Host Data to Read/Write - Slave and restart BombVault.
backup-failed restic failed for this dataset. The run details show why.
not-reached The run ended before this dataset. Run the backup again.
gone The dataset is no longer on the server. Nothing. Its backups stay restorable.
read-only-mount BombVault can only read the dataset, so it cannot restore into it. Set the mapping to Read/Write - Slave, or restore to a folder.
destination-not-mounted The folder is not on a mounted pool or share. Choose a folder on a pool or share.
not-enough-space Not enough free space at the destination. Free space or choose another folder.
safety-snapshot-failed The safety snapshot could not be taken, so nothing was restored. The details show zfs's message.
safety-name-too-long The dataset name is too long for a safety snapshot. Switch the safety snapshot off, or restore to a folder.
dataset-exists A dataset with this name already exists. Choose a new name, or restore into the dataset itself.
create-failed The new dataset could not be created. The details show zfs's message. Check that the dataset above it exists.
new-dataset-not-visible The new dataset was created, but BombVault cannot see it, so nothing was restored. The dataset stays on the server. Mount it below the Host Data path and restore into it.
set-properties-failed The stored properties could not be set, so nothing was restored. The details show zfs's message.
set-limits-failed The files were restored, but the stored quota or reservation could not be set. The details show zfs's message. Set the quota or reservation yourself with zfs set.

Checking what the container sees

Test snapshot access on the entry's Settings tab takes a real snapshot of its tree, looks for it inside BombVault for every dataset, and removes it again. It is the quickest way to prove the whole path before the first scheduled run.

To look yourself, run this on the server:

docker exec BombVault grep zfs /proc/self/mountinfo

Each line is one mount inside the container. The line of a dataset shows its path inside the container (below /host/user) and the dataset name. A master:N field on that line means the mount receives the mounts the host makes later, which is what snapshot access needs. When it is missing, set the Access Mode of Host Data to Read/Write - Slave and restart BombVault.

TrueNAS SCALE

  • When LIBVIRT_URI is set (as for VM backups on TrueNAS), BombVault takes the SSH host, user and port for its zfs commands from the URI, each one that is not set on its own. Without VM backups nothing has to be set: host.docker.internal does not resolve in a TrueNAS app, so BombVault reaches the host through the app's default gateway, as root on port 22. Set LIBVIRT_HOST, LIBVIRT_SSH_USER and LIBVIRT_SSH_PORT when you want another address or user, in the app's environment.
  • Add the Host SSH key from Settings, Integrations, Host SSH to root under Credentials, Users, and turn on the SSH service under System, Services. A replica to this or another TrueNAS needs the replica key as well, which is a different one.
  • A user other than root needs permission on the entry's top dataset, which then covers every dataset below it:
zfs allow <user> snapshot,destroy,mount <dataset>

Restoring into a new dataset also needs create on the dataset above it, and setting stored properties needs permission for those properties.

A non-root SSH session on TrueNAS does not have /usr/sbin in its path. BombVault then calls /usr/sbin/zfs directly. - The app's Host Data must be a host path above the datasets, for example /mnt/tank, not an ixVolume. With a host path the app passes the host's new mounts on to BombVault (rslave), which snapshot access needs. See TrueNAS SCALE for the whole app setup.