Configure MariaDB Galera SST with wsrep_sst_rsync

You will configure a MariaDB Galera node to use wsrep_sst_rsync for a physical state snapshot transfer, check the prerequisites, and verify the setting without starting an accidental transfer. The installed manpage describes the command only as an rsync-based state snapshot transfer, so the operational detail here is tied to the MariaDB 10.11 script installed on this machine.

Allow about 20 minutes for the checks and configuration, plus the time needed to copy your datadir if a real joiner needs an SST. You need root access for package and MariaDB configuration checks, two Galera nodes that can reach one another, and a maintenance window. An SST is service-impacting: the rsync donor takes a read lock while the snapshot is made, so do not test this by adding a production node during peak traffic.

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

The local package also installs /usr/bin/wsrep_sst_rsync_wan as a symlink to the same script. The script chooses its transfer mode from the name used to invoke it. The normal rsync method uses --whole-file, suited to a fast local link. The rsync_wan name leaves rsync's 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 change the running value only, 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 firewall 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 transfers binary data quickly, but it 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 ensure 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.

If the transfer fails, keep the joiner out of service, preserve the relevant error log, and check rsync versions, reachability, permissions and free space. The script cleans its temporary rsync and stunnel processes on exit, but inspect for leftovers before retrying. Do not delete a datadir as a first troubleshooting step. If you must reinitialise it, treat that as destructive, take a verified backup or snapshot first, and follow your cluster's documented recovery procedure.