documentation: update/fix ChangeLog, README.md, btrbk.conf.5; add "doc/upgrade_to_v0.23.0.md"

ChangeLog

@@ -1,13 +1,21 @@
 btrbk-current
 
+  * INCOMPATIBLE CONFIGURATION:
+    Please read "doc/upgrade_to_v0.23.0.md" for details on updating
+    the configuration file (/etc/btrbk/btrbk.conf).
+  * Create backups only if needed to satisfy retention policy.
+  * Preserve FIRST backup of hour/day/week/month instead of LAST.
+  * Replaced "{snapshot,target}_preserve_{daily,weekly,monthly}"
+    configuration options with "{snapshot,target}_preserve_min" and
+    "{snapshot,target}_preserve NNh NNd NNw NNm NNy" options.
+  * Removed "resume_missing" configuration option.
+  * Added hourly/yearly retention policies (close: #36, #69).
   * Allow regular directories for send-receive targets (close: #77).
   * Allow wildcards in subvolume section (close: #71).
   * Propagate targets defined in "volume" or "root" context to all
     "subvolume" sections (close: #78).
-  * Added "{snapshot,target}_preserve NNd NNw NNm NNy" shortcut.
-  * Added hourly retention policies (close: #36).
-  * Added yearly retention policies (close: #69).
   * Added configuration option "rate_limit" (close: #72).
+  * Added "--print-schedule" command line option.
   * Detect interrupted transfers of raw targets (close: #75).
   * Always read "readonly" flag (additional call to btrfs-progs).
   * Warn on receive targets at unexpected location (instead of abort).

README.md

@@ -20,10 +20,13 @@ Key Features:
   * Transfer via ssh
   * Resume of backups (if backup target was not reachable for a while)
   * Encrypted backups to non-btrfs destinations
+  * Wildcard subvolumes (useful for docker and lxc containers)
   * Transaction log
   * Display file changes between two backups
 
-btrbk is intended to be run as a cron job.
+btrbk is designed to run as a cron job for triggering periodic
+snapshots and backups, as well as from the command line (e.g. for
+instantly creating additional snapshots).
 
 
 Installation
@@ -40,11 +43,14 @@ Prerequisites
   * [btrfs-progs]: Btrfs filesystem utilities (use
     "btrfs_progs_compat" option for hosts running version prior to
     v3.17)
-  * Perl interpreter: probably already installed on your system
+  * [Perl interpreter]: probably already installed on your system
   * [Date::Calc]: Perl module
+  * [OpenSSH]: if you want to tranfer backups from/to remote locations
 
   [btrfs-progs]: http://www.kernel.org/pub/linux/kernel/people/kdave/btrfs-progs/
+  [Perl interpreter]: https://www.perl.org
   [Date::Calc]:  http://search.cpan.org/perldoc?Date::Calc
+  [OpenSSH]: http://www.openssh.org
 
 
 Instructions

doc/btrbk.conf.5

@@ -224,8 +224,8 @@ manipulated by hand (moved, deleted).
 Lines that contain a hash character (#) in the first column are
 treated as comments.
 .SH RETENTION POLICY
-btrbk uses separate retention policy for snapshots and backups, which
+btrbk uses separate retention policies for snapshots and backups,
-are defined by the \fIsnapshot_preserve_min\fR,
+which are defined by the \fIsnapshot_preserve_min\fR,
 \fIsnapshot_preserve\fR, \fItarget_preserve_min\fR,
 \fItarget_preserve\fR, and the \fIpreserve_day_of_week\fR
 configuration options.

doc/upgrade_to_v0.23.0.md

@@ -0,0 +1,92 @@
+Upgrading to btrbk-v0.23.0
+==========================
+
+In order to keep btrbk simple and intuitive while adding new features,
+it became inevitable to change the semantics of the "retention policy"
+related configuration options.
+
+
+What has changed?
+-----------------
+
+### Preserve *first* instead of *last* snapshot/backup
+
+btrbk used to *always* transfer the latest snapshot to the target
+location, while considering the *last* snapshot/backup of a day as a
+daily backup (and also the last weekly as a monthly). This made it
+very cumbersome when running btrbk in a cron job as well as manually,
+because the last manually created snapshot was immediately transferred
+on every run, and used as the daily backup (instead of the one created
+periodically by the cron job).
+
+The new semantics are to consider the *first* (instead of *last*)
+snapshot of a hour/day/week/month as the one to be preserved, while
+only transferring the snapshots needed to satisfy the target retention
+policy.
+
+
+### Preserve snapshots for a minimum amount of time
+
+In order to specify a minimum amount of time in which *all* snapshots
+should be preserved, the new "snapshot_preserve_min" and
+"target_preserve_min" configuration options were introduced. This was
+previously covered by "snapshot_preserve_daily", which caused a lot of
+confusion among users.
+
+
+Upgrading the configuration file: /etc/btrbk/btrbk.conf
+-------------------------------------------------------
+
+Please read the description of the "run" command in [btrbk(1)], as
+well as the "RETENTION POLICY" section in [btrbk.conf(5)] for a
+detailed description. Make sure to understand the new concept, and run
+`btrbk --print-schedule dryrun` after updating the configuration.
+
+
+### Upgrade retention policy
+
+If you want the same behaviour as before:
+
+    # replace this:
+    snapshot_preserve_daily   <daily>
+    snapshot_preserve_weekly  <weekly>
+    snapshot_preserve_monthly <monthly>
+
+    # with:
+    snapshot_preserve_min  <daily>d
+    snapshot_preserve      <weekly>w <monthly>m
+
+    # ... do the same with "target_preserve_*" options
+
+
+But what you probably want is something like:
+
+    snapshot_preserve_min  5d
+    snapshot_preserve      <daily>d <weekly>w <monthly>m
+
+    target_preserve_min    no
+    target_preserve        <daily>d <weekly>w <monthly>m *y
+
+This states:
+
+  * Keep all snapshots for five days (no matter how many there are)
+  * Transfer only the first snapshot ot a day to the target
+  * Keep all "first snapshots of a day" for <daily> days, etc.
+
+
+### Upgrade "resume_missing"
+
+If you have a line: "resume_missing yes" somwhere in your config,
+simply remove it. btrbk always resumes missing backups.
+
+If you have "resume_missing no", you can imitate this behaviour by
+setting:
+
+    target_preserve_min  latest
+    target_preserve      no
+
+This states: "always transfer the latest snapshot to the target".
+
+
+  [btrbk(1)]: http://digint.ch/btrbk/doc/btrbk.html
+  [btrbk.conf(5)]: http://digint.ch/btrbk/doc/btrbk.conf.html