[pbs-devel] [PATCH v3 proxmox-backup 56/58] docs: add section describing change detection mode

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

Describe the motivation and basic principle of the clients change
detection mode and show an example invocation.

Signed-off-by: Christian Ebner <c.ebner@proxmox.com>
---
changes since version 2:
- not present in previous version

 docs/backup-client.rst | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/docs/backup-client.rst b/docs/backup-client.rst
index 00a1abbb3..e54a52bf4 100644
--- a/docs/backup-client.rst
+++ b/docs/backup-client.rst
@@ -280,6 +280,39 @@ Multiple paths can be excluded like this:
 
     # proxmox-backup-client backup.pxar:./linux --exclude=/usr --exclude=/rust
 
+.. _client_change_detection_mode:
+
+Change detection mode
+~~~~~~~~~~~~~~~~~~~~~
+
+Backing up filesystems with large contents can take a long time, as the default
+behaviour for the Proxmox Backup Client is to read all data and re-encode it
+into chunks. For some usecases, where files do not change frequently this is not
+feasible and undesired.
+
+In order to instruct the client to not re-encode files with unchanged metadata,
+the `change-detection-mode` can be set from the default `data` to `metadata`.
+By this, regular file payloads for files with unchanged metadata are looked up
+and re-used from the previous backup runs snapshot when possible. For this to
+be feasible, the pxar archives for backup runs using this mode are split into
+two separate files, the `mpxar` containing the archives metadata and the `ppxar`
+containing a concatenation of the file payloads.
+
+During backup, the current file metadata is compared to the one looked up in the
+previous `mpxar` archive, and if unchanged, the payload of the file is included
+in the current backup by referencing the indices of the previous snaphshot. The
+increase in backup speed comes at the cost of a possible increase of used space,
+as chunks might only be partially reused, containing unneeded padding. This is
+however minimized by selectively re-encoding files where the padding overhead
+does not justify a re-use.
+
+The following shows an example for the client invocation with the `metadata`
+mode:
+
+.. code-block:: console
+
+    # proxmox-backup-client backup.pxar:./linux --change-detection-mode=metadata
+
 .. _client_encryption:
 
 Encryption
-- 
2.39.2