[pbs-devel] [PATCH proxmox-backup v2 1/2] docs: explain retention time for event allocation policy in more detail

[pbs-devel] [PATCH proxmox-backup v2 1/2] docs: explain retention time for event allocation policy in more detail

[Dominik Csapak]

'when the calendar event' triggers was too vague, it could mean for
the current media-set or the next time. Apart from that, it was not
technically correct all the time, since we take the start time of
the next media set if that exists first.

The idea here is that we begin the retention when the media set is
finished.

Signed-off-by: Dominik Csapak <d.csapak@proxmox.com>
---
 docs/tape-backup.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/tape-backup.rst b/docs/tape-backup.rst
index a8d6b7fd..ae597d3d 100644
--- a/docs/tape-backup.rst
+++ b/docs/tape-backup.rst
@@ -519,8 +519,9 @@ a single media pool, so a job only uses tapes from that pool.
 
      This balances between space efficiency and media count.
 
-     .. NOTE:: Retention period starts when the calendar event
-        triggers.
+     .. NOTE:: Retention period starts on the creation time of the next
+        media-set or, if that does not exist, when the calendar event
+        triggers the next time after the current media-set start time.
 
    Additionally, the following events may allocate a new media set:
 
-- 
2.30.2

[pbs-devel] [PATCH proxmox-backup v2 2/2] docs: add tape schedule examples

[Dominik Csapak]

just a few examples how one could configure tape pools and jobs.

Signed-off-by: Dominik Csapak <d.csapak@proxmox.com>
---
changes from v1:
* clarified how to manually trigger a new media-set in the simplest case
* reworded last example by removing 'rotation' (if a tape is rotated
  depends on how many tapes there are in the pool)

 docs/tape-backup.rst | 74 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 74 insertions(+)

diff --git a/docs/tape-backup.rst b/docs/tape-backup.rst
index ae597d3d..5d4ce444 100644
--- a/docs/tape-backup.rst
+++ b/docs/tape-backup.rst
@@ -979,3 +979,77 @@ This command does the following:
 - run drive cleaning operation
 
 - unload the cleaning tape (to slot 3)
+
+Example Setups
+--------------
+
+Here are a few example setups for how to manage media pools and schedules.
+This is not an exhaustive list, and there are many more possible combinations
+of useful settings.
+
+Simple Setup
+~~~~~~~~~~~~
+
+The most simple setup, always continue the media-set and never expire.
+All backups are stored on a single media set and never deleted.
+
+Allocation policy:
+  continue
+
+Retention policy:
+  keep
+
+Such a simple setup has the advantage that it uses not much space, and
+since there is only one media-set, it is easy to manage. On the other hand,
+it is prone to errors. If a single tape fails, all backups that uses chunks
+from that tape will not be restorable. If you want to start a new media-set
+manually, you can set the currently writable media of the set either to
+'full', or set the location to an offsite vault. In that case, a new
+media-set will be created.
+
+Weekday Scheme
+~~~~~~~~~~~~~~
+
+A slightly more complex scheme, where the goal is to have a tape for each
+weekday, e.g. from Monday to Friday. This can be solved by having a seperate
+media pool for each day, so 'Monday', 'Tuesday', etc.
+
+Allocation policy:
+  should be 'mon' for the 'Monday' pool, 'tue' for the Tuesday pool and so on.
+
+Retention policy:
+  overwrite
+
+There should be a (or more) tape-backup jobs for each pool on the correspondig
+weekday. This scheme is still easily managable with one media set per weekday,
+which can even be taken off site easily.
+
+Staggered Pools
+~~~~~~~~~~~~~~~
+
+Alternatively, more complex setups are possible with multiple media pools and
+different allocation and retention policies.
+
+An example would be to have a media pool with weekly allocation:
+
+Allocation policy:
+  mon
+
+Retention policy:
+  3 weeks
+
+This creates a new media set each week, and expires them after the 4th
+media set.
+
+Then in addition, there could be a yearly pool that only gets allocated
+once a year, but will not be expired (e.g. for long-term archival purposes):
+
+Allocation policy:
+  yearly
+
+Retention policy:
+  keep
+
+In combination with suited prune settings and tape backup schedules, this
+achieves long-term storage of some backups, while keeping the current
+backups on smaller media sets that get expired every 4 weeks.
-- 
2.30.2

[pbs-devel] applied: [PATCH proxmox-backup v2 1/2] docs: explain retention time for event allocation policy in more detail

[Dietmar Maurer]

applied both patches

Re: [pbs-devel] [PATCH proxmox-backup v2 2/2] docs: add tape schedule examples

