snazzer-receive

#!/usr/bin/env sh
set -e
SNAZZER_VERSION=0.0.3
SNAZZER_SNAPSHOTZ_PERMS=0755

if [ "$(id -u)" = "0" ]; then
    SUDO=""
else
    SUDO="sudo"
fi

squote_args() {
    while [ -n "$1" ]; do
        printf "'"; printf '%s' "$1" | sed "s|'|'\\\\''|g"; printf "' "
        shift
    done
}

check_ssh_err() {
    HOST=$1
    CMD=$2
    STDERR=$3
    RC=$4

    if [ -s "$STDERR" ] && grep '^sudo:' "$STDERR"; then
        cat <<HERE >&2

ERROR running:
  ssh "$HOST" "$CMD"
  $(cat "$STDERR")

  Is the sudo invocation above permitted to run passwordless on this host? Check
  sudoers config against the snazzer documentation (hint: snazzer-receive --man)
HERE
        exit 12
    elif [ "$RC" = "0" ]; then
        cat "$STDERR" >&2
    else
        cat <<HERE >&2

ERROR running:
  ssh "$HOST" "$CMD"
  $(cat "$STDERR")
HERE
        exit "$RC"
    fi
}

do_ssh() {
    HOST=$1
    CMD=$2
    STDERR=$(mktemp)
    RC=0

    ssh "$HOST" "$CMD" 2>"$STDERR" || RC=$?
    check_ssh_err "$HOST" "$CMD" "$STDERR" "$RC"

    rm "$STDERR"
}

dry_list_snapshots() {
    HOST=$1
    shift
    if [ "$LOCAL_RUN" = "1" ]; then
        cat <<CMD1
    $SUDO snazzer --list-snapshots "$@"
CMD1
    else
        cat <<CMD2
    ssh "$HOST" "sudo -n snazzer --list-snapshots $(squote_args "$@")"
CMD2
    fi
}

do_list_snapshots() {
    HOST=$1
    shift
    if [ "$LOCAL_RUN" = "1" ]; then
    # Don't forget to copy the lines below into dry_list_snapshots between CMD1
        $SUDO snazzer --list-snapshots "$@"
    else
    # Don't forget to copy the lines below into dry_list_snapshots between CMD2
        do_ssh "$HOST" "sudo -n snazzer --list-snapshots $(squote_args "$@")"
    fi
}

list_remote_snapshot_measurements() {
    HOST=$1
    HOST_ESC=$(echo "$1" | sed "s|'|'\\\\''|g")
    SUBVOL=$2
    SUBVOL_ESC=$(echo "$SUBVOL" | sed "s|'|'\\\\''|g")
    if [ "$LOCAL_RUN" = "1" ]; then
        MEAS_LIST=$($SUDO grep -srl "^> on $HOST at " \
            "$SUBVOL/.snapshotz/.measurements/" || true)
    else
        # Beware whitespace in do_ssh arg affects send-wrapper sanity checks
        MEAS_LIST=$(do_ssh "$HOST" "sudo -n grep -srl '^> on $HOST_ESC at ' \
'$SUBVOL_ESC/.snapshotz/.measurements/'" || ( \
            RC=$?
            if [ "$RC" != "1" ]; then
                exit "$RC"
            fi))
    fi
    echo "$MEAS_LIST" | sed "s|^.*/||g"
}

