Configure MariaDB 11.6 master-slave replication with SSL encryption and automatic failover

Advanced 45 min Apr 06, 2026 80 views
Ubuntu 24.04 Debian 12 AlmaLinux 9 Rocky Linux 9

Set up production-grade MariaDB master-slave replication with SSL/TLS encryption for secure data transmission and MaxScale for automatic failover and load balancing.

Prerequisites

  • Root or sudo access
  • Two or more servers for master-slave setup
  • Basic understanding of MariaDB administration
  • Network connectivity between servers
  • At least 2GB RAM per server

What this solves

MariaDB master-slave replication provides data redundancy and read scaling by maintaining synchronized copies of your database across multiple servers. This tutorial configures SSL-encrypted replication for secure data transmission and implements MaxScale for automatic failover, ensuring your database remains available even during primary server outages.

Step-by-step configuration

Update system packages

Start by updating your package manager and installing required dependencies for MariaDB 11.6 and SSL certificate management.

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl wget gnupg2 software-properties-common openssl
sudo dnf update -y
sudo dnf install -y curl wget gnupg2 openssl

Install MariaDB 11.6

Add the official MariaDB repository and install version 11.6 with the required packages for replication.

curl -LsS https://r.mariadb.com/downloads/mariadb_repo_setup | sudo bash -s -- --mariadb-server-version=11.6
sudo apt install -y mariadb-server mariadb-client mariadb-backup
curl -LsS https://r.mariadb.com/downloads/mariadb_repo_setup | sudo bash -s -- --mariadb-server-version=11.6
sudo dnf install -y mariadb-server mariadb-client mariadb-backup

Secure MariaDB installation

Run the security script to remove test databases, set root password, and disable remote root access.

sudo systemctl enable --now mariadb
sudo mariadb-secure-installation
Note: Choose a strong root password and answer 'Y' to all security questions except 'Disallow root login remotely?' - answer 'N' for now as we'll configure this properly.

Generate SSL certificates

Create SSL certificates for encrypted replication between master and slave servers. We'll use a self-signed CA for this setup.

sudo mkdir -p /etc/mysql/ssl
cd /etc/mysql/ssl

Generate the Certificate Authority (CA) key and certificate:

sudo openssl genrsa 2048 > ca-key.pem
sudo openssl req -new -x509 -nodes -days 3650 -key ca-key.pem -out ca-cert.pem -subj "/C=US/ST=State/L=City/O=Organization/CN=MariaDB-CA"

Generate server certificate and key:

sudo openssl req -newkey rsa:2048 -days 3650 -nodes -keyout server-key.pem -out server-req.pem -subj "/C=US/ST=State/L=City/O=Organization/CN=mariadb-server"
sudo openssl rsa -in server-key.pem -out server-key.pem
sudo openssl x509 -req -in server-req.pem -days 3650 -CA ca-cert.pem -CAkey ca-key.pem -set_serial 01 -out server-cert.pem

Generate client certificate and key:

sudo openssl req -newkey rsa:2048 -days 3650 -nodes -keyout client-key.pem -out client-req.pem -subj "/C=US/ST=State/L=City/O=Organization/CN=mariadb-client"
sudo openssl rsa -in client-key.pem -out client-key.pem
sudo openssl x509 -req -in client-req.pem -days 3650 -CA ca-cert.pem -CAkey ca-key.pem -set_serial 01 -out client-cert.pem

Set correct permissions on SSL files:

