From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <f.ebner@proxmox.com>
Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68])
 (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)
 key-exchange X25519 server-signature RSA-PSS (2048 bits))
 (No client certificate requested)
 by lists.proxmox.com (Postfix) with ESMTPS id B1B6662920
 for <pve-devel@lists.proxmox.com>; Tue, 24 Nov 2020 11:02:05 +0100 (CET)
Received: from firstgate.proxmox.com (localhost [127.0.0.1])
 by firstgate.proxmox.com (Proxmox) with ESMTP id 995AF9F1C
 for <pve-devel@lists.proxmox.com>; Tue, 24 Nov 2020 11:02:05 +0100 (CET)
Received: from proxmox-new.maurer-it.com (proxmox-new.maurer-it.com
 [212.186.127.180])
 (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)
 key-exchange X25519 server-signature RSA-PSS (2048 bits))
 (No client certificate requested)
 by firstgate.proxmox.com (Proxmox) with ESMTPS id CFCD79F13
 for <pve-devel@lists.proxmox.com>; Tue, 24 Nov 2020 11:02:04 +0100 (CET)
Received: from proxmox-new.maurer-it.com (localhost.localdomain [127.0.0.1])
 by proxmox-new.maurer-it.com (Proxmox) with ESMTP id 93099404B9
 for <pve-devel@lists.proxmox.com>; Tue, 24 Nov 2020 11:02:04 +0100 (CET)
From: Fabian Ebner <f.ebner@proxmox.com>
To: pve-devel@lists.proxmox.com
Date: Tue, 24 Nov 2020 11:02:00 +0100
Message-Id: <20201124100200.17646-1-f.ebner@proxmox.com>
X-Mailer: git-send-email 2.20.1
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
X-SPAM-LEVEL: Spam detection results:  0
 AWL -0.010 Adjusted score from AWL reputation of From: address
 KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment
 RCVD_IN_DNSWL_MED        -2.3 Sender listed at https://www.dnswl.org/,
 medium trust
 SPF_HELO_NONE           0.001 SPF: HELO does not publish an SPF Record
 SPF_PASS               -0.001 SPF: sender matches SPF record
Subject: [pve-devel] [PATCH docs] add documentation for the prune-backups
 option
X-BeenThere: pve-devel@lists.proxmox.com
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: Proxmox VE development discussion <pve-devel.lists.proxmox.com>
List-Unsubscribe: <https://lists.proxmox.com/cgi-bin/mailman/options/pve-devel>, 
 <mailto:pve-devel-request@lists.proxmox.com?subject=unsubscribe>
List-Archive: <http://lists.proxmox.com/pipermail/pve-devel/>
List-Post: <mailto:pve-devel@lists.proxmox.com>
List-Help: <mailto:pve-devel-request@lists.proxmox.com?subject=help>
List-Subscribe: <https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel>, 
 <mailto:pve-devel-request@lists.proxmox.com?subject=subscribe>
X-List-Received-Date: Tue, 24 Nov 2020 10:02:05 -0000

adapted from the PBS docs, and mention that maxfiles is deprecated.

Signed-off-by: Fabian Ebner <f.ebner@proxmox.com>
---
 pvesm.adoc  |  8 ++++-
 vzdump.adoc | 94 +++++++++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 98 insertions(+), 4 deletions(-)

diff --git a/pvesm.adoc b/pvesm.adoc
index ee7f598..67745a0 100644
--- a/pvesm.adoc
+++ b/pvesm.adoc
@@ -226,7 +226,13 @@ You can use this flag to disable the storage completely.
 
 maxfiles::
 
-Maximum number of backup files per VM. Use `0` for unlimited.
+Deprecated, please use `prune-backups` instead. Maximum number of backup files
+per VM. Use `0` for unlimited.
+
+prune-backups::
+
+Retention options for backups. For details, see
+xref:vzdump_retention[Backup Retention].
 
 format::
 