dry_send() {
    HOST=$1
    SNAP_ABSPATH=$2
    SNAP_ABSPATH_ESC=$(echo "$SNAP_ABSPATH" | sed "s|'|'\\\\''|g")
    SNAP_PARENT_PATH=$3
    SNAP_PARENT_PATH_ESC=$(echo "$SNAP_PARENT_PATH" | sed "s|'|'\\\\''|g")
    DEST_SUBVOL=$(echo "$SNAP_ABSPATH" | sed 's|^/*\(.*\)/\.snapshotz/.*|\1|g')
    DEST_SUBVOL_ESC=$(echo "$SNAP_ABSPATH_ESC" | sed 's|^/*\(.*\)/\.snapshotz/.*|\1|g')
    if [ -z "$DEST_SUBVOL" ]; then
        DEST_SUBVOL="."
        DEST_SUBVOL_ESC="."
    fi
    SNAP_NAME=$(basename "$SNAP_ABSPATH")
    # Don't forget to escape \$(mktemp) and delete usage of \$SEND_ERR!
    # Don't forget to use _ESC paths!
    cat <<CMD
    $SUDO mkdir --mode="$SNAZZER_SNAPSHOTZ_PERMS" \
        '$DEST_SUBVOL_ESC/.snapshotz/.incomplete'
    $(if [ "$LOCAL_RUN" = "1" ]; then
        if [ -n "$SNAP_PARENT_PATH" ]; then
            cat <<CMD2
                $SUDO btrfs send '-p' '$SNAP_PARENT_PATH_ESC' '$SNAP_ABSPATH_ESC' | \
                    $SUDO btrfs receive '$DEST_SUBVOL_ESC/.snapshotz/.incomplete'
CMD2
        else
            cat <<CMD3
                $SUDO btrfs send '$SNAP_ABSPATH_ESC' | \
                    $SUDO btrfs receive '$DEST_SUBVOL_ESC/.snapshotz/.incomplete'
CMD3
        fi
    else
        if [ -n "$SNAP_PARENT_PATH" ]; then
            CMD="sudo -n btrfs send '-p' '$SNAP_PARENT_PATH_ESC' '$SNAP_ABSPATH_ESC'"
        else
            CMD="sudo -n btrfs send '$SNAP_ABSPATH_ESC'"
        fi
        cat <<CMD4
        ssh '$HOST' "$CMD" | \
            $SUDO btrfs receive '$DEST_SUBVOL_ESC/.snapshotz/.incomplete'
CMD4
    fi)
    $SUDO btrfs subvolume snapshot -r \
        '$DEST_SUBVOL_ESC/.snapshotz/.incomplete/$SNAP_NAME' \
        '$DEST_SUBVOL_ESC/.snapshotz/' >/dev/null
    $SUDO btrfs subvolume delete \
        '$DEST_SUBVOL_ESC/.snapshotz/.incomplete/$SNAP_NAME' >/dev/null
    $SUDO rmdir '$DEST_SUBVOL_ESC/.snapshotz/.incomplete'
CMD
}

do_send() {
    # Don't forget to copy the lines below verbatim into dry_send()
    HOST=$1
    SNAP_ABSPATH=$2
    SNAP_ABSPATH_ESC=$(echo "$SNAP_ABSPATH" | sed "s|'|'\\\\''|g")
    SNAP_PARENT_PATH=$3
    SNAP_PARENT_PATH_ESC=$(echo "$SNAP_PARENT_PATH" | sed "s|'|'\\\\''|g")
    DEST_SUBVOL=$(echo "$SNAP_ABSPATH" | sed 's|^/*\(.*\)/\.snapshotz/.*|\1|g')
    DEST_SUBVOL_ESC=$(echo "$SNAP_ABSPATH_ESC" | sed 's|^/*\(.*\)/\.snapshotz/.*|\1|g')
    if [ -z "$DEST_SUBVOL" ]; then
        DEST_SUBVOL="."
        DEST_SUBVOL_ESC="."
    fi
    SNAP_NAME=$(basename "$SNAP_ABSPATH")
    # Can't use do_ssh below, we must stream ssh output to btrfs receive
    # Don't forget to copy the lines below into dry_send() between CMD heredoc
    $SUDO mkdir --mode="$SNAZZER_SNAPSHOTZ_PERMS" \
        "$DEST_SUBVOL/.snapshotz/.incomplete"
    if [ "$LOCAL_RUN" = "1" ]; then
        if [ -n "$SNAP_PARENT_PATH" ]; then
    # Don't forget to copy the lines below into dry_send() between CMD2 heredoc
            $SUDO btrfs send -p "$SNAP_PARENT_PATH" "$SNAP_ABSPATH" | \
                $SUDO btrfs receive "$DEST_SUBVOL/.snapshotz/.incomplete"
        else
    # Don't forget to copy the lines below into dry_send() between CMD3 heredoc
            $SUDO btrfs send "$SNAP_ABSPATH" | \
                $SUDO btrfs receive "$DEST_SUBVOL/.snapshotz/.incomplete"
        fi
    else
    # Don't forget to copy the lines below into dry_send() between CMD4 heredoc
        if [ -n "$SNAP_PARENT_PATH" ]; then
            CMD="sudo -n btrfs send '-p' '$SNAP_PARENT_PATH_ESC' '$SNAP_ABSPATH_ESC'"
        else
            CMD="sudo -n btrfs send '$SNAP_ABSPATH_ESC'"
        fi
        SEND_ERR=$(mktemp)
        (ssh "$HOST" "$CMD" 2>"$SEND_ERR" || \
            check_ssh_err "$HOST" "$CMD" "$SEND_ERR" "$?") | \
            $SUDO btrfs receive "$DEST_SUBVOL/.snapshotz/.incomplete"
        rm "$SEND_ERR"
    fi
    # Don't forget to copy the lines below into dry_send() between CMD heredoc
    $SUDO btrfs subvolume snapshot -r \
        "$DEST_SUBVOL/.snapshotz/.incomplete/$SNAP_NAME" \
        "$DEST_SUBVOL/.snapshotz/" >/dev/null
    $SUDO btrfs subvolume delete \
        "$DEST_SUBVOL/.snapshotz/.incomplete/$SNAP_NAME" >/dev/null
    $SUDO rmdir "$DEST_SUBVOL/.snapshotz/.incomplete"
}

