From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: 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 A1B2F70A79 for ; Mon, 16 May 2022 15:48:52 +0200 (CEST) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 988901DD2C for ; Mon, 16 May 2022 15:48:52 +0200 (CEST) Received: from proxmox-new.maurer-it.com (proxmox-new.maurer-it.com [94.136.29.106]) (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 486991DD21 for ; Mon, 16 May 2022 15:48:51 +0200 (CEST) Received: from proxmox-new.maurer-it.com (localhost.localdomain [127.0.0.1]) by proxmox-new.maurer-it.com (Proxmox) with ESMTP id 1986B43615 for ; Mon, 16 May 2022 15:48:51 +0200 (CEST) From: =?UTF-8?q?Fabian=20Gr=C3=BCnbichler?= To: pbs-devel@lists.proxmox.com Date: Mon, 16 May 2022 15:48:46 +0200 Message-Id: <20220516134846.2888227-1-f.gruenbichler@proxmox.com> X-Mailer: git-send-email 2.30.2 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-SPAM-LEVEL: Spam detection results: 0 AWL 0.173 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record T_SCC_BODY_TEXT_LINE -0.01 - Subject: [pbs-devel] [PATCH proxmox-backup] docs: add namespace section to sync documentation X-BeenThere: pbs-devel@lists.proxmox.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Proxmox Backup Server development discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 16 May 2022 13:48:52 -0000 Signed-off-by: Fabian Grünbichler --- 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