diff --git a/Documentation-AdminGuide-Backups.-.md b/Documentation-AdminGuide-Backups.-.md new file mode 100644 index 0000000..ac11bc6 --- /dev/null +++ b/Documentation-AdminGuide-Backups.-.md @@ -0,0 +1,192 @@ +# Backups + +**NOTE:** *This document is deprecated. Please see the [[https://rattailproject.org/docs/rattail-manual/backup/index.html|Rattail Manual]] instead.* + +The approach described here is meant to be useful for *any* machine, not just one which runs a Rattail/Poser app. Also it's meant to back up the entire machine, not just the Rattail/Poser app (if present). + +## Conventions + +Technically our approach *will* involve the installation of the `rattail` software package. (Note however that we are **not** describing the installation process here, only the end result.) + +We assume, as usual, that a virtual environment will be used, and that the "home" folder for these environments is at `/srv/envs`. We further assume a virtual environment named "backup" which lives at `/srv/envs/backup`. + +In addition to the `rattail` package, we also assume that [[https://borgbackup.readthedocs.io/|BorgBackup]] is installed to the virtual environment, as that does much of the heavy lifting. + +## Configuration + +Within the virtual environment, the file at `/srv/envs/backup/app/rattail.conf` is of particular importance. This will contain all configuration regarding the "specifics" of the machine's backup. + +Contents of `/srv/envs/backup/app/rattail.conf` should include something like the following. Note that we've used `thismachine` in place of this machine's hostname. + +Also PLEASE be sure to properly secure this file. Our recommendation is to make it readable only by the "root" user. + +```ini +############################################################ +# +# config for backups +# +############################################################ + + +############################## +# rattail +############################## + +[rattail.config] +# bring in system-wide rattail config, mostly for sake of generic logging config +include = /etc/rattail/rattail.conf + +[rattail.backup] + +# database dumps +dbdump = true +# here is shown default path, can set to whatever you like +#dbdump.output = /root/data +# if true, each table will also be dumped separately +#dbdump.dump_tables = false + +# rsync feature is typically disabled, since borg is a superior approach. however both +# the rsync and borg features will share the `rsync.include` and `rsync.exclude` config. +rsync = false + +# "global" borg config - in particular declares which remotes borg should write backups to +borg.enabled = true +# note that you can have just one, or as many remotes as you like; each "named" whatever here +borg.remotes = local, cloud +borg.archive_hostname = thismachine + +# borg config for "local" remote (note, the "local" name must correspond to a remote listed above) +borg.remote.local.repo = /trailer/borg/thismachine +borg.remote.local.passphrase = YOURBORGPASSPHRASE + +# borg config for "cloud" remote - note the different style of repo compared to "local" remote +borg.remote.cloud.repo = borg@cloud.example.com:/trailer/borg/thismachine +borg.remote.cloud.passphrase = YOURBORGPASSPHRASE +# this should represent the path to `borg` binary on remote cloud system +borg.remote.cloud.borg = /srv/envs/backup/bin/borg + +# these paths are to be included in any rsync or borg backup +rsync.include = + /etc + /home + /opt + /root + /srv + /usr/local + /var + +# these paths are to be excluded from any rsync or borg backup +rsync.exclude = + /var/lib/*/.cache/ + /var/spool/postfix/ + + +############################## +# logging +############################## + +# note, the minimal config here is made possible by including `/etc/rattail/rattail.conf` +# above, since that system-wide file contains most of the logging config + +[handler_file] +args = ('/srv/envs/backup/app/log/rattail.log', 'a', 'utf_8') + +[handler_email] +args = ('localhost', 'root@example.com', ['root@example.com'], "[Backup] Logging") +``` + +## Scripts + +**NOTE:** *Below we always run "sudo" commands as `sudo -H ...` because we want to ensure that the "root" user (whom we're running commands as) has access to the `/root` home folder. On some systems, if you omit the `-H` flag, root will think its home folder is "yours" - i.e. the same as whoever ran the `sudo` command. We must avoid this because `/root` is where certain Borg config etc. will reside, therefore accurate home folder is important.* + +While technically you can run the `rattail backup` command like this: + +```sh +cd /srv/envs/backup +sudo -H bin/rattail -c app/quiet.conf backup --help +``` + +We generally assume the presence of a script at `/usr/local/bin/rattail-backup` which is a wrapper around that and makes it a little nicer to run: + +```sh +sudo -H rattail-backup --help +``` + +However you likely won't be using that script too often. The more useful script is at `/usr/local/bin/backup-everything` which is yet another wrapper, also simple to run. Note that this command doesn't have an extensive help system, as it only supports one flag: + +```sh +sudo -H backup-everything [--verbose] +``` + +What that script does, is a) upgrade the `rattail` source/package, and b) run the `rattail backup` command. The behavior of the latter will of course depend on `/srv/envs/backup/app/rattail.conf` contents. + +## Scheduling with Cron + +This part may vary more often, but the default is to create a file at `/etc/cron.d/backup` which contains the backup cron job (usually there's just one). Contents of this would be like: + +``` +MAILTO="root,you@example.com" + +# backup everything of importance at 2:00am +# TODO: remove the `time -v` bit once you're happy with logic +# (this should mean no more emails unless an error happens) +00 02 * * * root /usr/bin/time -v /usr/local/bin/backup-everything +``` + +## Borg Archives + +Now what about accessing files from a Borg backup? Here we touch on a few commands you'll find useful. + +Please note that you will (most likely) be prompted for the Borg passphrase when using most of these commands. You should have a copy of this passphrase within your `/srv/envs/backup/app/rattail.conf` file. + +### Repo on Local Path + +These instructions assume you wish to interact with a "local path" from the perspective of the machine whose backups you're interested in. This path doesn't need to truly exist on the local disk, for instance it may be a CIFS mount on a NAS or similar. The important point is that it "appears" to be a local path. + +To see available archives: + +```sh +sudo -H borg list /trailer/borg/thismachine +``` + +To mount a particular archive, e.g.: + +```sh +sudo mkdir -p /mnt/borg +sudo -H borg mount /trailer/borg/thismachine::thismachine-2018-09-06T15:38:13 /mnt/borg +``` + +While that is mounted, you can access its files via the `/mnt/borg` folder. + +To unmount the archive: + +```sh +sudo -H borg umount /mnt/borg +``` + +### Repo on Remote Machine + +These instructions assume you wish to interact with a truly "remote" Borg repo, i.e. which resides on a machine other than the local one, and which must be accessed via SSH. + +Note that for each command you may will need to provide a path to the Borg binary on the remote machine, via `--remote-path` argument. + +To see available archives: + +```sh +sudo -H borg list borg@cloud.example.com:/trailer/borg/thismachine +``` + +To mount a particular archive, e.g.: + +```sh +sudo mkdir -p /mnt/borg +sudo -H borg mount borg@cloud.example.com:/trailer/borg/thismachine::thismachine-2018-09-06T15:38:13 /mnt/borg +``` + +While that is mounted, you can access its files via the `/mnt/borg` folder. + +To unmount the archive: + +```sh +sudo -H borg umount /mnt/borg +```