--- name: "snbk" section: "8" platform: "linux" package: "snapper" version: "0.13.2-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/snbk" --- # snbk(8) Command-line program to backup snapshots of snapper ## NAME snbk - Command-line program to backup snapshots of snapper ## SYNOPSIS **snbk** \[*--global-opts*\] *command* \[*command-arguments*\] **snbk** {--help} ## DESCRIPTION Snbk is a command-line program to backup snapshots of snapper. It can transfer and delete backup snapshots on local and remote btrfs filesystems. ## CONCEPTS ### Backup Configurations For each snapper config there can be several backup configs. Each backup config defines backups of the snapper snapshots at one location, either local or remote, see [**snapper-backup-configs**(5)](/snapper-backup-configs/5.md) for possible settings. ### Snapshot Statuses Each snapshot has a status on the source and on the target. Possible values for the source are: (empty) The snapshot is missing and thus considered obsolete on the target. It will be deleted on the target by the next delete command. read-only The snapshot is read-only. read-write The snapshot is read-write and thus cannot be backed-up. Possible values for the target are: (empty) The snapshot is missing. If the source snapshot is read-only it will be transferred to the target by the next transfer command. valid The snapshot is valid. That implies it is read-only. invalid The snapshot is invalid. Either the received UUID is wrong or it is read-write. That can happen if the transfer was interrupted. The next transfer command will try to transfer the snapshot again. legacy The snapshot is valid, but the source snapshot's metadata has changed since the transfer. The next transfer command will update the snapshot's metadata on the target. ### Visualization Snbk provides a *visualize* command for producing graphs in Graphviz DOT format for visualization purposes. Currently, producing tree diagrams for snapshots on both the source and the target is supported. The command output can be piped to the Graphviz tools to generate an image. Here is an example of producing a tree diagram for snapshots on the source side with the 'root' backup config: ``` # snbk -b root visualize source-tree | dot -T png -o root-source-tree.png ``` In the tree diagram for snapshots, a node has the properties *virtual* and *valid*. A virtual node means the corresponding Btrfs subvolume is not managed by a Snapper snapshot. A valid node means the node exists on both the source and target sides, and can be used as a valid Btrfs send parent to reduce disk usage during snapshot transfer or restoration. The root node of the diagram is a specialized virtual node, which is not a Btrfs subvolume, representing the Btrfs filesystem on the source or target. ### Highest Snapshot Number Synchronization To avoid reusing snapshot numbers, 'snapperd' keeps the highest snapshot folder (whether it is an empty snapshot or not) in .snapshots directory, ensuring snapshot numbers remain unique at all times. However, when performing a restore using various methods, the state of the highest snapshot number may vary: • Synchronized: The latest backed-up snapshot is restored to .snapshots using \`snbk restore\` or manual Btrfs send-receive. In this case, the highest snapshot number is synchronized. 'snapperd' creates snapshots with numbers greater than the restored snapshot, preventing snapshot number collisions. • Legacy: A restore is made with a previous but not the latest backed-up snapshot. In this case, the state of the highest snapshot number is not valid. 'snapperd' would create snapshots with numbers lower than the latest backed-up snapshot. This could invalidate the backed-up snapshots created later than the restored snapshot, and these invalid backed-up snapshots might be removed during the automatic Snapper backup process. • Legacy: When using a virtualization platform and the system is restored from a virtual machine backup. In this case, depending on the timing of the VM backup creation, the state of the highest snapshot number might not be synchronized. Snapshot number collisions might occur when 'snapperd' creates snapshots after the VM boots up. To avoid snapshot number collisions, The Snapper Backup package provides a 'snapper-sync' script, which can be triggered by \`snapper-sync.service\`, to synchronize the highest snapshot number across the source and backup target devices. Please consider enabling \`snapper-sync.service\` if any scenario related to 'Legacy' might occur in your environment. If any custom systemd timer or service is configured, please consider adding the following directives: ``` [Unit] After=snapper-sync.service ``` This ensures systemd schedules the custom unit to run after the highest snapshot number synchronization. ## GLOBAL OPTIONS - **-q, --quiet** Suppress normal output. Error messages will still be printed, though. - **-v, --verbose** Increase verbosity. - **--debug** Turn on debugging. - **--utc** Display dates and times in UTC. By default, local time is used. - **--iso** Display dates and times in ISO format. ISO format is always used for machine-readable outputs. - **-t, --table-style** *style* Specifies table style. Table style is identified by an integer number. - **--machine-readable** *format* Specifies a machine-readable output format. Possible options are csv and json. - **--csvout** Sets CSV output format. For some commands the CSV output contains more information than the default table output. See **RFC 4180**\[1\] for the details, except lines end with a LF, not CR+LF. - **--jsonout** Sets JSON output format. For some commands the JSON output contains more information than the default table output. - **--separator** *character* Specifies the character separator for CSV output format. - **--no-headers** Suppress headers for CSV output format. - **-b, --backup-config** *name* Use specified configuration instead of all configurations. - **--no-dbus** Operate without a DBus connection. Use with caution. - **--target-mode** *name* Only operate on backup configs with the specified target mode. - **--automatic** Only operate on backup configs which have the automatic flag set. - **--version** Print version and exit. ## COMMANDS Snbk provides a number of *commands*. Each command accepts the options listed in the GLOBAL OPTIONS section. These options must be specified *before* the command name. In addition, many commands have specific arguments, which are listed in this section. These command-specific arguments must be specified *after* the name of the command. **help** Show short help text. **list-configs** List available configurations. **list (ls)** List snapshots. **transfer \[***number***\]** Transfer all missing snapshots or the specified snapshot to the target. **restore \[***number***\]** Restore all missing snapshots or the specified snapshot back to the source. A backup config must be specified to run this command. A restart of the \`snapperd\` service is required to make the restored snapshots visible immediately. **delete (remove\|rm) \[***number***\]** Delete all obsolete snapshots or the specified snapshot from the target. **transfer-and-delete** Combines transfer and delete. **visualize \[options\]** *mode* Produce a Graphviz graph with the specified *mode*. See Visualization for more detail. - **-r, --rankdir** *rankdir* The 'rankdir' diagram attribute of Graphviz. Defaults to 'LR'. **source-tree** Produce a tree diagram of the snapshots on the source. **target-tree** Produce a tree diagram of the snapshots on the target. ## RESTORE Snapshots can be restored using the restore command. There are more methods to do a restore, e.g. the backup can be mounted and then copied or rsync can be used. Here we provide an example on how to manually use btrfs send and receive to restore a snapshot on the source system. In general using btrfs send and receive is a bit tricky. When using target-mode local: ``` # mkdir /.snapshots/42 # cp /backups/root/42/info.xml /.snapshots/42/ # btrfs send /backups/root/42/snapshot | btrfs receive /.snapshots/42 ``` When using target-mode ssh-push: ``` # mkdir /.snapshots/42 # scp backups.example.com:/backups/eberich/root/42/info.xml /.snapshots/42 # ssh backups.example.com btrfs send /backups/eberich/root/42/snapshot | btrfs receive /.snapshots/42 ``` If the system was reinstalled it is unfortunately in general not possible to simply use the restored snapshot as the new default snapshot since some files, e.g. /etc/fstab, likely need modifications. Also unfortunately for other subvolumes than root a rollback is not supported. If there are snapshots on the source to speed up the operation you can also use the -p option for btrfs send. ## NOTES The content of snapshots transferred must not be changed on the source system. Normally this is ensured since the snapshots are read-only. But it is possible to change snapshots to read-write. This can cause error during transfers in the future. ## PERMISSIONS Since the target-mode ssh-push needs root permissions on the target it is recommended to use a dedicated machine or container as a target. ## FILES /etc/snapper/backup-configs Directory containing configuration files. ## EXIT STATUS Normally the exit status is 0. If an error occurred the exit status is 1. ## HOMEPAGE **http://snapper.io/** ## AUTHORS Arvin Schnell \ ## SEE ALSO [**snapper-backup-configs**(5)](/snapper-backup-configs/5.md), [**snapper**(8)](/snapper/8.md), [**btrfs-send**(8)](/btrfs-send/8.md), [**btrfs-receive**(8)](/btrfs-receive/8.md) [**rsync**(1)](/rsync/1.md), [**sshfs**(1)](/sshfs/1.md) ## NOTES - 1\. RFC 4180 https://tools.ietf.org/html/rfc4180