[PATCH proxmox-backup v2 43/43] docs: document snapshot retention for new backup snapshots

[Christian Ebner <c.ebner@proxmox.com>]

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 <c.ebner@proxmox.com>
---
 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