rattail/moin-archive
2
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

Add Documentation-AdminGuide-Backups

Lance Edgar 2025-02-15 21:43:59 -06:00
parent dcbc31e2c6
commit 2f53f6df3d
1 changed files with 192 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

192
Documentation-AdminGuide-Backups.-.md Normal file

@ -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
```