XtraBackup Parameters¶
When using xtrabackup-v2
as your State Snapshot Transfer method, you can fine tune how the script operates using the [sst]
unit in the my.cnf
configuration file.
[mysqld]
wsrep_sst_method=xtrabackup-v2
[sst]
compressor="gzip"
decompressor="gzip -dc"
rebuild=ON
compact=ON
encrypt=3
tkey="/path/to/key.pem"
tcert="/path/to/cert.pem"
tca="/path/to/ca.pem"
Bear in mind, some XtraBackup parameters require that you match the configuration on donor and joiner nodes, (as designated in the table below).
Option | Default | Match |
---|---|---|
compressor | ||
cpat | 0 |
|
decompressor | ||
encrypt | 0 |
Yes |
encrypt-algo | ||
progress | ||
rebuild | 0 |
|
rlimit | ||
sst_special_dirs | 1 |
|
sockopt | ||
streamfmt | xbstream |
Yes |
tca | ||
tcert | ||
time | 0 |
|
transferfmt | socat |
Yes |
joiner_timeout | 60 |
|
donor_timeout | 10 |
compressor
Defines the compression utility the Donor Node uses to compress the state transfer.
System Variable | Name: | compressor |
---|---|---|
Match: | Yes | |
Permitted Values | Type: | String |
Default Value: |
This parameter defines whether the donor node performs compression on the state transfer stream. It also defines what compression utility it uses to perform the operation. You can use any compression utility which works on a stream, such as gzip
or pigz
. Given that the Joiner Node must decompress the state transfer before attempting to read it, you must match this parameter with the decompressor parameter, using the appropriate flags for each.
compression="gzip"
compact
Defines whether the joiner node performs compaction when rebuilding indexes after applying a State Snapshot Transfer.
System Variable | Name: | compact |
---|---|---|
Match: | No | |
Permitted Values | Type: | Boolean |
Default Value: | OFF |
This parameter operates on the joiner node with the rebuild parameter. When enabled, the node performs compaction when rebuilding indexes after applying a state transfer.
rebuild=ON
compact=ON
cpat
Defines what files to clean up from the datadir during state transfers.
System Variable | Name: | cpat |
---|---|---|
Match: | No | |
Permitted Values | Type: | String |
Default Value: |
When the donor node begins a State Snapshot Transfer, it cleans up various files from the datadir. This ensures that the joiner node can cleanly apply the state transfer. With this parameter, you can define what files you want the node to delete before the state transfer.
cpat=".*glaera\.cache$\|.*sst_in_progress$\|.*grastate\.dat$\|.*\.err"
decompressor
Defines the decompression utility the joiner node uses to decompress the state transfer.
System Variable | Name: | decompressor |
---|---|---|
Match: | No | |
Permitted Values | Type: | String |
Default Value: |
This parameter defines whether the joiner node performs decompression on the state transfer stream. It also defines what decompression utility it uses to perform the operation. You can use any compression utility which works on a stream, such as gzip
or pigz
. Given that the donor node must compress the state transfer before sending it, you must match this parameter with the compressor parameter, using the appropriate flags for each.
decompressor="gzip -dc"
encrypt
Defines whether the node uses SSL encryption for XtraBackup and what kind of encryption it uses.
System Variable | Name: | encrypt |
---|---|---|
Match: | Yes | |
Permitted Values | Type: | Integer |
Default Value: | 0 |
This parameter determines the type of SSL encryption the node uses when sending state transfers through xtrabackup. The recommended type is 2
when using the cluster over WAN.
Value | Description |
---|---|
0 |
No encryption. |
1 |
The node encrypts State Snapshot Transfers through XtraBackup. |
2 |
The node encrypts State Snapshot Transfers through OpenSSL, using Socat. |
3 |
The node encrypts State Snapshot Transfers through the key and certificate files implemented for Galera Cluster. |
encrypt=3
tkey="/path/to/key.pem"
tcert="/path/to/cert.pem"
tca="/path/to/ca.pem"
encrypt-algo
Defines the SSL encryption type the node uses for XtraBackup state transfers.
System Variable | Name: | encrypt-algo |
---|---|---|
Match: | No | |
Permitted Values | Type: | Integer |
Default Value: | 0 |
When using the encrypt parameter in both the [xtrabackup]
and [sst]
units, there is a potential issue in it having different meanings according to the unit under which it occurs. That is, in [xtrabackup]
, it turns encryption on while in [sst]
it both turns it on as specifies the algorithm.
In the event that you need to clarify the meaning, this parameter allows you to define the encryption algorithm separately from turning encryption on. It is only read in the event that encrypt is set to 1
encrypt=1
encrypt-algo=3
progress
Defines whether where the node reports State Snapshot Transfer progress.
System Variable | Name: | progress |
---|---|---|
Match: | No | |
Permitted Values | Type: | String |
Default Value: | ||
Valid Values: | 1 ; /path/to/file |
When you set this parameter, the node reports progress on XtraBackup progress in state transfers. If you set the value to 1
, the node makes these reports to the database server stderr. If you set the value to a file path, it writes the progress to that file.
Note
Keep in mind, that a 0
value is invalid. If you want to disable this parameter, delete or comment it out.
progress="/var/log/mysql/xtrabackup-progress.log"
rebuild
Defines whether the joiner node rebuilds indexes during a State Snapshot Transfer.
System Variable | Name: | rebuild |
---|---|---|
Match: | No | |
Permitted Values | Type: | Boolean |
Default Value: | OFF |
This parameter operates on the joiner node. When enabled, the node rebuilds indexes when applying the state transfer. Bear in mind, this operation is separate from compaction. Due to Bug #1192834, it is recommended that you use this parameter with compact.
rebuild=ON
compact=ON
rlimit
Defines the rate limit for the donor node.
System Variable | Name: | rlimit |
---|---|---|
Match: | No | |
Permitted Values | Type: | Integer |
Default Value: |
This parameter allows you to definite the rate-limit the donor node. This allows you to keep state transfers from blocking regular cluster operations.
rlimit=300M
sst_special_dirs
Defines whether the node uses special InnoDB home and log directories.
System Variable | Name: | sst_special_dirs |
---|---|---|
Match: | No | |
Permitted Values | Type: | Boolean |
Default Value: | OFF |
This parameter enables support for innodb_data_home_dir
and innodb_log_home_dir
parameters for XtraBackup. It requires that you define innodb_data_home_dir
and innodb_log_group_home_dir
in the [mysqld]
unit.
[mysqld]
innodb_data_home_dir="/var/mysqld/innodb"
innodb_log_group_home_dir="/var/log/innodb"
wsrep_sst_method="xtrabackup-v2"
[sst]
sst_special_dirs=TRUE
sockopt
Defines socket options.
System Variable | Name: | sockopt |
---|---|---|
Match: | No | |
Permitted Values | Type: | String |
Default Value: |
This parameter allows you to define one or more socket options for XtraBackup using the Socat transfer format.
streamfmt
Defines the stream formatting utility.
System Variable | Name: | streamfmt |
---|---|---|
Match: | Yes | |
Permitted Values | Type: | String |
Default Value: | xbstream |
|
Valid Values: | tar ; xbstream |
This parameter defines the utility the node uses to archive the node state before the transfer is sent and how to unarchive the state transfers that is receives. There are two methods available: tar
and xbstream
. Given that the receiving node needs to know how to read the stream, it is necessary that both nodes use the same values for this parameter.
The default and recommended utility is xbstream
given that it supports encryption, compression, parallel streaming, incremental backups and compaction. tar
does not support these features.
streamfmt='xbstream'
tca
Defines the Certificate Authority (CA) to use in SSL encryption.
System Variable | Name: | tca |
---|---|---|
Match: | No | |
Permitted Values | Type: | Path |
Default Value: |
This parameter defines the Certificate Authority (CA) file that the node uses with XtraBackup state transfers. In order to use SSL encryption with XtraBackup, you must configure the transferfmt parameter to use socat
.
For more information on using Socat with encryption, see Securing Traffic between Two Socat Instances using SSL.
transferfmt="socat"
tca="/path/to/ca.pem"
tcert
Defines the certificate to use in SSL encryption.
System Variable | Name: | tcert |
---|---|---|
Match: | No | |
Permitted Values | Type: | String |
Default Value: |
This parameter defines the SSL certificate file that the node uses with SSL encryption on XtraBackup state transfers. In order to use SSL encryption with XtraBackup, you must configure the transferfmt parameter to use Socat.
For more information on using Socat with encryption, see Securing Traffic between Two Socat Instances using SSL.
transferfmt="socat"
tcert="/path/to/cert.pem"
time
Defines whether XtraBackup instruments key stages in the backup and restore process for state transfers.
System Variable | Name: | time |
---|---|---|
Match: | No | |
Permitted Values | Type: | Boolean |
Default Value: | OFF |
This parameter instruments key stages of the backup and restore process for state transfers.
time=ON
transferfmt
Defines the transfer stream utility.
System Variable | Name: | transferfmt |
---|---|---|
Match: | YesNo” | |
Permitted Values | Type: | String |
Default Value: | socat |
|
Valid Values: | socat ; nc |
This parameter defines the utility that the node uses to format transfers sent from donor to joiner nodes. There are two methods supported: Socat and nc
. Given that the receiving node needs to know how to interpret the transfer, it is necessary that both nodes use the same values for this parameter.
The default and recommended utility is Socat, given that it allows for socket options, such as transfer buffer size. For more information, see the socat Documentation.
transferfmt="socat"
joiner_timeout
How soon joiner should timeout waiting for SST (seconds).
System Variable | Name: | joiner_timeout |
---|---|---|
Match: | No | |
Permitted Values | Type: | Integer |
Default Value: | 60 |
This parameter determines the initial timeout in seconds for the joiner to receive the first packet in a State Snapshot Transfer. This keeps the joiner node from hanging in the event that the donor node crashes while starting the operation.
joiner_timeout=120
donor_timeout
How soon donor should timeout on connection to joiner (seconds).
System Variable | Name: | donor_timeout |
---|---|---|
Match: | No | |
Permitted Values | Type: | Integer |
Default Value: | 10 |
This parameter determines how soon the donor should timeout on connection to joiner and return to normal operation in case the joiner turns to be unresponsive.
donor_timeout=5