Parse MariaDB SST Options with wsrep_sst_common

wsrep_sst_common is not a command you run, it is a parser you source: the boundary that trips people up first. You will find a safe way to inspect this common MariaDB state snapshot transfer (SST) parser, source it from another shell script, and verify the values it derives from an SST command line.

The examples below use MariaDB 10.11.14 from the installed mariadb-server package. The local manual is dated 15 May 2020 and labels the interface MariaDB 10.11, so keep the installed script and manual together when debugging a different release. Allow about fifteen minutes. You need a shell and the MariaDB server package; the examples use a temporary directory and do not need root.

1. Confirm what is installed

Check the package, path and file type before reading a script or changing an SST configuration. These are ordinary, read-only commands:

$ command -v wsrep_sst_common
/usr/bin/wsrep_sst_common
$ dpkg-query -W -f='${Package} ${Version}\n' mariadb-server
mariadb-server 1:10.11.14-0ubuntu0.24.04.1
$ file /usr/bin/wsrep_sst_common
/usr/bin/wsrep_sst_common: ASCII text

Your package revision may differ. What matters is that the command resolves to the expected MariaDB installation and that the package owns it:

$ dpkg-query -S /usr/bin/wsrep_sst_common
mariadb-server: /usr/bin/wsrep_sst_common

Checkpoint: If the path belongs to another package, stop and use that installation's documentation. Do not copy a helper from a second MariaDB installation into a live SST directory.

2. Do not execute the helper as a command

The manual describes this file as a common command-line parser to be sourced by other SST scripts. Direct execution still runs shell code, so it can look like a command, but it expects SST arguments and initialises variables and functions for its caller. It is not a program with a useful help screen.

On this installation, a direct help attempt demonstrates the boundary:

$ wsrep_sst_common --help
WSREP_SST: [ERROR] The '--datadir' parameter must be passed to the SST script (...)
$ printf 'exit status: %s\n' "$?"
exit status: 2

The timestamp and exact diagnostic details vary. A non-zero status here is expected: do not "fix" it by adding random options to a production SST command. The right caller is an SST script that supplies the datadir and then consumes the exported variables.

3. Source it in a disposable test shell

Use a temporary datadir value for a parser test. This does not create a database, but it keeps the test separate from MariaDB's real data directory. The address syntax below is representative: host, port, SST method, sequence or LSN, and version are all encoded in one value.

$ test_dir=$(mktemp -d /tmp/wsrep-sst-common.XXXXXX)
$ bash -c '
    source /usr/bin/wsrep_sst_common \
      --datadir "$1" \
      --address 127.0.0.1:4567/xtrabackup-v2/123/10.11
    printf "role=%s\n" "$WSREP_SST_OPT_ROLE"
    printf "host=%s\n" "$WSREP_SST_OPT_HOST"
    printf "port=%s\n" "$WSREP_SST_OPT_PORT"
    printf "module=%s\n" "$WSREP_SST_OPT_MODULE"
    printf "lsn=%s\n" "$WSREP_SST_OPT_LSN"
    printf "version=%s\n" "$WSREP_SST_OPT_SST_VER"
  ' _ "$test_dir"
WSREP_SST: [INFO] _ SST started on donor (...)
role=donor
host=127.0.0.1
port=4567
module=xtrabackup-v2
lsn=123
version=10.11
$ rmdir "$test_dir"

The log line is written to standard error by the helper. The parsed values are shell variables in the child shell, so they disappear when that shell exits, which is exactly what you want from a test: the command cannot accidentally alter your interactive shell's environment.

Checkpoint: Your host and version values are allowed to differ, but the supplied address should produce a numeric port and the expected method, LSN and version fields. If parsing stops with a datadir error, check the argument is present and follows --datadir.

4. Use the parser from an SST wrapper

A real SST script normally sources the helper near its start, then uses the variables and functions it provides. Keep the source path explicit and quote values when passing them to other commands:

#!/usr/bin/env bash
set -euo pipefail

source /usr/bin/wsrep_sst_common "$@"

printf 'SST role: %s\n' "$WSREP_SST_OPT_ROLE"
printf 'data directory: %s\n' "$WSREP_SST_OPT_DATA"
printf 'peer address: %s\n' "$WSREP_SST_OPT_ADDR"
printf 'transfer type: %s\n' "$WSREP_TRANSFER_TYPE"

In an actual SST implementation, replace the print statements with the documented transfer logic for your chosen method. The helper's variables are an interface between the MariaDB SST launcher and that script. Avoid renaming them, and do not assume an unset value means the same thing as an empty value unless the consuming script defines that contract.

The parser recognises options including --datadir, --address, --host, --port, --role, --user, --password, defaults-file options and mysqld arguments. It also normalises some paths and derives defaults such as the donor role and, when needed, port 4444. Those details are version-sensitive: inspect the installed helper before relying on an edge case.

5. Test address and role handling without a service

You can exercise common parser branches without starting MariaDB. The following uses an IPv6 address and an explicit joiner role:

$ test_dir=$(mktemp -d /tmp/wsrep-sst-common.XXXXXX)
$ bash -c '
    source /usr/bin/wsrep_sst_common \
      --datadir "$1" \
      --address "[2001:db8::10]:4568/mariabackup/456/10.11" \
      --role joiner
    printf "host=%s\n" "$WSREP_SST_OPT_HOST"
    printf "role=%s\n" "$WSREP_SST_OPT_ROLE"
    printf "address=%s\n" "$WSREP_SST_OPT_ADDR"
  ' _ "$test_dir"
host=[2001:db8::10]
role=joiner
address=[2001:db8::10]:4568/mariabackup/456/10.11
$ rmdir "$test_dir"

Use documentation-only addresses such as 2001:db8::10 for parser tests: they are not a connectivity test. Do not replace them with a live peer unless you intend to test an SST workflow.

6. Protect credentials and live services

Warning: Do not put a real SST password in a shell history, terminal transcript or pasted diagnostic. The helper accepts --password and can derive authentication values from configuration. Treat those values as secrets, and redact them before sharing output. Prefer the existing MariaDB configuration and secret-handling conventions used by your SST script.

Do not source an unreviewed copy of this file into a service account. Sourcing executes shell code in the current shell, including environment and signal handling changes. Compare the file with the package version, and test wrapper changes against a disposable shell first.

This guide makes no service, database or network change. If you have edited a wrapper while testing, restore its previous copy before restarting MariaDB. If a live SST has already begun, do not kill processes casually: follow your cluster's maintenance and recovery procedure, because interrupting a transfer can leave a node needing another join.

Done means