[Thomas Lamprecht]

On 28.02.22 12:20, Dominik Csapak wrote:
> just a few examples how one could configure tape pools and jobs.
> 
> Signed-off-by: Dominik Csapak <d.csapak@proxmox.com>
> ---
> changes from v1:
> * clarified how to manually trigger a new media-set in the simplest case
> * reworded last example by removing 'rotation' (if a tape is rotated
>   depends on how many tapes there are in the pool)
> 

some wording/typo/grammar comments inline

>  docs/tape-backup.rst | 74 ++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 74 insertions(+)
> 
> diff --git a/docs/tape-backup.rst b/docs/tape-backup.rst
> index ae597d3d..5d4ce444 100644
> --- a/docs/tape-backup.rst
> +++ b/docs/tape-backup.rst
> @@ -979,3 +979,77 @@ This command does the following:
>  - run drive cleaning operation
>  
>  - unload the cleaning tape (to slot 3)
> +
> +Example Setups
> +--------------
> +
> +Here are a few example setups for how to manage media pools and schedules.
> +This is not an exhaustive list, and there are many more possible combinations
> +of useful settings.
> +
> +Simple Setup
> +~~~~~~~~~~~~
> +

Not that hard feelings, but "simple setup" is not really telling.

"Continuously Incremental Keep" isn't that nice either but at least a bit
less ominous, maybe you got a better idea:

> +The most simple setup, always continue the media-set and never expire.

Either s/,/:/ or

The most simple setup is to always continue the media-set and never let it expire.

> +All backups are stored on a single media set and never deleted.

IMO first part superfluous and the never being deleted is a bit weird in context
of tapes which cannot be deleted anyway, I'd just drop that sentence and add a bit
more context below.

> +
> +Allocation policy:
> +  continue
> +
> +Retention policy:
> +  keep
> +
> +Such a simple setup has the advantage that it uses not much space, and

maybe:

That setup had the advantage of being easy to manage and re-using the benefits
from deduplication as much as possible. But, it's also prone to a failure of
any single tape, which would render all backups referring to chunks from that
tape unusable.


> +since there is only one media-set, it is easy to manage. On the other hand,
> +it is prone to errors. If a single tape fails, all backups that uses chunks
> +from that tape will not be restorable. If you want to start a new media-set
> +manually, you can set the currently writable media of the set either to
> +'full', or set the location to an offsite vault. In that case, a new
> +media-set will be created.

Feels a bit redundant, the sentence before that already starts with "If you want
to start a new media-set"

> +
> +Weekday Scheme
> +~~~~~~~~~~~~~~
> +
> +A slightly more complex scheme, where the goal is to have a tape for each

maybe add "independent", like: "... to have an independent tape ..."

> +weekday, e.g. from Monday to Friday. This can be solved by having a seperate

separate

Our technical writing style guide recommends to avoid "e.g.":
https://intranet.proxmox.com/index.php/Technical_Writing_Style_Guide#e.g..2Fi.e.

> +media pool for each day, so 'Monday', 'Tuesday', etc.
> +
> +Allocation policy:
> +  should be 'mon' for the 'Monday' pool, 'tue' for the Tuesday pool and so on.
> +
> +Retention policy:
> +  overwrite
> +
> +There should be a (or more) tape-backup jobs for each pool on the correspondig

corresponding

> +weekday. This scheme is still easily managable with one media set per weekday,

manageable

> +which can even be taken off site easily.

easily twice in the same sentence sounds a bit off.

> +
> +Staggered Pools
> +~~~~~~~~~~~~~~~

staggered sounds a bit hard to understand for a user

> +
> +Alternatively, more complex setups are possible with multiple media pools and
> +different allocation and retention policies.
> +
> +An example would be to have a media pool with weekly allocation:

I'd start off with mentioning both pools so that the user has it already
in mind when reading, for example the whole section could be roughly:

An example would be to have two media pools, one with weekly allocation:

 Allocation Policy:
 ...

And another one with yearly allocation that does not expire:

 ...

In combination with suited, ...

> +
> +Allocation policy:
> +  mon
> +
> +Retention policy:
> +  3 weeks
> +
> +This creates a new media set each week, and expires them after the 4th
> +media set.
> +
> +Then in addition, there could be a yearly pool that only gets allocated
> +once a year, but will not be expired (e.g. for long-term archival purposes):
> +
> +Allocation policy:
> +  yearly
> +
> +Retention policy:
> +  keep
> +
> +In combination with suited prune settings and tape backup schedules, this
> +achieves long-term storage of some backups, while keeping the current
> +backups on smaller media sets that get expired every 4 weeks.