Add Documentation-AdminGuide-Backups
parent
dcbc31e2c6
commit
2f53f6df3d
192
Documentation-AdminGuide-Backups.-.md
Normal file
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
|
||||||
|
```
|
||||||
Loading…
Reference in a new issue