-Managing Remotes
-================
+Managing Remotes & Sync
+=======================
.. _backup_remote:
``/etc/proxmox-backup/remote.cfg``.
.. image:: images/screenshots/pbs-gui-remote-add.png
+ :target: _images/pbs-gui-remote-add.png
:align: right
:alt: Add a remote
---------
.. image:: images/screenshots/pbs-gui-syncjob-add.png
+ :target: _images/pbs-gui-syncjob-add.png
:align: right
:alt: Add a Sync Job
If the ``group-filter`` option is set, only backup groups matching at least one
of the specified criteria are synced. The available criteria are:
-* backup type, for example to only sync groups of the `ct` (Container) type:
+* Backup type, for example, to only sync groups of the `ct` (Container) type:
.. code-block:: console
# proxmox-backup-manager sync-job update ID --group-filter type:ct
-* full group identifier
+* Full group identifier, to sync a specific backup group:
.. code-block:: console
# 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
+* Regular expression, matched against the full group identifier
+ .. code-block:: console
+
+ # proxmox-backup-manager sync-job update ID --group-filter regex:'^vm/1\d{2,3}$'
-The same filter is applied to local groups for handling of the
+The same filter is applied to local groups, for handling of the
``remove-vanished`` option.
.. 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 subsets 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's
+execution:
+
+- ``remote-ns``: the remote namespace anchor (default: the root namespace)
+
+- ``ns``: the local namespace anchor (default: the root namespace)
+
+- ``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
^^^^^^^^^^^^^^^
-Syncing datastores to an archive can produce lots of traffic and impact other
-users of the network. So, to avoid network or storage congetsion you can limit
-the bandwith of the sync job by setting the ``rate-in`` option either in the
-web interface or using the ``proxmox-backup-manager`` command-line tool:
+Syncing a datastore to an archive can produce a lot of traffic and impact other
+users of the network. In order to avoid network or storage congestion, you can
+limit the bandwidth of the sync job by setting the ``rate-in`` option either in
+the web interface or using the ``proxmox-backup-manager`` command-line tool:
.. code-block:: console
projects / proxmox-backup.git / blobdiff