=============
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.

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 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.

--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:

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: $TKLBAM_REGISTRY/profile

By default TKLBAM_REGISTRY=/var/lib/tklbam



SEE ALSO
========

``tklbam`` (8), ``tklbam-faq`` (7), ``tklbam-hooks`` (5)
