SSL for State Snapshot Transfers

When you finish generating the SSL certificates for your cluster, you can begin configuring the node for their use. Where SSL Configuration covers how to enable SSL for replication traffic and the database client, this page covers enabling it for State Snapshot Transfer scripts.

The particular method you use to secure the State Snapshot Transfer through SSL depends upon the method you use in state snapshot transfers: mysqldump, clone, rsync or xtrabackup.


For Gelera Cluster, SSL configurations are not dynamic. Since they must be set on every node in the cluster, if you want to enable this feature with an existing cluster you need to restart the entire cluster.

Enabling SSL for mysqldump

The procedure for securing mysqldump is fairly similar to that of securing the database server and client through SSL. Given that mysqldump connects through the database client, you can use the same SSL certificates you created for replication traffic.

Before you shut down the cluster, you need to create a user for mysqldump on the database server and grant it privileges through the cluster. This ensures that when the cluster comes back up, the nodes have the correct privileges to execute the incoming state snapshot transfers. In the event that you use the Total Order Isolation online schema upgrade method, you only need to execute the following commands on a single node.

  1. From the database client, check that you use Total Order Isolation for online schema upgrades.

    SHOW VARIABLES LIKE 'wsrep_OSU_method';
    | Variable_name    | Value |
    | wsrep_OSU_method | TOI   |

    If wsrep_OSU_method is set to Rolling Schema Upgrade, or ROI, then you need to execute the following commands on each node individually.

  2. Create a user for mysqldump.

    CREATE USER 'sst_user'@'%' IDENTIFIED BY PASSWORD 'sst_password';

    Bear in mind that, due to the manner in which the SST script is called, the user name and password must be the same on all nodes.

  3. Grant privileges to this user and require SSL.

    GRANT ALL ON *.* TO 'sst_user'@'%' REQUIRE SSL;
  4. From the database client on a different node, check to ensure that the user has replicated to the cluster.

    SELECT User, Host, ssl_type
    FROM mysql.user WHERE User='sst_user';
    | User     | Host | ssl_type |
    | sst_user | %    | Any      |

This configures and enables the mysqldump user for the cluster.


In the event that you find, wsrep_OSU_method set to ROI, you need to manually create the user on each node in the cluster. For more information on rolling schema upgrades, see Schema Upgrades.

With the user now on every node, you can shut the cluster down to enable SSL for mysqldump State Snapshot Transfers.

  1. Using your preferred text editor, update the my.cnf configuration file to define the parameters the node requires to secure state snapshot transfers.

    # MySQL Server
    ssl-ca = /path/to/ca-cert.pem
    ssl-key = /path/to/server-key.pem
    ssl-cert = /path/to/server-cert.pem
    # MySQL Client Configuration
    ssl-ca = /path/to/ca-cert.pem
    ssl-key = /path/to/client-key.pem
    ssl-cert = /path/to/client-cert.pem
  2. Additionally, configure wsrep_sst_auth with the SST user authentication information.

    # mysqldump SST auth
    wsrep_sst_auth = sst_user:sst_password

This configures the node to use mysqldump for state snapshot transfers over SSL. When all nodes are updated to SSL, you can begin restarting the cluster. For more information on how to do this, see Starting a Cluster.

Enabling SSL for clone based SST

Configurations for clone are handled through the my.cnf configuration file, in the same manner as for mysqldump-based SST above. You can use the same SSL certificate files as the node uses on the database server, client and with replication traffic.

# clone Configuration
ssl-cert= /path/to/server-cert.pem
ssl-key= /path/to/server-key.pem
ssl-ca= /path/to/ca.pem

[client] # or [sst]
ssl-cert= /path/to/client-cert.pem
ssl-key= /path/to/client-key.pem
ssl-ca= /path/to/ca.pem
ssl-mode= VERIFY_CA

Client SSL configuration on Donor Node must match server SSL configuration on Joiner. (That means: mysql client using client SSL configuration from Joiner should be able to connect to server on Donor) Client SSL configuration on Joiner must match CLONE SSL configuration on donor. If CLONE plugin on Donor is not loaded, or if CLONE SSL configuration is empty then server SSL configuration on Donor is used.

If for some reason general client SSL configuration is undesirable, client SSL configuration for clone SST can be put into the [sst] section of the configuration file. It will be used first.

Enabling SSL for xtrabackup and rsync based SSTs

The Physical State Transfer Method for state snapshot transfers, uses an external script to copy the physical data directly from the file system on one cluster node into another. Before releases 5.7.34 and 8.0.25 only xtrabackup-v2 SST supported SSL encryption and required custom configuration. Starting with releases 5.7.34 and 8.0.25 both rsync and xtrabackup-v2 scripts can use the standard MySQL SSL configuration and will use it BY DEFAULT.

New way SSL configuration for xtrabackup-v2 and rsync SSTs (releases 5.7.34 and 8.0.25 or newer)

If [mysqld] or [server] section of the configuration contains

ssl-cert= /path/to/server-cert.pem
ssl-key= /path/to/server-key.pem
ssl-ca= /path/to/ca.pem

those credentials will be automatically used for SSL encryption of SST unless explicitly overridden with the same parameters in [sst] section.

For backward compatibility no peer/CA authentication is performed unless explicitly requested in the [sst] section of the configuration using the standard ssl-mode option:




This is a backward incompatible option and should be used only on fully upgraded clusters.


disables SSL encryption for SST regardless server SSL settings

Old way SSL configuration for xtrabackup-v2 SST

This is deprecated, but for backward compatibility takes precedence if present.

Configurations for xtrabackup-v2 script are handled through the my.cnf configuration file, in the same as the database server and client. Use the [sst] unit to configure SSL for the script. You can use the same SSL certificate files as the node uses on the database server, client and with replication traffic.

# xtrabackup Configuration
encrypt = 3
tca = /path/to/ca.pem
tkey = /path/to/key.pem
tcert = /path/to/cert.pem

When you finish editing the configuration file, restart the node to apply the changes. xtrabackup now sends and receives state snapshot transfers through SSL.


In order to use SSL with xtrabackup, you need to set wsrep_sst_method to xtrabackup-v2, instead of xtrabackup.