add -r option and sample configurations

Implement the '-r N' option to use the Nth most recent local snapshot
instead of the newest.  This is useful for avoiding short-lived (e.g.
hourly) snapshots during a long-running backup, e.g. if the backup
hasn't run for a while.

Also add some sample configuration files, for normal and catchup use.

Author: adaugherity

README

@@ -8,12 +8,22 @@ snapshots continue to be taken even if the backup fails.  It does not
 necessarily require that package -- anything that regularly generates
 snapshots that follow a given pattern will suffice.
 
+Command-line options:
+  -n		debug/dry-run mode
+  -v		verbose mode
+  -f file	specify a configuration file
+  -r N		use the Nth most recent local snapshot rather than the newest
+  -h, -?	display help message
+
 
 Basic installation: After following the prerequisites, run manually to verify
 operation, and then add a line like the following to zfssnap's crontab:
-30 * * * * /path/to/zfs-backup.sh
+30 * * * * /path/to/zfs-backup.sh [ options ]
 (This for an hourly sync -- adjust accordingly if you only want to back up
-daily, etc.)
+daily, etc.  zfs-backup now supports commandline options and configuration
+files, so you can schedule different cron jobs with different config files,
+e.g. to back up to two different targets.  If you schedule multiple cron
+jobs, you should use different lockfiles in each configuration.)
 
 This aims to be much more robust than the backup functionality of
 zfs-auto-snapshot, namely:
@@ -27,21 +37,23 @@ zfs-auto-snapshot, namely:
 
 PREREQUISITES:
 1. zfs-auto-snapshot or equivalent package installed locally and regular
-   snapshots enabled (hourly, daily, etc.)
-2. home directory set for zfssnap role
+  snapshots enabled (hourly, daily, etc.)
+2. home directory set for zfssnap role (the user taking snapshots and doing
+  the sending)
 3. ssh keys set up between zfssnap@localhost and remuser@remhost
 4. zfs allow done for remuser on remhost
   (see http://mail.opensolaris.org/pipermail/zfs-auto-snapshot/2009-November/000198.html
   for guidance on #2-4; you may need to also allow further permissions such as
   sharenfs, userprop, hold, etc.)
 5. an initial (full) zfs send/receive done so that remhost has the fs we
-   are backing up, and the associated snapshots -- something like:
+  are backing up, and the associated snapshots -- something like:
   zfs send -R $POOL/$FS@zfs-auto-snap_daily-(latest) | ssh $REMUSER@$REMHOST zfs recv -dvF $REMPOOL
+  Note: 'zfs send -R' will send *all* snapshots associated with a dataset, so
+  if you wish to purge old snapshots, do that first.
 6. zfs allow any additional permissions needed, to fix any errors produced in step 5
 7. configure the tag/prop/remuser/remhost/rempool variables in this script or in a config file
-  (and update the CFG=... line accordingly)
 8. zfs set $PROP={ fullpath | basename } pool/fs
-   for each FS or volume you wish to back up.
+  for each FS or volume you wish to back up.
 
 PROPERTY VALUES:
 Given the hierarchy pool/a/b,
@@ -59,8 +71,15 @@ It's probably best to do a dry-run first (zfs recv -ndvF).
 
 Note: I use daily snapshots in these manual send/recv examples because
 it is less likely that the snapshot you are using will be rotated out
-in the middle of a send.  Also, ZFS will send all snapshots for a given
-filesystem before sending any for its children.
+in the middle of a send.  Also, note that ZFS will send all snapshots for a
+given filesystem before sending any for its children, rather than going in
+global date order.
+
+Alternatively, use a different tag (e.g. weekly) that still has common
+snapshots, possibly in combination with the -r option (Nth most recent) to
+avoid short-lived snapshots (e.g. hourly) being rotated out in the middle
+of your sync.  This is a good use case for an alternate configuration file.
+
 
 PROCEDURE:
   * find newest local hourly snapshot

example-catchup.cfg

@@ -0,0 +1,15 @@
+# Use the standard backup settings, but use daily snapshots to catch up
+# in case of missed backups.
+
+# $0 the is backup script that sources this, but $1 is in fact this very file.
+. `dirname $1`/example.cfg
+
+TAG="zfs-auto-snap_daily"
+VERBOSE="-v"
+
+# Use the 3rd most recent daily snapshot, to avoid the hourly snapshots
+# entirely.  To override this and get the most recent snapshot (like -N in the
+# old zfs-bak-sync-daily script), use '-r 1' on the cmdline.  I recommend you 
+# first run it as-is, then run with -r 1 afterwards.  After that it should be
+# ready to re-enable the hourly backups.
+RECENT=3