dry_copy() {
    HOST=$1
    SUBVOL_REMOTEPATH=$2
    SUBVOL_REMOTEPATH_ESC=$(echo "$SUBVOL_REMOTEPATH" | sed "s|'|'\\\\''|g")
    SUBVOL_LOCALPATH=$3
    SNAP_NAME=$4
    # Don't forget to escape \$(mktemp), \$MEAS_TMP, \$CMD!
    cat <<CMD
    $SUDO mkdir -vp --mode="$SNAZZER_SNAPSHOTZ_PERMS" \
        "$SUBVOL_REMOTEPATH/.snapshotz/.measurements"
    MEAS_TMP=\$(mktemp)
    $(if [ "$LOCAL_RUN" = "1" ]; then
        cat <<CMD2
    $SUDO cat "$SUBVOL_REMOTEPATH/.snapshotz/.measurements/$SNAP_NAME" \
        >"\$MEAS_TMP"
CMD2
    else
        cat <<CMD3
    CMD="cat '$SUBVOL_REMOTEPATH_ESC/.snapshotz/.measurements/$SNAP_NAME'"
    ssh "$HOST" "sudo -n \$CMD" >"\$MEAS_TMP"
CMD3
    fi)
    $SUDO tee -a "$SUBVOL_LOCALPATH/.snapshotz/.measurements/$SNAP_NAME" \
        <"\$MEAS_TMP" >/dev/null
    rm "\$MEAS_TMP"
CMD
}

do_copy() {
    # Don't forget to copy the lines below verbatim into dry_copy()
    HOST=$1
    SUBVOL_REMOTEPATH=$2
    SUBVOL_REMOTEPATH_ESC=$(echo "$SUBVOL_REMOTEPATH" | sed "s|'|'\\\\''|g")
    SUBVOL_LOCALPATH=$3
    SNAP_NAME=$4
    # We're using tee below to avoid giving sudo for cp
    # Don't forget to copy the lines below verbatim into dry_copy() between CMD
    $SUDO mkdir -vp --mode="$SNAZZER_SNAPSHOTZ_PERMS" \
        "$SUBVOL_REMOTEPATH/.snapshotz/.measurements"
    MEAS_TMP=$(mktemp)
    if [ "$LOCAL_RUN" = "1" ]; then
    # Don't forget to copy the lines below verbatim into dry_copy() between CMD2
        $SUDO cat "$SUBVOL_REMOTEPATH/.snapshotz/.measurements/$SNAP_NAME" \
            >"$MEAS_TMP"
    else
    # Don't forget to copy the lines below verbatim into dry_copy() between CMD3
        CMD="cat '$SUBVOL_REMOTEPATH_ESC/.snapshotz/.measurements/$SNAP_NAME'"
        do_ssh "$HOST" "sudo -n $CMD" >"$MEAS_TMP"
    fi
    # Don't forget to copy the lines below verbatim into dry_copy() between CMD
    $SUDO tee -a "$SUBVOL_LOCALPATH/.snapshotz/.measurements/$SNAP_NAME" \
        <"$MEAS_TMP" >/dev/null
    rm "$MEAS_TMP"
}

