<> {{{#!wiki warning This document is deprecated. Please see the [[https://rattailproject.org/docs/rattail-manual/backup/index.html|Rattail Manual]] instead. }}} = Backups = 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. {{{#!highlight 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 == {{{#!wiki 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: {{{ 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: {{{ 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: {{{ 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: {{{ sudo -H borg list /trailer/borg/thismachine }}} To mount a particular archive, e.g.: {{{ 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: {{{ 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: {{{ sudo -H borg list borg@cloud.example.com:/trailer/borg/thismachine }}} To mount a particular archive, e.g.: {{{ 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: {{{ sudo -H borg umount /mnt/borg }}}