borgmatic

How to snapshot your filesystems

Filesystem hooks

Many filesystems support taking snapshots—point-in-time, read-only "copies" of your data, ideal for backing up files that may change during the backup. These snapshots initially don't use any additional storage space and can be made almost instantly.

To help automate backup of these filesystems, borgmatic can use them to take snapshots.

ZFS

New in version 1.9.3 Beta feature borgmatic supports taking snapshots with the ZFS filesystem and sending those snapshots to Borg for backup.

To use this feature, first you need one or more mounted ZFS datasets. Then, enable ZFS within borgmatic by adding the following line to your configuration file:

zfs:

No other options are necessary to enable ZFS support, but if desired you can override some of the commands used by the ZFS hook. For instance:

zfs:
    zfs_command: /usr/local/bin/zfs
    mount_command: /usr/local/bin/mount
    umount_command: /usr/local/bin/umount

As long as the ZFS hook is in beta, it may be subject to breaking changes and/or may not work well for your use cases. But feel free to use it in production if you're okay with these caveats, and please provide any feedback you have on this feature.

Dataset discovery

You have a couple of options for borgmatic to find and backup your ZFS datasets:

If you have multiple borgmatic configuration files with ZFS enabled, and you'd like particular datasets to be backed up only for particular configuration files, use the source_directories option instead of the user property.

During a backup, borgmatic automatically snapshots these discovered datasets (non-recursively), temporary mounts the snapshots within its runtime directory, and includes the snapshotted files in the paths sent to Borg. borgmatic is also responsible for cleaning up (destroying) these snapshots after a backup completes.

Additionally, borgmatic rewrites the snapshot file paths so that they appear at their original dataset locations in a Borg archive. For instance, if your dataset is mounted at /mnt/dataset, then the snapshotted files will appear in an archive at /mnt/dataset as well.

With Borg version 1.2 and earlierSnapshotted files are instead stored at a path dependent on the runtime directory in use at the time the archive was created, as Borg 1.2 and earlier do not support path rewriting.

Extract a dataset

Filesystem snapshots are stored in a Borg archive as normal files, so you can use the standard extract action to extract them.

Btrfs

New in version 1.9.4 Beta feature borgmatic supports taking snapshots with the Btrfs filesystem and sending those snapshots to Borg for backup.

To use this feature, first you need one or more Btrfs subvolumes on mounted filesystems. Then, enable Btrfs within borgmatic by adding the following line to your configuration file:

btrfs:

No other options are necessary to enable Btrfs support, but if desired you can override some of the commands used by the Btrfs hook. For instance:

btrfs:
    btrfs_command: /usr/local/bin/btrfs
    findmnt_command: /usr/local/bin/findmnt

As long as the Btrfs hook is in beta, it may be subject to breaking changes and/or may not work well for your use cases. But feel free to use it in production if you're okay with these caveats, and please provide any feedback you have on this feature.

Subvolume discovery

For any subvolume you'd like backed up, add its path to borgmatic's source_directories option. During a backup, borgmatic snapshots these subvolumes (non-recursively) and includes the snapshotted files in the paths sent to Borg. borgmatic is also responsible for cleaning up (deleting) these snapshots after a backup completes.

Additionally, borgmatic rewrites the snapshot file paths so that they appear at their original subvolume locations in a Borg archive. For instance, if your subvolume exists at /mnt/subvolume, then the snapshotted files will appear in an archive at /mnt/subvolume as well.

With Borg version 1.2 and earlierSnapshotted files are instead stored at a path dependent on the temporary snapshot directory in use at the time the archive was created, as Borg 1.2 and earlier do not support path rewriting.

Extract a subvolume

Subvolume snapshots are stored in a Borg archive as normal files, so you can use the standard extract action to extract them.

Improve this documentation

Have an idea on how to make this documentation even better? Use our issue tracker to send your feedback!