MariaDB TLS Tutorial

The following guide will help you deploy the Minimus MariaDB image with self-signed, locally issued certificates to help you get started. Run the code to try it for yourself.

For production purposes, we recommend using publicly trusted certificates issued by a Certificate Authority (CA).

Components

MariaDB image built by Minimus: MariaDB container configured with the secure configuration for client authentication.
Dynamic certificate generation via OpenSSL:
- certgen.sh script: Shell script that generates a custom CA, server, and client certificates using OpenSSL.
- minidebug image: A Minimus dev toolkit that provides a shell, OpenSSL, and other utilities used to generate the certificates.

What this guide demonstrates

TLS handshake validation
Server/client certificate trust
Basic auth and MariaDB operations
Image compatibility

Directory Structure

.
├── certgen.sh             # Certificate generation script
├── create-certs.yml       # Compose file to run certgen container
└── docker-compose.yml     # Compose file to run MariaDB

Deploy MariaDB with TLS certificates

Step 1: Generate TLS certificates

Save script that generates TLS certificates

Save the following script to a file named certgen.sh. The script is used to generate the TLS certificates and store them in a certs folder on the host.

certgen.sh

#!/bin/sh
# Company: Minimus

set -e
cd /certs

cat > openssl.cnf <<EOF
[req]
distinguished_name = req_distinguished_name
prompt = no

[req_distinguished_name]
CN = mariadb

[v3_req]
keyUsage = keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth, clientAuth
subjectAltName = @alt_names

[v3_client]
keyUsage = digitalSignature
extendedKeyUsage = clientAuth
subjectAltName = @alt_names

[v3_ca]
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always,issuer
basicConstraints = critical, CA:true
keyUsage = critical, keyCertSign, cRLSign

[alt_names]
DNS.1 = mariadb
DNS.2 = localhost
IP.1 = 172.0.0.1
IP.1 = 192.168.60.0
IP.1 = 192.168.60.2
IP.1 = 192.168.60.3
EOF

openssl genrsa -out ca-key.pem 2048
openssl req -x509 -new -nodes -key ca-key.pem -sha256 -days 365 -out ca.pem \
  -subj "/CN=MariaDB Test CA" -extensions v3_ca -config openssl.cnf

openssl genrsa -out server-key.pem 2048
openssl req -new -key server-key.pem -out server.csr -config openssl.cnf -extensions v3_req
openssl x509 -req -in server.csr -CA ca.pem -CAkey ca-key.pem -CAcreateserial \
  -out server-cert.pem -days 365 -sha256 -extfile openssl.cnf -extensions v3_req

openssl genrsa -out client-key.pem 2048
openssl req -new -key client-key.pem -out client.csr -subj "/CN=root"
openssl x509 -req -in client.csr -CA ca.pem -CAkey ca-key.pem -CAcreateserial \
  -out client-cert.pem -days 365 -sha256 -extfile openssl.cnf -extensions v3_client

chmod 644 *.pem
chown -R 1000:1000 /certs/*.pem || true
echo "[SUCCESS] Certificates generated."

Save Docker Compose configuration

Save the following YAML file to run with Docker Compose. It uses the Minimus minidebug image to generate the certificates with the certgen.sh shell script. Minidebug is a Minimus dev toolkit that provides a shell, OpenSSL, and other utilities. The certificates will be persisted in the certs volume on the host.

create-certs.yml

services:
  certgen:
    image: reg.mini.dev/minidebug:latest
    container_name: mariadb_certgen
    volumes:
    - ./certs:/certs 
    - ./certgen.sh:/certgen.sh:ro
    entrypoint:
    - /bin/sh
    - /certgen.sh
    network_mode: none

Generate certificates

Run the following to generate the certificates:

docker compose -f create-certs.yml up

Congrats! You have just generated the following self-signed certificates:

CA certificate (ca.pem)
Server certificates (server-cert.pem, server-key.pem)
Client certificates for testuser (client-cert.pem, client-key.pem, client.csr)

The permissions for all .pem certificates are set to 644 and owned by UID 1000. Certificate permissions are adjusted to support non-root containers. In the next steps, you will mount these certificates into the MariaDB container.

Step 2: Deploy MariaDB server

Save Docker Compose script

Save the following Docker Compose script to a file named docker-compose.yml. This script sets up the MariaDB service with a healthcheck, mounts a volume with the certificates, and maps port 3307 on the host to port 3306 on the container.

docker-compose.yml

services:
  mariadb:
    image: reg.mini.dev/mariadb
    container_name: mariadb-1
    environment:
      MARIADB_ROOT_PASSWORD: rootpass
    ports:
    - 3307:3306
    volumes:
    - ./certs:/certs:ro
    command:
    - --ssl-ca=/certs/ca.pem
    - --ssl-cert=/certs/server-cert.pem
    - --ssl-key=/certs/server-key.pem
    - --require_secure_transport=ON
    healthcheck:
      test:
      - CMD
      - mariadb-admin
      - ping
      - -prootpass
      interval: 5s
      retries: 10

Run MariaDB

Start the MariaDB container in detached mode:

docker compose -f docker-compose.yml up -d

Step 3: Test your MariaDB server

Connect to your database to test its connectivity. First, make sure you are in the right folder, where the certs are available:

ls -l ./certs/

You can use mysql or mariadb-client to connect over TLS and run tests. For example, here are a few commands you can try out:

Connect to the db:

mysql -h 127.0.0.1 -P 3307 -u root -p \
  --ssl \
  --ssl-ca=./certs/ca.pem \
  --ssl-cert=./certs/client-cert.pem \
  --ssl-key=./certs/client-key.pem

Enter password: 
# Type in the password set in the docker-compose.yml: `rootpass`
Welcome to the MariaDB monitor.  Commands end with ; or \g.
Your MariaDB connection id is 181
Server version: 12.1.2-MariaDB MariaDB Server
Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
MariaDB [(none)]> 

Create and list databases:

CREATE DATABASE my_new_db; 
SHOW DATABASES;

Query OK, 1 row affected (0.001 sec)
MariaDB [(none)]> SHOW DATABASES;
+--------------------+
| Database           |
+--------------------+
| information_schema |
| my_new_db          |
| mysql              |
| new_db             |
| performance_schema |
| sys                |
+--------------------+
6 rows in set (0.001 sec)

Show server version:

SELECT version();

+----------------+
| version()      |
+----------------+
| 12.1.2-MariaDB |
+----------------+
1 row in set (0.001 sec)

Check that TLS is active:

SHOW VARIABLES LIKE 'have_ssl';
SHOW STATUS LIKE 'Ssl_cipher';
SHOW STATUS LIKE 'Ssl_version';

Building Secure Apps

Tutorials

K8s Guides

TLS Guides

Troubleshooting

Debugging

Components

What this guide demonstrates

Directory Structure

Deploy MariaDB with TLS certificates

Step 1: Generate TLS certificates

Step 2: Deploy MariaDB server

Step 3: Test your MariaDB server

​Components

​What this guide demonstrates

​Directory Structure

​Deploy MariaDB with TLS certificates

​Step 1: Generate TLS certificates

​Step 2: Deploy MariaDB server

​Step 3: Test your MariaDB server

Components

What this guide demonstrates

Directory Structure

Deploy MariaDB with TLS certificates

Step 1: Generate TLS certificates

Step 2: Deploy MariaDB server

Step 3: Test your MariaDB server