Skip to content

DOCS-5876 Update MaxScale hardening documentation #166

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Nov 6, 2025
Merged

DOCS-5876 Update MaxScale hardening documentation #166

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4eeb4e8
DOCS-5876 Update MaxScale hardening documentation
ekorh475 Nov 5, 2025
d2fabdf
Merge branch 'main' into maxscale-ssl
mariadb-stefan-hinz Nov 6, 2025
File filter

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
295 changes: 162 additions & 133 deletions maxscale/maxscale-security/securing-your-maxscale-deployment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,57 +2,49 @@

## Securing Your MaxScale Deployment

There are five main components that you need to make sure are completed
before you go into production:
The following hardening steps are recommended before going into production:

* Encrypting Plaintext Passwords
* Securing the GUI Interface
* Managing Users & Passwords
* Enabling Audit Logging
* Encrypting Database Connections
* Encrypt plaintext passwords
* Secure GUI & Admin Interface Connections
* Change Admin User & Password
* Enable Audit Logging
* Encrypt Incoming Database Connections
* Encrypt Outgoing Database Connections

### Encrypting Plaintext Passwords
### Encrypt Plaintext Passwords

Ensuring the security of your MaxScale setup involves stringent control over
the key file permissions. Utilizing
[maxkeys](../maxscale-management/deployment/maxscale-configuration-guide.md#encrypting-passwords)
is an effective approach to generate a secure key file.
MaxScale configuration includes credentials MaxScale uses to e.g. monitor
database servers. By default, the passwords are written in plaintext in the
configuration file, which exposes them to being accidentally shared. Reduce this
risk by encrypting the passwords. Generate an encryption key with the
*maxkeys*-command and then convert plaintext passwords to encrypted form with
the *maxpasswd*-command.

This generates a keyfile in `/var/lib/maxscale`
Run `maxkeys` to generate a key file in `/var/lib/maxscale`. File ownership is
given to the *maxscale* user and only the owner has read-permissions to the
file.

```
$ maxkeys
```
Once generated, the key file can be relocated to a secure location. This key
file serves a dual purpose: it enables the encryption of passwords and
decrypting those encrypted passwords. Typically, the MaxScale administrator
encrypts passwords and MaxScale itself decrypts them when required.

See
[Encrypting Passwords](../maxscale-management/deployment/maxscale-configuration-guide.md#encrypting-passwords)
for more information about `maxkeys`.

Once generated, this key file can be relocated to a secure location. This
key file serves a dual purpose: it enables the encryption of passwords and
facilitates MaxScale in decrypting those encrypted passwords.

To maintain confidentiality, it is crucial to adjust the ownership and
permissions of the key file appropriately using `chown`. This step ensures
that the key file remains secure and inaccessible to unauthorized users.

```
$ chown maxscale:maxscale /var/lib/maxscale/.secrets
```

Following the secure setup of the key file, you can proceed to encrypt the
plaintext passwords of users already created in your databases.
The key file must remain secure to maintain the security of the encrypted
passwords. If an attacker can read the contents of the key file, they can also
decrypt any passwords read from the configuration file. Use *chown* and *chmod*
to restrict access.

Encrypt plaintext passwords used in MaxScale configuration with `maxpasswd`.
```
$ maxpasswd plaintextpassword
96F99AA1315BDC3604B006F427DD9484
```

These encrypted passwords can then replace the plaintext passwords in your
MaxScale configuration (CNF) files. This enhances the overall security
of your database system by reducing the risk that passwords are accidentally
shared.

Replace the plaintext passwords in your MaxScale configuration (CNF) files with
the encrypted versions. This enhances overall security by reducing the risk that
passwords are accidentally shared.
```
[MariaDB-Service]
type=service
Expand All @@ -62,24 +54,17 @@ user=maxscale-user
password=96F99AA1315BDC3604B006F427DD9484
```

### Securing the GUI Interface

To enhance the security of your MaxScale environment, it’s crucial to
configure the GUI host address properly. The default setting, `0.0.0.0`,
allows unrestricted access from any network, which poses a significant
security risk. Instead, you should set the `admin_host` to a more secure
address. Additionally, you can change the default port (8989) to another
port for added security. For example, you can restrict access to the
localhost by setting:
See [encrypting-passwords](../maxscale-management/deployment/maxscale-configuration-guide.md#encrypting-passwords)
for more information regarding password encryption.

```
[maxscale]
admin_host=127.0.0.1
admin_port=2222
```
### Secure GUI & Admin Interface Connections

Alternatively, you can specify an internal network IP address to limit
access within your internal network, such as:
MaxScale is managed during runtime through the REST-API admin interface. This
interface is used by the GUI and the *MaxCtrl* utility. It can even be accessed
using *curl*. By default, the admin interface only accepts local connections. If
you need to allow external access, modify the `admin_host` setting to change the
network the admin interface listens on. To mitigate the security risk of
external access, you can change the listening port to a non-default value.

```
[maxscale]
Expand All @@ -88,25 +73,25 @@ admin_port=2222
```

If you need to allow external access, ensure that the network is adequately
secured and that only authorized users can access the MaxScale
interface. Consult with your network administrator to determine the most
appropriate and secure configuration.
secured and that only authorized users can access the MaxScale interface.
Consult with your network administrator to determine the most appropriate and
secure configuration.

#### Enabling TLS Encryption
#### Enable TLS Encryption

To further secure your MaxScale setup, enable TLS encryption for data in
To properly secure the MaxScale REST-API, enable TLS encryption for data in
transit. Follow these steps to configure SSL:

**1. Set Up SSL Keys and Certificates:**
**1. Generate SSL key and certificate:**

* Generate SSL keys and certificates. See [Certificate Creation with OpenSSL](../../server/security/securing-mariadb/encryption/data-in-transit-encryption/certificate-creation-with-openssl.md)
* Add them to the MaxScale configuration file.
* See [Certificate Creation with OpenSSL](https://app.gitbook.com/s/SsmexDFPv2xG2OTyO5yV/security/securing-mariadb/encryption/data-in-transit-encryption/certificate-creation-with-openssl.md)
for information on certificate creation.
* Move the generated files to a secure location MaxScale can access.

**2. Update the MaxScale Configuration:**
**2. Update MaxScale configuration:**

* Enable secure connections by setting `admin_secure_gui` to `true`.
* Specify the paths to the SSL certificate and key files in your CNF file:

```
[maxscale]
admin_secure_gui=true
Expand All @@ -117,65 +102,44 @@ admin_ssl_ca_cert=/certs/ca-cert.pem

**3. Verify Encryption:**

* Use the `Maxctrl` command to verify that TLS encryption is functioning correctly:

* Use `maxctrl` to verify that TLS encryption is functioning correctly:
```
$ maxctrl --user=my_user --password=my_password --secure --tls-ca-cert=/certs/ca-cert.pem --tls-verify-server-cert=false show maxscale
```

**4. Update Default Credentials:**

* It’s essential to change the default admin passwords. Create a new user with a strong password and remove the default admin user for enhanced security.

### Managing Users & Passwords
### Change Admin User & Password

MaxScale allows you to manage user access to its GUI, offering different
permission levels to suit various operational needs. Currently, MaxScale
supports two primary roles: `admin` and `basic`. This functionality is
particularly useful for organizations with hierarchical structures or
distinct departments, enabling you to grant status view access without
allowing execution or manipulation capabilities.

#### Creating and Deleting Users

To create or delete users in the MaxScale GUI, you can use the `maxctrl`
command. Here’s an example of creating a user with administrative
privileges:
The REST-API is initially configured to be accessed with username `admin` and
password `mariadb`. Any attacker would try these credentials first, so create a
new user account and delete the default one.

To create or delete REST-API users, use the `maxctrl`-command. To create a user
with administrative privileges, run:
```
$ maxctrl create user my_user my_password --type=admin
```
The password must be in cleartext.

To remove an existing user, such as the default admin user, you can use the following command:

To remove an existing user, such as the default admin user, use the following
command:
```
$ maxctrl destroy user admin
```
After these commands, MaxCtrl will no longer work unless you define credentials
either on the command line or in a config file.
See [MaxCtrl documentation](../reference/maxscale-maxctrl.md) for more
information.

#### Managing Users in the GUI

The MaxScale GUI also provides functionality to manage user access and
update the admin password. Through the GUI, you can:

* Add Users: Create users with basic or admin access.
* Modify User Permissions: Change roles as needed to adapt to evolving security requirements.
* Update Admin Password: Enhance security by regularly updating the admin password.
REST-API user accounts have one of two roles: *admin* and *basic*. *admin*
allows full read and write access, *basic* only allows reading.

By leveraging these features, you can ensure that your MaxScale environment
remains secure and that user access is appropriately managed according to
your organization’s needs.
REST-API user accounts can also be managed through the GUI.

### Enabling Audit Logging
### Enable Audit Logging

Turn on admin auditing to log all login, connection, and configuration
changes. Choose an audit file location and set up log rotation.

#### Enabling and Managing Admin Auditing in MaxScale

Admin auditing in MaxScale provides comprehensive tracking of all
administrative activities, including logins, connections, and
modifications. These activities are recorded in an audit file for enhanced
security and traceability.
Admin auditing in MaxScale provides comprehensive tracking of all administrative
activities, including logins, connections, and modifications. These activities
are recorded in an audit file for enhanced security and traceability.

To enable admin auditing, add the following configuration to your MaxScale
configuration file:
Expand All @@ -186,60 +150,125 @@ admin_audit = true
admin_audit_file = /var/log/maxscale/audit_files/audit.csv
```

This configuration activates auditing and specifies the location of the
audit file. Ensure that the specified directory exists before restarting
MaxScale.
This configuration activates auditing and specifies the location of the audit
file. Ensure that the specified directory exists before restarting MaxScale.

#### Setting Up and Managing Audit Logs
Implement log rotation to manage the size and number of audit files. This can be
achieved using standard Linux log rotation tools. See
[Rotating Logs on Unix and Linux](https://app.gitbook.com/s/SsmexDFPv2xG2OTyO5yV/server-management/server-monitoring-logs/rotating-logs-on-unix-and-linux.md)

**1. Enable Auditing:**
For manual log rotation, use the following MaxCtrl command:
```
$ maxctrl rotate logs
```

* Add the configuration lines to your MaxScale configuration file.
* Verify the directory specified in `admin_audit_file` exists.
### Encrypt Incoming Database Connections

**2. Audit File Management:**
Incoming database connections are the connections clients make to
MaxScale. Without encryption, an eavesdropper can listen to the client queries
and server responses. To enable encryption, MaxScale listeners need to be
configured for TLS.

* Implement log rotation to manage the size and number of audit files. This
can be achieved using standard Linux log rotation tools. See [Rotating Logs on Unix and Linux](../../server/server-management/server-monitoring-logs/rotating-logs-on-unix-and-linux.md)
#### 1. Enable TLS:

For manual log rotation, you can use the following MaxCtrl command:
Add `ssl=true` to the listener section in your MaxScale configuration file. This
enforces encrypted connections from incoming clients. The listener also
requires a certificate and its private key, configured with settings `ssl_cert`
and `ssl_key`. If using a X509v3 certificate with extendedKeyUsage extension
settings, the *serverAuth* flag should be set in the certificate.

The listener section should look like:
```
$ maxctrl rotate logs
[RWS-Listener]
type=listener
service=RWS-Service
ssl=true
ssl_key=/certs/my-cert-key.pem
ssl_cert=/certs/my-cert.pem
```

### Encrypting Database Connections
In MaxScale 25.10, the `ssl_cert` and `ssl_key` settings can be omitted, which
causes MaxScale to generate a self-signed certificate during startup. Recent
client versions (11.4 and later) can even verify this auto-generated
certificate.

For more information on SSL settings, see
[here](../maxscale-management/deployment/maxscale-configuration-guide.md#settings-for-tlsssl-encryption)

#### 2. Verify client certificates

If you want MaxScale to verify client certificates against a CA-certificate, set
`ssl_verify_peer_certificate=true` and define the CA-certificate with `ssl_ca`.
```
[RWS-Listener]
type=listener
service=RWS-Service
ssl=true
ssl_key=/certs/my-cert-key.pem
ssl_cert=/certs/my-cert.pem
ssl_ca=/certs/my_ca_cert.pem
```

Configuring SSL Encryption for MaxScale with an Encrypted MariaDB Server
### Encrypt Outgoing Database Connections

If you have already implemented encryption on your MariaDB server, it’s
crucial to extend this encryption configuration to MaxScale to ensure secure
communication. Once encryption is enabled on your MariaDB server, follow
these steps to configure MaxScale to utilize SSL.
Outgoing database connections are the connections MaxScale makes to MariaDB
Servers on behalf of incoming clients. If MaxScale and the servers are running
in the same network, and you consider the network already secure, then
encrypting these connections may not be necessary. If this is not the case, both
MaxScale and the servers need to be configured to use TLS. To configure MariaDB
Server for encryption, see
[Secure Connections Overview](https://app.gitbook.com/s/SsmexDFPv2xG2OTyO5yV/security/securing-mariadb/encryption/data-in-transit-encryption/secure-connections-overview.md).

Steps to Configure SSL in MaxScale:
To enable MaxScale to connect securely to MariaDB Servers:

#### 1. Enable SSL:
#### 1. Enable TLS:

* Add `ssl=true` to each server section in your MaxScale configuration file.
Add `ssl=true` to each server section in your MaxScale configuration file. This
enforces encrypted connections to the server.

#### 2. Verify Peer Certificates:
#### 2. Verify server certificate:

* Add `ssl_verify_peer_certificate=true` to ensure that MaxScale verifies
the server’s SSL certificates, providing an additional layer of security.
If you want MaxScale to verify the server certificate (to ensure it's signed by
a trusted CA), add `ssl_verify_peer_certificate=true`. The CA certificate path
is defined with `ssl_ca`. This prevents MaxScale from routing queries to a
malicious server that has hijacked the address of the real server.

Your MaxScale configuration file should look something like this:
The server section in your MaxScale configuration file should look like:

```
[MariaDB-Server1]
type=server
address=...
port=...
ssl=true
ssl_verify_peer_certificate=true
ssl_ca=/certs/my_ca_cert.pem
```

These settings instruct MaxScale to use SSL for connections to the MariaDB
server and to verify peer certificates, enhancing the security of data in
transit.
If you are using MaxScale 25.10 and a recent MariaDB Server version, certificate
verification no longer requires a ca-certificate. In this case, the `ssl_ca`
setting can be omitted. See [here](https://mariadb.org/mission-impossible-zero-configuration-ssl/)
for more information.

#### 3. Configure a pre-generated certificate for connecting to the server

If the MariaDB Server requires clients (such as MaxScale) to connect with a
verified certificate, then such a certificate must be defined in the MaxScale
configuration, with settings `ssl_cert` and `ssl_key`. If using a X509v3
certificate with extendedKeyUsage extension settings, the *clientAuth* flag
should be set in the certificate.

```
[MariaDB-Server1]
type=server
address=...
port=...
ssl=true
ssl_verify_peer_certificate=true
ssl_key=/certs/my-cert-key.pem
ssl_cert=/certs/my-cert.pem
ssl_ca=/certs/my_ca_cert.pem
```

<sub>_This page is licensed: CC BY-SA / Gnu FDL_</sub>

Expand Down
Loading