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