create_subvol() {
    DIR="$1"
    PARENT=$(dirname "$DIR")
    if [ "$DIR" != "$PARENT" ] && [ "$PARENT" != "." ]; then
        $SUDO mkdir -vp "$PARENT"
    fi
    $SUDO btrfs subvolume create "$DIR"
    $SUDO mkdir --mode="$SNAZZER_SNAPSHOTZ_PERMS" -vp "$DIR/.snapshotz"
}

is_subvol() {
    DIR=$1

    if $SUDO btrfs subvolume show "$DIR" >/dev/null 2>&1; then
        echo 1
    else
        echo 0
    fi
}

dispatch_copy() {
    HOST=$1
    SUBVOL_REMOTEPATH=$2
    SUBVOL_LOCALPATH=$3
    SNAP_NAME=$4
    if [ "$DRY_RUN" != "0" ]; then
        dry_copy "$HOST" "$SUBVOL_REMOTEPATH" "$SUBVOL_LOCALPATH" "$SNAP_NAME"
    else
        do_copy "$HOST" "$SUBVOL_REMOTEPATH" "$SUBVOL_LOCALPATH" "$SNAP_NAME"
    fi
}

do_subvolume_measurements() {
    HOST="$1"
    SUBVOL="$2"
    if [ -z "$SUBVOL" ]; then
        SUBVOL_RELPATH="."
    else
        SUBVOL_RELPATH="$SUBVOL"
    fi
    SUBVOL_RELPATH_ESC=$(echo "$SUBVOL_RELPATH" | sed "s|'|'\\\\''|g") 
    printf "  appending measurements..."
    if $SUDO test -e "$SUBVOL_RELPATH/.snapshotz/.incomplete"; then
        cat <<HERE >&2

ERROR: $SUBVOL_RELPATH/.snapshotz/.incomplete exists. Another instance is already
running, or a previous invocation was interrupted. If you are sure no other
instances are already running, remove this directory and snapshots under it:

btrfs subvolume delete '$SUBVOL_RELPATH_ESC/.snapshotz/.incomplete'/*
rmdir '$SUBVOL_RELPATH_ESC/.snapshotz/.incomplete'
HERE
        exit 2
    fi
    if [ "$(is_subvol "$SUBVOL_RELPATH")" != "1" ]; then
        echo "ERROR: $SUBVOL_RELPATH not a subvolume, this shouldn't happen."
        exit
    fi
    if ! $SUDO test -e "$SUBVOL_RELPATH/.snapshotz/.measurements"; then
        $SUDO mkdir --mode="$SNAZZER_SNAPSHOTZ_PERMS" \
            "$SUBVOL_RELPATH/.snapshotz/.measurements"
    fi
    SNAPSHOTS=$($SUDO ls "$SUBVOL_RELPATH/.snapshotz")
    MEAS_WANT=$(mktemp)
    MEAS_ABSENT=$($SUDO grep -srL "^> on $HOST at " \
        "$SUBVOL_RELPATH/.snapshotz/.measurements/" | \
        sed -n 's|^.*/\([^/]*\)|\1|p')
    MEAS_REMOTE=$(list_remote_snapshot_measurements "$HOST" "/$SUBVOL_RELPATH")
    # 1. Print snapshot measurements that we have locally but are missing
    #    mentions of remote $HOST;
    # 2. Print snapshot measurements available on the remote $HOST
    # 3. Write the union of these two lists (duplicates only) as a list of the
    #    snapshot names which we should grab remote $HOST's measurements of
    if [ -n "$MEAS_ABSENT" ] && [ -n "$MEAS_REMOTE" ]; then
        printf "%s\n%s" "$MEAS_ABSENT" "$MEAS_REMOTE" | sort | uniq -d \
            > "$MEAS_WANT"
    else
        printf "%s%s" "$MEAS_ABSENT" "$MEAS_REMOTE" | sort | uniq -d \
            > "$MEAS_WANT"
    fi
    NUM_WANT=$(wc -l "$MEAS_WANT" | cut -d ' ' -f 1)
    NUM_SNAP=$(echo "$SNAPSHOTS" | wc -l | cut -d ' ' -f 1)
    NUM_COPY=0
    NUM_REMOTE=$(echo "$MEAS_REMOTE" | wc -l | cut -d ' ' -f 1)
    while read -r SNAP_NAME <&4
    do
        dispatch_copy "$HOST" "/$SUBVOL_RELPATH" "$SUBVOL_RELPATH" "$SNAP_NAME"
        NUM_COPY=$((NUM_COPY + 1))
    done 4<"$MEAS_WANT"
    echo "$MEAS_REMOTE" > "$MEAS_WANT"
    while read -r SNAP_NAME <&4
    do
        if $SUDO test -e  "$SUBVOL_RELPATH/.snapshotz/$SNAP_NAME" && \
            ! $SUDO test -e \
            "$SUBVOL_RELPATH/.snapshotz/.measurements/$SNAP_NAME"; then
            dispatch_copy "$HOST" "/$SUBVOL_RELPATH" "$SUBVOL_RELPATH" "$SNAP_NAME"
            NUM_COPY=$((NUM_COPY + 1))
        fi
    done 4<"$MEAS_WANT"
    rm "$MEAS_WANT"
    echo " $NUM_COPY of $NUM_REMOTE."
}

