add restore docs, fixes #4670 (#4723)

add restore docs, fixes #4670

docs/quickstart.rst

@@ -432,3 +432,153 @@ mounting the remote filesystem, for example, using sshfs::
 You can also use other remote filesystems in a similar way. Just be careful,
 not all filesystems out there are really stable and working good enough to
 be acceptable for backup usage.
+
+
+Restoring a backup
+------------------
+
+Please note that we are only describing the most basic commands and options
+here - please refer to the command reference to see more.
+
+For restoring, you usually want to work **on the same machine as the same user**
+that was also used to create the backups of the wanted files. Doing it like
+that avoids quite some issues:
+
+- no confusion relating to pathes
+- same mapping of user/group names to user/group IDs
+- no permission issues
+- you likely already have a working borg setup there,
+
+  - maybe including a environment variable for the key passphrase (for encrypted repos),
+  - maybe including a keyfile for the repo (not needed for repokey mode),
+  - maybe including a ssh key for the repo server (not needed for locally mounted repos),
+  - maybe including a valid borg cache for that repo (quicker than cache rebuild).
+
+The **user** might be:
+
+- root (if full backups, backups including system stuff or multiple
+  users' files were made)
+- some specific user using sudo to execute borg as root
+- some specific user (if backups of that user's files were made)
+
+A borg **backup repository** can be either:
+
+- in a local directory (like e.g. a locally mounted USB disk)
+- on a remote backup server machine that is reachable via ssh (client/server)
+
+If the repository is encrypted, you will also need the **key** and the **passphrase**
+(which is protecting the key).
+
+The **key** can be located:
+
+- in the repository (**repokey** mode).
+
+  Easy, this will usually "just work".
+- in the home directory of the user who did the backup (**keyfile** mode).
+
+  This may cause a bit more effort:
+
+  - if you have just lost that home directory and you first need to restore the
+    borg key (e.g. from the separate backup you have made of it or from another
+    user or machine accessing the same repository).
+  - if you first must find out the correct machine / user / home directory
+    (where the borg client was run to make the backups).
+
+The **passphrase** for the key has been either:
+
+- entered interactively at backup time
+  (not practical if backup is automated / unattended).
+- acquired via some environment variable driven mechanism in the backup script
+  (look there for BORG_PASSPHRASE, BORG_PASSCOMMAND, etc. and just do it like
+  that).
+
+There are **2 ways to restore** files from a borg backup repository:
+
+- **borg mount** - use this if:
+
+  - you don't precisely know what files you want to restore
+  - you don't know which archive contains the files (in the state) you want
+  - you need to look into files / directories before deciding what you want
+  - you need a relatively low volume of data restored
+  - you don't care for restoring stuff that the FUSE mount is not implementing yet
+    (like special fs flags, ACLs)
+  - you have a client with good resources (RAM, CPU, temp. disk space)
+  - you want to rather use some filemanager to restore (copy) files than borg
+    extract shell commands
+
+- **borg extract** - use this if:
+
+  - you precisely know what you want (repo, archive, path)
+  - you need a high volume of files restored (best speed)
+  - you want a as-complete-as-it-gets reproduction of file metadata
+    (like special fs flags, ACLs)
+  - you have a client with low resources (RAM, CPU, temp. disk space)
+
+
+Example with **borg mount**:
+
+::
+
+    # open a new, separate terminal (this terminal will be blocked until umount)
+
+    # now we find out the archive names we have in the repo:
+    borg list /mnt/backup/borg_repo
+
+    # mount one archive from a borg repo:
+    borg mount /mnt/backup/borg_repo::myserver-system-2019-08-11 /mnt/borg
+
+    # alternatively, mount all archives from a borg repo (slower):
+    borg mount /mnt/backup/borg_repo /mnt/borg
+
+    # it may take a while until you will see stuff in /mnt/borg.
+
+    # now use another terminal or file browser and look into /mnt/borg.
+    # when finished, umount to unlock the repo and unblock the terminal:
+    borg umount /mnt/borg
+
+
+Example with **borg extract**:
+
+::
+
+    # borg extract always extracts into current directory and that directory
+    # should be empty (borg does not support transforming a non-empty dir to
+    # the state as present in your backup archive).
+    mkdir borg_restore
+    cd borg_restore
+
+    # now we find out the archive names we have in the repo:
+    borg list /mnt/backup/borg_repo
+
+    # we could find out the archive contents, esp. the path layout:
+    borg list /mnt/backup/borg_repo::myserver-system-2019-08-11
+
+    # we extract only some specific path (note: no leading / !):
+    borg extract /mnt/backup/borg_repo::myserver-system-2019-08-11 path/to/extract
+
+    # alternatively, we could fully extract the archive:
+    borg extract /mnt/backup/borg_repo::myserver-system-2019-08-11
+
+    # now move the files to the correct place...
+
+
+Difference when using a **remote borg backup server**:
+
+It is basically all the same as with the local repository, but you need to
+refer to the repo using a ``ssh://`` URL.
+
+In the given example, ``borg`` is the user name used to log into the machine
+``backup.example.org`` which runs ssh on port ``2222`` and has the borg repo
+in ``/path/to/repo``.
+
+Instead of giving a FQDN or a hostname, you can also give an IP address.
+
+As usual, you either need a password to log in or the backup server might
+have authentication set up via ssh ``authorized_keys`` (which is likely the
+case if unattended, automated backups were done).
+
+::
+
+    borg mount ssh://borg@backup.example.org:2222/path/to/repo /mnt/borg
+    # or
+    borg extract ssh://borg@backup.example.org:2222/path/to/repo