Configure MariaDB Galera SST with wsrep_sst_mariabackup

A node drops out of your Galera cluster, and wsrep_sst_mariabackup is what copies the whole database back across when it rejoins. This guide sets it up on both nodes, confirms the tooling is there, and checks the settings before a real node ever needs to join.

• Time: 20 to 30 minutes for configuration and checks, plus however long a test join takes.
• You need: administrative access to both MariaDB nodes, a maintenance window for any join that replaces data, and a tested recovery plan.
• Version: MariaDB Server 10.11.14-0ubuntu0.24.04.1. Its manpage is deliberately brief, so the executable and MariaDB's current Galera documentation supply the 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

• Name mismatch is normal. The script looks for mariadb-backup specifically, even though its historical name and the SST method setting both say mariabackup.
• socat is required too. It handles the standard transfer format. A missing helper or transfer program is a prerequisite failure, not something to patch around with a different command name in the configuration.
• Do not improvise a substitute. 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 process, then repeat the checks. Never 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 your installation uses:

[mariadb]
wsrep_sst_method = mariabackup

You can also change the setting dynamically on the node intended to donate:

SET GLOBAL wsrep_sst_method = 'mariabackup';

Persist the option in configuration as well, or a restart can quietly 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

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 lives 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 needs pv. Remove it if pv is not installed.
• The timeout is not a total-duration limit. It is in seconds and governs the initial connection or progress window, not the length of a large transfer.
• rlimit also needs pv. A rate limit can be added with rlimit, but test it against the time you actually have for the join.
• TLS is worth the extra step on a shared network. Configure the documented SST TLS files, such as tca, tcert and tkey, only after confirming certificate paths and permissions on both nodes. A private key should be readable by the MariaDB service account and 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 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, follow 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 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.

• Transfer fails before the joiner is replaced? Preserve the logs and fix the reported dependency, authentication, certificate or network problem.
• Joiner data already 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.
• Keep the old copy until the new node proves itself. Do not delete the original donor data or old backup until the new node is synced and application reads and writes have been checked.
• Changed the method only for a test? Restore the previous value afterwards and make the persistent option agree with the running server.