dsnap-sync

About

dsnap-sync is implemented as a posix shell script (dash). It takes advantage of the specific functionality of a btrfs file system and makes it possible to backup data while sending incremental snapshots to another drive. It's fine to store to dives on a remote host (using ssh).

Plug in and mount any btrfs-formatted device you want your system to be backed up to (eg. local USB drive, remote RAID drives).

dsnap-sync will support interactive an time scheduled backup runs.

• An interactive run will request you to select a mounted btrfs device. You can pre-select the target drive via command line options. Either use the UUID, the SUBVOLID or it's TARGET (read 'mount point').

• A scheduled run will take all needed parameters from config options.

For a backup run, dsnap-sync will iterate through all defined snapper configurations found on your source system. If you prefer to just run on a specific configuration, you can select this using the 'config' option -c. For each selected configuration it will use snapper to create an appropriate local snapshot.

We do also support systemd.timer units. Please refer to related paragraph below.

Requirements

dsnap-syncrelies on external tools to achieve its goal. At run-time their availability is checked. Following tools are are used:

• snapper
• awk
• sed
• notify-send

Installation

# make install

If your system uses a non-default location for the snapper configuration file, specify it on the command line with SNAPPER_CONFIG. For example, for Arch Linux use:

# make SNAPPER_CONFIG=/etc/conf.d/snapper install

The local snapper configuration will be extended to make use of a new template 'dsnap-sync'.

The package is also available in the AUR.

Options

Usage: dsnap-sync [options]

Options:
 -d, --description <desc> Change the snapper description. Default: "latest incremental backup"
 -c, --config <config>    Specify the snapper configuration to use. Otherwise will perform for each snapper
                          configuration. Can list multiple configurations within quotes, space-separated
                          (e.g. -c "root home").
 -n, --noconfirm          Do not ask for confirmation for each configuration. Will still prompt for backup
                          directory name on first backup
 -u, --uuid <UUID>        Specify the UUID of the mounted BTRFS subvolume to back up to. Otherwise will prompt.
     --UUID <UUID>        If multiple mount points are found with the same UUID, will prompt user.
 -s, --subvolid <subvlid> Specify the subvolume id of the mounted BTRFS subvolume to back up to. Defaults to 5.
     --SUBVOLID
 -t, --target <target>    Specify the mountpoint of the BTRFS subvolume to back up to.
     --TARGET <target>
     --remote <address>   Send the snapshot backup to a remote machine. The snapshot will be sent via ssh. You
                          should specify the remote machine's hostname or ip address. The 'root' user must be
                          permitted to login on the remote machine.
     --dry-run            perform a trial run with no changes made.
 -v, --verbose            Be more verbose on what's going on.

First run

If you have never synced to the paticular target device (first run), dsnap-sync will take care to create the necessary target file-structure to store the snapshot. As an option you can prepend a backup-path.

Before the sync job is started, source and target locations will be presented. You have to confirm any further operation, or use defaults (option: noconfirm).

Example command line usage

dsnap-sync to local target

Default: no selections, run for all snapper configs

# dsnap-sync

Default: Select two configs, the backupdir and verbose output

# dsnap-sync --verbose --config root --config data2 --backupdir=toshiba_r700

Dry-run: Select config, select Target, as batchjob (--noconfirm)

# dsnap-sync  -c root -s 265 --noconfirm --dry-run

dsnap-sync to remote host

dsnap-sync will rely on ssh access to the target host. For batch usage make sure, that your public key is accepted for remote login as user 'root'. You may have to adapt /root/.ssh/authorized_keys on the target host.

On your target host, you should also verify the availability of a dsnap-sync config-template for snapper. A template dsnap-sync is included in the package for your convenience.

Dryrun: Select remote host <ip/fqdn>, interactive, run for all configs

