[PATCH proxmox-backup v7 4/9] docs: add section on moving namespaces and groups

Hannes Laimer
2026-04-16T17:18:47Z

Document the move-group and move-namespace operations including merge
behavior, max-depth and delete-source parameters. Add an online help
anchor so the UI move dialogs can link directly to this section.

Signed-off-by: Hannes Laimer <h.laimer@proxmox.com>
---
docs/storage.rst | 45 ++++++++++++++++++++++++++++++++++++++++++-
www/OnlineHelpInfo.js | 4 ++++
2 files changed, 48 insertions(+), 1 deletion(-)

diff --git a/docs/storage.rst b/docs/storage.rst
index 672091f8..ad507fd4 100644
--- a/docs/storage.rst
+++ b/docs/storage.rst
@@ -527,7 +527,50 @@ For backup groups, the existing privilege rules still apply. You either need a
privileged enough permission or to be the owner of the backup group; nothing
changed here.

-.. todo:: continue
+.. _storage_move_namespaces_groups:
+
+Moving Namespaces and Groups
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Backup groups can be moved between namespaces within the same datastore.
+This is useful for reorganizing backup hierarchies without having to
+re-run backups.
+
+A single group can be moved with ``move-group``. To relocate an entire
+namespace subtree (including all child namespaces and their groups), use
+``move-namespace``.
+
+.. code-block:: console
+
+ # proxmox-backup-manager datastore move-group <store> --ns --target-ns <target> --backup-type <type> --backup-id <id>
+ # proxmox-backup-manager datastore move-namespace <store> --ns --target-ns <target>
+
+If the target namespace already exists, groups are moved into it. When a
+group with the same type and ID already exists in the target and
+``merge-groups`` is enabled, the snapshots are merged into the existing
+group provided:
+
+- both groups have the same owner
+- the oldest source snapshot is newer than the newest target snapshot
+
+Groups that cannot be merged or locked are skipped and reported in the
+task log. They remain at the source and can be retried individually with
+``move-group``.
+
+Optional parameters for ``move-namespace``:
+
+``merge-groups``
+ Allow merging snapshots into groups that already exist in the target
+ namespace with the same type and ID. Defaults to false.
+
+``max-depth``
+ Limits how many levels of child namespaces below the source are
+ included. When not set, the entire subtree is moved.
+
+``delete-source``
+ Controls whether the source namespace directories are removed after
+ all groups have been moved out. Defaults to true. Set to false to
+ keep the (now empty) source namespace structure.

Options
diff --git a/www/OnlineHelpInfo.js b/www/OnlineHelpInfo.js
index 89650cfb..e118b0ad 100644
--- a/www/OnlineHelpInfo.js
+++ b/www/OnlineHelpInfo.js
@@ -299,6 +299,10 @@ const proxmoxOnlineHelpInfo = {
"link": "/docs/storage.html#storage-namespaces",
"title": "Backup Namespaces"
},
+ "storage-move-namespaces-groups": {
+ "link": "/docs/storage.html#storage-move-namespaces-groups",
+ "title": "Moving Namespaces and Groups"
+ },
"datastore-tuning-options": {
"link": "/docs/storage.html#datastore-tuning-options",
"title": "Tuning"
--
2.47.3