[pbs-devel] [PATCH proxmox-backup] docs: add namespace section to sync documentation

["Fabian Grünbichler" <f.gruenbichler@proxmox.com>]

Signed-off-by: Fabian Grünbichler <f.gruenbichler@proxmox.com>
---
 docs/managing-remotes.rst | 82 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)

diff --git a/docs/managing-remotes.rst b/docs/managing-remotes.rst
index 7d47d8be..f9e4c038 100644
--- a/docs/managing-remotes.rst
+++ b/docs/managing-remotes.rst
@@ -107,6 +107,7 @@ of the specified criteria are synced. The available criteria are:
 
      # proxmox-backup-manager sync-job update ID --group-filter group:vm/100
 * regular expression matched against the full group identifier
+
 .. todo:: add example for regex
 
 The same filter is applied to local groups for handling of the
@@ -114,6 +115,87 @@ The same filter is applied to local groups for handling of the
 
 .. note:: The ``protected`` flag of remote backup snapshots will not be synced.
 
+Namespace Support
+^^^^^^^^^^^^^^^^^
+
+Sync jobs can be configured to not only sync datastores, but also sub-sets of
+datastores in the form of namespaces or namespace sub-trees. The following
+parameters influence how namespaces are treated as part of a sync job
+execution:
+
+- ``remote-ns``: the remote namespace anchor (default: the root namespace)
+
+- ``ns``: the local namespace anchor (default: the root naemspace)
+
+- ``max-depth``: whether to recursively iterate over sub-namespaces of the remote
+  namespace anchor (default: `None`)
+
+If ``max-depth`` is set to `0`, groups are synced from ``remote-ns`` into
+``ns``, without any recursion. If it is set to `None` (left empty), recursion
+depth will depend on the value of ``remote-ns`` and the remote side's
+availability of namespace support:
+
+- ``remote-ns`` set to something other than the root namespace: remote *must*
+  support namespaces, full recursion starting at ``remote-ns``.
+
+- ``remote-ns`` set to root namespace and remote *supports* namespaces: full
+  recursion starting at root namespace.
+
+- ``remote-ns`` set to root namespace and remote *does not support* namespaces:
+  backwards-compat mode, only root namespace will be synced into ``ns``, no
+  recursion.
+
+Any other value of ``max-depth`` will limit recursion to at most ``max-depth``
+levels, for example: ``remote-ns`` set to `location_a/department_b` and
+``max-depth`` set to `1` will result in `location_a/department_b` and at most
+one more level of sub-namespaces being synced.
+
+The namespace tree starting at ``remote-ns`` will be mapped into ``ns`` up to a
+depth of ``max-depth``.
+
+For example, with the following namespaces at the remote side:
+
+- `location_a`
+
+  - `location_a/department_x`
+
+    - `location_a/department_x/team_one`
+
+    - `location_a/department_x/team_two`
+
+  - `location_a/department_y`
+
+    - `location_a/department_y/team_one`
+
+    - `location_a/department_y/team_two`
+
+- `location_b`
+
+and ``remote-ns`` being set to `location_a/department_x` and ``ns`` set to
+`location_a_dep_x` resulting in the following namespace tree on the sync
+target:
+
+- `location_a_dep_x` (containing the remote's `location_a/department_x`)
+
+  - `location_a_dep_x/team_one` (containing the remote's `location_a/department_x/team_one`)
+
+  - `location_a_dep_x/team_two` (containing the remote's `location_a/department_x/team_two`)
+
+with the rest of the remote namespaces and groups not being synced (by this
+sync job).
+
+If a remote namespace is included in the sync job scope, but does not exist
+locally, it will be created (provided the sync job owner has sufficient
+privileges).
+
+If the ``remove-vanished`` option is set, namespaces that are included in the
+sync job scope but only exist locally are treated as vanished and removed
+(provided the sync job owner has sufficient privileges).
+
+.. note:: All other limitations on sync scope (such as remote user/API token
+   privileges, group filters) also apply for sync jobs involving one or
+   multiple namespaces.
+
 Bandwidth Limit
 ^^^^^^^^^^^^^^^
 
-- 
2.30.2