From 73906caacd26c7f1ff4ecbc11ffc6c4f6e686ea4 Mon Sep 17 00:00:00 2001 From: Axel Burri Date: Wed, 13 Apr 2016 19:56:35 +0200 Subject: [PATCH] documentation: update/fix ChangeLog, README.md, btrbk.conf.5; add "doc/upgrade_to_v0.23.0.md" --- ChangeLog | 14 ++++-- README.md | 10 ++++- doc/btrbk.conf.5 | 4 +- doc/upgrade_to_v0.23.0.md | 92 +++++++++++++++++++++++++++++++++++++++ 4 files changed, 113 insertions(+), 7 deletions(-) create mode 100644 doc/upgrade_to_v0.23.0.md diff --git a/ChangeLog b/ChangeLog index 64adc62..fb8e979 100644 --- a/ChangeLog +++ b/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). diff --git a/README.md b/README.md index 8d5a887..c7a1bdd 100644 --- a/README.md +++ b/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 diff --git a/doc/btrbk.conf.5 b/doc/btrbk.conf.5 index b295eb1..46d21c8 100644 --- a/doc/btrbk.conf.5 +++ b/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 -are defined by the \fIsnapshot_preserve_min\fR, +btrbk uses separate retention policies for snapshots and backups, +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. diff --git a/doc/upgrade_to_v0.23.0.md b/doc/upgrade_to_v0.23.0.md new file mode 100644 index 0000000..507eb01 --- /dev/null +++ b/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 + snapshot_preserve_weekly + snapshot_preserve_monthly + + # with: + snapshot_preserve_min d + snapshot_preserve w m + + # ... do the same with "target_preserve_*" options + + +But what you probably want is something like: + + snapshot_preserve_min 5d + snapshot_preserve d w m + + target_preserve_min no + target_preserve d w 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 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