.. highlight:: sh

=======================
 Restoring from Backup
=======================

Rattail tries to make the *backup* process more convenient, but it
does *not* offer any conveniences for the *restore* process.

However, it uses "standard" tools to create the backup, and each of
those tools essentially provides a way to restore.  We'll briefly
outline each and give links to further reading.


Database Dumps
==============

If your backup was configured to include database dumps, that
means you will have files generated by one or both of:

* ``mysqldump`` (MySQL / MariaDB)
* ``pg_dump`` (PostgreSQL)

By default these files will be in the ``/root/data`` folder on the
server (machine being backed up).  However if rsync/borg were used
then copies of these files should be elsewhere as well, e.g. borg
archives.

Each is simply a gzip-ed SQL dump file as generated by the above
commands.  See their docs for how to restore:

* MariaDB: https://mariadb.com/kb/en/restoring-data-from-dump-files/
* MySQL: https://dev.mysql.com/doc/mysql-backup-excerpt/8.0/en/reloading-sql-format-dumps.html
* PostgreSQL: https://www.postgresql.org/docs/current/backup-dump.html#BACKUP-DUMP-RESTORE


Rsync
=====

If your backup was configured to use ``rsync``, that just means that
some files were copied "as-is" from your server (machine being backed
up) to some target path.

There is no default location for the target path, it will be whatever
your config says.  Could be either a "local" path on the server, or
some remote path accessed via SSH.

Restoring such files is just a matter of copying them from that
"target" path, back to wherever you need them to be..

However note that the ``rsync`` method would normally only have the
"most recent" copy of the files, which may not be sufficient for you
to restore from, depending on the nature of the problem.  It's for
this reason that you're encouraged to use the Borg feature also /
instead.


Borg
====

If your backup involves Borg then that typically means you have one or
more target paths, to which Borg archives are written each night.  The
archives are in fact written to a Borg "repo" which contains multiple
archives, older ones being pruned over time to keep only so many
around at a time.

And again there may be more than one of these target paths (Borg
repos).  From the perspective of the server (machine being backed up),
there might be a Borg repo on an external disk, another on a local NAS
device, another in a cloud server.  All of the repos though probably
work the same and so you can restore from any the same.

First, the official Borg docs on the matter:

* https://borgbackup.readthedocs.io/en/stable/quickstart.html
* https://borgbackup.readthedocs.io/en/stable/usage/mount.html


Example Commands
----------------

For sake of example we'll show some commands to "mount" a Borg
archive, at which point it looks just like another folder in your file
system, and you can then copy files as you please.

Let's assume that the Borg repo lives on an external drive attached to
your server.  On your server then, we'll mount one of the archives.


Command Basics
~~~~~~~~~~~~~~

Just a reminder here that you'll need the Borg encryption passphrase
in order to decrypt the Borg repo and actually see "readable" files
etc.  (Borg will prompt you for it.)  That password should be
somewhere in ``/srv/envs/backup/app/rattail.conf`` on your server.

Also note that all commands shown here are meant to run on your
server, but *any* machine which has Borg installed, could be used for
this.  You'd likely need to have SSH config in place in order to have
basic access to the Borg repo location, and then would of course still
need the encryption passphrase.


List Borg Archives
~~~~~~~~~~~~~~~~~~

Next let's take a look at which archives are available, again assuming
they're on an external drive (and assuming ``myserver`` is the name of
your server)::

   sudo -H borg list /mnt/external/borg-repos/myserver

Note that if your Borg repo lives on another machine, then that
command would look more like::

   sudo -H borg list borg@cloud.example.com:/path/to/borg-repos/myserver


Mount a Borg Archive
~~~~~~~~~~~~~~~~~~~~

Depending on which archives were listed via previous command, you
would normally pick the one you wanted, and then "mount" it onto your
local file system.

First create a mount point just for this::

   sudo mkdir -p /mnt/borg

Then for instance, mount with something like::

   sudo -H borg mount /mnt/external/borg-repos/myserver::myserver-2021-12-01T15:38:13 /mnt/borg

And again if your Borg repo lives on another machine::

   sudo -H borg mount borg@cloud.example.com:/path/to/borg-repos/myserver::myserver-2021-12-01T15:38:13 /mnt/borg

Once mounted you can access the files just like you would any other
mounted network share etc., the one caveat being that only root should
have access to the borg mount.  For instance:

.. code-block:: none

   myuser@myserver:~$ sudo ls -l /mnt/borg
   total 0
   drwxr-xr-x 1 root root 0 Jun 25 19:31 etc
   drwxr-xr-x 1 root root 0 Sep  8  2019 home
   drwxr-xr-x 1 root root 0 Sep  8  2019 opt
   drwx------ 1 root root 0 Jul 18  2020 root
   drwxr-xr-x 1 root root 0 Sep  9  2019 srv
   drwxr-xr-x 1 root root 0 Dec  1 21:35 usr
   drwxr-xr-x 1 root root 0 Sep  8  2019 var


When you're finished you should unmount::

   sudo -H borg umount /mnt/borg