example.cfg

@@ -0,0 +1,11 @@
+# sample configuration for hourly backups
+
+# Don't forget to schedule a cron job such as:
+# 30 * * * * /path/to/zfs-backup.sh /path/to/this.cfg
+
+TAG="zfs-auto-snap_hourly"
+LOCK="/var/tmp/zfsbackup.lock"
+# remote settings (on destination host)
+REMUSER="zfsbak"
+REMHOST="backupserver.local"
+REMPOOL="backuppool"

zfs-backup.sh

@@ -74,9 +74,20 @@ usage() {
     echo "  -n\t\tdebug (dry-run) mode"
     echo "  -v\t\tverbose mode"
     echo "  -f\t\tspecify a configuration file"
+    echo "  -r N\t\tuse the Nth most recent snapshot instead of the newest"
     echo "If the configuration file is last option specified, the -f flag is optional."
     exit 1
 }
+# simple ordinal function, does not validate input
+ord() {
+    case $1 in
+        1|*[0,2-9]1) echo "$1st";;
+        2|*[0,2-9]2) echo "$1nd";;
+        3|*[0,2-9]3) echo "$1rd";;
+        *1[123]|*[0,4-9]) echo "$1th";;
+        *) echo $1;;
+    esac
+}
 
 # Option parsing
 set -- $(getopt h?nvf:r: $*)
@@ -89,6 +100,7 @@ for opt; do
 	-n) dbg_flag=Y; shift;;
 	-v) verb_flag=Y; shift;;
 	-f) CFG=$2; shift 2;;
+	-r) recent_flag=$2; shift 2;;
 	--) shift; break;;
     esac
 done
@@ -108,6 +120,7 @@ fi
 # Set options now, so cmdline opts override the cfg file
 [ "$dbg_flag" ] && DEBUG=1
 [ "$verb_flag" ] && VERBOSE="-v"
+[ "$recent_flag" ] && RECENT=$recent_flag
 # set default value so integer tests work
 if [ -z "$RECENT" ]; then RECENT=0; fi
 
@@ -134,9 +147,15 @@ do_backup() {
 	return 2
     fi
 
-    newest_local="$(/usr/sbin/zfs list -t snapshot -H -S creation -o name -d 1 $DATASET | grep $TAG | head -1)"
+    if [ $RECENT -gt 1 ]; then
+	newest_local="$(/usr/sbin/zfs list -t snapshot -H -S creation -o name -d 1 $DATASET | grep $TAG | awk NR==$RECENT)"
+	msg="using local snapshot ($(ord $RECENT) most recent):"
+    else
+	newest_local="$(/usr/sbin/zfs list -t snapshot -H -S creation -o name -d 1 $DATASET | grep $TAG | head -1)"
+	msg="newest local snapshot:"
+    fi
     snap2=${newest_local#*@}
-    [ "$DEBUG" -o "$VERBOSE" ] && echo "newest local snapshot: $snap2"
+    [ "$DEBUG" -o "$VERBOSE" ] && echo "$msg $snap2"
 
     # needs public key auth configured beforehand
     newest_remote="$(ssh -n $REMUSER@$REMHOST /usr/sbin/zfs list -t snapshot -H -S creation -o name -d 1 $TARGET | grep $TAG | head -1)"
@@ -172,6 +191,15 @@ do_backup() {
 	return 0
     fi
 
+    # sanity checking of snapshot times -- avoid going too far back with -r
+    snap1time=$(zfs get -Hp -o value creation $DATASET@$snap1)
+    snap2time=$(zfs get -Hp -o value creation $DATASET@$snap2)
+    if [ $snap2time -lt $snap1time ]; then
+	echo "Error: target snapshot $snap2 is older than $snap1!"
+	echo "Did you go too far back with '-r'?"
+	return 1
+    fi
+
     if [ $DEBUG ]; then
 	echo "would run: /usr/sbin/zfs send -R -I $snap1 $DATASET@$snap2 |"
 	echo "  ssh $REMUSER@$REMHOST /usr/sbin/zfs recv $RECV_OPT -vF $REMPOOL"