'\" t
.TH SNAP-SYNC 8 2021-01-24 SNAP-SYNC
.SH NAME
snap-sync \- send incremental btrfs snapshots, keeping track of them with snapper

.SH SYNOPSIS
.B snap-sync
[\fB-c\fR \fIconfig\fR] 
[\fB-d\fR \fIdesc\fR] 
[\fB-n\fR] 
[\fB-r\fR \fIaddress\fR] 
[\fB-p\fR \fIport\fR] 
[\fB--sudo\fR]
[\fB-s\fR \fIsubvolid\fR] 
[\fB-u\fR \fIUUID\fR]
[\fB-k\fR]
[\fB-q\fR]

.SH DESCRIPTION

This program sends incremental snapshots to another drive for backing up data. Plug in
and mount any btrfs-formatted device you want your system to be backed up to (like a
USB drive). When you run the script you will be prompted to select a mounted btrfs
device, or you can optionally select the disk using its UUID on the command line.

The script iterates through all snapper configurations by default (this can be changed
using the \fI-c\fR flag). For each configuration it creates a new local snapshot. If you
have never synced to the specified device you will be prompted to enter a directory on
the device where the backup snapshots will go. Additionally you are shown the location
of the backed up snapshot. If you have performed a backup to this device before, only
the changes since the last backup have to be sent.

Use `snapper` to view the snapshots for a subvolume you have backed up. A snapshots with
the description `Latest incremental backup` is kept on our local machine so that the
next time `snap-sync` runs it will only transfer the difference between it and a new
snapshot. Don't manually delete that snapshot unless you want to do an entirely new
backup, transferring all of the data again.

.SH OPTIONS

\fB\-c, \-\-config\fR \fIconfig\fR    
.RS 4
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").  
.RE
.PP

\fB\-d, \-\-description\fR \fIdesc\fR 
.RS 4
Change the snapper description. Default: "latest incremental backup"
.RE
.PP

\fB\-h, \-\-help\fR
.RS 4
Print the help message.
.RE
.PP

\fB\-n, \-\-noconfirm
.RS 4
Do not ask for confirmation for each configuration. Will still prompt for backup
directory name on first backup.
.RE
.PP

\fB\-k, \-\-keepold\fR
.RS 4
Keep the most recent local snapshot which is no longer needed.  By default, after a
backup is performed for a snapper configuration, the previous local snapshot is deleted
since a new local snapshot is created. It's not necessary to keep all of those
snapshots, but if you pass this flag, it will be kept.
.RE
.PP

\fB\-p, \-\-port\fR \fIport\fR
.RS 4
The remote port. Used with \fB--remote\fR.
.RE
.PP

\fB\-q, \-\-quiet\fR
.RS 4
Do not send notifications to notify system if it is available. Instead print
notifications to stdout.
.RE
.PP

\fB\-r, \-\-remote\fR \fIaddress\fR
.RS 4
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.
.RE
.PP

\fB\-\-sudo\fR
.RS 4
Use sudo on the remote machine. Only valid when used with the \fB\-\-remote\fR flag.
.RE
.PP

\fB\-s, \-\-subvolid\fR \fIsubvolid\fR
.RS 4
Specify the subvolume id of the mounted BTRFS subvolume to back up to. Defaults to 5.
.RE
.PP

\fB\-u, \-\-UUID\fR \fIUUID\fR
.RS 4
Specify the UUID of the mounted BTRFS subvolume to back up to. Otherwise will prompt.
If multiple mount points are found with the same UUID and subvolid, will prompt user.
.RE
.PP

.SH EXAMPLES
.PP
\fBsnap-sync\fR
.RS 4
Get prompted interactively on what disks to backup to and what snapshots to send.
.RE

.PP
.B
snap-sync 
\fB--UUID\fR \fI7360922b-c916-4d9f-a670-67fe0b91143c\fR \fB--subvolid\fR \fI5\fR
\fB--noconfirm\fR
.RS 4
Specify the UUID and subvolume of the external disk, backing up all subvolumes with a
snapper configuration without promptin for confirmation.
.RE

.SH FAQ
.SS How do I run this program on a schedule automatically?
You can create systemd unit and timer. Here is an example service:

.EX

    [Unit]
    Description=Run snap-sync backup 

    [Install]
    WantedBy=multi-user.target

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

.EE

And here is its corresponding timer:

.EX

    [Unit]
    Description=Run snap-sync weekly

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

    [Install]
    WantedBy=timers.target

.EE


.SH HOMEPAGE
https://github.com/wesbarnett/snap-sync

.SH AUTHORS
Wes Barnett wes@wbarnett.us

.SH SEE ALSO
.BR btrfs-send (8),
.BR snapper (8)