]>
Commit | Line | Data |
---|---|---|
acbb1949 TL |
1 | Managing Remotes & Sync |
2 | ======================= | |
04e24b14 | 3 | |
476328b3 OB |
4 | .. _backup_remote: |
5 | ||
04e24b14 DW |
6 | :term:`Remote` |
7 | -------------- | |
8 | ||
34407477 AZ |
9 | A remote refers to a separate `Proxmox Backup`_ Server installation and a user |
10 | on that installation, from which you can `sync` datastores to a local datastore | |
11 | with a `Sync Job`. You can configure remotes in the web interface, under | |
12 | **Configuration -> Remotes**. Alternatively, you can use the ``remote`` | |
13 | subcommand. The configuration information for remotes is stored in the file | |
04e24b14 DW |
14 | ``/etc/proxmox-backup/remote.cfg``. |
15 | ||
16 | .. image:: images/screenshots/pbs-gui-remote-add.png | |
5565e454 | 17 | :target: _images/pbs-gui-remote-add.png |
04e24b14 DW |
18 | :align: right |
19 | :alt: Add a remote | |
20 | ||
7ccbce03 DW |
21 | To add a remote, you need its hostname or IP address, a userid and password on |
22 | the remote, and its certificate fingerprint. To get the fingerprint, use the | |
04e24b14 DW |
23 | ``proxmox-backup-manager cert info`` command on the remote, or navigate to |
24 | **Dashboard** in the remote's web interface and select **Show Fingerprint**. | |
25 | ||
26 | .. code-block:: console | |
27 | ||
28 | # proxmox-backup-manager cert info |grep Fingerprint | |
29 | Fingerprint (sha256): 64:d3:ff:3a:50:38:53:5a:9b:f7:50:...:ab:fe | |
30 | ||
31 | Using the information specified above, you can add a remote from the **Remotes** | |
32 | configuration panel, or by using the command: | |
33 | ||
34 | .. code-block:: console | |
35 | ||
36 | # proxmox-backup-manager remote create pbs2 --host pbs2.mydomain.example --userid sync@pam --password 'SECRET' --fingerprint 64:d3:ff:3a:50:38:53:5a:9b:f7:50:...:ab:fe | |
37 | ||
38 | Use the ``list``, ``show``, ``update``, ``remove`` subcommands of | |
39 | ``proxmox-backup-manager remote`` to manage your remotes: | |
40 | ||
41 | .. code-block:: console | |
42 | ||
43 | # proxmox-backup-manager remote update pbs2 --host pbs2.example | |
44 | # proxmox-backup-manager remote list | |
45 | ┌──────┬──────────────┬──────────┬───────────────────────────────────────────┬─────────┐ | |
46 | │ name │ host │ userid │ fingerprint │ comment │ | |
47 | ╞══════╪══════════════╪══════════╪═══════════════════════════════════════════╪═════════╡ | |
48 | │ pbs2 │ pbs2.example │ sync@pam │64:d3:ff:3a:50:38:53:5a:9b:f7:50:...:ab:fe │ │ | |
49 | └──────┴──────────────┴──────────┴───────────────────────────────────────────┴─────────┘ | |
50 | # proxmox-backup-manager remote remove pbs2 | |
51 | ||
52 | ||
53 | .. _syncjobs: | |
54 | ||
55 | Sync Jobs | |
56 | --------- | |
57 | ||
58 | .. image:: images/screenshots/pbs-gui-syncjob-add.png | |
5565e454 | 59 | :target: _images/pbs-gui-syncjob-add.png |
04e24b14 DW |
60 | :align: right |
61 | :alt: Add a Sync Job | |
62 | ||
63 | Sync jobs are configured to pull the contents of a datastore on a **Remote** to | |
6227b9ba | 64 | a local datastore. You can manage sync jobs in the web interface, from the |
7ccbce03 DW |
65 | **Sync Jobs** tab of the **Datastore** panel or from that of the Datastore |
66 | itself. Alternatively, you can manage them with the ``proxmox-backup-manager | |
67 | sync-job`` command. The configuration information for sync jobs is stored at | |
68 | ``/etc/proxmox-backup/sync.cfg``. To create a new sync job, click the add button | |
69 | in the GUI, or use the ``create`` subcommand. After creating a sync job, you can | |
70 | either start it manually from the GUI or provide it with a schedule (see | |
71 | :ref:`calendar-event-scheduling`) to run regularly. | |
04e24b14 DW |
72 | |
73 | .. code-block:: console | |
74 | ||
75 | # proxmox-backup-manager sync-job create pbs2-local --remote pbs2 --remote-store local --store local --schedule 'Wed 02:30' | |
76 | # proxmox-backup-manager sync-job update pbs2-local --comment 'offsite' | |
77 | # proxmox-backup-manager sync-job list | |
78 | ┌────────────┬───────┬────────┬──────────────┬───────────┬─────────┐ | |
79 | │ id │ store │ remote │ remote-store │ schedule │ comment │ | |
80 | ╞════════════╪═══════╪════════╪══════════════╪═══════════╪═════════╡ | |
81 | │ pbs2-local │ local │ pbs2 │ local │ Wed 02:30 │ offsite │ | |
82 | └────────────┴───────┴────────┴──────────────┴───────────┴─────────┘ | |
83 | # proxmox-backup-manager sync-job remove pbs2-local | |
84 | ||
7ccbce03 | 85 | To set up sync jobs, the configuring user needs the following permissions: |
04e24b14 | 86 | |
9de7c71a | 87 | #. ``Remote.Read`` on the ``/remote/{remote}/{remote-store}`` path |
7ccbce03 | 88 | #. At least ``Datastore.Backup`` on the local target datastore (``/datastore/{store}``) |
9de7c71a | 89 | |
4954d313 TL |
90 | .. note:: A sync job can only sync backup groups that the configured remote's |
91 | user/API token can read. If a remote is configured with a user/API token that | |
92 | only has ``Datastore.Backup`` privileges, only the limited set of accessible | |
93 | snapshots owned by that user/API token can be synced. | |
94 | ||
9de7c71a FG |
95 | If the ``remove-vanished`` option is set, ``Datastore.Prune`` is required on |
96 | the local datastore as well. If the ``owner`` option is not set (defaulting to | |
7ccbce03 | 97 | ``root@pam``) or is set to something other than the configuring user, |
9de7c71a FG |
98 | ``Datastore.Modify`` is required as well. |
99 | ||
df325307 TL |
100 | If the ``group-filter`` option is set, only backup groups matching at least one |
101 | of the specified criteria are synced. The available criteria are: | |
102 | ||
6481fd24 | 103 | * Backup type, for example, to only sync groups of the `ct` (Container) type: |
df325307 TL |
104 | .. code-block:: console |
105 | ||
106 | # proxmox-backup-manager sync-job update ID --group-filter type:ct | |
6481fd24 | 107 | * Full group identifier, to sync a specific backup group: |
df325307 TL |
108 | .. code-block:: console |
109 | ||
110 | # proxmox-backup-manager sync-job update ID --group-filter group:vm/100 | |
6481fd24 DW |
111 | * Regular expression, matched against the full group identifier |
112 | .. code-block:: console | |
8c413170 | 113 | |
6481fd24 | 114 | # proxmox-backup-manager sync-job update ID --group-filter regex:'^vm/1\d{2,3}$' |
df325307 | 115 | |
6481fd24 | 116 | The same filter is applied to local groups, for handling of the |
df325307 | 117 | ``remove-vanished`` option. |
01ae7bfa | 118 | |
64dec8d6 | 119 | A ``group-filter`` can be inverted by prepending ``exclude:`` to it. |
f93cbdae PH |
120 | |
121 | * Regular expression example, excluding the match: | |
122 | .. code-block:: console | |
123 | ||
124 | # proxmox-backup-manager sync-job update ID --group-filter exclude:regex:'^vm/1\d{2,3}$' | |
125 | ||
126 | For mixing include and exclude filter, following rules apply: | |
127 | ||
128 | - no filters: all backup groups | |
129 | - include: only those matching the include filters | |
130 | - exclude: all but those matching the exclude filters | |
131 | - both: those matching the include filters, but without those matching the exclude filters | |
ef1923ca | 132 | |
149b969d | 133 | .. note:: The ``protected`` flag of remote backup snapshots will not be synced. |
4954d313 | 134 | |
8c413170 FG |
135 | Namespace Support |
136 | ^^^^^^^^^^^^^^^^^ | |
137 | ||
6481fd24 | 138 | Sync jobs can be configured to not only sync datastores, but also subsets of |
8c413170 | 139 | datastores in the form of namespaces or namespace sub-trees. The following |
6481fd24 | 140 | parameters influence how namespaces are treated as part of a sync job's |
8c413170 FG |
141 | execution: |
142 | ||
143 | - ``remote-ns``: the remote namespace anchor (default: the root namespace) | |
144 | ||
513da8ed | 145 | - ``ns``: the local namespace anchor (default: the root namespace) |
8c413170 FG |
146 | |
147 | - ``max-depth``: whether to recursively iterate over sub-namespaces of the remote | |
148 | namespace anchor (default: `None`) | |
149 | ||
150 | If ``max-depth`` is set to `0`, groups are synced from ``remote-ns`` into | |
151 | ``ns``, without any recursion. If it is set to `None` (left empty), recursion | |
152 | depth will depend on the value of ``remote-ns`` and the remote side's | |
153 | availability of namespace support: | |
154 | ||
155 | - ``remote-ns`` set to something other than the root namespace: remote *must* | |
156 | support namespaces, full recursion starting at ``remote-ns``. | |
157 | ||
158 | - ``remote-ns`` set to root namespace and remote *supports* namespaces: full | |
159 | recursion starting at root namespace. | |
160 | ||
161 | - ``remote-ns`` set to root namespace and remote *does not support* namespaces: | |
162 | backwards-compat mode, only root namespace will be synced into ``ns``, no | |
163 | recursion. | |
164 | ||
165 | Any other value of ``max-depth`` will limit recursion to at most ``max-depth`` | |
166 | levels, for example: ``remote-ns`` set to `location_a/department_b` and | |
167 | ``max-depth`` set to `1` will result in `location_a/department_b` and at most | |
168 | one more level of sub-namespaces being synced. | |
169 | ||
170 | The namespace tree starting at ``remote-ns`` will be mapped into ``ns`` up to a | |
171 | depth of ``max-depth``. | |
172 | ||
173 | For example, with the following namespaces at the remote side: | |
174 | ||
175 | - `location_a` | |
176 | ||
177 | - `location_a/department_x` | |
178 | ||
179 | - `location_a/department_x/team_one` | |
180 | ||
181 | - `location_a/department_x/team_two` | |
182 | ||
183 | - `location_a/department_y` | |
184 | ||
185 | - `location_a/department_y/team_one` | |
186 | ||
187 | - `location_a/department_y/team_two` | |
188 | ||
189 | - `location_b` | |
190 | ||
191 | and ``remote-ns`` being set to `location_a/department_x` and ``ns`` set to | |
192 | `location_a_dep_x` resulting in the following namespace tree on the sync | |
193 | target: | |
194 | ||
195 | - `location_a_dep_x` (containing the remote's `location_a/department_x`) | |
196 | ||
197 | - `location_a_dep_x/team_one` (containing the remote's `location_a/department_x/team_one`) | |
198 | ||
199 | - `location_a_dep_x/team_two` (containing the remote's `location_a/department_x/team_two`) | |
200 | ||
201 | with the rest of the remote namespaces and groups not being synced (by this | |
202 | sync job). | |
203 | ||
204 | If a remote namespace is included in the sync job scope, but does not exist | |
205 | locally, it will be created (provided the sync job owner has sufficient | |
206 | privileges). | |
207 | ||
208 | If the ``remove-vanished`` option is set, namespaces that are included in the | |
209 | sync job scope but only exist locally are treated as vanished and removed | |
210 | (provided the sync job owner has sufficient privileges). | |
211 | ||
212 | .. note:: All other limitations on sync scope (such as remote user/API token | |
213 | privileges, group filters) also apply for sync jobs involving one or | |
214 | multiple namespaces. | |
215 | ||
4954d313 TL |
216 | Bandwidth Limit |
217 | ^^^^^^^^^^^^^^^ | |
218 | ||
6481fd24 DW |
219 | Syncing a datastore to an archive can produce a lot of traffic and impact other |
220 | users of the network. In order to avoid network or storage congestion, you can | |
221 | limit the bandwidth of the sync job by setting the ``rate-in`` option either in | |
222 | the web interface or using the ``proxmox-backup-manager`` command-line tool: | |
4954d313 TL |
223 | |
224 | .. code-block:: console | |
225 | ||
226 | # proxmox-backup-manager sync-job update ID --rate-in 20MiB |