Document interaction between min and non-min options

[asymmetric]

I find the documentation of the snapshot_preserve_min and target_preserv_min options a bit confusing.

First of all, the manual for those options says "regardless of how many there are", seeming to imply that there's a way to count backups/snapshots and remove the ones in excess. This doesn't seem to be possible: all retention options are time-based. Is there a way to declare "only keep the last 10 snapshots"? If so, then the _min options would make a lot more sense.

Secondly, it's not clear why there are two sets of options in the first place. Somewhere on IRC it was mentioned that the _min options are there to make sure that snapshots/backups produced during manual runs are preserved: how does this work in practice? Why would they be removed without the _min options? Presumably they would follow the same filename naming scheme, so they could be handled by snapshot_preserve/target_preserve.

Then there's the issue that if snapshot_preserve_min/target_preserve_min are set to all, that snapshot_preserve/target_preserve are effectively meaningless. This should also be documented.

Please let me know if I'm right on the above points, and I'll be happy to improve the documentation accordingly.

[ghost]

Isn't snapshot on the source volume whereas target refers to snapshots stored on the backup volume?

[digint]

I think the main confusion here is the term "regardless of how many there are". Make sure to understand how the retention mechanism works: e.g. btrbk does not differtiate if it is called by a timer or manually, it simply always respects the retention policy (see btrbk.conf(5), RETENTION POLICY).

Then there's the issue that if snapshot_preserve_min/target_preserve_min are set to all, that snapshot_preserve/target_preserve are effectively meaningless. This should also be documented.

No, its not meaningless. The defaults are "keep everything forever". So unless the user configures it otherwise, nothing will be deleted ever.

Hope that helps, sorry for the late reply...

[bronger]

Just because I’m still confused: Does setting snapshot_preserve without setting snapshot_preserve_min have any effect?

[bronger]

Sorry for the noise, I found my answer in https://github.com/digint/btrbk/issues/190#issuecomment-333555360.

I acknowledge that the documentation is complete but because it is at least against my intuition, the sentence

[If] you [do] not specify snapshot_preserve_min and target_preserve_min, they both default to "all", making your snapshot_preserve and target_preserve options meaningless.

would help in the documentation.

[ghost]

I just stumbled on this issue again earlier today. I had forgotten to set target_preserve_min. I do think that the default to preserve all is sane and useful as it prevents unintended dataloss.

[bronger]

I don’t put the default in question.

My issue is that the behaviour is – at least for me – unexpected. snapshot_preserve_min serves two purposes: 1. It sets the maximum age of snapshots to keep under all circumstances. 2. It switches on snapshot deletion in the first place. This double role is okay and even elegant, but double roles need extra care in documentation.

Therefore, I think that an additional, albeit redundant, sentence in the docs would be helpful.

[digint]

Added some documentation in 4d1b9119475f5d91c2b96c6b1b1a5ef8f9eec323, thanks for your suggestions!

[jsebean]

Forgive me for my ignorance but I'm failing to understand: what is the point of the non-min option at all then when you can set your retention policy in _min? Nobody has clearly answered:

Secondly, it's not clear why there are two sets of options in the first place. Somewhere on IRC it was mentioned that the _min options are there to make sure that snapshots/backups produced during manual runs are preserved: how does this work in practice? Why would they be removed without the _min options?

[Apteryks]

I too have been looping the various options in the man btrbk.conf, trying to get a clue, in vain. My intuition was that target_preserve_min be the lower bound retention policy to honor at all times, while target_preserve is an upper bound, best effort retention policy that is dependent on space availability? But that's just a guess.

[digint]

While I'm sure that from a technical point the documentation is correct and comprehensive, I agree that it's not that easy to understand. I've tried to make it clear on top of the "Retention Policy" section, but maybe it's not enough: https://digint.ch/btrbk/doc/btrbk.conf.5.html#_retention_policy

Maybe the main problem is that one needs to know how btrbk operates in order to understand the text?

Or maybe I should copy some examples from README.md to the man pages to make things more clear?

Let me reopen this issue, and add "help wanted", and hope that someone who is not as biased as I am has some suggestions on how to improve these (very basic and important) options.

[luxagen]

I commented similarly on a similar ticket, but I'll put this here too. I think the biggest problem with this part of the docs is that, although one can figure it out, it's not immediately clear that one is a policy and the other a maximum age. The crucial difference between the two is that policies, depending on the algorithm for identifying daily, weekly, etc. snapshots, will often delete a discontiguous snapshot set, whereas the max-age options will just delete anything older than (now - timespan).

IMO explaining this very explicitly in the docs would put an end to tickets like this because all other nuances follow from this distinction.