documentation: added documenation for new "snapshot_create" configuration option, while removing deprecated "snapshot_create_always". Added an "multiple btrbk instances" example to README.md

ChangeLog

@@ -4,6 +4,9 @@ btrbk-current
   * Set PATH variable instead of using absolute "/sbin/btrfs" for
     compatibility with all linux distros out there, which all install
     'btrfs' in different locations (closes: #20).
+  * Added configuration option "snapshot_create", replacing option
+    "snapshot_create_always". This allows setups with multiple btrbk
+    instances on several hosts (closes: #18).
   * Added command line option -r (resume only).
   * Catch and display errors from "btrfs subvolume show".
   * Include systemd service and timer unit for daily backups.

README.md

@@ -156,11 +156,10 @@ Retention policy:
   - `/mnt/btr_backup/mylaptop/rootfs.YYYYMMDD`
   - `/mnt/btr_backup/mylaptop/home.YYYYMMDD`
 
-If you want the snapshots to be created even if the backup disk is not
+If you want the snapshots to be created only if the backup disk is
-attached (when you're on the road), simply add the following line to
+attached, simply add the following line to the config:
-the config:
 
-    snapshot_create_always     yes
+    snapshot_create            ondemand
 
 
 Example: host-initiated backup on fileserver
@@ -215,19 +214,51 @@ This will pull backups from alpha/beta.mydomain.com and locally create:
 Example: local time-machine (daily snapshots)
 ---------------------------------------------
 
-If all you want is a local time-machine of your home directory:
+If all you want is creating snapshots of your home directory on a
+regular basis:
 
-/etc/btrbk/btrbk-timemachine.conf:
+/etc/btrbk/btrbk.conf:
 
     volume /mnt/btr_pool
-      subvolume home
       snapshot_dir btrbk_snapshots
-        snapshot_create_always yes
+      subvolume home
 
 /etc/cron.daily/btrbk:
 
     #!/bin/bash
-    /usr/sbin/btrbk -c /etc/btrbk/btrbk-timemachine.conf run
+    /usr/sbin/btrbk run
+
+Note that you can run btrbk more than once a day, e.g. by creating the
+above script in `/etc/cron.hourly/btrbk`, or by calling `sudo btrbk
+run` from the command line.
+
+
+Example: multiple btrbk instances
+---------------------------------
+
+Let's say we have a host (at 192.168.0.42) running btrbk with the
+setup of the time-machine example above, and we need a backup server
+to only fetch the snapshots.
+
+/etc/btrbk/btrbk.conf (on backup server):
+
+    volume ssh://192.168.0.42/mnt/btr_pool
+      subvolume home
+        snapshot_dir             btrbk_snapshots
+        snapshot_preserve_daily  all
+        snapshot_create          no
+        resume_missing           yes
+
+        target_preserve_daily    0
+        target_preserve_weekly   10
+        target_preserve_monthly  all
+
+        target send-receive  /mnt/btr_backup/my-laptop.com
+
+If the server runs btrbk with this config, the latest snapshot (which
+is *always* transferred) as well as 10 weeklies and all monthlies are
+received from 192.168.0.42. The source filesystem is never altered
+because of `snapshot_preserve_daily all`.
 
 
 Setting up SSH

btrbk.conf.example

@@ -22,14 +22,15 @@
 snapshot_dir               _btrbk_snap
 
 # Perform incremental backups (set to "strict" if you want to prevent
-# creation of initial backups if no parent is found).
+# creation of non-incremental backups if no parent is found).
 incremental                yes
 
-# Always create snapshots, even if the target volume is unreachable.
+# Always create snapshots (set to "ondemand" to only create snapshots
-snapshot_create_always     yes
+# if the target volume is reachable).
+snapshot_create            always
 
-# Resume missing backups if the target volume is reachable again.
+# Resume missing backups if the target volume is reachable again (set
-# Useful in conjunction with "snapshot_create_always".
+# to "no" if you don't want to resume missing backups).
 resume_missing             yes
 
 # ssh key for ssh volumes/targets
@@ -115,3 +116,15 @@ volume ssh://my-remote-host.com/mnt/btr_pool
     snapshot_dir  snapshots/btrbk
     snapshot_name data_main
     target send-receive    /mnt/btr_backup/_btrbk/my-remote-host.com
+
+
+# Resume backups from remote host which runs its own btrbk instance
+# creating snapshots for "home" in "/mnt/btr_pool/btrbk_snapshots".
+volume ssh://my-remote-host.com/mnt/btr_pool
+  subvolume home
+    snapshot_dir  btrbk_snapshots
+    snapshot_preserve_daily  all
+    snapshot_create          no
+    resume_missing           yes
+
+    target send-receive    /mnt/btr_backup/_btrbk/my-remote-host.com

doc/btrbk.conf.5

@@ -56,14 +56,15 @@ Base name of the created snapshot (and backup). Defaults to
 \fI<subvolume-name>\fR. This option is only valid in the \fItarget\fR
 section.
 .TP
-\fBsnapshot_create_always\fR  yes|no
+\fBsnapshot_create\fR  always|ondemand|no
-If set, the snapshots are always created, even if the backup subvolume
+If set to \[lq]ondemand\[rq], the snapshots are only created if the
-cannot be created (e.g. if the target subvolume cannot be
+target subvolume is reachable (useful if you are tight on disk space
-reached). Use in conjunction with the \fIresume_missing\fR option to
+and you only need btrbk for backups to an external disk which is not
-make sure that the backups are created as soon as the target subvolume
+always connected). If set to \[lq]always\[rq], the snapshots are
-is reachable again. Useful for laptop filesystems in order to make
+always created, regardless of the target reachability. If set to
-sure the snapshots are created even if you are on the road. Defaults
+\[lq]no\[rq], the snapshots are never created (useful in conjunction
-to \[lq]no\[rq].
+with the \fIresume_missing\fR option if another instance of btrbk is
+taking care of snapshot creation). Defaults to \[lq]always\[rq].
 .TP
 \fBincremental\fR  yes|no|strict
 Perform incremental backups. Defaults to \[lq]yes\[rq]. If set to