Use rsync_wan for a MariaDB Galera SST over a slower link

You will configure a MariaDB Galera node to request the rsync_wan state snapshot transfer method, confirm that MariaDB accepted it, and understand what happens when a joining node needs a full state copy. Allow about 15 minutes for the configuration and verification, plus the time required for the transfer itself.

Before you start

This guide assumes a working Galera cluster, administrative access to its MariaDB configuration, and the mariadb-server package. The local package examined here is MariaDB 10.11.14 on Ubuntu 24.04. The installed manual page describes wsrep_sst_rsync_wan as an rsync-based state snapshot transfer using delta transfers. It is a helper used by the server during an SST, not a general-purpose backup command.

Check both nodes before changing anything. The joiner must be able to reach the donor on the SST address and port selected by the cluster, and rsync must be installed on the participating hosts. A firewall change may require elevated privileges, but the read-only checks below do not.

command -v rsync
sudo mariadb -e "SHOW GLOBAL VARIABLES LIKE 'wsrep_sst_method';"
sudo mariadb -e "SHOW GLOBAL VARIABLES LIKE 'wsrep_sst_receive_address';"

Expected output includes an rsync path and a row for wsrep_sst_method. Do not treat a missing receive address as harmless: MariaDB's documented default is AUTO, which derives an address from the node configuration. An address set to localhost cannot serve a joiner on another host.

Checkpoint: record the current setting

Save the current method and the relevant configuration before editing. This gives you an undo value if the cluster behaves differently from expected.

sudo mariadb -NBe "SHOW GLOBAL VARIABLES LIKE 'wsrep_sst_method';" | tee /tmp/wsrep-sst-method.before
sudo mariadb -NBe "SHOW GLOBAL VARIABLES LIKE 'wsrep_sst_receive_address';" | tee /tmp/wsrep-sst-address.before

The first file should contain the current method, commonly rsync. Files under /tmp may be readable by other local users, so remove them after use if the output contains information you do not want to retain.

1. Set the SST method

Edit the active MariaDB configuration file as root. Use the file already included by your installation, represented below by /path/to/active-mariadb.cnf. Put the setting in the group used for server options, normally [mariadb] or [mysqld] in the existing cluster configuration.

sudoedit /path/to/active-mariadb.cnf

Add or change one line in that group:

wsrep_sst_method = rsync_wan

Do not add a made-up wsrep_sst_rsync_wan command line to a shell startup file. The executable is the SST helper selected by the server's method setting. On this installation, /usr/bin/wsrep_sst_rsync_wan is a symbolic link to wsrep_sst_rsync; the helper uses the name it was called by to choose WAN-style delta transfers.

2. Check the effective configuration

Restarting or reloading a clustered database can affect service availability. Plan a maintenance window and follow your cluster's normal node-draining procedure. After the setting has been loaded, ask MariaDB rather than trusting the edited file.

sudo mariadb -e "SHOW GLOBAL VARIABLES LIKE 'wsrep_sst_method';"

The value should be rsync_wan. If it is still rsync, inspect duplicate option groups and included files. If MariaDB refuses to start, restore the previous line from your configuration backup, then start the service using your distribution's normal service procedure. Do not repeatedly restart both cluster members while diagnosing a failed join.

3. Understand when the transfer runs

You normally do not invoke the helper yourself. Galera starts it with internal arguments and environment values describing the donor or joiner, data directory, address, role and port. A direct call without those values is not a useful test; on this machine it exits while trying to read missing SST settings.

When a node cannot catch up with an incremental state transfer, Galera can request an SST. The rsync method copies the donor's database state while the donor is blocked by a read lock. The WAN variant keeps rsync's delta-transfer behaviour, so an existing, older datadir on the joiner can reduce network traffic. That is useful over a slower link, but it does not make an SST non-disruptive.

Watch the MariaDB error log on both donor and joiner during a planned test. Use your distribution's configured log location; do not assume that a systemd journal is the only destination.

sudo journalctl -u mariadb.service --since "10 minutes ago" --no-pager | grep -iE 'sst|rsync|wsrep'
sudo mariadb -e "SHOW GLOBAL STATUS LIKE 'wsrep%';"

Exact log wording varies by MariaDB and Galera build. A successful join should end with the node reporting a connected, synced cluster state. Confirm that with your normal cluster health checks before returning traffic to the node.

Safety boundaries and recovery

If the slower link is unreliable, first stop the join attempt through your cluster's normal operational controls. Do not delete the joiner's datadir as a troubleshooting shortcut. Preserve the error logs, restore wsrep_sst_method to the value recorded in /tmp/wsrep-sst-method.before, and resolve the address, firewall, disk-space or certificate issue before retrying. If you enabled SST TLS settings, verify the certificate and key configuration on both nodes; encryption is a transport setting, not a substitute for node authentication or access control.

To undo this guide's configuration change, restore the original wsrep_sst_method value in the same option group, then apply it through your normal MariaDB maintenance procedure. Verify the result:

sudo mariadb -e "SHOW GLOBAL VARIABLES LIKE 'wsrep_sst_method';"
rm -f /tmp/wsrep-sst-method.before /tmp/wsrep-sst-address.before