README.rst - salt-formulas/xtrabackup - Gitiles


 ===================
 Usage
 ===================

 Xtrabackup allows you to backup and restore databases from full
 backups or full backups and its incrementals.

 Sample pillars
 ==============

 Backup client with ssh/rsync remote host:

 .. code-block:: yaml

     xtrabackup:
       client:
         enabled: true
         full_backups_to_keep: 3
         hours_before_full: 48
         hours_before_incr: 12
         database:
           user: username
           password: password
         target:
           host: cfg01

 .. note:: The ``full_backups_to_keep`` parameter states how many backup will
    be stored locally on xtrabackup client. More options to relocate local
    backups can be done using ``salt-formula-backupninja``.

 Backup client using DB API instead of socket (still needs to be run on the same server as DB):

 .. code-block:: yaml

     xtrabackup:
       client:
         enabled: true
         full_backups_to_keep: 3
         hours_before_full: 48
         hours_before_incr: 12
         database:
           user: username
           password: password
           host: localhost
           port: 3306
         target:
           host: cfg01

 .. note:: DB user ``username`` must have "RELOAD" and "REPLICATION CLIENT"
    privileges on all databases.

 Backup client with local backup only:

 .. code-block:: yaml

     xtrabackup:
       client:
         enabled: true
         full_backups_to_keep: 3
         hours_before_full: 48
         hours_before_incr: 12
         database:
           user: username
           password: password

 .. note:: The ``full_backups_to_keep`` parameter states how many backup will
    be stored locally on xtrabackup client.

 Backup client with ssh/rsync to remote host with compression, IO throttling and non-default
 backup directory on server:

 .. code-block:: yaml

     xtrabackup:
       client:
         enabled: true
         full_backups_to_keep: 3
         hours_before_full: 48
         hours_before_incr: 12
         compression: true
         rsync_tables: true
         compression_threads: 2
         throttle: 20
         database:
           user: username
           password: password
         target:
           host: cfg01
       server:
         enabled: false
         backup_dir: /srv/backup

 .. note:: More options to relocate local backups can be done using
    ``salt-formula-backupninja``.

 .. note:: If the ``server`` section is ommited, backups will be made to
    default location, same on both client and server side.

 Backup client at exact times:

 .. code-block:: yaml

   xtrabackup:
     client:
       enabled: true
       full_backups_to_keep: 3
       incr_before_full: 3
       backup_dir: /var/backups/mysql/xtrabackup
       backup_times:
         day_of_week: 0
         hour: 4
         minute: 52
       compression: true
       rsync_tables: true
       compression_threads: 2
       database:
         user: user
         password: password
       target:
         host: host01

 .. note:: Parameters in ``backup_times`` section can be used to set up exact
    time the cron job should be executed. In this example, the backup job
    would be executed every Sunday at 4:52 AM. If any of the individual
    ``backup_times`` parameters is not defined, the defalut ``*`` value will
    be used. For example, if minute parameter is ``*``, it will run the backup
    every minute, which is ususally not desired.

    Available parameters include:

    * ``day_of_week``
    * ``day_of_month``
    * ``month``
    * ``hour``
    * ``minute``.

    See the crontab reference for further info on how to set these
    parameters.

 .. note:: Please be aware that only ``backup_times`` section OR
    ``hours_before_full(incr)`` can be defined. If both are defined. The
    ``backup_times`` section will be peferred.

 .. note:: New parameter ``incr_before_full`` needs to be defined. This
    number sets number of incremental backups to be run, before a full backup
    is performed.

 Backup server rsync and non-default backup directory:

 .. code-block:: yaml

     xtrabackup:
       server:
         enabled: true
         hours_before_full: 48
         full_backups_to_keep: 5
         key:
           xtrabackup_pub_key:
             enabled: true
             key: key
         backup_dir: /srv/backup

 .. note:: The ``hours_before_full`` parameter should have the same value as
    is stated on xtrabackup client

 .. note:: If the ``backup_dir`` argument is ommited backups will be made to
    default location, same on both client and server side.

 Backup server without strict client restriction:

 .. code-block:: yaml

     xtrabackup:
       server:
         restrict_clients: false

 Backup server at exact times:

 .. code-block:: yaml

   xtrabackup:
     server:
       enabled: true
       full_backups_to_keep: 3
       incr_before_full: 3
       backup_dir: /srv/backup
       backup_times:
         day_of_week: 0
         hour: 4
         minute: 52
       key:
         xtrabackup_pub_key:
           enabled: true
           key: key

 .. note:: Parameters in ``backup_times`` section can be used to set up exact
    time the cron job should be executed. In this example, the backup job
    would be executed every Sunday at 4:52 AM. If any of the individual
    ``backup_times`` parameters is not defined, the defalut ``*`` value will
    be used. For example, if minute parameter is ``*``, it will run the backup
    every minute, which is ususally not desired.

    See the crontab reference for further info on how to set these parameters.

 .. note:: Please be aware that only ``backup_times`` section OR
    ``hours_before_full(incr)`` can be defined. If both are defined. The
    ``backup_times`` section will be peferred.

 .. note:: New parameter ``incr_before_full`` needs to be defined. This
    number sets number of incremental backups to be run, before a full backup
    is performed.

 Client restore from local backups:

 .. code-block:: yaml

     xtrabackup:
       client:
         enabled: true
         full_backups_to_keep: 5
         hours_before_full: 48
         hours_before_incr: 12
         restore_full_latest: 1
         restore_from: local
         compression: true
         rsync_tables: true
         compressThreads: 2
         database:
           user: username
           password: password
         target:
           host: cfg01
         qpress:
           source: tar
           name: url

 .. note:: restore_full_latest param with a value of 1 means to restore
    db from the last full backup and its increments. 2 would mean to
    restore second latest full backup and its increments

 Client restore from remote backups:

 .. code-block:: yaml

     xtrabackup:
       client:
         enabled: true
         full_backups_to_keep: 5
         hours_before_full: 48
         hours_before_incr: 12
         restore_full_latest: 1
         restore_from: remote
         compression: true
         rsync_tables: true
         compressThreads: 2
         force_non_empty_directories: true
         database:
           user: username
           password: password
         target:
           host: cfg01
         qpress:
           source: tar
           name: url

 .. note:: The ``restore_full_latest`` parameter with a value of 1
    means to restore db from the last full backup and its increments.
    2 would mean to restore second latest full backup and its increments

 Read more
 =========

 * https://labs.riseup.net/code/projects/xtrabackup/wiki/Configuration
 * http://www.debian-administration.org/articles/351
 * http://duncanlock.net/blog/2013/08/27/comprehensive-linux-backups-with-etckeeper-xtrabackup/
 * https://github.com/riseuplabs/puppet-xtrabackup
 * http://www.ushills.co.uk/2008/02/backup-with-xtrabackup.html

	===================
	Usage
	===================

	Xtrabackup allows you to backup and restore databases from full
	backups or full backups and its incrementals.

	Sample pillars
	==============

	Backup client with ssh/rsync remote host:

	.. code-block:: yaml

	xtrabackup:
	client:
	enabled: true
	full_backups_to_keep: 3
	hours_before_full: 48
	hours_before_incr: 12
	database:
	user: username
	password: password
	target:
	host: cfg01

	.. note:: The ``full_backups_to_keep`` parameter states how many backup will
	be stored locally on xtrabackup client. More options to relocate local
	backups can be done using ``salt-formula-backupninja``.

	Backup client using DB API instead of socket (still needs to be run on the same server as DB):

	.. code-block:: yaml

	xtrabackup:
	client:
	enabled: true
	full_backups_to_keep: 3
	hours_before_full: 48
	hours_before_incr: 12
	database:
	user: username
	password: password
	host: localhost
	port: 3306
	target:
	host: cfg01

	.. note:: DB user ``username`` must have "RELOAD" and "REPLICATION CLIENT"
	privileges on all databases.

	Backup client with local backup only:

	.. code-block:: yaml

	xtrabackup:
	client:
	enabled: true
	full_backups_to_keep: 3
	hours_before_full: 48
	hours_before_incr: 12
	database:
	user: username
	password: password

	.. note:: The ``full_backups_to_keep`` parameter states how many backup will
	be stored locally on xtrabackup client.

	Backup client with ssh/rsync to remote host with compression, IO throttling and non-default
	backup directory on server:

	.. code-block:: yaml

	xtrabackup:
	client:
	enabled: true
	full_backups_to_keep: 3
	hours_before_full: 48
	hours_before_incr: 12
	compression: true
	rsync_tables: true
	compression_threads: 2
	throttle: 20
	database:
	user: username
	password: password
	target:
	host: cfg01
	server:
	enabled: false
	backup_dir: /srv/backup

	.. note:: More options to relocate local backups can be done using
	``salt-formula-backupninja``.

	.. note:: If the ``server`` section is ommited, backups will be made to
	default location, same on both client and server side.

	Backup client at exact times:

	.. code-block:: yaml

	xtrabackup:
	client:
	enabled: true
	full_backups_to_keep: 3
	incr_before_full: 3
	backup_dir: /var/backups/mysql/xtrabackup
	backup_times:
	day_of_week: 0
	hour: 4
	minute: 52
	compression: true
	rsync_tables: true
	compression_threads: 2
	database:
	user: user
	password: password
	target:
	host: host01

	.. note:: Parameters in ``backup_times`` section can be used to set up exact
	time the cron job should be executed. In this example, the backup job
	would be executed every Sunday at 4:52 AM. If any of the individual
	``backup_times`` parameters is not defined, the defalut ``*`` value will
	be used. For example, if minute parameter is ``*``, it will run the backup
	every minute, which is ususally not desired.

	Available parameters include:

	* ``day_of_week``
	* ``day_of_month``
	* ``month``
	* ``hour``
	* ``minute``.

	See the crontab reference for further info on how to set these
	parameters.

	.. note:: Please be aware that only ``backup_times`` section OR
	``hours_before_full(incr)`` can be defined. If both are defined. The
	``backup_times`` section will be peferred.

	.. note:: New parameter ``incr_before_full`` needs to be defined. This
	number sets number of incremental backups to be run, before a full backup
	is performed.

	Backup server rsync and non-default backup directory:

	.. code-block:: yaml

	xtrabackup:
	server:
	enabled: true
	hours_before_full: 48
	full_backups_to_keep: 5
	key:
	xtrabackup_pub_key:
	enabled: true
	key: key
	backup_dir: /srv/backup

	.. note:: The ``hours_before_full`` parameter should have the same value as
	is stated on xtrabackup client

	.. note:: If the ``backup_dir`` argument is ommited backups will be made to
	default location, same on both client and server side.

	Backup server without strict client restriction:

	.. code-block:: yaml

	xtrabackup:
	server:
	restrict_clients: false

	Backup server at exact times:

	.. code-block:: yaml

	xtrabackup:
	server:
	enabled: true
	full_backups_to_keep: 3
	incr_before_full: 3
	backup_dir: /srv/backup
	backup_times:
	day_of_week: 0
	hour: 4
	minute: 52
	key:
	xtrabackup_pub_key:
	enabled: true
	key: key

	.. note:: Parameters in ``backup_times`` section can be used to set up exact
	time the cron job should be executed. In this example, the backup job
	would be executed every Sunday at 4:52 AM. If any of the individual
	``backup_times`` parameters is not defined, the defalut ``*`` value will
	be used. For example, if minute parameter is ``*``, it will run the backup
	every minute, which is ususally not desired.

	See the crontab reference for further info on how to set these parameters.

	.. note:: Please be aware that only ``backup_times`` section OR
	``hours_before_full(incr)`` can be defined. If both are defined. The
	``backup_times`` section will be peferred.

	.. note:: New parameter ``incr_before_full`` needs to be defined. This
	number sets number of incremental backups to be run, before a full backup
	is performed.

	Client restore from local backups:

	.. code-block:: yaml

	xtrabackup:
	client:
	enabled: true
	full_backups_to_keep: 5
	hours_before_full: 48
	hours_before_incr: 12
	restore_full_latest: 1
	restore_from: local
	compression: true
	rsync_tables: true
	compressThreads: 2
	database:
	user: username
	password: password
	target:
	host: cfg01
	qpress:
	source: tar
	name: url

	.. note:: restore_full_latest param with a value of 1 means to restore
	db from the last full backup and its increments. 2 would mean to
	restore second latest full backup and its increments

	Client restore from remote backups:

	.. code-block:: yaml

	xtrabackup:
	client:
	enabled: true
	full_backups_to_keep: 5
	hours_before_full: 48
	hours_before_incr: 12
	restore_full_latest: 1
	restore_from: remote
	compression: true
	rsync_tables: true
	compressThreads: 2
	force_non_empty_directories: true
	database:
	user: username
	password: password
	target:
	host: cfg01
	qpress:
	source: tar
	name: url

	.. note:: The ``restore_full_latest`` parameter with a value of 1
	means to restore db from the last full backup and its increments.
	2 would mean to restore second latest full backup and its increments

	Read more
	=========

	* https://labs.riseup.net/code/projects/xtrabackup/wiki/Configuration
	* http://www.debian-administration.org/articles/351
	* http://duncanlock.net/blog/2013/08/27/comprehensive-linux-backups-with-etckeeper-xtrabackup/
	* https://github.com/riseuplabs/puppet-xtrabackup
	* http://www.ushills.co.uk/2008/02/backup-with-xtrabackup.html