diff --git a/docs/store-backup-history.md b/docs/store-backup-history.md index 6d2e9b8c..c5961dff 100644 --- a/docs/store-backup-history.md +++ b/docs/store-backup-history.md @@ -40,7 +40,96 @@ some catastrophic event, you will need to either perform a `mysqldump`, partial backup or `SELECT` \* on the history table after *xtrabackup* completes and store the results with you backup set. -For the necessary privileges, see Permissions and Privileges Needed. +For the necessary privileges, see [Permissions and Privileges Needed](privileges.md). + +## Store backup history on a different server + +### Version changes + +Percona XtraBackup 9.7.2-2 introduces the ability to store backup history on a different server. + +### Overview + +By default, Percona XtraBackup writes the history record to the server you back up. The write fails if that server does not accept writes, for example, a replica or a secondary member of a single-primary Group Replication cluster with `super_read_only` enabled. In this case, the server returns error 1290 and does not store the record. + +To write the history record to another, writeable server, use the below options to describe the connections parameters of the server: + +| Option | Description | Default | +| ------ | ----------- | ------- | +| [`--history-host`](xtrabackup-option-reference.md#history-host) | Host of the history server | Value of `--host` | +| [`--history-port`](xtrabackup-option-reference.md#history-port) | TCP/IP port of the history server | Value of `--port` | +| [`--history-socket`](xtrabackup-option-reference.md#history-socket) | UNIX socket of the history server | Value of `--socket`, if you do not set `--history-host` | +| [`--history-user`](xtrabackup-option-reference.md#history-user) | User account on the history server | Value of `--user` | +| [`--history-password`](xtrabackup-option-reference.md#history-password) | Password of the history user | Value of `--password`, if you do not set `--history-user` | +| [`--history-ssl-mode`](xtrabackup-option-reference.md#history-ssl-mode) | Security state of the connection | Value of `--ssl-mode` | +| [`--history-ssl-ca`](xtrabackup-option-reference.md#history-ssl-ca) | CA file in PEM format | Value of `--ssl-ca` | +| [`--history-ssl-capath`](xtrabackup-option-reference.md#history-ssl-capath) | Directory of CA certificates | Value of `--ssl-capath` | +| [`--history-ssl-cert`](xtrabackup-option-reference.md#history-ssl-cert) | X509 certificate in PEM format | Value of `--ssl-cert` | +| [`--history-ssl-key`](xtrabackup-option-reference.md#history-ssl-key) | X509 key in PEM format | Value of `--ssl-key` | + +If you do not set an option, Percona XtraBackup takes the value of the matching connection option for the server you back up, with the following exceptions: + +* If you set `--history-host`, Percona XtraBackup ignores the `--socket` value, because that socket belongs to the server you back up. + +* If you set `--history-user`, Percona XtraBackup ignores the `--password` value. Set `--history-password` for the history user. + +* Percona XtraBackup treats the `--history-ssl-*` options as a group. If you set any of these options, Percona XtraBackup uses only the `--history-ssl-*` values and ignores all `--ssl-*` values for the history connection. + +* If you set `--history-ssl-ca` or `--history-ssl-capath` without `--history-ssl-mode`, Percona XtraBackup uses the `VERIFY_CA` SSL mode for the history connection. + +The following example backs up a read-only replica and stores the history record on the source server: + +```bash +xtrabackup --backup --target-dir=/backups/full \ + --user=bkpuser --password= --socket=/var/run/mysqld/mysqld.sock \ + --history=nightly \ + --history-host=source.example.com --history-port=3306 \ + --history-user=history_user --history-password= +``` + +Percona XtraBackup uses the history server only to store and read the history record. Percona XtraBackup runs all other backup operations, such as locks and redo log copying, on the server you back up. + +The [`--incremental-history-name`](xtrabackup-option-reference.md#incremental-history-name) and [`--incremental-history-uuid`](xtrabackup-option-reference.md#incremental-history-uuid) options also read from the history server. For incremental backups, pass the same `--history-*` options so that Percona XtraBackup reads the base LSN from the server that stores the records: + +```bash +xtrabackup --backup --incremental --target-dir=/backups/inc1 \ + --user=bkpuser --password= --socket=/var/run/mysqld/mysqld.sock \ + --incremental-history-name=nightly \ + --history-host=source.example.com --history-port=3306 \ + --history-user=history_user --history-password= +``` + +### Requirements and behavior + +* The `--history-*` options require [`--history`](xtrabackup-option-reference.md#history), [`--incremental-history-name`](xtrabackup-option-reference.md#incremental-history-name), or [`--incremental-history-uuid`](xtrabackup-option-reference.md#incremental-history-uuid). If you set a `--history-*` option without any of these options, Percona XtraBackup reports an error and does not start the backup. + +* Percona XtraBackup connects to the history server when the backup starts. If the connection fails, Percona XtraBackup stops the backup before copying any data. + +* If Percona XtraBackup cannot apply the TLS settings to the history connection, Percona XtraBackup does not connect to the history server. + +* If you set `--history-ssl-ca` or `--history-ssl-capath` and set `--history-ssl-mode` lower than `VERIFY_CA`, Percona XtraBackup prints a warning that the certificate of the history server remains unverified. + +* Percona XtraBackup hides the `--history-password` value in the same way as the `--password` value: in the process list, in the log, and in the `tool_command` column of the history record. + +### History server privileges + +If you store the backup history on a different server with the `--history-*` options, Percona XtraBackup checks the `CREATE`, `ALTER`, `INSERT`, and `SELECT` privileges on `PERCONA_SCHEMA` for the history user on the history server, not for the backup user. The backup user does not need these privileges. + +The history user needs the following privileges on the history server: + +* `CREATE`, `ALTER`, and `INSERT` on `PERCONA_SCHEMA` to use `--history`. The history user needs the `CREATE` privilege even if the `PERCONA_SCHEMA.xtrabackup_history` table already exists. + +* `SELECT` on `PERCONA_SCHEMA.xtrabackup_history` to use `--incremental-history-name` or `--incremental-history-uuid`. + +* `SELECT` on `performance_schema.replication_group_members`. + +To create a history user with the minimum privileges, run the following statements on the history server: + +```sql +CREATE USER 'history_user'@'%' IDENTIFIED BY ''; +GRANT CREATE, ALTER, INSERT, SELECT ON PERCONA_SCHEMA.* TO 'history_user'@'%'; +GRANT SELECT ON performance_schema.replication_group_members TO 'history_user'@'%'; +``` ### PERCONA_SCHEMA.XTRABACKUP_HISTORY table @@ -53,7 +142,7 @@ taken with `--history` option. | uuid | Unique backup id | | name | User provided name of backup series. There may be multiple entries with the same name used to identify related backups in a series. | | tool_name | Name of tool used to take backup | -| tool_command | Exact command line given to the tool with --password and --encryption_key obfuscated | +| tool_command | Exact command line given to the tool, with the --password, --history-password, and --encryption_key values hidden | | tool_version | Version of tool used to take backup | | ibbackup_version | Version of the xtrabackup binary used to take backup | | server_version | Server version on which backup was taken | diff --git a/docs/xtrabackup-option-reference.md b/docs/xtrabackup-option-reference.md index 034d8e67..8c492d07 100644 --- a/docs/xtrabackup-option-reference.md +++ b/docs/xtrabackup-option-reference.md @@ -491,6 +491,104 @@ Usage: `--history=NAME` This option enables the tracking of backup history in the `PERCONA_SCHEMA.xtrabackup_history` table. You can specify a history series name placed with the current backup's history record. +By default, Percona XtraBackup writes the history record to the server you back up. To write the record to a different server, use the `--history-*` options. See [Store backup history on a different server](store-backup-history.md#store-backup-history-on-a-different-server). + +### history-host + +Usage: `--history-host=HOST` + +Introduced in Percona XtraBackup 9.7.2-2. + +This option specifies the host of the server that stores the backup history table. Use this option when the server you back up does not accept writes, for example, a read-only replica. The default value is the value of [`--host`](#host). + +If you set this option, Percona XtraBackup ignores the [`--socket`](#socket) value for the history connection. + +This option requires [`--history`](#history), [`--incremental-history-name`](#incremental-history-name), or [`--incremental-history-uuid`](#incremental-history-uuid). + +### history-password + +Usage: `--history-password=PASSWORD` + +Introduced in Percona XtraBackup 9.7.2-2. + +This option specifies the password of the user that connects to the server that stores the backup history table. The default value is the value of [`--password`](#password). If you set [`--history-user`](#history-user), Percona XtraBackup ignores the `--password` value, and you must set this option. + +Percona XtraBackup hides this value in the process list, in the log, and in the history record. + +### history-port + +Usage: `--history-port=PORT` + +Introduced in Percona XtraBackup 9.7.2-2. + +This option specifies the TCP/IP port of the server that stores the backup history table. The default value is the value of [`--port`](#port). + +### history-socket + +Usage: `--history-socket=SOCKET` + +Introduced in Percona XtraBackup 9.7.2-2. + +This option specifies the UNIX domain socket of the server that stores the backup history table. If you do not set [`--history-host`](#history-host), the default value is the value of [`--socket`](#socket). + +### history-ssl-ca + +Usage: `--history-ssl-ca=FILE` + +Introduced in Percona XtraBackup 9.7.2-2. + +This option specifies the CA file in PEM format that Percona XtraBackup uses to verify the certificate of the server that stores the backup history table. + +If you set this option without [`--history-ssl-mode`](#history-ssl-mode), Percona XtraBackup uses the `VERIFY_CA` SSL mode for the history connection. + +### history-ssl-capath + +Usage: `--history-ssl-capath=DIRECTORY` + +Introduced in Percona XtraBackup 9.7.2-2. + +This option specifies the directory of CA certificates that Percona XtraBackup uses to verify the certificate of the server that stores the backup history table. + +If you set this option without [`--history-ssl-mode`](#history-ssl-mode), Percona XtraBackup uses the `VERIFY_CA` SSL mode for the history connection. + +### history-ssl-cert + +Usage: `--history-ssl-cert=FILE` + +Introduced in Percona XtraBackup 9.7.2-2. + +This option specifies the X509 certificate in PEM format that Percona XtraBackup presents to the server that stores the backup history table. + +### history-ssl-key + +Usage: `--history-ssl-key=FILE` + +Introduced in Percona XtraBackup 9.7.2-2. + +This option specifies the X509 key in PEM format for [`--history-ssl-cert`](#history-ssl-cert). + +Percona XtraBackup treats the `--history-ssl-*` options as a group. If you set any of these options, Percona XtraBackup takes all five values from the `--history-ssl-*` options and ignores the [`--ssl-*`](#ssl-mode) values for the history connection. + +### history-ssl-mode + +Usage: `--history-ssl-mode=MODE` + +Introduced in Percona XtraBackup 9.7.2-2. + +This option specifies the security state of the connection to the server that stores the backup history table. This option accepts the same values as [`--ssl-mode`](#ssl-mode). The default value is the value of `--ssl-mode`. + +If you set [`--history-ssl-ca`](#history-ssl-ca) or [`--history-ssl-capath`](#history-ssl-capath) without this option, Percona XtraBackup uses the `VERIFY_CA` mode. + +### history-user + +Usage: `--history-user=USERNAME` + +Introduced in Percona XtraBackup 9.7.2-2. + +This option specifies the user that connects to the server that stores the backup history table. The default value is the value of [`--user`](#user). + +If you set this option, Percona XtraBackup ignores the [`--password`](#password) value. Set [`--history-password`](#history-password). + ### host Usage: `--host=HOST`