tklbam-backup: Backup the current system

Full man page source

SYNOPSIS

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

ARGUMENTS

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

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

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

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. /path\ with\ space/ or "/path with space/".

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 MySQL/MariaDB databases and tables are backed up.

Similarly, ALL PostgreSQL databases are included - with the EXCEPTION of the postgres database - an empty database included by default in all PostgreSQL installs.

Exclusion of default postgres PostgreSQL database

The exclusion of the postgres database can NOT be overriden, even if explicitly added as an override.

Some documentation suggests that it is "best practice" to not use the default postgres database for user data. However, there is no documented strict reason why it shouldn't be used. So the inability to include this database is considered a bug and will be addressed in a future TKLBAM update. If you are already using the postgres database, the database can be renamed, or you can move your data to a new database.

Database override detail

Adding a positive override (e.g., mysql:mydatabase / pgsql:mydatabase) changes the default behavior so that only the database or table specified in the override is included in the backup. If you wish to use overrides to include multiple databases but not all, they must all be noted separately.

Negative database/table overrides (with a dash prefix) exclude a single database or table (e.g., -mysql:mydatabase / -pgsql:mydatabase ).

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.

Positive and negative overrides can be mixed to give fine grained control.

Examples:

# exclude Drupal10 sessions table
-mysql:drupal10/sessions

# only include drupal10 database
mysql:drupal10

# only include Mahara PostgreSQL database
pgsql:mahara

OPTIONS

              Note: Alternate targets may require additional dependancies 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.

• --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: manual backup target URL. Default: 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

• --resume: Resume aborted backup session
• --disable-resume: Disable implicit --resume when rerunning an aborted backup
• --simulate, -s: 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
• --skip-files: don't backup filesystem
• --skip-database: don't backup databases
• --skip-packages: don't backup new packages
• --s3-parallel-uploads N: Number of parallel volume chunk uploads (Default: 1)
• --force-profile=PROFILE_ID: Force backup profile (e.g., "core")
• --full-backup FREQUENCY: Time frequency of full backup. Default: 1M <frequency> := <int>[DWM]|now

  e.g.,
  now
  3D - three days
  2W - two weeks
  1M - one month

Resolution order for configurable options

1. comand line (highest precedence)
2. configuration file (/etc/tklbam/conf):

   # comment
   <option-name> <value>
   

3. 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: /var/lib/tklbam/profile