btrbk is a backup tool for Btrfs disks.

Warning Warning: This page is a work in progress and is not completed. Important informations might be missing or wrong.

Setup Server

The backup server will be the machine that will receive the backup data. Clients will connect to it to sent their backup data. As a consequence, your server must be reachable from all your clients.

Destination Disk

Create a Btrfs volume or subvolume and mount it on /backup.


$ sudo adduser --system --shell /bin/sh --home /backup/ --group --no-create-home btrbk
Adding system user `btrbk' (UID 122) ...
Adding new group `btrbk' (GID 124) ...
Adding new user `btrbk' (UID 122) with group `btrbk' ...
Not creating home directory `/backup/'.
$ sudo mkdir /backup/.ssh
$ sudo touch /backup/.ssh/authorized_keys
$ sudo chown root:btrbk /backup/
$ sudo chmod 710 /backup/

This user will need to run btrfs tools as root. Let’s add this to the /etc/sudoers file

btrbk   ALL=NOPASSWD:/bin/btrfs

If you limited access to certain users through SSH, add btrbk to the AllowUsers list and restart SSH

Setup Client

Install btrbk

btrbk is not yet included in Debian Jessie. Make sure you configure stretch source before running the command bellow.

$ sudo apt install btrbk


Create an SSH key dedicated to your backups

$ sudo mkdir /etc/btrbk/ssh
$ sudo chmod 700 /etc/btrbk/ssh
$ sudo ssh-keygen -t ed25519 -N "" -f /etc/btrbk/ssh/id_ed25519
Generating public/private ed25519 key pair.
Your identification has been saved in /etc/btrbk/ssh/id_ed25519.
Your public key has been saved in /etc/btrbk/ssh/
The key fingerprint is:
The key's randomart image is:
+--[ED25519 256]--+
|    .            |
|   o + . .       |
|    + + o o .    |
|   . o + . +     |
|  . . ooS.o      |
| . ....Eoo..     |
|o .. o oo o.     |
|oo*.o.  *=...    |
|*X==. .+.+=.     |
$ sudo cat /etc/btrbk/ssh/

Keep the result of the last command, you will need it at the next step.

Register Client on the Server

Note: On the instructions bellow, the token <client> must be replace by the machine name.

Create Destination Folder

On the backup server, create a new folder for the client.

$ sudo mkdir /backup/<client>
$ sudo chmod 700 /backup/<client>

Setup SSH Key

Then, on the backup server, add the following line to /backup/.ssh/authorized_keys. The key at the end of the line must be replaced with the public key that you created above.

If you have OpenSSH 7.2 or above (test using ssh -V), use this line

command="/usr/share/btrbk/scripts/ --target --info -p /backup/<client> --sudo",restrict ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIB5ScAgJnpqYCipj6PyrOjbXpsaQZIzys7uHcVe1J3ay

Otherwise, you need the more verbose version

command="/usr/share/btrbk/scripts/ --target --info -p /backup/<client> --sudo",no-agent-forwarding,no-port-forwarding,no-pty,no-user-rc,no-X11-forwarding ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIB5ScAgJnpqYCipj6PyrOjbXpsaQZIzys7uHcVe1J3ay

Configure btrbk

Create file /ect/btrbk/btrbk.conf

# Enable transaction log
transaction_log             /var/log/btrbk.log

# Directory in which the btrfs snapshots are created. Relative to
# <volume-directory> of the volume section.
# If not set, the snapshots are created in <volume-directory>.
# If you want to set a custom name for the snapshot (and backups),
# use the "snapshot_name" option within the subvolume section.
# NOTE: btrbk does not autmatically create this directory, and the
# snapshot creation will fail if it is not present.
snapshot_dir                _btrbk_snap

# Specify SSH private key for "ssh://" volumes / targets:
ssh_identity                /etc/btrbk/ssh/id_ed25519
ssh_user                    btrbk
#ssh_port                   default
#ssh_compression            no
#ssh_cipher_spec            default

# Don't wait for transaction commit on deletion. Set this to "after"
# or "each" to make sure the deletion of subvolumes is committed to
# disk when btrbk terminates.
#btrfs_commit_delete        no

# Set this to "yes" to enable btrfs-progs < 3.17 compatibility.
# Set this either globally or in a specific "target" section.
#btrfs_progs_compat         no

snapshot_preserve_min 5d
snapshot_preserve     14d 2w 1m

target_preserve_min 5d
target_preserve     14d 10w 24m

# Volume section: "volume <volume-directory>"
#   <volume-directory>  Directory of a btrfs volume (or subvolume)
#                       containing the subvolume to be backuped
#                       (usually the mount-point of a btrfs filesystem
#                       mounted with subvolid=0 option)
# Subvolume section: "subvolume <subvolume-name>
#   <subvolume-name>    Subvolume to be backuped, relative to
#                       <volume-directory> in volume section.
# Target section: "target <type> <volume-directory>"
#   <type>              Backup type, currently only "send-receive".
#   <volume-directory>  Directory of a btrfs volume (or subvolume)
#                       receiving the backups.
# NOTE: The parser does not care about indentation, this is only for
# human readability. The options always apply to the last section
# encountered, overriding the corresponding option of the upper
# section. This means that the global options must be set before any
# "volume" section.

Add a Backup Volume

$ sudo btrfs subvolume create /backup/<client>/<volume>