Configure MariaDB Galera SST with wsrep_sst_rsync

A new Galera node comes up empty and needs the whole dataset before it can join: wsrep_sst_rsync is the default script that copies it across. This guide sets the method, checks the prerequisites, and verifies the setting without triggering an accidental transfer.

• Time: about 20 minutes for checks and configuration, plus however long a real datadir copy takes.
• You need: root access for package and MariaDB configuration checks, two Galera nodes that can reach each other, and a maintenance window.
• Version: the operational detail here is tied to the MariaDB 10.11 script installed on this machine; the manpage itself just calls it an rsync-based SST.

1. Confirm the installed components

Check the command, MariaDB package version, and rsync version. These are ordinary read-only commands:

$ command -v wsrep_sst_rsync
/usr/bin/wsrep_sst_rsync
$ dpkg-query -W -f='${Package} ${Version}\n' mariadb-server
mariadb-server 1:10.11.14-0ubuntu0.24.04.1
$ rsync --version | head -2
rsync  version 3.2.7  protocol version 31

• One script, two names. The local package also installs /usr/bin/wsrep_sst_rsync_wan as a symlink to the same script; it chooses its transfer mode from the name it was invoked as.
• rsync uses --whole-file, suited to a fast local link.
• rsync_wan leaves delta transfer mode enabled, which can help when the joiner already contains an older datadir.

Do not run wsrep_sst_rsync as a standalone backup command. Galera supplies the role, addresses, datadir and state through its SST interface; invoking it without that environment is not a meaningful test.

2. Check the Galera method and donor choice

On a running MariaDB node, inspect the current method and donor preference. This reads server state and does not start an SST:

$ mariadb -e "SHOW GLOBAL VARIABLES WHERE Variable_name IN ('wsrep_on','wsrep_sst_method','wsrep_sst_donor','wsrep_sst_receive_address');"
+--------------------------+----------------+
| Variable_name            | Value          |
+--------------------------+----------------+
| wsrep_on                 | ON             |
| wsrep_sst_method         | rsync          |
| wsrep_sst_donor          |                |
| wsrep_sst_receive_address| 192.0.2.12:4444|
+--------------------------+----------------+

Your addresses and donor list will differ. The documented default for wsrep_sst_method is rsync, and the variable is dynamic. For a temporary, controlled change on the node that may donate or join, use:

$ sudo mariadb -e "SET GLOBAL wsrep_sst_method='rsync';"
$ mariadb -e "SHOW GLOBAL VARIABLES LIKE 'wsrep_sst_method';"
+------------------+-------+
| Variable_name    | Value |
+------------------+-------+
| wsrep_sst_method | rsync |
+------------------+-------+

For a persistent setting, add the same method to the server option group used by your installation, commonly [mariadb]:

[mariadb]
wsrep_sst_method = rsync

Apply a persistent configuration at the next planned MariaDB restart. If you only change the running value, a later restart can revert it. Keep the method consistent across nodes, because a donor and joiner must be able to use the same SST method.

3. Check the network and datadir boundaries

The joiner supplies the address and port where its temporary rsync daemon listens. The installed script writes a temporary rsync configuration under the MariaDB data area and normally uses port 4444 from the Galera SST settings. Confirm the receive address on every node and check that the intended interface is reachable:

$ mariadb -e "SHOW GLOBAL VARIABLES LIKE 'wsrep_sst_receive_address';"
$ getent hosts donor.example.test
$ nc -vz donor.example.test 4444

The final command is only a reachability check. It may report a refusal when no SST is active, which is expected outside a transfer. Do not expose the port broadly just to make this check pass: restrict it to the cluster addresses with the host firewall, and confirm the change through your normal review process.

The script transfers MariaDB data directories and selected InnoDB, undo, Aria and binary-log state. It is not a general rsync of an arbitrary directory. Both nodes must have compatible MariaDB and storage settings. In particular, MariaDB documents that this SST method does not support tables created with DATA DIRECTORY or INDEX DIRECTORY; use mariadb-backup when that layout is required.

4. Choose local or WAN transfer deliberately

• Use rsync when the nodes have a fast local network and the donor's read lock can be tolerated for the copy. It is the default, and it transfers binary data quickly, but it still blocks the donor with a read lock during the SST.
• Use rsync_wan only when the slower link and an existing joiner datadir justify delta transfers. It is the same underlying script reached through a different name, not an independent method.
• Do not switch names casually during an outage. Test the exact node pair, and make sure the joiner contains a valid, disposable state that can be replaced.

For data in transit, the installed script can use stunnel when SST TLS settings and certificates are configured. Without a deliberate TLS configuration, treat rsync traffic as cluster-internal traffic and protect it with network policy. Do not paste private keys into the MariaDB option file or into shell history.

5. Perform a controlled join and observe the transfer

When the prerequisites pass, start the join through your normal Galera procedure. Do not improvise a direct shell invocation. Watch the MariaDB error log on both nodes and confirm the cluster state from SQL:

$ sudo tail -f /var/log/mysql/error.log
$ mariadb -e "SHOW GLOBAL STATUS WHERE Variable_name IN ('wsrep_local_state_comment','wsrep_cluster_status','wsrep_cluster_size');"
+--------------------------+---------+
| Variable_name            | Value   |
+--------------------------+---------+
| wsrep_local_state_comment| Synced  |
| wsrep_cluster_status     | Primary |
| wsrep_cluster_size       | 3       |
+--------------------------+---------+

Expected SST log messages vary by MariaDB build, but a successful join ends with the new node reaching Synced. A non-zero rsync result, a protocol mismatch, an occupied port, or a missing rsync binary is a failed transfer, not a partial success. Stop sending application traffic to the joining node until its state is Synced.