Encrypting rConfig Database Connections with TLS (V8.3.2+)

rConfig V8.3.2 and later can encrypt the connection between the application and its MySQL, MariaDB, or PostgreSQL database using TLS. After reading this page, you can configure certificate paths in .env, mount certificates into container deployments, and verify that traffic to the database is encrypted.

When to use this

Use this guide when your database runs on a separate host from rConfig and traffic between them crosses a network you do not fully trust, or when a security policy (PCI DSS, ISO 27001, internal hardening standards) requires encryption in transit for all database connections. If rConfig and its database run on the same host and connect over localhost or a UNIX socket, TLS adds little benefit.

Prerequisites

• rConfig V8.3.2 or later. Earlier versions ignore these settings, although PostgreSQL connections before V8.3.2 already used a hardcoded sslmode of prefer: opportunistic encryption when the server offers TLS, with no certificate verification and silent fallback to plaintext.
• A database server already configured to accept TLS connections, with its CA certificate available to copy to the rConfig host. Enabling TLS on the database server itself is covered by the MySQL, MariaDB, and PostgreSQL vendor documentation.
• A client certificate and key pair, only if your database server enforces mutual TLS.
• Shell access to the rConfig server (or container host) with permission to edit .env.

Copy the certificates to the rConfig host

1. Create a directory for the certificates. The examples below use the same paths as the commented template in .env.example:

   mkdir -p /etc/ssl/mariadb    # MySQL and MariaDB
   mkdir -p /etc/ssl/postgres   # PostgreSQL

2. Copy the CA certificate (and the client certificate and key, if using mutual TLS) into that directory.

3. Make the files readable by the web server user:

   chown -R root:apache /etc/ssl/mariadb
   chmod 640 /etc/ssl/mariadb/*

PostgreSQL private key permissions

If you use a client key with PostgreSQL, libpq rejects a key file with permissions wider than 0600 unless it is owned by root with group read only. Set chmod 600 on client.key and make the web server user its owner.

Configure the .env file

Edit .env in the rConfig application root and add the settings for your database engine. The variables are already present as a commented template in .env.example.

MySQL / MariaDB

Both MySQL and MariaDB use DB_CONNECTION=mysql. Setting MYSQL_ATTR_SSL_CA alone is enough to enable an encrypted connection; the client certificate and key are only needed when the server enforces mutual TLS.

MYSQL_ATTR_SSL_CA=/etc/ssl/mariadb/ca.pem
MYSQL_ATTR_SSL_VERIFY_SERVER_CERT=true

# Only for mutual TLS:
MYSQL_ATTR_SSL_CERT=/etc/ssl/mariadb/client-cert.pem
MYSQL_ATTR_SSL_KEY=/etc/ssl/mariadb/client-key.pem

Set MYSQL_ATTR_SSL_VERIFY_SERVER_CERT=false only if the server certificate’s hostname does not match your DB_HOST value (common with self-signed certificates issued to another name). Leaving verification on protects against man-in-the-middle attacks, so treat false as a last resort.

The same certificate paths are passed automatically to mysqldump for scheduled database backups, so no separate backup configuration is needed.

PostgreSQL

PostgreSQL connections (DB_CONNECTION=pgsql) use the standard libpq sslmode values: disable, allow, prefer, require, verify-ca, and verify-full. rConfig defaults to prefer when DB_SSLMODE is not set.

DB_SSLMODE=verify-full
DB_SSLROOTCERT=/etc/ssl/postgres/root.crt

# Only for mutual TLS:
DB_SSLCERT=/etc/ssl/postgres/client.crt
DB_SSLKEY=/etc/ssl/postgres/client.key

Use verify-full where the server certificate’s hostname matches DB_HOST, and verify-ca where it does not. Both validate the certificate against DB_SSLROOTCERT.

Container deployments: mount the certificates

The rConfig V8 Pro container cannot read certificates that only exist on the host, and the .env paths must be valid inside the container. Mount the certificate directory into the container at the same path referenced by .env.

1. Place the certificates on the container host, for example under /home/rconfig/certs/.

2. Add a read-only bind mount to the rConfig service in the supplied docker-compose.yml, alongside the existing volume entries:

   volumes:
     # ... existing rConfig volume mappings, unchanged ...
     - /home/rconfig/certs:/etc/ssl/mariadb:ro   # or /etc/ssl/postgres for PostgreSQL

3. Set the .env certificate paths to the in-container path (/etc/ssl/mariadb/ca.pem), not the host path.

4. Recreate the container so the new mount takes effect:

   docker compose up -d

Do not change the existing volume layout

Add the certificate mount as a new entry only. Do not remap or edit the existing volume mappings in docker-compose.yml; the supported container layout is described in the Docker deployment guide.

Apply the configuration

1. Clear the cached configuration so the new settings load:

   cd /var/www/html/rconfig8/current
   php artisan rconfig:clear-all

   On container deployments, run the same command inside the container: docker exec -it <container_name> php artisan rconfig:clear-all.

2. Restart the queue workers so long-running processes pick up the new connection settings:

   systemctl restart supervisord

   On container deployments, restarting the container in the previous section already covers this.

Verify the connection is encrypted

Run the check through rConfig itself so you are testing the application’s own connection, not a separate client session.

MySQL / MariaDB

cd /var/www/html/rconfig8/current
php artisan tinker --execute="print_r(DB::select(\"SHOW STATUS LIKE 'Ssl_cipher'\"));"

An encrypted connection returns a cipher name:

[Value] => TLS_AES_256_GCM_SHA384

An empty Value means the connection is not encrypted. Re-check the .env paths and confirm the database server has TLS enabled.

PostgreSQL

cd /var/www/html/rconfig8/current
php artisan tinker --execute="print_r(DB::select('SELECT ssl, version, cipher FROM pg_stat_ssl WHERE pid = pg_backend_pid()'));"

An encrypted connection returns ssl => true with the negotiated TLS version and cipher. ssl => false means the session fell back to plaintext.

Common gotchas

• PostgreSQL’s default sslmode of prefer silently falls back to an unencrypted connection if TLS negotiation fails. Set require, verify-ca, or verify-full to make encryption mandatory.
• On container deployments, the .env certificate paths must be the in-container paths from the volume mount, not the host paths. A host path in .env fails with a “file not found” style connection error.
• Certificate files that the web server user cannot read cause every database connection to fail, which takes the whole application down. Verify permissions before restarting services.
• The MySQL and MariaDB certificate paths are also passed to mysqldump for database backups. If you later move or rotate the certificates, update .env at the same time or scheduled backups will start failing.

What’s next

• Set up SSL for the rConfig web interface →
• Configure scheduled system and database backups →
• Tune database performance settings →