From a7dab629daac4e925d90c820d79ac83f77258889 Mon Sep 17 00:00:00 2001 From: Lance Edgar Date: Wed, 1 Dec 2021 21:40:11 -0600 Subject: [PATCH] Add docs for restoring from backup, esp. Borg archive --- docs/backup/index.rst | 1 + docs/backup/restore.rst | 159 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 160 insertions(+) create mode 100644 docs/backup/restore.rst diff --git a/docs/backup/index.rst b/docs/backup/index.rst index 600da5c..1eadf90 100644 --- a/docs/backup/index.rst +++ b/docs/backup/index.rst @@ -23,3 +23,4 @@ existing Rattail app in charge of backups. config running features/index + restore diff --git a/docs/backup/restore.rst b/docs/backup/restore.rst new file mode 100644 index 0000000..2f9b9bd --- /dev/null +++ b/docs/backup/restore.rst @@ -0,0 +1,159 @@ + +.. 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