mirror of https://github.com/digint/btrbk
documentation: update/fix ChangeLog, README.md, btrbk.conf.5; add "doc/upgrade_to_v0.23.0.md"
Axel Burri
parent
be608a04b2
commit
73906caacd
14
ChangeLog
14
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).
|
||||
|
|
|
|||
10
README.md
10
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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
Loading…
Reference in New Issue