From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from gate001.proxmox.com (gate001.proxmox.com [45.144.208.40]) by lore.proxmox.com (Postfix) with ESMTPS id 8C7CB1FF0AF for ; Fri, 06 Nov 2026 18:24:56 +0100 (CET) Received: from gate001.proxmox.com (localhost.localdomain [127.0.0.1]) by gate001.proxmox.com (Proxmox) with ESMTP id 1FAD321877; Fri, 06 Nov 2026 18:23:48 +0100 (CET) From: Christian Ebner To: pbs-devel@lists.proxmox.com Subject: [PATCH proxmox-backup v2 43/43] docs: document snapshot retention for new backup snapshots Date: Fri, 6 Nov 2026 18:22:35 +0100 Message-ID: <20261106172235.890542-44-c.ebner@proxmox.com> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20261106172235.890542-1-c.ebner@proxmox.com> References: <20261106172235.890542-1-c.ebner@proxmox.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1793985782040 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.441 Adjusted score from AWL reputation of From: address DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment (newer systems) 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 Message-ID-Hash: 334GSO5XCDCMWBEJ5IC5IMW54EXOYLPR X-Message-ID-Hash: 334GSO5XCDCMWBEJ5IC5IMW54EXOYLPR X-MailFrom: c.ebner@proxmox.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header X-Mailman-Version: 3.3.10 Precedence: list List-Id: Proxmox Backup Server development discussion List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: Basic description of what it does and limitations in connection with datastore options, examples for how to set a new retention via the client and for sync job configuration. Signed-off-by: Christian Ebner --- docs/backup-client.rst | 28 ++++++++++++++++++++++++++++ docs/maintenance.rst | 22 ++++++++++++++++++++++ docs/managing-remotes.rst | 20 ++++++++++++++++++++ docs/storage.rst | 7 +++++++ 4 files changed, 77 insertions(+) diff --git a/docs/backup-client.rst b/docs/backup-client.rst index bf207452f..32841f71a 100644 --- a/docs/backup-client.rst +++ b/docs/backup-client.rst @@ -299,6 +299,32 @@ device images. To create a backup of a block device, run the following command: # proxmox-backup-client backup mydata.img:/dev/mylvm/mydata +Setting a Retention Lock on New Backups +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can specify a retention timestamp when creating a backup by passing the +``--retain-until`` parameter formatted as an RFC 3339 timestamp: + +.. code-block:: console + + # proxmox-backup-client backup root.pxar:/ --retain-until '2026-12-31T23:59:59Z' + +Another convenient way to set a retention is by specifying a timespan via the +``--retention-timespan`` parameter, which will calculate the timestamp relative +to the current system time for you: + +.. code-block:: console + + # proxmox-backup-client backup root.pxar:/ --retention-timespan 1h + + +When set, the backup server locks the snapshot with a retention lock. The +snapshot cannot be deleted or pruned until the retention timestamp is reached. +The specified retention must be within the ``max-retention-timespan`` as +configured on the backup server's datastore, otherwise the backup request is +rejected. If the server has no configuration, setting retentions is not +possible. + Excluding Files/Directories from a Backup ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -864,6 +890,8 @@ they are newer than the last successful backup. In this case, the last failed backup is retained. Snapshots whose timestamps are in the future relative to the system time of the PBS will be ignored and always kept when pruning, only applying retention options to older snapshots. +Snapshots protected by an active retention lock (``retain-until``) cannot be pruned +or forgotten until their retention period expires. .. code-block:: console diff --git a/docs/maintenance.rst b/docs/maintenance.rst index d23a3774f..0b059c732 100644 --- a/docs/maintenance.rst +++ b/docs/maintenance.rst @@ -76,6 +76,28 @@ Old unfinished or incomplete backups will be removed by the prune command, unless they are newer than the last successful backup. In this case, the last failed backup is retained. + +.. _snapshot_retention: + +Snapshot Retention (WORM Protection) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Individual backup snapshots can be protected by a retention lock until a specified timestamp +(``retain-until``). This provides Write-Once-Read-Many (WORM) immutability to guard against +premature deletion, ransomware, and administrative errors. + +* **Immutability**: A retained snapshot cannot be pruned, forgotten, or destroyed until its + retention period has expired. +* **Prune Independence**: Retained snapshots are excluded from the keep slots (such as + ``keep-daily`` or ``keep-weekly``) evaluated by the prune engine. This ensures that retained + snapshots do not crowd out or starve regular un-retained snapshots from their intended keep slots. +* **Strict Modification Control**: Only the superuser (``root@pam``) can modify the retention + timestamp of an existing snapshot. Retention can only be extended; it can never be shortened + or cleared before it expires. +* **Group and Datastore Guard**: A backup group containing retained snapshots cannot be deleted + during group removal operations. Furthermore, a datastore containing active retentions cannot + be destroyed with ``--destroy-data``. + Prune Simulator ^^^^^^^^^^^^^^^ diff --git a/docs/managing-remotes.rst b/docs/managing-remotes.rst index b25e3d532..294e9c613 100644 --- a/docs/managing-remotes.rst +++ b/docs/managing-remotes.rst @@ -184,6 +184,26 @@ buffered briefly to keep related lines together. Note that the memory and connection count on both endpoints grow roughly linearly with the number of workers, so higher values are not always better. +.. _sync_job_retention: + +Sync Job Retention Timespan +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Sync jobs can be configured with a ``retention-timespan`` (for example, ``30d`` +or ``1y``). When set, any backup snapshot newly synced by the job will have an +active retention lock applied automatically upon creation: + +.. code-block:: console + + # proxmox-backup-manager sync-job update pbs2-local --retention-timespan '30d' + +This ensures that synced snapshots cannot be deleted or pruned until their +retention period expires, forming a reliable off-site WORM backup target. The +sync job's retention can however never exceed the ``max-retention-timespan`` +configured for the target datastore, if it is not set, no retention is allowed. +If no retention timespan is configured on the sync job, the target datastore's +``default-retention-timespan`` is applied as a fallback, if set. + Namespace Support ^^^^^^^^^^^^^^^^^ diff --git a/docs/storage.rst b/docs/storage.rst index 4e2374499..3f97f625a 100644 --- a/docs/storage.rst +++ b/docs/storage.rst @@ -614,6 +614,13 @@ There are a few per-datastore options: * Maximum allowed time skew for snapshot timestamps (<= 1 day, default: 1 minute). Does not allow for backup snapshot timestamps to be further in the future than the configured value relative to the server's system time. +* **Maximum Retention Timespan** (``max-retention-timespan``): Enforces an upper + limit on how far into the future a snapshot's retention lock can be set on + this datastore. Backups or sync operations requesting retention beyond this + limit are rejected. +* **Default Retention Timespan** (``default-retention-timespan``): Default + retention period automatically applied to new backup snapshots or sync pulls + if the client or sync job does not supply an explicit retention timestamp. .. _datastore_tuning_options: -- 2.47.3