Configure MariaDB Galera SST with wsrep_sst_mariabackup

You will configure MariaDB Galera to use wsrep_sst_mariabackup for a state snapshot transfer (SST), check that both nodes have the required tools, and verify the settings before a node needs to join. The script is a cluster helper, not a general-purpose backup command: Galera starts it with internal arguments and environment variables.

Allow 20 to 30 minutes for configuration and checks, plus the time needed for a test join. You need administrative access to both MariaDB nodes, a maintenance window for any join that replaces data, and a tested recovery plan. The installed package examined here is MariaDB Server 10.11.14-0ubuntu0.24.04.1. Its manpage is deliberately brief, so the executable and MariaDB's current Galera documentation provide the operational detail below.

1. Check the method and its dependencies

Run these ordinary, read-only checks on every node that may donate or receive an SST:

$ command -v wsrep_sst_mariabackup
/usr/bin/wsrep_sst_mariabackup
$ command -v mariadb-backup
/usr/bin/mariadb-backup
$ command -v socat
/usr/bin/socat
$ dpkg-query -W -f='${Package} ${Version}\n' mariadb-server

The local script looks specifically for mariadb-backup, even though its historical name and SST method setting contain mariabackup. It also uses socat for the standard transfer format. A missing helper or transfer program is a prerequisite failure, not something to fix by adding a different command name to the configuration.

On the inspected machine, the script exists but mariadb-backup is not installed, so an SST cannot start there yet. Install the matching MariaDB backup package through your normal package-management process, then repeat the checks. Do not mix an arbitrary backup binary from another major MariaDB release into the cluster.

2. Set the same SST method on both nodes

Place the method in the MariaDB server option group on both donor and joiner. The exact group can be [mariadb] or the server group used by your installation:

[mariadb]
wsrep_sst_method = mariabackup

The setting can also be changed dynamically on the node intended to donate:

SET GLOBAL wsrep_sst_method = 'mariabackup';

Persist the option in configuration as well, or a restart can return the node to another method. MariaDB recommends using the same method on all nodes because any node can later become a donor or joiner.

SHOW GLOBAL VARIABLES LIKE 'wsrep_sst_method';

3. Configure authentication without exposing a password

The SST process must authenticate to the local MariaDB server on the donor. For a traditional setup, create a dedicated account with the privileges documented for this method, then pass its credentials through wsrep_sst_auth:

CREATE USER 'sst_user'@'localhost' IDENTIFIED BY 'REPLACE_WITH_A_LONG_RANDOM_PASSWORD';
GRANT RELOAD, PROCESS, LOCK TABLES, REPLICATION CLIENT ON *.* TO 'sst_user'@'localhost';

Configure the value in the server option group, with the real secret supplied through your protected configuration process:

[mariadb]
wsrep_sst_auth = sst_user:REPLACE_WITH_A_LONG_RANDOM_PASSWORD

Treat this as security-sensitive. Protect the option file, avoid putting the password in shell history, and do not paste it into logs or tickets. MariaDB Enterprise Server has a separate automatic temporary-user mechanism when wsrep_sst_auth is left unset; do not assume that feature exists in community MariaDB 10.11.

4. Add only the transport settings you need

The default stream format is mbstream and the default transfer utility is socat. Start with those defaults. If the link is bandwidth-constrained, compression is configured in the [sst] group and must be available on the relevant nodes:

[sst]
streamfmt = mbstream
transferfmt = socat
compressor = lz4 -z
decompressor = lz4 -d
progress = 1
sst-initial-timeout = 600

progress=1 requires pv. Remove it if pv is not installed. The timeout is in seconds and controls the initial connection or progress window; it is not a limit on the total duration of a large transfer. A rate limit can be added with rlimit, but it also depends on pv and should be tested against the time available for the join.

For a protected network, configure the documented SST TLS files, such as tca, tcert and tkey, only after confirming the certificate paths and permissions on both nodes. A private key should be readable by the MariaDB service account and by nobody else who does not need it.

5. Check version boundaries before joining

Compare the MariaDB major versions and the installed mariadb-backup versions before scheduling the join. Changes to the InnoDB redo log format in MariaDB 10.5 and 10.8 mean that this SST method is not suitable for some major-version upgrades. The joiner must prepare the received backup with a compatible backup tool. For a major-version upgrade, use the documented upgrade procedure and consider the default rsync method where appropriate instead of improvising with this helper.

Record the current state before changing anything:

SELECT VERSION();
SHOW GLOBAL VARIABLES LIKE 'wsrep_sst_method';
SHOW GLOBAL STATUS LIKE 'wsrep_cluster%';

6. Test and recover safely

Use a disposable or deliberately rebuilt joiner for the first test. Watch the MariaDB error log and SST log, and confirm that the joiner reaches the expected synced state. The helper writes Galera metadata and backup preparation logs in the data directory, including mariabackup.prepare.log on a preparation failure.

If the transfer fails before the joiner is replaced, preserve the logs and correct the reported dependency, authentication, certificate, or network problem. If the joiner data has already been removed, stop MariaDB and restore that node from the last known-good backup or rebuild it from a donor using the approved cluster recovery procedure. There is no undo command that reconstructs deleted database files.

Do not delete the original donor data or old backup until the new node is synced and application reads and writes have been checked. If you change wsrep_sst_method only for a test, restore the previous value after the test and make the persistent option agree with the running server.