|
|
|
|
@ -15,9 +15,8 @@ plugin modules that tailor the behavior of the program.
|
|
|
|
|
* [Global Settings](#global-settings)
|
|
|
|
|
* [Service](#service)
|
|
|
|
|
* [Server](#server)
|
|
|
|
|
* [Server and SSL](#server-and-ssl)
|
|
|
|
|
* [Listener](#listener)
|
|
|
|
|
* [Listener and SSL](#listener-and-ssl)
|
|
|
|
|
* [TLS/SSL Encryption](#tlsssl-encryption)
|
|
|
|
|
* [Router Modules](#routing-modules)
|
|
|
|
|
* [Diagnostic Modules](#diagnostic-modules)
|
|
|
|
|
* [Monitor Modules](#monitor-modules)
|
|
|
|
|
@ -198,13 +197,14 @@ auth_write_timeout=10
|
|
|
|
|
|
|
|
|
|
#### `query_retries`
|
|
|
|
|
|
|
|
|
|
The number of times an interrupted query will be retried. This feature was added
|
|
|
|
|
in MaxScale 2.1.10 and is disabled by default.
|
|
|
|
|
The number of times an interrupted internal query will be retried. This feature
|
|
|
|
|
was added in MaxScale 2.1.10 and is disabled by default.
|
|
|
|
|
|
|
|
|
|
An interrupted query is any query that is interrupted by a network
|
|
|
|
|
error. Connection timeouts are included in network errors and thus is it
|
|
|
|
|
advisable to make sure that the value of `query_retry_timeout` is set to an
|
|
|
|
|
adequate value.
|
|
|
|
|
adequate value. Internal queries are only used to retrieve authentication data
|
|
|
|
|
and monitor the servers.
|
|
|
|
|
|
|
|
|
|
#### `query_retry_timeout`
|
|
|
|
|
|
|
|
|
|
@ -1183,100 +1183,6 @@ Option string given to the authenticator module. The value of this parameter
|
|
|
|
|
should be a comma-separated list of key-value pairs. See authenticator specific
|
|
|
|
|
documentation for more details.
|
|
|
|
|
|
|
|
|
|
### Server and SSL
|
|
|
|
|
|
|
|
|
|
This section describes configuration parameters for servers that control the
|
|
|
|
|
SSL/TLS encryption method and the various certificate files involved in it when
|
|
|
|
|
applied to back end servers. To enable SSL between MaxScale and a back end
|
|
|
|
|
server, you must configure the `ssl` parameter in the relevant server section to
|
|
|
|
|
the value `required` and provide the three files for `ssl_cert`, `ssl_key` and
|
|
|
|
|
`ssl_ca_cert`. After this, MaxScale connections to this server will be encrypted
|
|
|
|
|
with SSL. Attempts to connect to the server without using SSL will cause
|
|
|
|
|
failures. Hence, the database server in question must have been configured to be
|
|
|
|
|
able to accept SSL connections.
|
|
|
|
|
|
|
|
|
|
#### `ssl`
|
|
|
|
|
|
|
|
|
|
This enables SSL connections to the server, when set to `required`. If that is
|
|
|
|
|
done, the three certificate files mentioned below must also be supplied.
|
|
|
|
|
MaxScale connections to this server will then be encrypted with SSL. If this is
|
|
|
|
|
not possible, client connection attempts that rely on the server will fail.
|
|
|
|
|
|
|
|
|
|
#### `ssl_key`
|
|
|
|
|
|
|
|
|
|
A string giving a file path that identifies an existing readable file. The file
|
|
|
|
|
must be the SSL client private key MaxScale should use with the server. This
|
|
|
|
|
will be the private key that is used as the client side private key during a
|
|
|
|
|
MaxScale-server SSL handshake. This is currently a required parameter for SSL
|
|
|
|
|
enabled servers.
|
|
|
|
|
|
|
|
|
|
#### `ssl_cert`
|
|
|
|
|
|
|
|
|
|
A string giving a file path that identifies an existing readable file. The file
|
|
|
|
|
must be the SSL client certificate MaxScale should use with the server. This
|
|
|
|
|
will be the public certificate that is used as the client side certificate
|
|
|
|
|
during a MaxScale-server SSL handshake. This is a required parameter for SSL
|
|
|
|
|
enabled servers. The certificate must be compatible with the key defined above.
|
|
|
|
|
|
|
|
|
|
#### `ssl_ca_cert`
|
|
|
|
|
|
|
|
|
|
A string giving a file path that identifies an existing readable file. The file
|
|
|
|
|
must be the SSL Certificate Authority (CA) certificate for the CA that signed
|
|
|
|
|
the client certificate referred to in the previous parameter. It will be used to
|
|
|
|
|
verify that the client certificate is valid. This is a required parameter for
|
|
|
|
|
SSL enabled listeners.
|
|
|
|
|
|
|
|
|
|
#### `ssl_version`
|
|
|
|
|
|
|
|
|
|
This parameter controls the level of encryption used. Accepted values are:
|
|
|
|
|
|
|
|
|
|
* TLSv10
|
|
|
|
|
* TLSv11
|
|
|
|
|
* TLSv12
|
|
|
|
|
* MAX
|
|
|
|
|
|
|
|
|
|
The default is to use the highest level of encryption available. For OpenSSL 1.0
|
|
|
|
|
and newer this is TLSv1.2. Older versions use TLSv1.0 as the default transport
|
|
|
|
|
layer encryption.
|
|
|
|
|
|
|
|
|
|
**Note:** It is highly recommended to leave this parameter to the default value
|
|
|
|
|
of _MAX_. This will guarantee that the strongest available encryption is used.
|
|
|
|
|
|
|
|
|
|
#### `ssl_cert_verification_depth`
|
|
|
|
|
|
|
|
|
|
The maximum length of the certificate authority chain that will be accepted.
|
|
|
|
|
Legal values are positive integers. Note that if the client is to submit an SSL
|
|
|
|
|
certificate, the `ssl_cert_verification_depth` parameter must not be 0. If no
|
|
|
|
|
value is specified, the default is 9.
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
# Example
|
|
|
|
|
ssl_cert_verification_depth=5
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**Example SSL enabled server configuration:**
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
[server1]
|
|
|
|
|
type=server
|
|
|
|
|
address=10.131.24.62
|
|
|
|
|
port=3306
|
|
|
|
|
protocol=MySQLBackend
|
|
|
|
|
#persistpoolmax=200
|
|
|
|
|
persistmaxtime=3000
|
|
|
|
|
ssl=required
|
|
|
|
|
ssl_version=TLSv10
|
|
|
|
|
ssl_cert=/usr/local/mariadb/maxscale/ssl/crt.max-client.pem
|
|
|
|
|
ssl_key=/usr/local/mariadb/maxscale/ssl/key.max-client.pem
|
|
|
|
|
ssl_ca_cert=/usr/local/mariadb/maxscale/ssl/crt.ca.maxscale.pem
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
This example configuration requires all connections to this server to be
|
|
|
|
|
encrypted with SSL. It also specifies that TLSv1.0 should be used as the
|
|
|
|
|
encryption method. The paths to the server certificate files and the Certificate
|
|
|
|
|
Authority file are also provided.
|
|
|
|
|
|
|
|
|
|
### Listener
|
|
|
|
|
|
|
|
|
|
The listener defines a port and protocol pair that is used to listen for
|
|
|
|
|
@ -1390,73 +1296,98 @@ This protocol module is currently still under development, it provides a means
|
|
|
|
|
to create HTTP connections to MariaDB MaxScale for use by web browsers or
|
|
|
|
|
RESTful API clients.
|
|
|
|
|
|
|
|
|
|
### Listener and SSL
|
|
|
|
|
### TLS/SSL encryption
|
|
|
|
|
|
|
|
|
|
This section describes configuration parameters for listeners that control the
|
|
|
|
|
SSL/TLS encryption method and the various certificate files involved in it. To
|
|
|
|
|
enable SSL from client to MaxScale, you must configure the `ssl` parameter to
|
|
|
|
|
the value `required` and provide the three files for `ssl_cert`, `ssl_key` and
|
|
|
|
|
`ssl_ca_cert`. After this, MySQL connections to this listener will be encrypted
|
|
|
|
|
with SSL. Attempts to connect to the listener with a non-SSL client will fail.
|
|
|
|
|
Note that the same service can have an SSL listener and a non-SSL listener if
|
|
|
|
|
you wish, although they must be on different ports.
|
|
|
|
|
This section describes configuration parameters for both servers and listeners
|
|
|
|
|
that control the TLS/SSL encryption method and the various certificate files
|
|
|
|
|
involved in it.
|
|
|
|
|
|
|
|
|
|
To enable TLS/SSL for a listener or a server, you must set the `ssl` parameter
|
|
|
|
|
to `required` and provide the three files for `ssl_cert`, `ssl_key` and
|
|
|
|
|
`ssl_ca_cert`.
|
|
|
|
|
|
|
|
|
|
After this, MaxScale connections between the server and/or the client will be
|
|
|
|
|
encrypted. Note that the database must be configured to use TLS/SSL connections
|
|
|
|
|
if backend connection encryption is used. When client-side encryption is
|
|
|
|
|
enabled, only encrypted connections to MaxScale can be created.
|
|
|
|
|
|
|
|
|
|
#### `ssl`
|
|
|
|
|
|
|
|
|
|
This enables SSL connections to the listener, when set to `required`. If that is
|
|
|
|
|
done, the three certificate files mentioned below must also be supplied. Client
|
|
|
|
|
connections to this listener will then be encrypted with SSL. Non-SSL
|
|
|
|
|
connections will get an error when they try to connect to the listener.
|
|
|
|
|
This enables SSL connections when set to `required`. If enabled, the three
|
|
|
|
|
certificate files mentioned below must also be supplied. MaxScale connections
|
|
|
|
|
to will then be encrypted with TLS/SSL.
|
|
|
|
|
|
|
|
|
|
#### `ssl_key`
|
|
|
|
|
|
|
|
|
|
A string giving a file path that identifies an existing readable file. The file
|
|
|
|
|
must be the SSL private key the listener should use. This will be the private
|
|
|
|
|
key that is used as the server side private key during a client-server SSL
|
|
|
|
|
handshake. This is a required parameter for SSL enabled listeners.
|
|
|
|
|
must be the SSL client private key MaxScale should use. This is a required
|
|
|
|
|
parameter for SSL enabled configurations.
|
|
|
|
|
|
|
|
|
|
#### `ssl_cert`
|
|
|
|
|
|
|
|
|
|
A string giving a file path that identifies an existing readable file. The file
|
|
|
|
|
must be the SSL certificate the listener should use. This will be the public
|
|
|
|
|
certificate that is used as the server side certificate during a client-server
|
|
|
|
|
SSL handshake. This is a required parameter for SSL enabled listeners. The
|
|
|
|
|
certificate must be compatible with the key defined above.
|
|
|
|
|
must be the SSL client certificate MaxScale should use with the server. This is
|
|
|
|
|
a required parameter for SSL enabled configurations. The certificate must match
|
|
|
|
|
the key defined in `ssl_key`.
|
|
|
|
|
|
|
|
|
|
#### `ssl_ca_cert`
|
|
|
|
|
|
|
|
|
|
A string giving a file path that identifies an existing readable file. The file
|
|
|
|
|
must be the SSL Certificate Authority (CA) certificate for the CA that signed
|
|
|
|
|
the server certificate referred to in the previous parameter. It will be used to
|
|
|
|
|
verify that the server certificate is valid. This is a required parameter for
|
|
|
|
|
SSL enabled listeners.
|
|
|
|
|
must be the Certificate Authority (CA) certificate for the CA that signed the
|
|
|
|
|
certificate referred to in the previous parameter. It will be used to verify
|
|
|
|
|
that the certificate is valid. This is a required parameter for SSL enabled
|
|
|
|
|
configurations.
|
|
|
|
|
|
|
|
|
|
#### `ssl_version`
|
|
|
|
|
|
|
|
|
|
This parameter controls the level of encryption used. Accepted values are:
|
|
|
|
|
|
|
|
|
|
* TLSv10
|
|
|
|
|
* TLSv11
|
|
|
|
|
* TLSv12
|
|
|
|
|
* MAX
|
|
|
|
|
|
|
|
|
|
If possible, use TLSv12 for best security. Recent Linux systems will include a
|
|
|
|
|
version of OpenSSL that supports TLS version 1.2. Only if you are using
|
|
|
|
|
MaxScale on a system that does not have OpenSSL with support for this should
|
|
|
|
|
earlier versions be used. It is unlikely that TLS 1.1 will be available unless
|
|
|
|
|
TLS 1.2 is also available. MAX will use the best available version.
|
|
|
|
|
The default is to use the highest level of encryption available. For OpenSSL 1.0
|
|
|
|
|
and newer this is TLSv1.2. Older versions use TLSv1.0 as the default transport
|
|
|
|
|
layer encryption.
|
|
|
|
|
|
|
|
|
|
#### `ssl_cert_verification_depth`
|
|
|
|
|
**Note:** It is highly recommended to leave this parameter to the default value
|
|
|
|
|
of _MAX_. This will guarantee that the strongest available encryption is used.
|
|
|
|
|
|
|
|
|
|
#### `ssl_cert_verify_depth`
|
|
|
|
|
|
|
|
|
|
The maximum length of the certificate authority chain that will be accepted.
|
|
|
|
|
Legal values are positive integers. Note that if the client is to submit an SSL
|
|
|
|
|
certificate, the `ssl_cert_verification_depth` parameter must not be 0. If no
|
|
|
|
|
certificate, the `ssl_cert_verify_depth` parameter must not be 0. If no
|
|
|
|
|
value is specified, the default is 9.
|
|
|
|
|
|
|
|
|
|
#### `ssl_verify_peer_certificate`
|
|
|
|
|
|
|
|
|
|
Peer certificate verification. This functionality is enabled by default.
|
|
|
|
|
|
|
|
|
|
When this feature is enabled, the certificate sent by the peer is verified
|
|
|
|
|
against the configured Certificate Authority. If you are using self-signed
|
|
|
|
|
certificates, disable this feature.
|
|
|
|
|
|
|
|
|
|
**Example SSL enabled server configuration:**
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
# Example
|
|
|
|
|
ssl_cert_verification_depth=5
|
|
|
|
|
[server1]
|
|
|
|
|
type=server
|
|
|
|
|
address=10.131.24.62
|
|
|
|
|
port=3306
|
|
|
|
|
protocol=MySQLBackend
|
|
|
|
|
ssl=required
|
|
|
|
|
ssl_cert=/usr/local/mariadb/maxscale/ssl/crt.max-client.pem
|
|
|
|
|
ssl_key=/usr/local/mariadb/maxscale/ssl/key.max-client.pem
|
|
|
|
|
ssl_ca_cert=/usr/local/mariadb/maxscale/ssl/crt.ca.maxscale.pem
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
This example configuration requires all connections to this server to be
|
|
|
|
|
encrypted with SSL. The paths to the certificate files and the Certificate
|
|
|
|
|
Authority file are also provided.
|
|
|
|
|
|
|
|
|
|
**Example SSL enabled listener configuration:**
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
@ -1464,21 +1395,16 @@ ssl_cert_verification_depth=5
|
|
|
|
|
type=listener
|
|
|
|
|
service=RW Split Router
|
|
|
|
|
protocol=MySQLClient
|
|
|
|
|
address=10.131.218.83
|
|
|
|
|
port=3306
|
|
|
|
|
authenticator=MySQL
|
|
|
|
|
ssl=required
|
|
|
|
|
ssl_cert=/usr/local/mariadb/maxscale/ssl/crt.maxscale.pem
|
|
|
|
|
ssl_key=/usr/local/mariadb/maxscale/ssl/key.csr.maxscale.pem
|
|
|
|
|
ssl_ca_cert=/usr/local/mariadb/maxscale/ssl/crt.ca.maxscale.pem
|
|
|
|
|
ssl_version=TLSv12
|
|
|
|
|
ssl_cert_verify_depth=9
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
This example configuration requires all connections to be encrypted with SSL. It
|
|
|
|
|
also specifies that TLSv1.2 should be used as the encryption method. The paths
|
|
|
|
|
to the server certificate files and the Certificate Authority file are also
|
|
|
|
|
provided.
|
|
|
|
|
This example configuration requires all connections to be encrypted with
|
|
|
|
|
SSL. The paths to the certificate files and the Certificate Authority file are
|
|
|
|
|
also provided.
|
|
|
|
|
|
|
|
|
|
## Routing Modules
|
|
|
|
|
|
|
|
|
|
|
Markus Mäkelä