Skip to content

SSL and Domains Updated 2026-05-27

SSL/TLS for MySQL, MariaDB, and Percona

The Stack Harbor PaaS SSL/TLS encryption-in-transit add-on for MySQL, MariaDB, and Percona — installation, certificate locations, ProxySQL configuration, and connecting from a client with SSL.

MySQL, MariaDB, and Percona environments on the Stack Harbor PaaS support a built-in SSL/TLS add-on that turns on encryption in transit for database connections. Once installed, every step happens automatically — certificate generation, encryption, authentication, decryption, and verification. You connect over an encrypted channel with no application-side changes beyond a flag.

The add-on can be installed on MySQL, MariaDB, Percona, and ProxySQL nodes. For clustered topologies that include ProxySQL load balancing, install the add-on on both layers.

Install the add-on

  1. In the dashboard, open the database layer.
  2. Go to Add-Ons.
  3. Click Install on the SSL/TLS Encrypted Connection card.
  4. Select the target environment and the node groups where the add-on should run. For clusters with ProxySQL, select both the database layer and the ProxySQL layer.
  5. Click Install.

The reconfiguration takes about a minute. The database daemon is restarted with the new TLS configuration once.

Where certificates live

  • Certificates are generated by the platform’s /usr/local/sbin/selfcertgen utility.
  • They are self-signed and issued for the hostname of each node — every node has its own pair. When you authenticate, use the certificates matching the node you connect to.
  • Both server and client certificates are stored under /var/lib/stackharbor/keys/SSL-TLS/, with two subdirectories:
    • server/ — server certificates used for TLS termination on the database side
    • client/ — downloadable client certificates for mutual TLS authentication

The keys shortcut in the file manager points to the same location.

MySQL / MariaDB / Percona configuration

The add-on writes its settings to a dedicated file at /etc/mysql/conf.d/ssl-config.cnf:

[mysqld]
ssl_cert=/var/lib/stackharbor/keys/SSL-TLS/server/server.crt
ssl_key=/var/lib/stackharbor/keys/SSL-TLS/server/server.key
ssl-cipher=ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-SHA
#require_secure_transport=ON

The require_secure_transport directive is commented out by default — the server accepts both plain and TLS connections. Uncomment it to reject all plain-text connections.

ProxySQL configuration

In clustered topologies with ProxySQL, the add-on flips two variables on each ProxySQL node:

  • mysql-have_ssl set to true — enables SSL on frontend connections from clients to ProxySQL.
  • use_ssl set to 1 in mysql_servers — tells ProxySQL that backend MySQL nodes also accept SSL.

The equivalent SQL the add-on runs on each node:

UPDATE global_variables SET variable_value='true' WHERE variable_name='mysql-have_ssl';
LOAD MYSQL VARIABLES TO RUNTIME; SAVE MYSQL VARIABLES TO DISK;
UPDATE mysql_servers SET use_ssl=1 WHERE port=3306;
LOAD MYSQL VARIABLES TO RUNTIME; LOAD MYSQL SERVERS TO RUNTIME; SAVE MYSQL SERVERS TO DISK;

Connect from a client with SSL

Encryption in transit (server-side) is active immediately after installation. Test it from any MySQL client:

mysql --ssl-mode=required -h <host> -P <port> -u <user> -p

For the MariaDB client, the equivalent flag is --ssl instead of --ssl-mode=required.

Once connected, run status and check the SSL line in the output to confirm the connection is encrypted.

Require client certificates (mutual TLS)

To require the client to present a certificate as well — true mutual TLS — alter the user account:

FLUSH PRIVILEGES;
ALTER USER '<user>'@'%' REQUIRE X509;
ALTER USER '<user>'@'localhost' REQUIRE X509;
FLUSH PRIVILEGES;

To additionally check the Common Name on the client certificate matches the username:

FLUSH PRIVILEGES;
ALTER USER '<user>'@'%' REQUIRE SUBJECT 'CN=<user>';
ALTER USER '<user>'@'localhost' REQUIRE SUBJECT 'CN=<user>';
FLUSH PRIVILEGES;

You can also remove the password requirement and authenticate exclusively with certificates via ALTER USER ... IDENTIFIED WITH ....

Download client certificates from the /var/lib/stackharbor/keys/SSL-TLS/client/ directory of the corresponding node and provide them to your client (--ssl-cert, --ssl-key, --ssl-ca).

Re-issue and uninstall

The add-on adds a Re-issue certificates button under the Add-Ons tab of the layer — use it if a key is compromised or accidentally removed. Uninstall in the add-on’s overflow menu removes the configuration and the generated certificates.

See also