From 4c14d41d2ce82851344f6263580ef7a9048da2b1 Mon Sep 17 00:00:00 2001 From: Alina Derkach Date: Thu, 29 Oct 2026 18:16:06 +0100 Subject: [PATCH 1/2] PXB-3910 [DOCS] Document the ability of --history to write its record to another server (9.7) modified: docs/store-backup-history.md modified: docs/xtrabackup-option-reference.md --- docs/store-backup-history.md | 93 ++++++++++++++++++++++++++- docs/xtrabackup-option-reference.md | 98 +++++++++++++++++++++++++++++ 2 files changed, 189 insertions(+), 2 deletions(-) diff --git a/docs/store-backup-history.md b/docs/store-backup-history.md index 6d2e9b8c1..a05835ceb 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 `--history-*` options to store the 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, writable server, add one or more `--history-*` options that describe the connection to that 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 034d8e678..8c492d07a 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` From 117bbbe728c6be8efb7637fd9c4b6826b3802aff Mon Sep 17 00:00:00 2001 From: Alina Derkach Date: Tue, 3 Nov 2026 18:40:59 +0100 Subject: [PATCH 2/2] Fixes after the review --- docs/store-backup-history.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/store-backup-history.md b/docs/store-backup-history.md index a05835ceb..c5961dff3 100644 --- a/docs/store-backup-history.md +++ b/docs/store-backup-history.md @@ -46,13 +46,13 @@ For the necessary privileges, see [Permissions and Privileges Needed](privileges ### Version changes -Percona XtraBackup 9.7.2-2 introduces the `--history-*` options to store the backup history on a different server. +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, writable server, add one or more `--history-*` options that describe the connection to that server: +To write the history record to another, writeable server, use the below options to describe the connections parameters of the server: | Option | Description | Default | | ------ | ----------- | ------- |