dsnap-sync --dry-run --remote 172.16.0.3
Selecting a mounted BTRFS device for backups on 172.16.0.3.
  0) / (uuid=5af3413e-59ea-4862-8cff-304afe25420f,subvolid=257,subvol=/root)
  1) /.snapshots (uuid=5af3413e-59ea-4862-8cff-304afe25420f,subvolid=258,subvol=/@snapshots-root)
  2) /data2 (uuid=62a45211-9197-4a5f-aeaf-0ab803a42c32,subvolid=261,subvol=/data2)
  3) /home (uuid=62a45211-9197-4a5f-aeaf-0ab803a42c32,subvolid=258,subvol=/home)
  4) /data2/.snapshots (uuid=62a45211-9197-4a5f-aeaf-0ab803a42c32,subvolid=262,subvol=/@snapshots-data2)
  5) /home/.snapshots (uuid=62a45211-9197-4a5f-aeaf-0ab803a42c32,subvolid=259,subvol=/@snapshots-home)
  6) /var/lib/machines (uuid=2ba04452-74aa-44df-b1c7-74e0a70c6543,subvolid=260,subvol=/machines)
  7) /var/lib/libvirt (uuid=2ba04452-74aa-44df-b1c7-74e0a70c6543,subvolid=261,subvol=/libvirt)
  8) /data (uuid=2ba04452-74aa-44df-b1c7-74e0a70c6543,subvolid=257,subvol=/data)
  9) /var/lib/machines/.snapshots (uuid=2ba04452-74aa-44df-b1c7-74e0a70c6543,subvolid=2121,subvol=/@snapshots-machines)
 10) /data/.snapshots (uuid=2ba04452-74aa-44df-b1c7-74e0a70c6543,subvolid=258,subvol=/@snapshots-data)
 11) /var/lib/dsnap-sync (uuid=753eba7a-41ce-49e0-b2e3-24ee07811efd,subvolid=420,subvol=/dsnap-sync)
  x) Exit
Enter a number: 11

Dry-run with given Target for snapper config 'home', no confirmations

Sync: Select config 'data2', remote host <ip/fqdn>, target '/data', as batchjob (--noconfirm)

# dsnap-sync --config data2 --remote 172.16.0.3 --target /data --noconfirm

systemd example

service

[Unit]
Description=Run dsnap-sync backup

[Install]
WantedBy=multi-user.target

[Service]
Type=simple
ExecStart=/usr/bin/dsnap-sync --UUID 7360922b-c916-4d9f-a670-67fe0b91143c --subvolid 5 --noconfirm

timer

[Unit]
Description=Run dsnap-sync weekly

[Timer]
OnCalendar=weekly
AccuracySec=12h
Persistent=true

[Install]
WantedBy=timers.target

snapper template

###
# template for dsnap-sync handling
###

# subvolume to snapshot
SUBVOLUME="/var/lib/dsnap-sync"

# filesystem type
FSTYPE="btrfs"

# users and groups allowed to work with config
ALLOW_USERS=""
ALLOW_GROUPS="adm"

# sync users and groups from ALLOW_USERS and ALLOW_GROUPS to .snapshots
# directory
SYNC_ACL="yes"

# start comparing pre- and post-snapshot in background after creating
# post-snapshot
BACKGROUND_COMPARISON="yes"

# run daily number cleanup
NUMBER_CLEANUP="no"

# limit for number cleanup
NUMBER_MIN_AGE="1800"
NUMBER_LIMIT="10"
NUMBER_LIMIT_IMPORTANT="2"

# use systemd.timer for timeline
TIMELINE_CREATE="no"

# use systemd.timer for cleanup
TIMELINE_CLEANUP="no"

# dsnap-sync as timer unit
SNAP_SYNC_EXCLUDE="yes"

Contributing

Help is very welcome! Feel free to fork and issue a pull request to add features or tackle open issues.

Related projects

I did fork from Wes Barnetts original work and wanted that to be merged back. Beside the fact that this version doesn't use any bashisms, Wes did let me know, that he doesn't have the time to review the changes appropriately to make it a merge. Anyone willing to do so is invided.

Until that date, i will offer this fork for the public. To overcome any name clashes i renamed this work to dsnap-sync.

License

This work is licensed under a Creative Common License 4.0

© 2016, 2017 James W. Barnett © 2017 - 2018 Ralf Zerres