====== Tarsnap Online Backup ====== AstLinux now supports performing remote, online, "Trust No One" encrypted snapshots using the [[https://www.tarsnap.com|Tarsnap Backup]] service. The Tarsnap service uses Amazon Web Services (EC2 and S3) for it's infrastructure. Tarsnap is the brainchild of Tarsnap Backup Inc. founder [[https://github.com/cperciva|Colin Percival]]. Tarsnap is a pre-pay service, opening an account with the minimum $5 USD will get you started, which will last about 1.5 years with an averaged 1 GB of storage. Multiple AstLinux boxes can share one account with a unique ''tarsnap.key'' generated on each box. AstLinux uses the ''tarsnap-backup'' command as a front-end to the core ''tarsnap'' commands provided by the [[https://github.com/Tarsnap/tarsnap|Tarsnap]] project. The ''tarsnap-backup'' command helps generate a ''tarsnap.key'', add/remove cron entries and perform "dry-run" backup testing as well as the actual backups. The core ''tarsnap'' command is used for data restores. The Command Line Interface (CLI) must be used to generate a ''tarsnap.key'', "dry-run" backup testing as well as restoring data. !!Tip ->!! Be certain to perform your own due diligence as for any online backup service. !!Note: AstLinux 1.3.1 or later is required!! \\ ===== Tarsnap Backup Options ===== Select the Network Tab in the web interface.\\ {{:userdoc:ipv6-tunnel-network-tab.jpg?nolink|Network Tab}} {{:userdoc:tarsnap-backup-options.jpg?nolink|Tarsnap Backup Options}} The default values will be used in the CLI examples below. It is recommended to configure the "Email Notifications:" section to make sure you are aware of any backup issues. !!Note ->!! If either Backup ''[kd]'' or ''[asturw]'' types have Defaults ''disabled'' and empty Dirs and Files, then no backup archive will be generated for that backup type. {{:userdoc:tarsnap-backup-kd-files.png?nolink|Tarsnap Backup kd Files}} Above is an example where the Backup ''[kd]'' type uses the default set as well includes a text CDR records file. !!Tip ->!! It is more desirable to backup uncompressed text data files, rather then compressed or binary database files. Advanced users can make use of the optional ''/mnt/kd/tarsnap-backup.script'' to export database files to text in a special directory to efficiently create backup snapshots. Here is a backup options example where all the directories and files are included in the ''[kd]'' backup, set Defaults ''disabled'' and ''*'' for both Dirs and Files. {{:userdoc:tarsnap-backup-kd-all.png?nolink|Tarsnap Backup kd All}} For this example creating a full ''[kd]'' backup, be sure to test with ''tarsnap-backup --cron --dry-run'' to make sure you are not including unnecessary files. !!Tip ->!! Both the Dirs and Files fields may contain the ''*'' wildcard character, for example Files: ''voicemail/default/*/unavail.*'' "Automatic Archive Aging" is a useful option to manage the amount of data you store. Pruning is disabled by default, but automatically deleting archives older then 30 days seems like a good setting for many users: {{:userdoc:tarsnap-backup-prune.png?nolink|Tarsnap Prune}} Currently (Sept/2017), listing archives is a rather slow process (~5/sec), so limiting the number of archives can be useful, it also saves on storage costs. \\ ===== Generating a Key ===== Before you can generate a key you must create an account at [[https://www.tarsnap.com|Tarsnap]], the password you choose along with your account email address will be needed whenever you create a new key. Each unique key is associated with a set of archives. The optional ''--machine'' defaults to the local hostname and is only a label associated with the key, which is displayed in the administration web interface. While not required, it is best to make sure ''--machine'' is unique for every key. Your Tarsnap account can have many keys, but only one key per AstLinux box, hence one set of archives per AstLinux box. So, you have a Tarsnap account and password, begin by typing ''tarsnap-backup'' without any arguments... pbx ~ # tarsnap-backup tarsnap-backup: Missing '/mnt/kd/tarsnap/tarsnap.key' keyfile. You must register with Tarsnap [ https://www.tarsnap.com ] and define account credentials. Using account credentials, generate a local '/mnt/kd/tarsnap/tarsnap.key'. **don't lose it** Example: tarsnap-backup --keygen me@example.com [ --machine machine-name ] --machine will default to 'pbx' Simple enough, use your account email and password, specify ''--machine'' if the default is not to your liking... pbx ~ # tarsnap-backup --keygen me@example.com Enter tarsnap account password: Store a copy of your ''/mnt/kd/tarsnap/tarsnap.key'' somewhere safe, keeping track which AstLinux box it belongs to. !!Warning ->!! If you lose your ''tarsnap.key'', you will not be able to access your archived data! \\ ===== Manual Backup ===== A good practice after defining the web interface backup options is to perform a ''--dry-run'' to view what is being archived. When using ''--dry-run'' nothing is sent to the Tarsnap servers, only a local operation. pbx ~ # tarsnap-backup --cron --dry-run **** Dry Run **** a etc -- snip -- Total size Compressed size All archives 9.9 kB 2.8 kB (unique data) 9.9 kB 2.8 kB This archive 9.9 kB 2.8 kB New data 9.9 kB 2.8 kb **** Dry Run **** a rc.conf.d -- snip -- Total size Compressed size All archives 1.2 MB 335 kB (unique data) 1.2 MB 335 kB This archive 1.2 MB 335 kB New data 1.2 MB 335 kB **** Dry Run **** The first set is the ''[asturw]'' archive, and the second set is the ''[kd]'' archive. Study the output, adjust the web interface backup options if desired until you get the ''--dry-run'' result you want. Normally your backups will occur nightly via ''cron'', but your first set of archives should be done manually, same as before but don't include ''--dry-run''. pbx ~ # tarsnap-backup --cron Total size Compressed size All archives 9.9 kB 2.7 kB (unique data) 9.9 kB 2.7 kB This archive 9.9 kB 2.7 kB New data 9.9 kB 2.7 kB tarsnap-backup: Backup success: Created Tarsnap archive: pbx-asturw-20170912-100831, New Data: 2.7 kB, Unique Archived: 2.7 kB Total size Compressed size All archives 1.2 MB 337 kB (unique data) 1.2 MB 337 kB This archive 1.2 MB 335 kB New data 1.2 MB 335 kB tarsnap-backup: Backup success: Created Tarsnap archive: pbx-kd-20170912-100839, New Data: 335 kB, Unique Archived: 337 kB Hopefully all goes well and no errors. For fun, list the newly created archives... pbx ~ # tarsnap-backup --list pbx-asturw-20170912-100831 pbx-kd-20170912-100839 and show the storage statistics... pbx ~ # tarsnap-backup --stats Total size Compressed size All archives 1.2 MB 337 kB (unique data) 1.2 MB 337 kB You are now ready to perform backups nightly, see the "Automating Backups" topic below. \\ ===== Automating Backups ===== Tarsnap uses "data deduplication" and compression to reduce the size of archives, therefore it is efficient to run ''tarsnap-backup --cron'' once a day. The following command will add a cron entry between 0(midnight) and 1(am) with a randomly generated minute value: tarsnap-backup --install-cronjob if you ever want do disable automatic backups: tarsnap-backup --uninstall-cronjob !!Tip:!! Don't use a cronjob between 02:00 and 03:00 in the night, because of DST switching :-). \\ ===== Restore from an Archive ===== Find all archives on a specific date: tarsnap-backup --list | grep -e '-20170911-' outputs pbx4-asturw-20170911-021201 pbx4-kd-20170911-021208 \\ List (verbose) of an archive: tarsnap -tvf pbx4-kd-20170911-021208 Just as you would use ''tar'' to extract a file: mkdir restore tarsnap -xvf pbx4-kd-20170911-021208 -C restore asterisk/modules.conf Then copy the file over to ''/mnt/kd/'' if it looks OK, or for the daring you could have used ''-C /mnt/kd'' to directly overwrite. You might also restore saved database dumps respectively. See below in the last part of the [[#optional_action_script|Optional Action Script]]. !!Note ->!! If you restore to a different media than the original, you need to run this command afterwards to re-create the [[https://www.tarsnap.com/cachedir.html|cache directory]] and to be able to create backups again ((This option is not listed in the program help!)): tarsnap --fsck \\ ===== Restore to a New Install ===== It is quite useful to use a Tarsnap Backup to restore a machine following a new install. This may occur after a disk failure or an upgrade to different hardware. !!Note ->!! It is best practice that every instance (''--machine'') has a unique ''tarsnap.key'', and the previous disk/hardware is no longer used with the same ''tarsnap.key''. !!Warning ->!! You should not use a Tarsnap Backup to "clone" an active system to create a new install, as that will duplicate private keys (SSH, VPN, etc.) which must be unique across deployed systems. First, configure AstLinux using the standard **[[userdoc:new-install|New Install]]**.\\ Set the "Management Password" via the web interface, it may be different from what is archived in the Tarsnap Backup if you wish. Then, using the CLI, create the tarsnap directory: mkdir /mnt/kd/tarsnap Copy the stored unique ''tarsnap.key'' to ''/mnt/kd/tarsnap/'' Restore all the ''/mnt/kd'' files from the previous ''kd'' archive: tarsnap -xvf machine-kd-archive -C /mnt/kd !!Note ->!! We are skipping restoring the ''machine-asturw-archive'' to ''/oldroot/mnt/asturw'' as it may be hardware specific and the "Management Password" was set above. Resync the tarsnap cache directory: tarsnap --fsck Finally, Reboot the system to use the restored data. \\ ===== Nuke All Archives ===== There may be a time when you want to delete all the stored archives associated with a ''tarsnap.key''. The ''--nuke'' option only applies to the ''/mnt/kd/tarsnap/tarsnap.key'' generated archives. If you have other keys on other boxes, their associated archives will not be effected. !!Warning ->!! This process is not reversible! tarsnap --nuke tarsnap --fsck \\ ===== Useful CLI Commands ===== Show the online storage used, note the ''Compressed size'' -> ''(unique data)'' is the actual storage you are paying for. tarsnap-backup --stats \\ Show the online storage used for a named archive: tarsnap-backup --stats pbx4-kd-20170911-021208 \\ Show the online storage used for all archives: tarsnap-backup --stats '*' \\ List all archives sorted by name: tarsnap-backup --list \\ List all archives sorted by time: tarsnap-backup --list --sort time \\ List (verbose) of an archive: tarsnap -tvf pbx4-kd-20170911-021208 \\ Extract a file from the archive and output to ''stdout'': tarsnap -xOf pbx4-kd-20170911-021208 crontabs/root \\ Show the version of Tarsnap: tarsnap-backup --version \\ Here is the complete [[https://www.tarsnap.com/man-tarsnap.1.html|manual]] \\ ===== Global Tarsnap Config ===== The ''/etc/tarsnap.conf'' file contains the system defaults for the core ''tarsnap'' commands. The user is allowed to edit the ''/etc/tarsnap.conf'' file, thought only do so when there is no other solution. The most common entries that might be edited are the ''exclude'' entries: exclude *.bak exclude *.db exclude *.mdb exclude *.sqlite3 exclude *.fossil exclude *.netset exclude *.rom exclude *.bin If you are choosing to do a full backup, you may also define directory paths to be excluded. \\ ===== Optional Action Script ===== Optionally, if there exists an executable ''/mnt/kd/tarsnap-backup.script'' script file it will be called before a backup and after a backup. Before the backup, the arguments passed to the script are: PRE_BACKUP (day 1-31) (month 1-12) (weekday 0-6) After the backup, the arguments passed to the script are: POST_BACKUP (day 1-31) (month 1-12) (weekday 0-6) \\ For example, before the backup on Tuesday, September 12, the arguments are: PRE_BACKUP 12 9 2 and after the backup POST_BACKUP 12 9 2 !!Tip ->!! If you have constantly changing database files, you could choose to export them to a text file once a week so it will be efficiently archived. Example ''/mnt/kd/tarsnap-backup.script'' script: //(make it executable)// #!/bin/sh ## Action: PRE_BACKUP POST_BACKUP ACTION="$1" ## Day: 1-31 DAY="$2" ## Month: 1-12 MONTH="$3" ## Weekday: 0=Sunday 1=Monday 2=Tuesday 3=Wednesday 4=Thursday 5=Friday 6=Saturday WEEKDAY="$4" ## Directory for text snapshots of databases and such ## Note: Add "custom-backup" to Web Interface / Tarsnap Backup Options / Backup [kd] Dirs: CUSTOM_BACKUP_DIR="/mnt/kd/custom-backup" if [ ! -d "$CUSTOM_BACKUP_DIR" ]; then mkdir "$CUSTOM_BACKUP_DIR" fi if [ "$ACTION" = "PRE_BACKUP" ]; then ## Backup manually created blocklist netset's since *.netset files are excluded, copy only when changed for x in /mnt/kd/blocklists/whitelist.netset \ /mnt/kd/blocklists/whitelistv6.netset \ /mnt/kd/blocklists/blocked-hosts*.netset; do if [ -f "$x" ]; then rsync -c "$x" "$CUSTOM_BACKUP_DIR/${x##*/}.copy" fi done ## Backup astdb.sqlite3 and astlinux.fossil once a week (Friday) if [ "$WEEKDAY" = "5" ]; then if [ -f /mnt/kd/astdb.sqlite3 ]; then sqlite3 /mnt/kd/astdb.sqlite3 .dump > "$CUSTOM_BACKUP_DIR/astdb.sqlite3.dump" fi if [ -f /mnt/kd/fossil/astlinux.fossil ]; then sqlite3 /mnt/kd/fossil/astlinux.fossil .dump > "$CUSTOM_BACKUP_DIR/astlinux.fossil.dump" fi fi fi \\