The Library

• Documentation

• Knowledge Base
• Training

• Training Courses
• Tutorial Articles
• Training Videos

• FAQ
• Search Page

• Home

• Docs

• KB

• Training

• FAQ

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