do_subvolume() {
    HOST=$1
    SUBVOL=$2
    if [ -z "$SUBVOL" ]; then
        SUBVOL="."
    fi
    SUBVOL_ESC=$(echo "$SUBVOL" | sed "s|'|'\\\\''|g") 
    echo "subvolume $SUBVOL:"
    if $SUDO test -e "$SUBVOL/.snapshotz/.incomplete"; then
        cat <<HERE >&2

ERROR: $SUBVOL/.snapshotz/.incomplete exists. Another instance is already
running, or a previous invocation was interrupted. If you are sure no other
instances are already running, remove this directory and snapshots under it:

btrfs subvolume delete '$SUBVOL_ESC/.snapshotz/.incomplete'/*
rmdir '$SUBVOL_ESC/.snapshotz/.incomplete'
HERE
        exit 2
    fi
    if [ "$(is_subvol "$SUBVOL")" != "1" ]; then
        create_subvol "$SUBVOL"
    fi
    if ! $SUDO test -e "$SUBVOL/.snapshotz"; then
        $SUDO mkdir --mode="$SNAZZER_SNAPSHOTZ_PERMS" \
            "$SUBVOL/.snapshotz"
    fi
    # Last snapshot seen in the local target fs
    PREV_SNAP=
    if [ "$SUBVOL" = "." ]; then
        SNAPSHOTS=$(do_list_snapshots "$HOST" "/")
    else
        SNAPSHOTS=$(do_list_snapshots "$HOST" "/$SUBVOL")
    fi
    SNAP_WANT=$(mktemp)
    echo "$SNAPSHOTS" | snazzer-prune-candidates --invert > "$SNAP_WANT"
    NUM_WANT=$(wc -l "$SNAP_WANT" | cut -d ' ' -f 1)
    NUM_SNAP=$(echo "$SNAPSHOTS" | wc -l | cut -d ' ' -f 1)
    NUM_PRUN=$((NUM_SNAP - NUM_WANT))
    NUM_RECV=0
    NUM_SKIP=0
    while read -r SNAPSHOT <&4
    do
        SNAP_RELPATH=$(echo "$SNAPSHOT" | sed 's|^/*||g')
        if $SUDO test -e "$SNAP_RELPATH"; then
            NUM_SKIP=$((NUM_SKIP + 1))
        else
            NUM_RECV=$((NUM_RECV + 1))
            if [ "$DRY_RUN" != "0" ]; then
                dry_send \
                    "$HOST" "$SNAPSHOT" "$PREV_SNAP"
            else
                do_send \
                    "$HOST" "$SNAPSHOT" "$PREV_SNAP"
            fi
        fi
        PREV_SNAP="$SNAPSHOT"
    done 4<"$SNAP_WANT"
    rm "$SNAP_WANT"
    printf " %s of %s snapshots received " "$NUM_RECV" "$NUM_SNAP"
    echo "($NUM_PRUN pruned, $NUM_WANT considered, $NUM_SKIP skipped)"
}

#SMELL: Assumes --list-snapshots lines are grouped by subvol, ordered by date
#FIXME: Subvols containing mixed timezone snapshots will use suboptimal parents
do_host() {
    HOST=$1
    if [ "$LOCAL_RUN" = "1" ]; then
        HOST=$(hostname)
    elif [ "$HOST" = "--" ]; then
        echo "ERROR: This should never happen" >&2
        exit 127
    fi
    NUM_SUBVOL=0
    LIST_ERR=$(mktemp)
    LIST_OUT=$(mktemp)
    shift
    # This is messy because we want to capture stderr but at the same time still
    # emit it should do_list_snapshots actually exit with a non-zero return code
    LIST=$( (do_list_snapshots "$HOST" "$@" 2>"$LIST_ERR") || \
        (RC=$$; cat "$LIST_ERR" >&2; exit "$RC" ) )
    echo "$LIST" | \
        sed 's|^/*\(.*\)/\.snapshotz/.*|\1|g' | sort | uniq > "$LIST_OUT"
    NUM_SUBVOL=$(wc -l "$LIST_OUT" | cut -d ' ' -f 1)
    while read -r SUBVOL <&5
    do
        do_subvolume "$HOST" "$SUBVOL"
        do_subvolume_measurements "$HOST" "$SUBVOL"
    done 5<"$LIST_OUT"
    printf "Processed %s subvolume(s)." "$NUM_SUBVOL"
    if [ -s "$LIST_ERR" ]; then
        echo " Additional output from:"
        printf "  "
        dry_list_snapshots "$HOST" "$@"
        grep . "$LIST_ERR" | sed 's/^/    /g'
    else
        echo ""
    fi
    rm "$LIST_OUT"
    rm "$LIST_ERR"
}

DRY_RUN=0
LOCAL_RUN=0

while [ "$(echo "$1" | grep -c "^-")" != "0" ] && [ "$LOCAL_RUN" != "1" ]
do
    case "$1" in
        -v | --version )
            echo "$SNAZZER_VERSION"
            exit
            ;;
        -h | --help )
            pod2usage -exit 0 "$0"
            exit
            ;;
        --man )
            pod2usage -exit 0 -verbose 3 "$0"
            exit
            ;;
        --man-roff )
            pod2man --release=$SNAZZER_VERSION "$0"
            exit
            ;;
        --man-markdown )
            cat <<HERE | perl -Mstrict
if ( eval { require Pod::Markdown; 1; } ) {
    Pod::Markdown->new->filter('$0');
}
else {
    print STDERR "ERROR: --man-markdown requires Pod::Markdown\n\$@\n";
    exit 9;
}
HERE
            exit
            ;;
        -d | --dry-run )
            DRY_RUN=1;
            shift
            ;;
        -- )
            LOCAL_RUN=1
            ;;
        * )
            echo "ERROR: Invalid argument '$1'" >&2
            exit
            ;;
    esac
done

if [ -z "$1" ]; then
    pod2usage -exit 0 "$0"
    echo "ERROR: Missing argument" >&2
    exit 1
fi

do_host "$@"

<<__DNE__
__END__
=head1 NAME

snazzer-receive - receive remote snazzer snapshots to current working dir

=head1 SYNOPSIS

Receive snapshots from remote host via ssh:

  snazzer-receive [--dry-run] host --all [/path/to/btrfs/mountpoint]

  snazzer-receive [--dry-run] host [/remote/subvol1 [/subvol2 [..]]]

Receive snapshots from local filesystem:

  snazzer-receive [--dry-run] -- --all [/path/to/btrfs/mountpoint]

  snazzer-receive [--dry-run] -- /local/subvol1 [/subvol2 [..]]

=head1 DESCRIPTION

First, B<snazzer-receive> obtains a list of snapshots to be received by running
C<snazzer --list-snapshots [args]>, where [args] are all B<snazzer-receive>
arguments after the hostname or C<--> separator argument.

If the first non-option positional argument is C<-->,
C<snazzer --list-snapshots [args]> is executed locally and [args] will refer to
local filesystem paths. Otherwise, it is taken to mean an ssh hostname which is
used to run the C<snazzer --list-snapshots [args]> command remotely, and [args]
will refer to paths on that remote host.

B<snazzer-receive> then iterates through this list of snapshots recreating a
filesystem similar to the source by creating subvolumes and C<.snapshotz>
directories where necessary. Missing snapshots are instantiated directly with
C<btrfs send> and C<btrfs receive>, using C<btrfs send -p [parent]> where
possible to reduce transport overhead of incremental snapshots.

B<snazzer-receive> never deletes any snapshots from the current working dir,
even if the snapshots were e.g. pruned from the source.
This can be used to build a flexible, multi-tiered backup strategy with
different settings of how many snapshots to keep, but means that
C<snazzer --prune> needs to be run on the current working directory as well for
old snapshots to be deleted.


Rather than offer ssh user/port/host specifications through B<snazzer-receive>,
it is assumed all remote hosts are properly configured through your ssh config
file usually at C<$HOME/.ssh/config>.

=head1 OPTIONS

=over

=item B<--dry-run>: print rather than execute commands that would be run

=item B<--help>: Brief help message

=item B<--version>: Print version

=item B<--man>: Full documentation

=item B<--man-roff>: Full documentation as *roff output, Eg:

    snazzer-receive --man-roff | nroff -man

=item B<--man-markdown>: Full documentation as markdown output, Eg:

    snazzer-receive --man-markdown > snazzer-manpage.md

=back

=head1 ENVIRONMENT

=head2 sudo requirements for sender/remote hosts

B<snazzer-receive> assumes the ssh user (or local user, if receiving a local
filesystem) which will be running C<btrfs send> (among other things) has
passwordless sudo for the commands it needs to run. Only a few commands are
necessary, the following lines in C</etc/sudoers> or C</etc/sudoers.d/snazzer>
should suffice (replace "sendinguser" with the actual username you will use):

    sendinguser ALL=(root:nobody) NOPASSWD: /usr/bin/snazzer --list-snapshots *
    sendinguser ALL=(root:nobody) NOPASSWD:NOEXEC: \
        /bin/grep -srl */.snapshotz/.measurements/, \
        /sbin/btrfs send */.snapshotz/*, \
        /bin/cat */.snapshotz/.measurements/*

=head2 sudo and cron user requirements for receiving hosts

For interactive use of B<snazzer-receive>, a typical user with full sudo
permissions should work out of the box.

For scripted use such as a cron job, or interactive use in more restrictive
environments - running ssh as the root user is generally considered a bad idea.
A dedicated non-root user will require at minimum the following lines in
C</etc/sudoers> or C</etc/sudoers.d/snazzer> (replace "receiveruser" with the
actual username your cron job will use, and remove C<NOPASSWD:> if this is for
an interactive/shell user):

    receiveruser ALL=(root:nobody) NOPASSWD:NOEXEC: \
      /usr/bin/test -e */.snapshotz*, \
      /sbin/btrfs subvolume show *, \
      /bin/ls */.snapshotz, \
      /bin/grep -srL */.snapshotz/.measurements/, \
      /bin/mkdir --mode=0755 */.snapshotz, \
      /bin/mkdir --mode=0755 */.snapshotz/.measurements, \
      /bin/mkdir --mode=0755 */.snapshotz/.incomplete, \
      /sbin/btrfs receive */.snapshotz/.incomplete, \
      /sbin/btrfs subvolume create *, \
      /sbin/btrfs subvolume snapshot -r */.snapshotz/.incomplete/* */.snapshotz/,\
      /sbin/btrfs subvolume delete */.snapshotz/.incomplete/*, \
      /bin/rmdir */.snapshotz/.incomplete, \
      /bin/mkdir -vp *, \
      /bin/mkdir --mode=0755 -vp */.snapshotz, \
      /usr/bin/tee -a */.snapshotz/.measurements/*


=head1 SECURITY CONSIDERATIONS

=head2 Remote hosts

B<snazzer-receive> relies on running ssh remote commands. It is agnostic about
the auth method used, but this documentation assumes key-based.

Combined with passwordless sudo, remote hosts are vulnerable to and must have
absolute trust in the ssh key-holder, user and host running B<snazzer-receive>.

Your deployment should include or consider the following steps, among others not
listed here, to attempt to reduce the impact of or slow down an attacker which
has gained control of the B<snazzer-receive> user accounts or ssh keys:

=over

=item * Protect ssh keys

The ssh key used to authenticate B<snazzer-receive> typically has passwordless
sudo for C<btrfs send> (among other things) and you should assume that whomever
wields it has access to everything:

=over

=item * Avoid passphraseless ssh keyfiles

This should be obvious: once an attacker has copied such a keyfile they no
longer need the compromised host to authenticate, and you will have a bigger,
more urgent job searching for malicious use (and key removal from machines
which trusted it).

=item * Avoid ssh private keyfiles

Even passphrase-protected keyfiles are vulnerable to keyloggers and
memory scraping. Consider using smartcards, TPMs, Yubikeys or GoldKeys etc. to
at least force an attacker to depend on whichever machine has the authentication
device attached.

This is especially important when passphrase-protected keyfiles are not
practical (eg. scripted use of B<snazzer-receive> such as cron).

=item * Use the timeout option if using an ssh-agent

=back

=item * Grant minimal sudo rights

Refer to "sudo requirements for remote hosts". Don't give the B<snazzer-receive>
user the option to run arbitrary commands remotely as root.

=item * C<~/.ssh/authorized_keys>: specify a forced-command/shell-wrapper

Even if sudo is locked down, don't give the B<snazzer-receive> user the option
of running arbitrary commands remotely. Use a shell wrapper which permits only
the required sudo commands.
TODO: provide example
TODO: Document shell wrapper

NOTE: This does not prevent data exfiltration via C<sudo btrfs send>, but
may slow down an attacker who would abuse the account in other ways.

=item * C<~/.ssh/authorized_keys>: restrict originating IP address

Use the C<from> option to limit which machine the B<snazzer-receive> host's ssh
key may connect from. This might force an attacker to still depend on the
B<snazzer-receive> host even if they have obtained the private key somehow.
TODO: provide example
TODO: link to a guide on this

=item * Disable interactive shells/logins

Reduce opportunities for the B<snazzer-receive> user to run arbitrary commands;
remove the account password. NOTE: this doesn't stop ssh remote commands.
TODO: link to a guide on this

=item * Log remote ssh commands

Most distros do zero logging of remote ssh commands. Logging such commands may
be your only way to spot abuse of the B<snazzer-receive> account. The
C<snazzer-send-wrapper> uses C<logger -p user.info [cmd]> to log commands on
remote hosts which are invoking C<btrfs send>.
TODO: link to a guide on this

=back

=head1 BUGS AND LIMITATIONS

B<NOTE:> B<snazzer-receive> tries to recreate a filesystem similar to that of
the remote host, starting at the current working directory which represents the
root filesystem. If the remote host has a root btrfs filesystem, this means that
the current working directory should itself also be a btrfs subvolume in order
to receive snapshots under ./.snapshotz. However, B<snazzer-receive> will be
unable to replace the current working directory with a btrfs subvolume if it
isn't already one.

Therefore, if required, ensure the current working directory is already a btrfs
subvolume prior to running B<snazzer-receive> if you need to receive btrfs root.

=head1 EXIT STATUS

B<snazzer-receive> will abort with an error message printed to STDERR and
non-zero exit status under the following conditions:

=over

=item 1. invalid arguments

=item 2. C<.snapshotz/.incomplete> already exists at a given destination subvolume

=item 9. tried to display man page with a formatter which is not installed

=item 12. remote ssh sudo command failed

=back

=head1 TODO

=over

=item 1. improve fetch/append of remote host's measurements

B<snazzer-receive> currently does some clumsy concatenation of the remote host's
measurement file onto the local measurement file for a given snapshot if the
local measurement file is either missing or does not mention that remote host's
hostname. Whilst this supports the simple use-case of wanting to obtain initial
measurements performed on a remote host, once a remote host's measurements have
been appended there is no attempt to append any further measurement results onto
the local measurements file.  If this bothers you, please report detailed
use-cases to the author (patches welcome).

=item 2. include restricted wrapper script to be used as ssh forced command

The snazzer project assumes that systems administrators would prefer to restrict
the possible exposure of a dedicated snazzer remote user account, even if sudo
is locked down. To that end, a wrapper script shall be provided which restricts
possible ssh remote commands to only the few actually necessary for snazzer
operation.

Even so, commands which snazzer relies on such as C<sudo btrfs send> are
extremely dangerous no matter if it's the only command allowed by the system -
securing ssh keys is of utmost importance; consider protecting ssh keys with
smartcards, TPM, hardware OTP solution such as Yubi/GoldKeys etc.

=back

=head1 SEE ALSO

snazzer, snazzer-measure, snazzer-prune-candidates

=head1 AUTHOR

Snazzer Authors are listed in the AUTHORS.md file in the root of this
distribution. See https://github.com/csirac2/snazzer for more information.
NOTE: Please extend that file, not this notice.

=head1 LICENSE AND COPYRIGHT

Copyright (C) 2015-2016, Snazzer Authors All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
=cut
__DNE__