WIUNIX ACADEMY

Install MariaDB primary-replica replication with GTID and TLS

Page 4 of 4. Review the earlier steps and prerequisites before continuing.

YOUR SYSTEM. YOUR STEPS.

Where are you working?

Choose your OS and version. The prerequisites, commands and troubleshooting follow your environment.

Ubuntu 26.10Reviewed against official documentation · 2026-10-20

USE YOUR OWN VALUES

Configure this tutorial

Set the example values for your environment; related explanations and copy panels update together. Never enter passwords, private keys or tokens. Values stay in this tab and are not sent to the server or share links. Check actual DNS, certificates and network policy before running commands.

Edit 3 tutorial values

LET’S BUILD

Start and recheck both stages

Replica only, after the preceding consistency decision. No service restart is required to explicitly start the existing channel. Repeat exact GTID wait and row verification using the primary’s actual current target. A successful start is not proof of identical data.

Replica

(
set -euo pipefail
sudo mariadbd --verbose --help >/dev/null
sudo mariadb -e "START SLAVE; SHOW SLAVE STATUS\G; SELECT @@read_only,@@GLOBAL.gtid_slave_pos;"
)

How do I know it worked?

Yes/Yes with zero errors; read_only1; bounded GTID wait/data comparison repeated successfully.

Promotion needs fencing and a separate runbook

This tutorial deliberately stops short of promotion. Planned switchover requires a real write fence (including privileged sessions), a final committed position, confirmed replica catch-up, routing changes and a safe way to rejoin the old node. Unplanned primary loss may lose acknowledged transactions; a zero lag sample does not establish zero RPO. Never make both writable or rejoin an old primary blindly. Replica reads can be stale; read-after-write-sensitive requests stay on the primary.

Diagnose the failing stage before recovery

Run only the relevant diagnostic panel, on the named host. Logs may contain internal names and authentication details; redact before sharing. Missing binlogs or row drift require a new consistent seed on a separate fresh replacement, never guessed positions or skipped errors.

Service refuses startup

On the affected host inspect option errors, missing certificate/key permissions and private bind address. Correct that file with the earlier editor, validate again, then use that host’s explicit restart panel. Do not start a second daemon on the same data directory.

sudo mariadbd --verbose --help >/dev/null
sudo systemctl status mariadb --no-pager
sudo journalctl -u mariadb -n 60 --no-pager
ip -br address

Receiver is not Yes

Replica: distinguish DNS/TCP failure from1045 credentials or TLS certificate errors in Last_IO_Error. Check actual source IP and the primary firewall with its earlier panel. Do not disable TLS verification or widen the account host to a wildcard.

getent ahostsv4 db-primary.example.internal
sudo mariadb -e "SHOW SLAVE STATUS\G"
sudo -u mysql test -r /etc/mariadb/tls/ca.pem
sudo journalctl -u mariadb -n 60 --no-pager

Applier stops or GTID wait times out

Replica:1062 duplicate row,1032 missing row or GTID out-of-order indicates drift/incorrect seeding; do not skip or reset. Keep the node out of reads and retain it for diagnosis using the pause procedure. A wait timeout can also mean normal backlog; inspect both threads, errors and storage before deciding.

sudo mariadb -e "SHOW SLAVE STATUS\G; SELECT @@GLOBAL.gtid_slave_pos;"
df -h /var/lib/mariadb
df -i /var/lib/mariadb
sudo journalctl -u mariadb -n 60 --no-pager

Required primary binlogs expired

Primary: compare available binary logs with receiver error1236 and your retained seed position. Do not purge/reset history or reuse an old seed with a newer GTID. Preserve this node; provision a separate fresh replica from a new consistent seed. Increase future retention only after sizing disk.

sudo mariadb -e "SHOW BINARY LOGS; SELECT @@GLOBAL.gtid_binlog_pos,@@binlog_expire_logs_seconds;"
df -h /var/lib/mariadb

Certificate renewal changes trust

Primary: check validity, SAN and matching key using the earlier certificate panel. Replica: retain strict verification and deliver an approved overlapping CA chain before a CA rotation. A primary restart disrupts connections; schedule it and recheck both threads and data afterward. Never share private keys/logs to debug a public ticket.

sudo openssl x509 -in /etc/mariadb/tls/server.pem -noout -dates -ext subjectAltName
sudo openssl x509 -in /etc/mariadb/tls/server.pem -checkend 604800 -noout

Operate the replica as a monitored dependency

Alert on either stopped thread, nonzero replication errors, stale progress, growing relay logs, disk/inodes, certificate expiry and backup/restore failures. Keep a separate recovery plan and review access/retention regularly. Replication credentials grant access to the binary-log stream; treat the replica as a trusted data holder. Distribute reads only after measuring acceptable staleness and testing application behavior. Continue with backup restoration and a fenced switchover exercise in a separate lab.

GO TO THE SOURCE

Official references

Each environment states how it was reviewed. A documentation review does not claim a hands-on test of every version.

KEEP LEARNING

Your next step

Explore all tutorials ↗