==============
tklbam-restore
==============

----------------
Restore a backup
----------------

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

SYNOPSIS
========

tklbam-restore [ -options ] [ <hub-backup> ]

ARGUMENTS
=========

`<hub-backup>` := backup-id || unique label pattern || path/to/backup/extract


OPTIONS
=======

General options
---------------

--raw-download=path/to/backup/    Download backup to directory without doing a system restore

Duplicity related options
-------------------------

--time=TIME                       Time to restore from

  TIME := YYYY-MM-DD | YYYY-MM-DDThh:mm:ss | <int>[mhDWMY]
    
    e.g.,::

          2010-08-06 - 2010, August 6th, 00:00

          2010-08-07T14:00 - 2010, August 7th 14:00 UTC

          6m - 6 minutes
          5h - 5 hours
          4D - 4 days ago
          3W - 3 weeks ago
          2M - 2 months ago
          1Y - 1 year ago

--keyfile=KEYFILE                 Path to tklbam-escrow created keyfile
                                  
                                  Default: automatically retrieved from the Hub

--address=TARGET_URL              Custom backup target URL (needs --keyfile)

                                  Default: S3 storage bucket automatically provided by 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
                                      
System restore options
----------------------

--simulate                        Do a dry run simulation of the system restore

--limits=LIMITS                   Restore filesystem or database limitations. You can use this 
                                  to control what parts of the backup will be restored.

                                  Preceding a limit with a minus sign
                                  turns it into an exclusion.

  `LIMITS` := "``LIMIT``-1 .. ``LIMIT``-N"
  
  ``LIMIT`` :=  -?( /path/to/include/or/exclude | 
                     mysql:database[/table] |
                     pgsql:database[/table] )



--skip-files                      Don't restore filesystem
--skip-database                   Don't restore databases
--skip-packages                   Don't restore new packages

--logfile=PATH                    Path to log file.
                                  Default: /var/log/tklbam-restore

--no-rollback                     Disable rollback
--silent                          Disable feedback

--force                           Disable sanity checking

--debug                           Run $SHELL after Duplicity

Configurable options
--------------------

--restore-cache-size=SIZE         The maximum size of the download cache
                                  default: 50%

--restore-cache-dir=PATH          The path to the download cache directory
                                  default: /var/cache/tklbam/restore

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

::

    # Restore Hub backup id 1
    tklbam-restore 1

    # Same result as above but in two steps: first download the extract, then apply it
    tklbam-restore 1 --raw-download=/tmp/mybackup
    tklbam-restore /tmp/mybackup

    # Restore backup created with tklbam-backup --raw-upload=/srv
    tklbam-restore 2 --raw-download=/srv

    # Restore from Duplicity archives at a custom backup address on the local filesystem
    tklbam-restore --address=file:///mnt/backups/mybackup --keyfile=mybackup.escrow 

    # Simulate restoring Hub backup id 1 while excluding changes to the /root path,
    # mysql 'customers' DB, and the 'emails' table in the 'webapps' DB
    tklbam-restore 1 --simulate --limits="-/root -mysql:customers -mysql:webapp/emails"

    # Simulate restoring only the /root files in Hub backup id 1
    tklbam-restore 1 --simulate --skip-database --skip-packages --limits="/root"

FILES
=====

:Configuration files: /etc/tklbam/conf, /etc/tklbam/hooks.d

:Restore cache: /var/cache/tklbam/restore (by default, see --restore-cache-dir=PATH option)

SEE ALSO
========

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