add The Gist

README.md

@@ -1,20 +1,41 @@
-# zfsbk utils
+# zfsbk Overview
 
-This is a minimalistic utility to manage backups for systems using the
+This is a minimalistic utility to fully automate backups for systems using the
-outstanding [http://en.wikipedia.org/wiki/ZFS ZFS] filesystem.
+outstanding [ZFS](http://en.wikipedia.org/wiki/ZFS) filesystem.
 
 It relies on Snapshots to provide:
 
 * local backups – they help you recover files from earlier in time.
 * remote backups – they help you recover whole datasets for system failures.
 
+ZFS snapshots are extremely lightweight on the system (actually cheaper to take
+snapshot than not!) and cheap on storage (only changed blocks are saved) and
+allow you to restore files from past versions.
 
-## Installation
+
+# The gist
+
+You run these tools from cron to periodically
+
+* take ZFS snapshots (`zfssnap.sh`)
+* serialize and export them remotely (`zfsbk.sh`)
+
+The tools take care of limiting the number of snapshots, so you do not
+have to periodically prune old snapshots.
+
+Snapshots can be named so you can create groups of them, e.g. "hourly snapshots",
+"newdeplo snapshots" and "exported snapshots".
+
+An additional tool takes care of exporting such snapshots, and uploading them
+to a remote server.
+
+
+# Installation
 
 Simply place all `*.sh` files of the package into directory `/usr/local/sbin/`.
 
 
-## Snapshot management
+# Snapshot management
 
 You run `zfssnap.sh` for taking snapshots, typically from cron:
 
@@ -33,7 +54,7 @@ Only 24 of these snapshots will be kept (see Rotation below). The name of each
 snapshot comes with format `zbk-[tag]-[date]-[time]`. Date is `YYYYMMDD` and
 time is `hhmmss`.
 
-### Snapshot groups
+## Snapshot groups
 
 Each snapshot is tagged:
 
@@ -47,12 +68,14 @@ Multiple groups can exist, just take snapshots with different tags:
 
     # take 2 'hourly' snaps
     zfssnap.sh hourly 10
-    # take 2 'daily' snaps
+    zfssnap.sh hourly 10
+    # take 3 'daily' snaps
+    zfssnap.sh daily 10
+    zfssnap.sh daily 10
     zfssnap.sh daily 10
     # ls /.zfs/snapshot
     zfs-hourly-20140318-140001
     zfs-hourly-20140318-140003
-    zfs-daily-20140318-140110
     zfs-daily-20140318-140111
     zfs-daily-20140318-140112
     zfs-daily-20140318-140114
@@ -63,7 +86,7 @@ scripts, so inherent limitations of arguments length could get in your way.
 
 I recommend staying under 50 snaps per group and 200 snaps total.
 
-### Snapshot rotation
+## Snapshot rotation
 
 `zfssnap.sh` takes a new snapshot every time it's run. When the number of
 existing snapshots exceeds the given limit, the oldest snapshot of that group
@@ -77,32 +100,7 @@ This bounds the number of snapshots for each group to 2. To remove all snaps in
     # remove all snaps of group xyz
     zfssnap.sh xyz 0
 
-### Recovering files (local backup)
+## Excluding dataset from backup
-
-Lost a file? Find it under:
-
-    # list content of michele's home at 2pm (1400)
-    ls /.zfs/snapshot/zbk-hour-140000/home/michele
-
-Notice that you must look for the `/.zfs` directory at the root of the dataset actually holding it:
-
-    # list content of michele's home, if /home is on zroot/home
-    ls /home/.zfs/snapshot/zbk-hour-140000/michele
-
-### Full snapshot management cron example
-
-    # take 15' backups for the last hour
-    */15 * * * * root /usr/local/sbin/zfssnap.sh qrt 4
-    # take hourly backups for the 6 hours
-    1 * * * * root /usr/local/sbin/zfssnap.sh hourly 6
-    # take 6-hours backups for the last day
-    1 */6 * * * root /usr/local/sbin/zfssnap.sh 6hr 4
-    # take daily backups for the last week
-    1 1 * * * root /usr/local/sbin/zfssnap.sh day 7
-    # take weekly backups for the last 2 months
-    1 1 * * 1 root /usr/local/sbin/zfssnap.sh week 8
-
-### Excluding dataset from backup
 
 `zfssnap.sh` takes a recursive backup of the `zroot` pool. If you do not intend
 to maintain backups for certain datasets, you can exclude them with the
@@ -124,8 +122,32 @@ The following datasets, common for FreeBSD users, are excluded by default:
 
 If you do not want these excluded, pass an empty `EXCLUDES` envvar.
 
+# Recovering files (local backup)
 
-## Generating remote backups
+Lost a file? Find it under:
+
+    # list content of michele's home at 2pm (1400)
+    ls /.zfs/snapshot/zbk-hour-140000/home/michele
+
+Notice that you must look for the `/.zfs` directory at the root of the dataset actually holding it:
+
+    # list content of michele's home, if /home is on zroot/home
+    ls /home/.zfs/snapshot/zbk-hour-140000/michele
+
+# Full snapshot management cron example
+
+    # take 15' backups for the last hour
+    */15 * * * * root /usr/local/sbin/zfssnap.sh qrt 4
+    # take hourly backups for the 6 hours
+    1 * * * * root /usr/local/sbin/zfssnap.sh hourly 6
+    # take 6-hours backups for the last day
+    1 */6 * * * root /usr/local/sbin/zfssnap.sh 6hr 4
+    # take daily backups for the last week
+    1 1 * * * root /usr/local/sbin/zfssnap.sh day 7
+    # take weekly backups for the last 2 months
+    1 1 * * 1 root /usr/local/sbin/zfssnap.sh week 8
+
+# Generating remote backups
 
 The `zfsbk.sh` lets you generate backups and upload them to a remote location.
 
@@ -136,8 +158,7 @@ This takes a snapshot with tag `mybk` and serializes it in file `/backups/zbk-my
     ls /backups
     zfs-mybk-20140318-061900.dump
 
-
+# Incremental backups
-## Incremental backups
 
 Pass a number to `zfsbk.sh` and it will create incremental snapshots:
 
@@ -154,8 +175,7 @@ Incremental packages are named after their snapshot endpoints:
 If the given integer is 1, `zfsbk.sh` sends full replication packages for every
 run.
 
-
+# Uploading backups remotely
-## Uploading backups remotely
 
 `zfsbk.sh` can upload each replication package after generating it, at the end of the run.