From 4e065b7433f22c58d38ad4416e6d27212f390572 Mon Sep 17 00:00:00 2001 From: Kevin McCormick Date: Thu, 4 Aug 2016 16:30:45 -0700 Subject: [PATCH] Write README --- README.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) diff --git a/README.md b/README.md index caf6ab8..9419924 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,66 @@ # backup-zfs zfs snapshot send/receive supporting pull + +## Basic Usage + backup-zfs remote_host:src_pool/fs dest_pool + +This will create a new snapshot on the remote host (via SSH) and "send" it to +your local host where it will be received into dest_pool/fs. + +I use this on my laptop to backup my home server to a removable drive. This +*pull* functionality was something I had trouble finding in the other similar +scripts out there, and was the main reason I wrote this. + +## Features +* pull from a remote source to a local (or remote) destination + * (source and destination can each be either local or remote) +* keeps its own set of snapshots +* SSH connection is made with regular user, and uses sudo for ZFS commands +* sends incremental snapshots after first run + +## Limitations +* always uses sudo +* always creates recursive snapshots (`zfs snapshot -r`) +* always sends full replication stream (`zfs send -R`) +* always keeps the full zfs path, minus the first component (`zfs recv -d`) + +## Install/Requirements +* There is no need to install, just clone/download where you like and run +* Created & tested with [ZFS On Linux][1] on Ubuntu 16.04 +* Requires bash(1), date(1), sudo(8), and zfs(8) +* Requires ssh(1) for remote hosts + * If your SSH environment requires a custom port or other configuration + options, that will need to be done in your ssh_config(5) file + +## Usage/Examples + backup-zfs [-hvq] [-t tag] [-k keep] [-d dateopts] src dest + use zfs send/recv to push/pull snapshots + + src the source fs, specified as [host:]pool/path/to/fs + dest the destination fs parent, specified as [host:]pool/path/to/fs + (the final path component of src will be appended to dest) + + -h help + -v verbose mode + -q quiet mode + -t tag tag to use for naming snapshots (default: backup-zfs) + -k keep number of snapshots to keep on src (default: 5) + -d dateopts options for date(1) - used to name the snapshots (default: +%F_%T) + + # Local mode: Backup tank/system to backup/tank/system + backup-zfs tank/system backup/tank + + # Pull mode: Backup tank/system on tankhost to localhost + backup-zfs tankhost:tank/system backup/tank + + # Push mode: Backup tank/system on localhost to backuphost + backup-zfs tank/system backuphost:backup/tank + + # Double remote mode: Backup tank/system on tankhost to backuphost + backup-zfs tankhost:tank/system backuphost:backup/tank + + # In this mode, your client will establish two separate SSH sessions, + # connect them with a pipe, and pull data from one while pushing to the + # other. No data will be stored locally. + +[1]: https://github.com/zfsonlinux/zfs