+The regular creation of backups is a necessary step to avoid data
+loss. More important, however, is the restoration. It is good practice to perform
+periodic recovery tests to ensure that you can access the data in
+case of problems.
+
+First, you need to find the snapshot which you want to restore. The snapshot
+command gives a list of all snapshots on the server:
+
+.. code-block:: console
+
+ # proxmox-backup-client snapshots
+ ┌────────────────────────────────┬─────────────┬────────────────────────────────────┐
+ │ snapshot │ size │ files │
+ ╞════════════════════════════════╪═════════════╪════════════════════════════════════╡
+ │ host/elsa/2019-12-03T09:30:15Z │ 51788646825 │ root.pxar catalog.pcat1 index.json │
+ ├────────────────────────────────┼─────────────┼────────────────────────────────────┤
+ │ host/elsa/2019-12-03T09:35:01Z │ 51790622048 │ root.pxar catalog.pcat1 index.json │
+ ├────────────────────────────────┼─────────────┼────────────────────────────────────┤
+ ...
+
+You can inspect the catalog to find specific files.
+
+.. code-block:: console
+
+ # proxmox-backup-client catalog dump host/elsa/2019-12-03T09:35:01Z
+ ...
+ d "./root.pxar.didx/etc/cifs-utils"
+ l "./root.pxar.didx/etc/cifs-utils/idmap-plugin"
+ d "./root.pxar.didx/etc/console-setup"
+ ...
+
+The restore command lets you restore a single archive from the
+backup.
+
+.. code-block:: console
+
+ # proxmox-backup-client restore host/elsa/2019-12-03T09:35:01Z root.pxar /target/path/
+
+To get the contents of any archive you can restore the ``ìndex.json`` file in the
+repository and restore it to '-'. This will dump the content to the standard output.
+
+.. code-block:: console
+
+ # proxmox-backup-client restore host/elsa/2019-12-03T09:35:01Z index.json -
+
+
+Interactive Restores
+^^^^^^^^^^^^^^^^^^^^
+
+If you only want to restore a few individual files, it is often easier
+to use the interactive recovery shell.
+
+.. code-block:: console
+
+ # proxmox-backup-client catalog shell host/elsa/2019-12-03T09:35:01Z root.pxar
+ Starting interactive shell
+ pxar:/ > ls
+ bin boot dev etc home lib lib32
+ ...
+
+The interactive recovery shell is a minimalistic command line interface that
+utilizes the metadata stored in the catalog to quickly list, navigate and
+search files in a file archive.
+To restore files, you can select them individually or match them with a glob
+pattern.
+
+Using the catalog for navigation reduces the overhead considerably because only
+the catalog needs to be downloaded and, optionally, decrypted.
+The actual chunks are only accessed if the metadata in the catalog is not enough
+or for the actual restore.
+
+Similar to common UNIX shells ``cd`` and ``ls`` are the commands used to change
+working directory and list directory contents in the archive.
+``pwd`` shows the full path of the current working directory with respect to the
+archive root.
+
+Being able to quickly search the contents of the archive is a often needed feature.
+That's where the catalog is most valuable.
+For example:
+
+.. code-block:: console
+
+ pxar:/ > find etc/ **/*.txt --select
+ "/etc/X11/rgb.txt"
+ pxar:/ > list-selected
+ etc/**/*.txt
+ pxar:/ > restore-selected /target/path
+ ...
+
+This will find and print all files ending in ``.txt`` located in ``etc/`` or a
+subdirectory and add the corresponding pattern to the list for subsequent restores.
+``list-selected`` shows these patterns and ``restore-selected`` finally restores
+all files in the archive matching the patterns to ``/target/path`` on the local
+host. This will scan the whole archive.
+
+With ``restore /target/path`` you can restore the sub-archive given by the current
+working directory to the local target path ``/target/path`` on your host.
+By additionally passing a glob pattern with ``--pattern <glob>``, the restore is
+further limited to files matching the pattern.
+For example:
+
+.. code-block:: console
+
+ pxar:/ > cd /etc/
+ pxar:/etc/ > restore /target/ --pattern **/*.conf
+ ...
+
+The above will scan trough all the directories below ``/etc`` and restore all
+files ending in ``.conf``.
+
+.. todo:: Explain interactive restore in more detail
+
+Mounting of Archives via FUSE
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The :term:`FUSE` implementation for the pxar archive allows you to mount a
+file archive as a read-only filesystem to a mountpoint on your host.
+
+.. code-block:: console
+
+ # proxmox-backup-client mount host/backup-client/2020-01-29T11:29:22Z root.pxar /mnt
+ # ls /mnt
+ bin dev home lib32 libx32 media opt root sbin sys usr
+ boot etc lib lib64 lost+found mnt proc run srv tmp var
+
+This allows you to access the full content of the archive in a seamless manner.
+
+.. note:: As the FUSE connection needs to fetch and decrypt chunks from the
+ backup servers datastore, this can cause some additional network and CPU
+ load on your host, depending on the operations you perform on the mounted
+ filesystem.
+
+To unmount the filesystem use the ``umount`` command on the mountpoint:
+
+.. code-block:: console
+
+ # umount /mnt
+
+Login and Logout
+~~~~~~~~~~~~~~~~
+
+The client tool prompts you to enter the logon password as soon as you
+want to access the backup server. The server checks your credentials
+and responds with a ticket that is valid for two hours. The client
+tool automatically stores that ticket and uses it for further requests
+to this server.
+
+You can also manually trigger this login/logout using the login and
+logout commands:
+
+.. code-block:: console
+
+ # proxmox-backup-client login
+ Password: **********
+
+To remove the ticket, issue a logout:
+
+.. code-block:: console
+
+ # proxmox-backup-client logout
+
+
+.. _pruning:
+
+Pruning and Removing Backups
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can manually delete a backup snapshot using the ``forget``
+command:
+
+.. code-block:: console
+
+ # proxmox-backup-client forget <snapshot>
+
+
+.. caution:: This command removes all archives in this backup
+ snapshot. They will be inaccessible and unrecoverable.
+
+
+The manual removal is sometimes required, but normally the prune
+command is used to systematically delete older backups. Prune lets
+you specify which backup snapshots you want to keep. The
+following retention options are available:
+
+``--keep-last <N>``
+ Keep the last ``<N>`` backup snapshots.
+
+``--keep-hourly <N>``
+ Keep backups for the last ``<N>`` hours. If there is more than one
+ backup for a single hour, only the latest is kept.
+
+``--keep-daily <N>``
+ Keep backups for the last ``<N>`` days. If there is more than one
+ backup for a single day, only the latest is kept.
+
+``--keep-weekly <N>``
+ Keep backups for the last ``<N>`` weeks. If there is more than one
+ backup for a single week, only the latest is kept.
+
+ .. note:: Weeks start on Monday and end on Sunday. The software
+ uses the `ISO week date`_ system and handles weeks at
+ the end of the year correctly.
+
+``--keep-monthly <N>``
+ Keep backups for the last ``<N>`` months. If there is more than one
+ backup for a single month, only the latest is kept.
+
+``--keep-yearly <N>``
+ Keep backups for the last ``<N>`` years. If there is more than one
+ backup for a single year, only the latest is kept.
+
+The retention options are processed in the order given above. Each option
+only covers backups within its time period. The next option does not take care
+of already covered backups. It will only consider older backups.
+
+Unfinished and incomplete backups will be removed by the prune command unless
+they are newer than the last successful backup. In this case, the last failed
+backup is retained.
+
+.. code-block:: console
+
+ # proxmox-backup-client prune <group> --keep-daily 7 --keep-weekly 4 --keep-monthly 3
+
+
+You can use the ``--dry-run`` option to test your settings. This only
+shows the list of existing snapshots and which action prune would take.
+
+.. code-block:: console
+
+ # proxmox-backup-client prune host/elsa --dry-run --keep-daily 1 --keep-weekly 3
+ ┌────────────────────────────────┬──────┐
+ │ snapshot │ keep │
+ ╞════════════════════════════════╪══════╡
+ │ host/elsa/2019-12-04T13:20:37Z │ 1 │
+ ├────────────────────────────────┼──────┤
+ │ host/elsa/2019-12-03T09:35:01Z │ 0 │
+ ├────────────────────────────────┼──────┤
+ │ host/elsa/2019-11-22T11:54:47Z │ 1 │
+ ├────────────────────────────────┼──────┤
+ │ host/elsa/2019-11-21T12:36:25Z │ 0 │
+ ├────────────────────────────────┼──────┤
+ │ host/elsa/2019-11-10T10:42:20Z │ 1 │
+ └────────────────────────────────┴──────┘
+
+.. note:: Neither the ``prune`` command nor the ``forget`` command free space
+ in the chunk-store. The chunk-store still contains the data blocks. To free
+ space you need to perform :ref:`garbage-collection`.
+
+
+.. _garbage-collection:
+
+Garbage Collection
+~~~~~~~~~~~~~~~~~~
+
+The ``prune`` command removes only the backup index files, not the data
+from the data store. This task is left to the garbage collection
+command. It is recommended to carry out garbage collection on a regular basis.
+
+The garbage collection works in two phases. In the first phase, all
+data blocks that are still in use are marked. In the second phase,
+unused data blocks are removed.
+
+.. note:: This command needs to read all existing backup index files
+ and touches the complete chunk-store. This can take a long time
+ depending on the number of chunks and the speed of the underlying
+ disks.
+
+
+.. code-block:: console
+
+ # proxmox-backup-client garbage-collect
+ starting garbage collection on store store2
+ Start GC phase1 (mark used chunks)
+ Start GC phase2 (sweep unused chunks)
+ percentage done: 1, chunk count: 219
+ percentage done: 2, chunk count: 453
+ ...
+ percentage done: 99, chunk count: 21188
+ Removed bytes: 411368505
+ Removed chunks: 203
+ Original data bytes: 327160886391
+ Disk bytes: 52767414743 (16 %)
+ Disk chunks: 21221
+ Average chunk size: 2486565
+ TASK OK
+
+
+.. todo:: howto run garbage-collection at regular intervalls (cron)
+