]>
Commit | Line | Data |
---|---|---|
24406ebc TL |
1 | Backup Management |
2 | ================= | |
7e688b71 | 3 | |
24406ebc TL |
4 | .. The administration guide. |
5 | .. todo:: either add a bit more explanation or remove the previous sentence | |
c4f1b69f | 6 | |
fea8789c DM |
7 | Terminology |
8 | ----------- | |
9 | ||
85e139b7 DM |
10 | Backup Content |
11 | ~~~~~~~~~~~~~~ | |
12 | ||
13 | When doing deduplication, there are different strategies to get | |
14 | optimal results in terms of performance and/or deduplication rates. | |
8c6e5ce2 | 15 | Depending on the type of data, it can be split into *fixed* or *variable* |
85e139b7 DM |
16 | sized chunks. |
17 | ||
8c6e5ce2 | 18 | Fixed sized chunking requires minimal CPU power, and is used to |
85e139b7 DM |
19 | backup virtual machine images. |
20 | ||
21 | Variable sized chunking needs more CPU power, but is essential to get | |
22 | good deduplication rates for file archives. | |
23 | ||
8c6e5ce2 | 24 | The Proxmox Backup Server supports both strategies. |
85e139b7 DM |
25 | |
26 | ||
57905a61 DM |
27 | File Archives: ``<name>.pxar`` |
28 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
85e139b7 DM |
29 | |
30 | .. see https://moinakg.wordpress.com/2013/06/22/high-performance-content-defined-chunking/ | |
31 | ||
4f3db187 | 32 | A file archive stores a full directory tree. Content is stored using |
8c6e5ce2 | 33 | the :ref:`pxar-format`, split into variable-sized chunks. The format |
4f3db187 | 34 | is optimized to achieve good deduplication rates. |
85e139b7 DM |
35 | |
36 | ||
57905a61 DM |
37 | Image Archives: ``<name>.img`` |
38 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
85e139b7 DM |
39 | |
40 | This is used for virtual machine images and other large binary | |
8c6e5ce2 | 41 | data. Content is split into fixed-sized chunks. |
85e139b7 DM |
42 | |
43 | ||
44 | Binary Data (BLOBs) | |
45 | ^^^^^^^^^^^^^^^^^^^ | |
46 | ||
4f3db187 AL |
47 | This type is used to store smaller (< 16MB) binary data such as |
48 | configuration files. Larger files should be stored as image archive. | |
85e139b7 DM |
49 | |
50 | .. caution:: Please do not store all files as BLOBs. Instead, use the | |
51 | file archive to store whole directory trees. | |
52 | ||
53 | ||
57905a61 DM |
54 | Catalog File: ``catalog.pcat1`` |
55 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
56 | ||
4f3db187 | 57 | The catalog file is an index for file archives. It contains |
8c6e5ce2 | 58 | the list of files and is used to speed up search operations. |
57905a61 DM |
59 | |
60 | ||
61 | The Manifest: ``index.json`` | |
62 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
63 | ||
4f3db187 AL |
64 | The manifest contains the list of all backup files, their |
65 | sizes and checksums. It is used to verify the consistency of a | |
57905a61 DM |
66 | backup. |
67 | ||
68 | ||
fea8789c DM |
69 | Backup Type |
70 | ~~~~~~~~~~~ | |
71 | ||
72 | The backup server groups backups by *type*, where *type* is one of: | |
73 | ||
74 | ``vm`` | |
a129fdd9 | 75 | This type is used for :term:`virtual machine`\ s. Typically |
8c6e5ce2 | 76 | consists of the virtual machine's configuration file and an image archive |
fea8789c DM |
77 | for each disk. |
78 | ||
79 | ``ct`` | |
8c6e5ce2 OB |
80 | This type is used for :term:`container`\ s. Consists of the container's |
81 | configuration and a single file archive for the filesystem content. | |
fea8789c DM |
82 | |
83 | ``host`` | |
4f3db187 AL |
84 | This type is used for backups created from within the backed up machine. |
85 | Typically this would be a physical host but could also be a virtual machine | |
86 | or container. Such backups may contain file and image archives, there are no restrictions in this regard. | |
fea8789c DM |
87 | |
88 | ||
89 | Backup ID | |
90 | ~~~~~~~~~ | |
91 | ||
8c6e5ce2 | 92 | A unique ID. Usually the virtual machine or container ID. ``host`` |
fea8789c DM |
93 | type backups normally use the hostname. |
94 | ||
95 | ||
96 | Backup Time | |
97 | ~~~~~~~~~~~ | |
98 | ||
99 | The time when the backup was made. | |
100 | ||
101 | ||
6e5a0c03 DM |
102 | Backup Group |
103 | ~~~~~~~~~~~~ | |
104 | ||
4f3db187 AL |
105 | The tuple ``<type>/<ID>`` is called a backup group. Such a group |
106 | may contain one or more backup snapshots. | |
6e5a0c03 DM |
107 | |
108 | ||
fea8789c DM |
109 | Backup Snapshot |
110 | ~~~~~~~~~~~~~~~ | |
111 | ||
4f3db187 | 112 | The triplet ``<type>/<ID>/<time>`` is called a backup snapshot. It |
fea8789c DM |
113 | uniquely identifies a specific backup within a datastore. |
114 | ||
115 | .. code-block:: console | |
116 | :caption: Backup Snapshot Examples | |
117 | ||
118 | vm/104/2019-10-09T08:01:06Z | |
119 | host/elsa/2019-11-08T09:48:14Z | |
120 | ||
4f3db187 | 121 | As you can see, the time format is RFC3399_ with Coordinated |
fea8789c DM |
122 | Universal Time (UTC_, identified by the trailing *Z*). |
123 | ||
8c6e5ce2 OB |
124 | Backup Server Management |
125 | ------------------------ | |
126 | ||
127 | The command line tool to configure and manage the backup server is called | |
128 | :command:`proxmox-backup-manager`. | |
129 | ||
130 | ||
fea8789c DM |
131 | |
132 | :term:`DataStore` | |
133 | ~~~~~~~~~~~~~~~~~ | |
134 | ||
4f3db187 | 135 | A datastore is a place where backups are stored. The current implementation |
fea8789c | 136 | uses a directory inside a standard unix file system (``ext4``, ``xfs`` |
4f3db187 | 137 | or ``zfs``) to store the backup data. |
fea8789c | 138 | |
4f3db187 | 139 | Datastores are identified by a simple *ID*. You can configure it |
fea8789c DM |
140 | when setting up the backup server. |
141 | ||
538c2b6d TL |
142 | .. note:: The `File Layout`_ requires the file system to support at least *65538* |
143 | subdirectories per directory. That number comes from the 2\ :sup:`16` | |
144 | pre-created chunk namespace directories, and the ``.`` and ``..`` default | |
145 | directory entries. This requirement excludes certain filesystems and | |
146 | filesystem configuration from being supported for a datastore. For example, | |
147 | ``ext3`` as a whole or ``ext4`` with the ``dir_nlink`` feature manually disabled. | |
fea8789c | 148 | |
58ea88c8 DM |
149 | |
150 | Datastore Configuration | |
151 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
152 | ||
8c6e5ce2 OB |
153 | You can configure multiple datastores. Minimum one datastore needs to be |
154 | configured. The datastore is identified by a simple `name` and points to a | |
22231524 SI |
155 | directory on the filesystem. Each datastore also has associated retention |
156 | settings of how many backup snapshots for each interval of ``hourly``, | |
aef49768 | 157 | ``daily``, ``weekly``, ``monthly``, ``yearly`` as well as a time-independent |
22231524 SI |
158 | number of backups to keep in that store. :ref:`Pruning <pruning>` and |
159 | :ref:`garbage collection <garbage-collection>` can also be configured to run | |
160 | periodically based on a configured :term:`schedule` per datastore. | |
58ea88c8 DM |
161 | |
162 | The following command creates a new datastore called ``store1`` on :file:`/backup/disk1/store1` | |
163 | ||
164 | .. code-block:: console | |
165 | ||
166 | # proxmox-backup-manager datastore create store1 /backup/disk1/store1 | |
167 | ||
4f3db187 | 168 | To list existing datastores run: |
58ea88c8 DM |
169 | |
170 | .. code-block:: console | |
171 | ||
172 | # proxmox-backup-manager datastore list | |
17ec699d DM |
173 | ┌────────┬──────────────────────┬─────────────────────────────┐ |
174 | │ name │ path │ comment │ | |
175 | ╞════════╪══════════════════════╪═════════════════════════════╡ | |
176 | │ store1 │ /backup/disk1/store1 │ This is my default storage. │ | |
177 | └────────┴──────────────────────┴─────────────────────────────┘ | |
58ea88c8 | 178 | |
22231524 SI |
179 | You can change settings of a datastore, for example to set a prune and garbage |
180 | collection schedule or retention settings using ``update`` subcommand and view | |
181 | a datastore with the ``show`` subcommand: | |
182 | ||
183 | .. code-block:: console | |
184 | ||
185 | # proxmox-backup-manager datastore update store1 --keep-last 7 --prune-schedule daily --gc-schedule 'Tue 04:27' | |
186 | # proxmox-backup-manager datastore show store1 | |
187 | ┌────────────────┬─────────────────────────────┐ | |
188 | │ Name │ Value │ | |
189 | ╞════════════════╪═════════════════════════════╡ | |
190 | │ name │ store1 │ | |
191 | ├────────────────┼─────────────────────────────┤ | |
192 | │ path │ /backup/disk1/store1 │ | |
193 | ├────────────────┼─────────────────────────────┤ | |
194 | │ comment │ This is my default storage. │ | |
195 | ├────────────────┼─────────────────────────────┤ | |
196 | │ gc-schedule │ Tue 04:27 │ | |
197 | ├────────────────┼─────────────────────────────┤ | |
198 | │ keep-last │ 7 │ | |
199 | ├────────────────┼─────────────────────────────┤ | |
200 | │ prune-schedule │ daily │ | |
201 | └────────────────┴─────────────────────────────┘ | |
202 | ||
4f3db187 | 203 | Finally, it is possible to remove the datastore configuration: |
58ea88c8 DM |
204 | |
205 | .. code-block:: console | |
206 | ||
207 | # proxmox-backup-manager datastore remove store1 | |
208 | ||
4f3db187 | 209 | .. note:: The above command removes only the datastore configuration. It does |
58ea88c8 DM |
210 | not delete any data from the underlying directory. |
211 | ||
212 | ||
fea8789c DM |
213 | File Layout |
214 | ^^^^^^^^^^^ | |
215 | ||
8c6e5ce2 OB |
216 | After creating a datastore, the following default layout will appear: |
217 | ||
218 | .. code-block:: console | |
24406ebc | 219 | |
8c6e5ce2 OB |
220 | # ls -arilh /backup/disk1/store1 |
221 | 276493 -rw-r--r-- 1 backup backup 0 Jul 8 12:35 .lock | |
222 | 276490 drwxr-x--- 1 backup backup 1064960 Jul 8 12:35 .chunks | |
223 | ||
224 | `.lock` is an empty file used for process locking. | |
225 | ||
226 | The `.chunks` directory contains folders, starting from `0000` and taking hexadecimal values until `ffff`. These | |
227 | directories will store the chunked data after a backup operation has been executed. | |
228 | ||
229 | .. code-block:: console | |
24406ebc | 230 | |
8c6e5ce2 OB |
231 | # ls -arilh /backup/disk1/store1/.chunks |
232 | 545824 drwxr-x--- 2 backup backup 4.0K Jul 8 12:35 ffff | |
233 | 545823 drwxr-x--- 2 backup backup 4.0K Jul 8 12:35 fffe | |
234 | 415621 drwxr-x--- 2 backup backup 4.0K Jul 8 12:35 fffd | |
235 | 415620 drwxr-x--- 2 backup backup 4.0K Jul 8 12:35 fffc | |
236 | 353187 drwxr-x--- 2 backup backup 4.0K Jul 8 12:35 fffb | |
237 | 344995 drwxr-x--- 2 backup backup 4.0K Jul 8 12:35 fffa | |
238 | 144079 drwxr-x--- 2 backup backup 4.0K Jul 8 12:35 fff9 | |
239 | 144078 drwxr-x--- 2 backup backup 4.0K Jul 8 12:35 fff8 | |
240 | 144077 drwxr-x--- 2 backup backup 4.0K Jul 8 12:35 fff7 | |
241 | ... | |
242 | 403180 drwxr-x--- 2 backup backup 4.0K Jul 8 12:35 000c | |
243 | 403179 drwxr-x--- 2 backup backup 4.0K Jul 8 12:35 000b | |
244 | 403177 drwxr-x--- 2 backup backup 4.0K Jul 8 12:35 000a | |
245 | 402530 drwxr-x--- 2 backup backup 4.0K Jul 8 12:35 0009 | |
246 | 402513 drwxr-x--- 2 backup backup 4.0K Jul 8 12:35 0008 | |
247 | 402509 drwxr-x--- 2 backup backup 4.0K Jul 8 12:35 0007 | |
248 | 276509 drwxr-x--- 2 backup backup 4.0K Jul 8 12:35 0006 | |
249 | 276508 drwxr-x--- 2 backup backup 4.0K Jul 8 12:35 0005 | |
250 | 276507 drwxr-x--- 2 backup backup 4.0K Jul 8 12:35 0004 | |
251 | 276501 drwxr-x--- 2 backup backup 4.0K Jul 8 12:35 0003 | |
252 | 276499 drwxr-x--- 2 backup backup 4.0K Jul 8 12:35 0002 | |
253 | 276498 drwxr-x--- 2 backup backup 4.0K Jul 8 12:35 0001 | |
254 | 276494 drwxr-x--- 2 backup backup 4.0K Jul 8 12:35 0000 | |
255 | 276489 drwxr-xr-x 3 backup backup 4.0K Jul 8 12:35 .. | |
256 | 276490 drwxr-x--- 1 backup backup 1.1M Jul 8 12:35 . | |
257 | ||
fea8789c DM |
258 | |
259 | ||
17ec699d DM |
260 | User Management |
261 | ~~~~~~~~~~~~~~~ | |
262 | ||
8c6e5ce2 | 263 | Proxmox Backup Server supports several authentication realms, and you need to |
17ec699d DM |
264 | choose the realm when you add a new user. Possible realms are: |
265 | ||
266 | :pam: Linux PAM standard authentication. Use this if you want to | |
8c6e5ce2 | 267 | authenticate as Linux system user (Users need to exist on the |
17ec699d DM |
268 | system). |
269 | ||
270 | :pbs: Proxmox Backup Server realm. This type stores hashed passwords in | |
271 | ``/etc/proxmox-backup/shadow.json``. | |
272 | ||
273 | After installation, there is a single user ``root@pam``, which | |
274 | corresponds to the Unix superuser. You can use the | |
275 | ``proxmox-backup-manager`` command line tool to list or manipulate | |
276 | users: | |
277 | ||
278 | .. code-block:: console | |
279 | ||
280 | # proxmox-backup-manager user list | |
26d29e0e DM |
281 | ┌─────────────┬────────┬────────┬───────────┬──────────┬────────────────┬────────────────────┐ |
282 | │ userid │ enable │ expire │ firstname │ lastname │ email │ comment │ | |
283 | ╞═════════════╪════════╪════════╪═══════════╪══════════╪════════════════╪════════════════════╡ | |
284 | │ root@pam │ 1 │ │ │ │ │ Superuser │ | |
285 | └─────────────┴────────┴────────┴───────────┴──────────┴────────────────┴────────────────────┘ | |
17ec699d DM |
286 | |
287 | The superuser has full administration rights on everything, so you | |
288 | normally want to add other users with less privileges: | |
289 | ||
290 | .. code-block:: console | |
291 | ||
292 | # proxmox-backup-manager user create john@pbs --email john@example.com | |
293 | ||
8c6e5ce2 OB |
294 | The create command lets you specify many options like ``--email`` or |
295 | ``--password``. You can update or change any of them using the | |
17ec699d DM |
296 | update command later: |
297 | ||
298 | .. code-block:: console | |
299 | ||
300 | # proxmox-backup-manager user update john@pbs --firstname John --lastname Smith | |
301 | # proxmox-backup-manager user update john@pbs --comment "An example user." | |
302 | ||
17ec699d DM |
303 | .. todo:: Mention how to set password without passing plaintext password as cli argument. |
304 | ||
305 | ||
8c6e5ce2 | 306 | The resulting user list looks like this: |
17ec699d DM |
307 | |
308 | .. code-block:: console | |
309 | ||
310 | # proxmox-backup-manager user list | |
311 | ┌──────────┬────────┬────────┬───────────┬──────────┬──────────────────┬──────────────────┐ | |
312 | │ userid │ enable │ expire │ firstname │ lastname │ email │ comment │ | |
313 | ╞══════════╪════════╪════════╪═══════════╪══════════╪══════════════════╪══════════════════╡ | |
314 | │ john@pbs │ 1 │ │ John │ Smith │ john@example.com │ An example user. │ | |
315 | ├──────────┼────────┼────────┼───────────┼──────────┼──────────────────┼──────────────────┤ | |
316 | │ root@pam │ 1 │ │ │ │ │ Superuser │ | |
317 | └──────────┴────────┴────────┴───────────┴──────────┴──────────────────┴──────────────────┘ | |
318 | ||
8c6e5ce2 | 319 | Newly created users do not have any permissions. Please read the next |
17ec699d DM |
320 | section to learn how to set access permissions. |
321 | ||
8c6e5ce2 | 322 | If you want to disable a user account, you can do that by setting ``--enable`` to ``0`` |
8f3b3cc1 DM |
323 | |
324 | .. code-block:: console | |
325 | ||
326 | # proxmox-backup-manager user update john@pbs --enable 0 | |
327 | ||
8c6e5ce2 | 328 | Or completely remove the user with: |
8f3b3cc1 DM |
329 | |
330 | .. code-block:: console | |
331 | ||
332 | # proxmox-backup-manager user remove john@pbs | |
333 | ||
334 | ||
17ec699d DM |
335 | Access Control |
336 | ~~~~~~~~~~~~~~ | |
337 | ||
8c6e5ce2 OB |
338 | By default new users do not have any permission. Instead you need to |
339 | specify what is allowed and what is not. You can do this by assigning | |
8df51d48 DM |
340 | roles to users on specific objects like datastores or remotes. The |
341 | following roles exist: | |
342 | ||
8c6e5ce2 OB |
343 | **NoAccess** |
344 | Disable Access - nothing is allowed. | |
345 | ||
8df51d48 DM |
346 | **Admin** |
347 | The Administrator can do anything. | |
348 | ||
349 | **Audit** | |
350 | An Auditor can view things, but is not allowed to change settings. | |
351 | ||
8df51d48 DM |
352 | **DatastoreAdmin** |
353 | Can do anything on datastores. | |
354 | ||
355 | **DatastoreAudit** | |
356 | Can view datastore settings and list content. But | |
357 | is not allowed to read the actual data. | |
358 | ||
359 | **DataStoreReader** | |
360 | Can Inspect datastore content and can do restores. | |
361 | ||
362 | **DataStoreBackup** | |
363 | Can backup and restore owned backups. | |
364 | ||
365 | **DatastorePowerUser** | |
366 | Can backup, restore, and prune owned backups. | |
367 | ||
368 | **RemoteAdmin** | |
369 | Can do anything on remotes. | |
370 | ||
371 | **RemoteAudit** | |
372 | Can view remote settings. | |
373 | ||
374 | **RemoteSyncOperator** | |
375 | Is allowed to read data from a remote. | |
376 | ||
17ec699d | 377 | |
9634ca07 SI |
378 | :term:`Remote` |
379 | ~~~~~~~~~~~~~~ | |
380 | ||
aef49768 | 381 | A remote refers to a separate Proxmox Backup Server installation and a user on that |
9634ca07 SI |
382 | installation, from which you can `sync` datastores to a local datastore with a |
383 | `Sync Job`. | |
384 | ||
aef49768 DW |
385 | To add a remote, you need its hostname or ip, a userid and password on the |
386 | remote, and its certificate fingerprint. To get the fingerprint, use the | |
387 | ``proxmox-backup-manager cert info`` command on the remote. | |
9634ca07 SI |
388 | |
389 | .. code-block:: console | |
390 | ||
391 | # proxmox-backup-manager cert info |grep Fingerprint | |
392 | Fingerprint (sha256): 64:d3:ff:3a:50:38:53:5a:9b:f7:50:...:ab:fe | |
393 | ||
aef49768 | 394 | Using the information specified above, add the remote with: |
9634ca07 SI |
395 | |
396 | .. code-block:: console | |
397 | ||
398 | # 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 | |
399 | ||
400 | Use the ``list``, ``show``, ``update``, ``remove`` subcommands of | |
401 | ``proxmox-backup-manager remote`` to manage your remotes: | |
402 | ||
403 | .. code-block:: console | |
404 | ||
405 | # proxmox-backup-manager remote update pbs2 --host pbs2.example | |
406 | # proxmox-backup-manager remote list | |
407 | ┌──────┬──────────────┬──────────┬───────────────────────────────────────────┬─────────┐ | |
408 | │ name │ host │ userid │ fingerprint │ comment │ | |
409 | ╞══════╪══════════════╪══════════╪═══════════════════════════════════════════╪═════════╡ | |
410 | │ pbs2 │ pbs2.example │ sync@pam │64:d3:ff:3a:50:38:53:5a:9b:f7:50:...:ab:fe │ │ | |
411 | └──────┴──────────────┴──────────┴───────────────────────────────────────────┴─────────┘ | |
412 | # proxmox-backup-manager remote remove pbs2 | |
413 | ||
414 | ||
415 | Sync Jobs | |
416 | ~~~~~~~~~ | |
417 | ||
418 | Sync jobs are configured to pull the contents of a datastore on a `Remote` to a | |
419 | local datastore. You can either start the sync job manually on the GUI or | |
420 | provide it with a :term:`schedule` to run regularly. The | |
421 | ``proxmox-backup-manager sync-job`` command is used to manage sync jobs: | |
422 | ||
423 | .. code-block:: console | |
424 | ||
425 | # proxmox-backup-manager sync-job create pbs2-local --remote pbs2 --remote-store local --store local --schedule 'Wed 02:30' | |
426 | # proxmox-backup-manager sync-job update pbs2-local --comment 'offsite' | |
427 | # proxmox-backup-manager sync-job list | |
428 | ┌────────────┬───────┬────────┬──────────────┬───────────┬─────────┐ | |
429 | │ id │ store │ remote │ remote-store │ schedule │ comment │ | |
430 | ╞════════════╪═══════╪════════╪══════════════╪═══════════╪═════════╡ | |
431 | │ pbs2-local │ local │ pbs2 │ local │ Wed 02:30 │ offsite │ | |
432 | └────────────┴───────┴────────┴──────────────┴───────────┴─────────┘ | |
433 | # proxmox-backup-manager sync-job remove pbs2-local | |
434 | ||
435 | ||
cb01363c DM |
436 | Backup Client usage |
437 | ------------------- | |
58ea88c8 DM |
438 | |
439 | The command line client is called :command:`proxmox-backup-client`. | |
440 | ||
a129fdd9 | 441 | |
0c1c492d TL |
442 | Repository Locations |
443 | ~~~~~~~~~~~~~~~~~~~~ | |
58ea88c8 | 444 | |
4f3db187 | 445 | The client uses the following notation to specify a datastore repository |
58ea88c8 DM |
446 | on the backup server. |
447 | ||
448 | [[username@]server:]datastore | |
449 | ||
8c6e5ce2 OB |
450 | The default value for ``username`` ist ``root``. If no server is specified, |
451 | the default is the local host (``localhost``). | |
58ea88c8 | 452 | |
4f3db187 AL |
453 | You can pass the repository with the ``--repository`` command |
454 | line option, or by setting the ``PBS_REPOSITORY`` environment | |
58ea88c8 DM |
455 | variable. |
456 | ||
457 | ||
458 | Environment Variables | |
53ea6556 | 459 | ~~~~~~~~~~~~~~~~~~~~~ |
58ea88c8 DM |
460 | |
461 | ``PBS_REPOSITORY`` | |
462 | The default backup repository. | |
463 | ||
464 | ``PBS_PASSWORD`` | |
465 | When set, this value is used for the password required for the | |
466 | backup server. | |
467 | ||
468 | ``PBS_ENCRYPTION_PASSWORD`` | |
58ea88c8 DM |
469 | When set, this value is used to access the secret encryption key (if |
470 | protected by password). | |
471 | ||
3243f93c DM |
472 | ``PBS_FINGERPRINT`` When set, this value is used to verify the server |
473 | certificate (only used if the system CA certificates cannot | |
474 | validate the certificate). | |
475 | ||
53ea6556 DM |
476 | |
477 | Output Format | |
478 | ~~~~~~~~~~~~~ | |
479 | ||
4f3db187 AL |
480 | Most commands support the ``--output-format`` parameter. It accepts |
481 | the following values: | |
53ea6556 DM |
482 | |
483 | :``text``: Text format (default). Structured data is rendered as a table. | |
484 | ||
485 | :``json``: JSON (single line). | |
486 | ||
487 | :``json-pretty``: JSON (multiple lines, nicely formatted). | |
488 | ||
489 | ||
490 | Please use the following environment variables to modify output behavior: | |
491 | ||
492 | ``PROXMOX_OUTPUT_FORMAT`` | |
493 | Defines the default output format. | |
494 | ||
495 | ``PROXMOX_OUTPUT_NO_BORDER`` | |
496 | If set (to any value), do not render table borders. | |
497 | ||
498 | ``PROXMOX_OUTPUT_NO_HEADER`` | |
499 | If set (to any value), do not render table headers. | |
500 | ||
4f3db187 | 501 | .. note:: The ``text`` format is designed to be human readable, and |
53ea6556 | 502 | not meant to be parsed by automation tools. Please use the ``json`` |
4f3db187 | 503 | format if you need to process the output. |
53ea6556 DM |
504 | |
505 | ||
cee53b34 | 506 | .. _creating-backups: |
58ea88c8 DM |
507 | |
508 | Creating Backups | |
509 | ~~~~~~~~~~~~~~~~ | |
510 | ||
4f3db187 AL |
511 | This section explains how to create a backup from within the machine. This can |
512 | be a physical host, a virtual machine, or a container. Such backups may contain file | |
513 | and image archives. There are no restrictions in this case. | |
a129fdd9 | 514 | |
8c6e5ce2 | 515 | .. note:: If you want to backup virtual machines or containers on Proxmox VE, see :ref:`pve-integration`. |
a129fdd9 | 516 | |
4f3db187 AL |
517 | For the following example you need to have a backup server set up, working |
518 | credentials and need to know the repository name. | |
519 | In the following examples we use ``backup-server:store1``. | |
a129fdd9 DM |
520 | |
521 | .. code-block:: console | |
522 | ||
523 | # proxmox-backup-client backup root.pxar:/ --repository backup-server:store1 | |
524 | Starting backup: host/elsa/2019-12-03T09:35:01Z | |
525 | Client name: elsa | |
526 | skip mount point: "/boot/efi" | |
527 | skip mount point: "/dev" | |
528 | skip mount point: "/run" | |
529 | skip mount point: "/sys" | |
530 | Uploaded 12129 chunks in 87 seconds (564 MB/s). | |
531 | End Time: 2019-12-03T10:36:29+01:00 | |
532 | ||
533 | This will prompt you for a password and then uploads a file archive named | |
534 | ``root.pxar`` containing all the files in the ``/`` directory. | |
535 | ||
4f3db187 | 536 | .. Caution:: Please note that the proxmox-backup-client does not |
ed858b0a | 537 | automatically include mount points. Instead, you will see a short |
4f3db187 AL |
538 | ``skip mount point`` notice for each of them. The idea is to |
539 | create a separate file archive for each mounted disk. You can | |
a129fdd9 DM |
540 | explicitly include them using the ``--include-dev`` option |
541 | (i.e. ``--include-dev /boot/efi``). You can use this option | |
4f3db187 | 542 | multiple times for each mount point that should be included. |
a129fdd9 | 543 | |
4f3db187 | 544 | The ``--repository`` option can get quite long and is used by all |
a129fdd9 DM |
545 | commands. You can avoid having to enter this value by setting the |
546 | environment variable ``PBS_REPOSITORY``. | |
547 | ||
548 | .. code-block:: console | |
549 | ||
78ee20d7 | 550 | # export PBS_REPOSITORY=backup-server:store1 |
a129fdd9 | 551 | |
4f3db187 | 552 | After this you can execute all commands without specifying the ``--repository`` |
a129fdd9 DM |
553 | option. |
554 | ||
4f3db187 AL |
555 | One single backup is allowed to contain more than one archive. For example, if |
556 | you want to backup two disks mounted at ``/mmt/disk1`` and ``/mnt/disk2``: | |
a129fdd9 DM |
557 | |
558 | .. code-block:: console | |
559 | ||
560 | # proxmox-backup-client backup disk1.pxar:/mnt/disk1 disk2.pxar:/mnt/disk2 | |
561 | ||
4f3db187 | 562 | This creates a backup of both disks. |
a129fdd9 DM |
563 | |
564 | The backup command takes a list of backup specifications, which | |
4f3db187 AL |
565 | include the archive name on the server, the type of the archive, and the |
566 | archive source at the client. The format is: | |
a129fdd9 DM |
567 | |
568 | <archive-name>.<type>:<source-path> | |
569 | ||
570 | Common types are ``.pxar`` for file archives, and ``.img`` for block | |
4f3db187 | 571 | device images. To create a backup of a block device run the following command: |
a129fdd9 DM |
572 | |
573 | .. code-block:: console | |
574 | ||
575 | # proxmox-backup-client backup mydata.img:/dev/mylvm/mydata | |
576 | ||
50b8f9dd CE |
577 | Excluding files/folders from a backup |
578 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
579 | ||
580 | Sometimes it is desired to exclude certain files or folders from a backup archive. | |
4f3db187 AL |
581 | To tell the Proxmox backup client when and how to ignore files and directories, |
582 | place a text file called ``.pxarexclude`` in the filesystem hierarchy. | |
583 | Whenever the backup client encounters such a file in a directory, it interprets | |
584 | each line as glob match patterns for files and directories that are to be excluded | |
585 | from the backup. | |
586 | ||
587 | The file must contain a single glob pattern per line. Empty lines are ignored. | |
588 | The same is true for lines starting with ``#``, which indicates a comment. | |
589 | A ``!`` at the beginning of a line reverses the glob match pattern from an exclusion | |
590 | to an explicit inclusion. This makes it possible to exclude all entries in a | |
591 | directory except for a few single files/subdirectories. | |
592 | Lines ending in ``/`` match only on directories. | |
593 | The directory containing the ``.pxarexclude`` file is considered to be the root of | |
594 | the given patterns. It is only possible to match files in this directory and its subdirectories. | |
595 | ||
596 | ``\`` is used to escape special glob characters. | |
597 | ``?`` matches any single character. | |
598 | ``*`` matches any character, including an empty string. | |
599 | ``**`` is used to match subdirectories. It can be used to, for example, exclude | |
600 | all files ending in ``.tmp`` within the directory or subdirectories with the | |
50b8f9dd CE |
601 | following pattern ``**/*.tmp``. |
602 | ``[...]`` matches a single character from any of the provided characters within | |
0c1c492d | 603 | the brackets. ``[!...]`` does the complementary and matches any single character |
4f3db187 AL |
604 | not contained within the brackets. It is also possible to specify ranges with two |
605 | characters separated by ``-``. For example, ``[a-z]`` matches any lowercase | |
606 | alphabetic character and ``[0-9]`` matches any one single digit. | |
50b8f9dd | 607 | |
aef49768 DW |
608 | The order of the glob match patterns defines whether a file is included or |
609 | excluded, that is to say later entries override previous ones. | |
50b8f9dd | 610 | This is also true for match patterns encountered deeper down the directory tree, |
4f3db187 AL |
611 | which can override a previous exclusion. |
612 | Be aware that excluded directories will **not** be read by the backup client. | |
aef49768 | 613 | Thus, a ``.pxarexclude`` file in an excluded subdirectory will have no effect. |
4f3db187 | 614 | ``.pxarexclude`` files are treated as regular files and will be included in the |
50b8f9dd CE |
615 | backup archive. |
616 | ||
4f3db187 | 617 | For example, consider the following directory structure: |
50b8f9dd CE |
618 | |
619 | .. code-block:: console | |
620 | ||
621 | # ls -aR folder | |
622 | folder/: | |
623 | . .. .pxarexclude subfolder0 subfolder1 | |
624 | ||
625 | folder/subfolder0: | |
626 | . .. file0 file1 file2 file3 .pxarexclude | |
627 | ||
628 | folder/subfolder1: | |
629 | . .. file0 file1 file2 file3 | |
630 | ||
4f3db187 | 631 | The different ``.pxarexclude`` files contain the following: |
50b8f9dd CE |
632 | |
633 | .. code-block:: console | |
634 | ||
635 | # cat folder/.pxarexclude | |
636 | /subfolder0/file1 | |
637 | /subfolder1/* | |
638 | !/subfolder1/file2 | |
639 | ||
640 | .. code-block:: console | |
641 | ||
642 | # cat folder/subfolder0/.pxarexclude | |
643 | file3 | |
644 | ||
645 | This would exclude ``file1`` and ``file3`` in ``subfolder0`` and all of | |
646 | ``subfolder1`` except ``file2``. | |
647 | ||
4f3db187 | 648 | Restoring this backup will result in: |
50b8f9dd CE |
649 | |
650 | .. code-block:: console | |
651 | ||
652 | ls -aR restored | |
653 | restored/: | |
654 | . .. .pxarexclude subfolder0 subfolder1 | |
655 | ||
656 | restored/subfolder0: | |
657 | . .. file0 file2 .pxarexclude | |
658 | ||
659 | restored/subfolder1: | |
660 | . .. file2 | |
a129fdd9 | 661 | |
58ea88c8 DM |
662 | Encryption |
663 | ^^^^^^^^^^ | |
664 | ||
aef49768 DW |
665 | Proxmox Backup supports client-side encryption with AES-256 in GCM_ |
666 | mode. To set this up, you first need to create an encryption key: | |
5a499f32 DM |
667 | |
668 | .. code-block:: console | |
669 | ||
670 | # proxmox-backup-client key create my-backup.key | |
671 | Encryption Key Password: ************** | |
672 | ||
673 | The key is password protected by default. If you do not need this | |
674 | extra protection, you can also create it without a password: | |
675 | ||
676 | .. code-block:: console | |
677 | ||
4f3db187 | 678 | # proxmox-backup-client key create /path/to/my-backup.key --kdf none |
5a499f32 DM |
679 | |
680 | ||
681 | .. code-block:: console | |
682 | ||
683 | # proxmox-backup-client backup etc.pxar:/etc --keyfile /path/to/my-backup.key | |
684 | Password: ********* | |
685 | Encryption Key Password: ************** | |
686 | ... | |
687 | ||
688 | ||
4f3db187 | 689 | You can avoid entering the passwords by setting the environment |
5a499f32 DM |
690 | variables ``PBS_PASSWORD`` and ``PBS_ENCRYPTION_PASSWORD``. |
691 | ||
692 | .. todo:: Explain master-key | |
693 | ||
58ea88c8 DM |
694 | |
695 | Restoring Data | |
696 | ~~~~~~~~~~~~~~ | |
697 | ||
aef49768 DW |
698 | The regular creation of backups is a necessary step to avoiding data |
699 | loss. More importantly, however, is the restoration. It is good practice to perform | |
4f3db187 | 700 | periodic recovery tests to ensure that you can access the data in |
64b85116 DM |
701 | case of problems. |
702 | ||
4f3db187 | 703 | First, you need to find the snapshot which you want to restore. The snapshot |
aef49768 | 704 | command provides a list of all the snapshots on the server: |
64b85116 DM |
705 | |
706 | .. code-block:: console | |
707 | ||
708 | # proxmox-backup-client snapshots | |
96feecd6 DM |
709 | ┌────────────────────────────────┬─────────────┬────────────────────────────────────┐ |
710 | │ snapshot │ size │ files │ | |
711 | ╞════════════════════════════════╪═════════════╪════════════════════════════════════╡ | |
712 | │ host/elsa/2019-12-03T09:30:15Z │ 51788646825 │ root.pxar catalog.pcat1 index.json │ | |
713 | ├────────────────────────────────┼─────────────┼────────────────────────────────────┤ | |
714 | │ host/elsa/2019-12-03T09:35:01Z │ 51790622048 │ root.pxar catalog.pcat1 index.json │ | |
715 | ├────────────────────────────────┼─────────────┼────────────────────────────────────┤ | |
64b85116 DM |
716 | ... |
717 | ||
4f3db187 | 718 | You can inspect the catalog to find specific files. |
64b85116 DM |
719 | |
720 | .. code-block:: console | |
721 | ||
3c50a9d8 | 722 | # proxmox-backup-client catalog dump host/elsa/2019-12-03T09:35:01Z |
64b85116 DM |
723 | ... |
724 | d "./root.pxar.didx/etc/cifs-utils" | |
725 | l "./root.pxar.didx/etc/cifs-utils/idmap-plugin" | |
726 | d "./root.pxar.didx/etc/console-setup" | |
727 | ... | |
728 | ||
729 | The restore command lets you restore a single archive from the | |
730 | backup. | |
731 | ||
732 | .. code-block:: console | |
733 | ||
734 | # proxmox-backup-client restore host/elsa/2019-12-03T09:35:01Z root.pxar /target/path/ | |
735 | ||
aef49768 DW |
736 | To get the contents of any archive, you can restore the ``ìndex.json`` file in the |
737 | repository to the target path '-'. This will dump the contents to the standard output. | |
64b85116 DM |
738 | |
739 | .. code-block:: console | |
740 | ||
741 | # proxmox-backup-client restore host/elsa/2019-12-03T09:35:01Z index.json - | |
742 | ||
743 | ||
744 | Interactive Restores | |
745 | ^^^^^^^^^^^^^^^^^^^^ | |
746 | ||
747 | If you only want to restore a few individual files, it is often easier | |
748 | to use the interactive recovery shell. | |
749 | ||
750 | .. code-block:: console | |
751 | ||
3c50a9d8 | 752 | # proxmox-backup-client catalog shell host/elsa/2019-12-03T09:35:01Z root.pxar |
64b85116 DM |
753 | Starting interactive shell |
754 | pxar:/ > ls | |
755 | bin boot dev etc home lib lib32 | |
756 | ... | |
757 | ||
3f0983b7 | 758 | The interactive recovery shell is a minimalistic command line interface that |
4f3db187 AL |
759 | utilizes the metadata stored in the catalog to quickly list, navigate and |
760 | search files in a file archive. | |
761 | To restore files, you can select them individually or match them with a glob | |
762 | pattern. | |
763 | ||
764 | Using the catalog for navigation reduces the overhead considerably because only | |
765 | the catalog needs to be downloaded and, optionally, decrypted. | |
3f0983b7 CE |
766 | The actual chunks are only accessed if the metadata in the catalog is not enough |
767 | or for the actual restore. | |
768 | ||
769 | Similar to common UNIX shells ``cd`` and ``ls`` are the commands used to change | |
4f3db187 | 770 | working directory and list directory contents in the archive. |
3f0983b7 CE |
771 | ``pwd`` shows the full path of the current working directory with respect to the |
772 | archive root. | |
773 | ||
aef49768 | 774 | Being able to quickly search the contents of the archive is a commmonly needed feature. |
3f0983b7 CE |
775 | That's where the catalog is most valuable. |
776 | For example: | |
777 | ||
778 | .. code-block:: console | |
779 | ||
a83674ad | 780 | pxar:/ > find etc/**/*.txt --select |
3f0983b7 CE |
781 | "/etc/X11/rgb.txt" |
782 | pxar:/ > list-selected | |
783 | etc/**/*.txt | |
784 | pxar:/ > restore-selected /target/path | |
785 | ... | |
786 | ||
787 | This will find and print all files ending in ``.txt`` located in ``etc/`` or a | |
788 | subdirectory and add the corresponding pattern to the list for subsequent restores. | |
789 | ``list-selected`` shows these patterns and ``restore-selected`` finally restores | |
790 | all files in the archive matching the patterns to ``/target/path`` on the local | |
791 | host. This will scan the whole archive. | |
792 | ||
793 | With ``restore /target/path`` you can restore the sub-archive given by the current | |
794 | working directory to the local target path ``/target/path`` on your host. | |
795 | By additionally passing a glob pattern with ``--pattern <glob>``, the restore is | |
796 | further limited to files matching the pattern. | |
797 | For example: | |
798 | ||
799 | .. code-block:: console | |
800 | ||
801 | pxar:/ > cd /etc/ | |
802 | pxar:/etc/ > restore /target/ --pattern **/*.conf | |
803 | ... | |
804 | ||
805 | The above will scan trough all the directories below ``/etc`` and restore all | |
806 | files ending in ``.conf``. | |
807 | ||
808 | .. todo:: Explain interactive restore in more detail | |
64b85116 | 809 | |
c7971d7f CE |
810 | Mounting of Archives via FUSE |
811 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
812 | ||
813 | The :term:`FUSE` implementation for the pxar archive allows you to mount a | |
814 | file archive as a read-only filesystem to a mountpoint on your host. | |
815 | ||
816 | .. code-block:: console | |
817 | ||
818 | # proxmox-backup-client mount host/backup-client/2020-01-29T11:29:22Z root.pxar /mnt | |
819 | # ls /mnt | |
820 | bin dev home lib32 libx32 media opt root sbin sys usr | |
821 | boot etc lib lib64 lost+found mnt proc run srv tmp var | |
822 | ||
aef49768 | 823 | This allows you to access the full contents of the archive in a seamless manner. |
c7971d7f CE |
824 | |
825 | .. note:: As the FUSE connection needs to fetch and decrypt chunks from the | |
aef49768 | 826 | backup server's datastore, this can cause some additional network and CPU |
c7971d7f CE |
827 | load on your host, depending on the operations you perform on the mounted |
828 | filesystem. | |
829 | ||
4f3db187 | 830 | To unmount the filesystem use the ``umount`` command on the mountpoint: |
c7971d7f CE |
831 | |
832 | .. code-block:: console | |
833 | ||
834 | # umount /mnt | |
58ea88c8 | 835 | |
ac456d85 DM |
836 | Login and Logout |
837 | ~~~~~~~~~~~~~~~~ | |
838 | ||
839 | The client tool prompts you to enter the logon password as soon as you | |
840 | want to access the backup server. The server checks your credentials | |
841 | and responds with a ticket that is valid for two hours. The client | |
4f3db187 | 842 | tool automatically stores that ticket and uses it for further requests |
ac456d85 DM |
843 | to this server. |
844 | ||
845 | You can also manually trigger this login/logout using the login and | |
846 | logout commands: | |
847 | ||
848 | .. code-block:: console | |
849 | ||
850 | # proxmox-backup-client login | |
851 | Password: ********** | |
852 | ||
4f3db187 | 853 | To remove the ticket, issue a logout: |
ac456d85 DM |
854 | |
855 | .. code-block:: console | |
856 | ||
857 | # proxmox-backup-client logout | |
858 | ||
859 | ||
22231524 SI |
860 | .. _pruning: |
861 | ||
6e5a0c03 DM |
862 | Pruning and Removing Backups |
863 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
864 | ||
865 | You can manually delete a backup snapshot using the ``forget`` | |
866 | command: | |
867 | ||
868 | .. code-block:: console | |
869 | ||
870 | # proxmox-backup-client forget <snapshot> | |
871 | ||
872 | ||
4f3db187 AL |
873 | .. caution:: This command removes all archives in this backup |
874 | snapshot. They will be inaccessible and unrecoverable. | |
6e5a0c03 DM |
875 | |
876 | ||
4f3db187 | 877 | The manual removal is sometimes required, but normally the prune |
52b2be97 | 878 | command is used to systematically delete older backups. Prune lets |
4f3db187 AL |
879 | you specify which backup snapshots you want to keep. The |
880 | following retention options are available: | |
52b2be97 DM |
881 | |
882 | ``--keep-last <N>`` | |
883 | Keep the last ``<N>`` backup snapshots. | |
884 | ||
102d8d41 | 885 | ``--keep-hourly <N>`` |
4f3db187 AL |
886 | Keep backups for the last ``<N>`` hours. If there is more than one |
887 | backup for a single hour, only the latest is kept. | |
102d8d41 | 888 | |
52b2be97 | 889 | ``--keep-daily <N>`` |
4f3db187 AL |
890 | Keep backups for the last ``<N>`` days. If there is more than one |
891 | backup for a single day, only the latest is kept. | |
52b2be97 DM |
892 | |
893 | ``--keep-weekly <N>`` | |
4f3db187 AL |
894 | Keep backups for the last ``<N>`` weeks. If there is more than one |
895 | backup for a single week, only the latest is kept. | |
52b2be97 | 896 | |
4f3db187 AL |
897 | .. note:: Weeks start on Monday and end on Sunday. The software |
898 | uses the `ISO week date`_ system and handles weeks at | |
899 | the end of the year correctly. | |
1af66370 | 900 | |
52b2be97 | 901 | ``--keep-monthly <N>`` |
4f3db187 AL |
902 | Keep backups for the last ``<N>`` months. If there is more than one |
903 | backup for a single month, only the latest is kept. | |
52b2be97 DM |
904 | |
905 | ``--keep-yearly <N>`` | |
4f3db187 AL |
906 | Keep backups for the last ``<N>`` years. If there is more than one |
907 | backup for a single year, only the latest is kept. | |
908 | ||
909 | The retention options are processed in the order given above. Each option | |
910 | only covers backups within its time period. The next option does not take care | |
911 | of already covered backups. It will only consider older backups. | |
52b2be97 | 912 | |
4f3db187 AL |
913 | Unfinished and incomplete backups will be removed by the prune command unless |
914 | they are newer than the last successful backup. In this case, the last failed | |
915 | backup is retained. | |
02d22dec | 916 | |
6e5a0c03 DM |
917 | .. code-block:: console |
918 | ||
919 | # proxmox-backup-client prune <group> --keep-daily 7 --keep-weekly 4 --keep-monthly 3 | |
920 | ||
921 | ||
4f3db187 | 922 | You can use the ``--dry-run`` option to test your settings. This only |
aef49768 | 923 | shows the list of existing snapshots and what actions prune would take. |
84322d8c DM |
924 | |
925 | .. code-block:: console | |
926 | ||
927 | # proxmox-backup-client prune host/elsa --dry-run --keep-daily 1 --keep-weekly 3 | |
a66d5898 DM |
928 | ┌────────────────────────────────┬──────┐ |
929 | │ snapshot │ keep │ | |
930 | ╞════════════════════════════════╪══════╡ | |
931 | │ host/elsa/2019-12-04T13:20:37Z │ 1 │ | |
932 | ├────────────────────────────────┼──────┤ | |
933 | │ host/elsa/2019-12-03T09:35:01Z │ 0 │ | |
934 | ├────────────────────────────────┼──────┤ | |
935 | │ host/elsa/2019-11-22T11:54:47Z │ 1 │ | |
936 | ├────────────────────────────────┼──────┤ | |
937 | │ host/elsa/2019-11-21T12:36:25Z │ 0 │ | |
938 | ├────────────────────────────────┼──────┤ | |
939 | │ host/elsa/2019-11-10T10:42:20Z │ 1 │ | |
940 | └────────────────────────────────┴──────┘ | |
84322d8c | 941 | |
52b2be97 | 942 | .. note:: Neither the ``prune`` command nor the ``forget`` command free space |
4f3db187 AL |
943 | in the chunk-store. The chunk-store still contains the data blocks. To free |
944 | space you need to perform :ref:`garbage-collection`. | |
6e5a0c03 DM |
945 | |
946 | ||
947 | .. _garbage-collection: | |
948 | ||
949 | Garbage Collection | |
950 | ~~~~~~~~~~~~~~~~~~ | |
951 | ||
e1c356ec DM |
952 | The ``prune`` command removes only the backup index files, not the data |
953 | from the data store. This task is left to the garbage collection | |
4f3db187 | 954 | command. It is recommended to carry out garbage collection on a regular basis. |
e1c356ec DM |
955 | |
956 | The garbage collection works in two phases. In the first phase, all | |
957 | data blocks that are still in use are marked. In the second phase, | |
958 | unused data blocks are removed. | |
959 | ||
960 | .. note:: This command needs to read all existing backup index files | |
f0188322 CE |
961 | and touches the complete chunk-store. This can take a long time |
962 | depending on the number of chunks and the speed of the underlying | |
e1c356ec DM |
963 | disks. |
964 | ||
8314ca9c AL |
965 | .. note:: The garbage collection will only remove chunks that haven't been used |
966 | for at least one day (exactly 24h 5m). This grace period is necessary because | |
967 | chunks in use are marked by touching the chunk which updates the ``atime`` | |
968 | (access time) property. Filesystems are mounted with the ``relatime`` option | |
969 | by default. This results in a better performance by only updating the | |
970 | ``atime`` property if the last access has been at least 24 hours ago. The | |
255ed621 TL |
971 | downside is, that touching a chunk within these 24 hours will not always |
972 | update its ``atime`` property. | |
8314ca9c | 973 | |
255ed621 TL |
974 | Chunks in the grace period will be logged at the end of the garbage |
975 | collection task as *Pending removals*. | |
e1c356ec DM |
976 | |
977 | .. code-block:: console | |
978 | ||
979 | # proxmox-backup-client garbage-collect | |
980 | starting garbage collection on store store2 | |
981 | Start GC phase1 (mark used chunks) | |
982 | Start GC phase2 (sweep unused chunks) | |
983 | percentage done: 1, chunk count: 219 | |
984 | percentage done: 2, chunk count: 453 | |
985 | ... | |
986 | percentage done: 99, chunk count: 21188 | |
987 | Removed bytes: 411368505 | |
988 | Removed chunks: 203 | |
989 | Original data bytes: 327160886391 | |
990 | Disk bytes: 52767414743 (16 %) | |
991 | Disk chunks: 21221 | |
992 | Average chunk size: 2486565 | |
993 | TASK OK | |
994 | ||
995 | ||
996 | .. todo:: howto run garbage-collection at regular intervalls (cron) | |
6e5a0c03 DM |
997 | |
998 | ||
a129fdd9 DM |
999 | .. _pve-integration: |
1000 | ||
58ea88c8 DM |
1001 | `Proxmox VE`_ integration |
1002 | ------------------------- | |
cb01363c | 1003 | |
f9dcfa41 DM |
1004 | You need to define a new storage with type 'pbs' on your `Proxmox VE`_ |
1005 | node. The following example uses ``store2`` as storage name, and | |
1006 | assumes the server address is ``localhost``, and you want to connect | |
1007 | as ``user1@pbs``. | |
1008 | ||
1009 | .. code-block:: console | |
1010 | ||
1011 | # pvesm add pbs store2 --server localhost --datastore store2 | |
1012 | # pvesm set store2 --username user1@pbs --password <secret> | |
1013 | ||
1014 | If your backup server uses a self signed certificate, you need to add | |
1015 | the certificate fingerprint to the configuration. You can get the | |
1016 | fingerprint by running the following command on the backup server: | |
1017 | ||
1018 | .. code-block:: console | |
1019 | ||
1020 | # proxmox-backup-manager cert info |grep Fingerprint | |
1021 | Fingerprint (sha256): 64:d3:ff:3a:50:38:53:5a:9b:f7:50:...:ab:fe | |
1022 | ||
1023 | Please add that fingerprint to your configuration to establish a trust | |
1024 | relationship: | |
1025 | ||
1026 | .. code-block:: console | |
1027 | ||
1028 | # pvesm set store2 --fingerprint 64:d3:ff:3a:50:38:53:5a:9b:f7:50:...:ab:fe | |
1029 | ||
1030 | After that you should be able to see storage status with: | |
1031 | ||
1032 | .. code-block:: console | |
1033 | ||
1034 | # pvesm status --storage store2 | |
1035 | Name Type Status Total Used Available % | |
1036 | store2 pbs active 3905109820 1336687816 2568422004 34.23% | |
1037 | ||
1038 | ||
cb01363c DM |
1039 | |
1040 | .. include:: command-line-tools.rst | |
1041 | ||
1042 | .. include:: services.rst |