sudo chown mysql:mysql /etc/mysql/ssl/*
sudo chmod 600 /etc/mysql/ssl/*-key.pem
sudo chmod 644 /etc/mysql/ssl/*-cert.pem

Configure MariaDB master server

Configure the master server with SSL support, binary logging, and replication settings.

[mysqld]

Server identification

server-id = 1

Binary logging for replication

log-bin = mysql-bin log-bin-index = mysql-bin.index binlog_format = ROW expire_logs_days = 7 max_binlog_size = 100M

SSL Configuration

ssl-ca = /etc/mysql/ssl/ca-cert.pem ssl-cert = /etc/mysql/ssl/server-cert.pem ssl-key = /etc/mysql/ssl/server-key.pem require_secure_transport = ON

Network and security

bind-address = 0.0.0.0 port = 3306

Performance tuning

innodb_buffer_pool_size = 1G innodb_log_file_size = 256M innodb_flush_log_at_trx_commit = 1 sync_binlog = 1

Replication settings

gtid_domain_id = 1 log_slave_updates = ON replica_skip_errors = 1062

Configure MariaDB slave server

On the slave server, install MariaDB following the same steps, then configure it with a different server ID.

[mysqld]

Server identification (different from master)

server-id = 2

Binary logging for potential promotion

log-bin = mysql-bin log-bin-index = mysql-bin.index binlog_format = ROW expire_logs_days = 7 max_binlog_size = 100M

SSL Configuration

ssl-ca = /etc/mysql/ssl/ca-cert.pem ssl-cert = /etc/mysql/ssl/server-cert.pem ssl-key = /etc/mysql/ssl/server-key.pem require_secure_transport = ON

Network and security

bind-address = 0.0.0.0 port = 3306

Performance tuning

innodb_buffer_pool_size = 1G innodb_log_file_size = 256M innodb_flush_log_at_trx_commit = 1 sync_binlog = 1

Replication settings

gtid_domain_id = 1 log_slave_updates = ON replica_skip_errors = 1062 read_only = ON
Note: Copy the SSL certificates from the master to the slave server in the same directory structure with identical permissions.

Restart MariaDB services

Restart both master and slave servers to apply the new configuration.

sudo systemctl restart mariadb
sudo systemctl status mariadb

Create replication user on master

Create a dedicated user for replication with SSL requirements and proper permissions.

sudo mariadb -u root -p
CREATE USER 'replication'@'%' IDENTIFIED BY 'StrongReplicationPassword123!' REQUIRE SSL;
GRANT REPLICATION SLAVE ON . TO 'replication'@'%';
FLUSH PRIVILEGES;
SHOW MASTER STATUS;
EXIT;
Note: Record the File and Position values from SHOW MASTER STATUS - you'll need them for slave configuration.

Configure replication on slave

Connect the slave to the master using SSL-encrypted replication. Replace the master host, log file, and position with your actual values.

sudo mariadb -u root -p
CHANGE MASTER TO
  MASTER_HOST='203.0.113.10',
  MASTER_USER='replication',
  MASTER_PASSWORD='StrongReplicationPassword123!',
  MASTER_LOG_FILE='mysql-bin.000001',
  MASTER_LOG_POS=328,
  MASTER_SSL=1,
  MASTER_SSL_CA='/etc/mysql/ssl/ca-cert.pem',
  MASTER_SSL_CERT='/etc/mysql/ssl/client-cert.pem',
  MASTER_SSL_KEY='/etc/mysql/ssl/client-key.pem';

START SLAVE;
SHOW SLAVE STATUS\G
EXIT;

Install and configure MaxScale

Install MaxScale for automatic failover and load balancing between master and slave servers.

curl -sS https://downloads.mariadb.com/MariaDB/mariadb_repo_setup | sudo bash -s -- --skip-server --mariadb-maxscale-version=24.02
sudo apt install -y maxscale
curl -sS https://downloads.mariadb.com/MariaDB/mariadb_repo_setup | sudo bash -s -- --skip-server --mariadb-maxscale-version=24.02
sudo dnf install -y maxscale

Create MaxScale monitoring user

Create a user on the master server for MaxScale to monitor server health and perform failover operations.

sudo mariadb -u root -p
CREATE USER 'maxscale'@'%' IDENTIFIED BY 'MaxScaleMonitorPassword123!' REQUIRE SSL;
GRANT SELECT ON mysql.user TO 'maxscale'@'%';
GRANT SELECT ON mysql.db TO 'maxscale'@'%';
GRANT SELECT ON mysql.tables_priv TO 'maxscale'@'%';
GRANT SELECT ON mysql.columns_priv TO 'maxscale'@'%';
GRANT SELECT ON mysql.procs_priv TO 'maxscale'@'%';
GRANT SELECT ON mysql.proxies_priv TO 'maxscale'@'%';
GRANT SELECT ON mysql.roles_mapping TO 'maxscale'@'%';
GRANT SHOW DATABASES ON . TO 'maxscale'@'%';
GRANT REPLICATION CLIENT ON . TO 'maxscale'@'%';
GRANT SUPER ON . TO 'maxscale'@'%';
FLUSH PRIVILEGES;
EXIT;

Configure MaxScale

Configure MaxScale with SSL support, monitoring, and automatic failover capabilities.

[maxscale]
threads=auto
log_warning=1
log_notice=1
log_info=0
log_debug=0

[server1]
type=server
address=203.0.113.10
port=3306
protocol=MariaDBBackend
ssl=required
ssl_cert=/etc/mysql/ssl/client-cert.pem
ssl_key=/etc/mysql/ssl/client-key.pem
ssl_ca_cert=/etc/mysql/ssl/ca-cert.pem

[server2]
type=server
address=203.0.113.11
port=3306
protocol=MariaDBBackend
ssl=required
ssl_cert=/etc/mysql/ssl/client-cert.pem
ssl_key=/etc/mysql/ssl/client-key.pem
ssl_ca_cert=/etc/mysql/ssl/ca-cert.pem

[MariaDB-Monitor]
type=monitor
module=mariadbmon
servers=server1,server2
user=maxscale
password=MaxScaleMonitorPassword123!
monitor_interval=2000
auto_failover=true
auto_rejoin=true
failover_timeout=30
switchover_timeout=30

[Read-Write-Service]
type=service
router=readwritesplit
servers=server1,server2
user=maxscale
password=MaxScaleMonitorPassword123!
master_failure_mode=fail_on_write
max_slave_connections=100%
max_slave_replication_lag=10

[Read-Only-Service]
type=service
router=readconnroute
router_options=slave
servers=server1,server2
user=maxscale
password=MaxScaleMonitorPassword123!

[Read-Write-Listener]
type=listener
service=Read-Write-Service
protocol=MariaDBClient
port=4006
address=0.0.0.0

[Read-Only-Listener]
type=listener
service=Read-Only-Service
protocol=MariaDBClient
port=4008
address=0.0.0.0

Copy SSL certificates to MaxScale

Copy the SSL certificates to MaxScale directory and set appropriate permissions.

sudo mkdir -p /etc/mysql/ssl
sudo cp /path/to/ssl/certificates/* /etc/mysql/ssl/
sudo chown maxscale:maxscale /etc/mysql/ssl/*
sudo chmod 600 /etc/mysql/ssl/*-key.pem
sudo chmod 644 /etc/mysql/ssl/*-cert.pem

Start and enable MaxScale

Start MaxScale and enable it to start automatically on boot.

sudo systemctl enable --now maxscale
sudo systemctl status maxscale

Configure firewall rules

Open necessary ports for MariaDB and MaxScale communication.

sudo ufw allow 3306/tcp comment "MariaDB"
sudo ufw allow 4006/tcp comment "MaxScale Read-Write"
sudo ufw allow 4008/tcp comment "MaxScale Read-Only"
sudo ufw allow from 203.0.113.0/24 to any port 3306 comment "MariaDB replication"
sudo firewall-cmd --permanent --add-port=3306/tcp
sudo firewall-cmd --permanent --add-port=4006/tcp
sudo firewall-cmd --permanent --add-port=4008/tcp
sudo firewall-cmd --reload

Verify your setup

Test the replication setup and MaxScale functionality.

# Check replication status on slave
sudo mariadb -u root -p -e "SHOW SLAVE STATUS\G" | grep -E "Slave_IO_Running|Slave_SQL_Running|Seconds_Behind_Master|SSL_Allowed"

Test MaxScale connectivity

mariadb -h 127.0.0.1 -P 4006 -u root -p -e "SELECT @@hostname, @@server_id;"

Check MaxScale status

sudo maxctrl list servers sudo maxctrl show server server1

Test SSL encryption

sudo mariadb -u root -p -e "SHOW STATUS LIKE 'Ssl_cipher';"

Test failover by creating test data on master

sudo mariadb -u root -p -e "CREATE DATABASE test_replication; USE test_replication; CREATE TABLE test (id INT PRIMARY KEY, data VARCHAR(50)); INSERT INTO test VALUES (1, 'replication test');"

Verify data appears on slave

sudo mariadb -h 203.0.113.11 -u root -p -e "USE test_replication; SELECT * FROM test;"
Note: Both Slave_IO_Running and Slave_SQL_Running should show "Yes" and SSL_Allowed should show "Yes" for proper encrypted replication.

Common issues

SymptomCauseFix
Slave_IO_Running: NoSSL certificate issues or network connectivityCheck SSL certificate paths and permissions, verify network connectivity between servers
Slave_SQL_Running: NoDuplicate key errors or data inconsistencyCheck error log, use SET GLOBAL sql_slave_skip_counter=1; START SLAVE; for single event skip
MaxScale connection refusedUser permissions or SSL configurationVerify maxscale user has correct permissions and SSL certificates are readable
SSL connection failedCertificate mismatch or incorrect pathsRegenerate certificates ensuring correct CN and verify file paths in configuration
Replication lag increasingHigh write load or inadequate slave resourcesMonitor Seconds_Behind_Master, consider upgrading slave hardware or optimizing queries
Automatic failover not workingMaxScale monitor configuration or permissionsCheck MaxScale logs, verify monitor user has SUPER privilege and auto_failover is enabled

Next steps

Automated install script

Run this to automate the entire setup

Need help?

Don't want to manage this yourself?

We handle high availability infrastructure for businesses that depend on uptime. From initial setup to ongoing operations.