diff --git a/vzdump.adoc b/vzdump.adoc
index 1c39680..24e3ff2 100644
--- a/vzdump.adoc
+++ b/vzdump.adoc
@@ -143,9 +143,9 @@ backup time into the filename, for example
 
  vzdump-lxc-105-2009_10_09-11_04_43.tar
 
-That way it is possible to store several backup in the same
-directory. The parameter `maxfiles` can be used to specify the
-maximum number of backups to keep.
+That way it is possible to store several backup in the same directory. You can
+limit the number of backups that are kept with various retention options, see
+the xref:vzdump_retention[Backup Retention] section below.
 
 Backup File Compression
 -----------------------
@@ -180,6 +180,94 @@ If the backup file name doesn't end with one of the above file extensions, then
 it was not compressed by vzdump.
 
 
+[[vzdump_retention]]
+Backup Retention
+----------------
+
+With the `prune-backups` option you can specify which backups you want to keep
+in a flexible manner. The following retention options are available:
+
+`keep-all <boolean>` ::
+Keep all backups. If this is `true`, no other options can be set.
+
+`keep-last <N>` ::
+Keep the last `<N>` backups.
+
+`keep-hourly <N>` ::
+Keep backups for the last `<N>` hours. If there is more than one
+backup for a single hour, only the latest is kept.
+
+`keep-daily <N>` ::
+Keep backups for the last `<N>` days. If there is more than one
+backup for a single day, only the latest is kept.
+
+`keep-weekly <N>` ::
+Keep backups for the last `<N>` weeks. If there is more than one
+backup for a single week, only the latest is kept.
+
+NOTE: Weeks start on Monday and end on Sunday. The software uses the
+`ISO week date`-system and handles weeks at the end of the year correctly.
+
+`keep-monthly <N>` ::
+Keep backups for the last `<N>` months. If there is more than one
+backup for a single month, only the latest is kept.
+
+`keep-yearly <N>` ::
+Keep backups for the last `<N>` years. If there is more than one
+backup for a single year, only the latest is kept.
+
+The retention options are processed in the order given above. Each option
+only covers backups within its time period. The next option does not take care
+of already covered backups. It will only consider older backups.
+
+Specify the retention options you want to use as a
+comma-separated list, for example:
+
+ # vzdump 777 --prune-backups keep-last=3,keep-daily=13,keep-yearly=9
+
+While you can pass `prune-backups` directly to `vzdump`, it is often more
+sensible to configure the setting on the storage level, which can be done via
+the web interface.
+
+NOTE: The old `maxfiles` option is deprecated and should be replaced either by
+`keep-last` or, in case `maxfiles` was `0` for unlimited retention, by
+`keep-all`.
+
+Retention Settings Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The backup frequency and retention of old backups may depend on how often data
+changes, and how important an older state may be, in a specific work load.
+When backups act as a company's document archive, there may also be legal
+requirements for how long backups must be kept.
+
+For this example, we assume that you are doing daily backups, have a retention
+period of 10 years, and the period between backups stored gradually grows.
+
+`keep-last=3` - even if only daily backups are taken, an admin may want to
+  create an extra one just before or after a big upgrade. Setting keep-last
+  ensures this.
+
+`keep-hourly` is not set - for daily backups this is not relevant. You cover
+  extra manual backups already, with keep-last.
+
+`keep-daily=13` - together with keep-last, which covers at least one
+  day, this ensures that you have at least two weeks of backups.
+
+`keep-weekly=8` - ensures that you have at least two full months of
+  weekly backups.
+
+`keep-monthly=11` - together with the previous keep settings, this
+  ensures that you have at least a year of monthly backups.
+
+`keep-yearly=9` - this is for the long term archive. As you covered the
+  current year with the previous options, you would set this to nine for the
+  remaining ones, giving you a total of at least 10 years of coverage.
+
+We recommend that you use a higher retention period than is minimally required
+by your environment; you can always reduce it if you find it is unnecessarily
+high, but you cannot recreate backups once they have been removed.
+
 [[vzdump_restore]]
 Restore
 -------
-- 
2.20.1