tklbam-backup

Backup the current system

Author:	Liraz Siri <liraz@turnkeylinux.org>
Date:	2013-09-05
Manual section:	8
Manual group:	backup

SYNOPSIS

tklbam-backup [ -options ] [ override ... ]

ARGUMENTS

<override> := <filesystem-override> | <database-override>

Overrides are usually configured in /etc/tklbam/overrides.

Note overrides that include a space in their path do NOT need to be escaped when included in /etc/tklbam/overrides (just put them on their own line). If excluding/including them from the commandline, they can be escaped or quoted. E.g. /pathwithspace/ or "/path with space/".

Filesystem overrides

<filesystem-override> := -?/path/to/include/or/exclude

This includes or excludes additional files and directories from being backed up if they've changed since installation.

Overrides defaults in /var/lib/tklbam/profile/dirindex.conf

Gotchas:

If you add a directory handled by package management this may break package management on the system you restore to.
Only changes (e.g., new files, edited files, deleted files) from the base installation are included in a backup.

Examples:

# exclude log files in /var/www
-/var/www/*/logs

# ignores changes to webmin configuration
-/etc/webmin

# include the contents of an external hard disk...
/mnt/images

Database overrides

<database-override> := -?mysql:database[/table]

<database-override> := -?pgsql:database[/table]

By default ALL databases and database tables are backed up.

Adding a positive override (e.g., mysql:mydatabase) changes the default behavior so that only the database or table specified in the override is included in the backup.

Negative overrides exclude a database (e.g., -mysql:mydatabase) or table (e.g., -mysql:mydatabase/mytable) from being included in the backup.

Excluding a table only excludes its data. The schema of an excluded table is still backed up, as it takes up a trivial amount of space and other tables or views may depend on it.

You can mix positive overrides with negative overrides.

Examples:

# exclude Drupal6 sessions table
-mysql:drupal6/sessions

# only include drupal6 database
mysql:drupal6

# only include mahara postgres database
pgsql:mahara

OPTIONS

`--dump=DIR`	Dump a raw backup extract to path. Tip: tklbam-restore path/to/raw/extract/
`--raw-upload=PATH`
	Use Duplicity to upload raw path contents to --address
`--address=TARGET_URL`
	custom backup target URL. Default: S3 storage bucket automatically configured via Hub Supported storage backends and their URL formats: file:///some_dir rsync://user[:password]@other.host[:port]//absolute_path rsync://user[:password]@other.host[:port]/relative_path rsync://user[:password]@other.host[:port]::/module/some_dir s3://other.host/bucket_name[/prefix] s3+http://bucket_name[/prefix] ftp://user[:password]@other.host[:port]/some_dir ftps://user[:password]@other.host[:port]/some_dir hsi://user[:password]@other.host[:port]/some_dir imap://user[:password]@other.host[:port]/some_dir scp://user[:password]@other.host[:port]/some_dir ssh://user[:password]@other.host[:port]/some_dir tahoe://alias/directory webdav://user[:password]@other.host/some_dir webdavs://user[:password]@other.host/some_dir gdocs://user[:password]@other.host/some_dir Note: Alternate targets may require additional dependencies E.g. to use SSH you will need to install 'python-paramiko' (apt-get update && apt-get install python-paramiko). Currently the requirements of each target are not documented; however if you keep in mind that TKLBAM uses Duplicity as a back end, google should provide guidance.
`--resume`	Resume aborted backup session
`--disable-resume`
	Disable implicit --resume when rerunning an aborted backup
`--simulate`	Simulate operation. Don't actually backup. Useful for inspecting /TKLBAM by hand.
`--quiet, -q`	Be less verbose
`--logfile=PATH`	Path of file to log output to. Default: /var/log/tklbam-backup
`--debug`	Run $SHELL before Duplicity

Configurable options

`--volsize MB`	Size of backup volume in MBs. Default: 50
`--s3-parallel-uploads=N`
	Number of parallel volume chunk uploads Default: 1
`--full-backup FREQUENCY`
	Time frequency of full backup. Default: 1M <frequency> := now \| <int>[DWM] e.g.,: now - always do a full backup 60m - 60 minutes 12h - 12 hours 3D - three days 2W - two weeks 1M - one month
`--skip-files`	Don't backup filesystem
`--skip-database`
	Don't backup databases
`--skip-packages`
	Don't backup new packages
`--force-profile=PROFILE_ID`
	Force backup profile (e.g., "core")

Resolution order for configurable options:

command line (highest precedence)
configuration file (/etc/tklbam/conf):
```
# comment
<option-name> <value>
```
built-in default (lowest precedence)

USAGE EXAMPLES

# Full system-level backup
tklbam-backup

# Same result as above but in two steps: first dump to a directory, then upload it
tklbam-backup --dump=/tmp/mybackup
tklbam-backup --raw-upload=/tmp/mybackup

# Backup Duplicity archives to a custom address on the local filesystem
tklbam-backup --address=file:///mnt/backups/mybackup
tklbam-escrow this-keyfile-needed-to-restore-mybackup.escrow

# Simulate a backup that excludes the mysql customers DB and the 'emails' table in the webapp DB
# Tip: usually you'd want to configure excludes in /etc/tklbam/overrides
tklbam-backup --simulate -- -/srv -mysql:customers -mysql:webapp/emails

# Create separate backups with unique backup ids containing the previously excluded items
# Tip: use tklbam-status after tklbam-backup to determine the Hub backup ID
export TKLBAM_REGISTRY=/var/lib/tklbam.customers-and-webapp-emails
tklbam-backup --skip-files --skip-packages -- mysql:customers mysql:webapp/emails

export TKLBAM_REGISTRY=/var/lib/tklbam.raw-srv
tklbam-backup --raw-upload=/srv

FILES

Configuration files:
	/etc/tklbam/overrides, /etc/tklbam/conf, /etc/tklbam/hooks.d
Local cache of profile:
	$TKLBAM_REGISTRY/profile

By default TKLBAM_REGISTRY=/var/lib/tklbam