MariaDB MaxScale Installation Guide

We recommend to install MaxScale on a separate server, to ensure that there can be no competition of resources between MaxScale and a MariaDB Server that it manages.

Install MariaDB MaxScale From MariaDB Repositories

The recommended approach is to use the MariaDB package repository to install MaxScale. After enabling the repository by following the instructions, MaxScale can be installed with the following commands.

• For RHEL/Rocky Linux/Alma Linux, use dnf install maxscale.

• For Debian and Ubuntu, run apt update followed by apt install maxscale.

• For SLES, use zypper install maxscale.

Install MariaDB MaxScale From a RPM/DEB Package

Download the correct MaxScale package for your CPU architecture and operating system from the MariaDB Downloads page. MaxScale can be installed with the following commands.

• For RHEL/Rocky Linux/Alma Linux, use dnf install /path/to/maxscale-*.rpm

• For Debian and Ubuntu, use apt install /path/to/maxscale-*.deb.

• For SLES, use zypper install /path/to/maxscale-*.rpm.

Install MariaDB MaxScale Using a Tarball

MaxScale can also be installed using a tarball. That may be required if you are using a Linux distribution for which there exist no installation package or if you want to install many different MaxScale versions side by side. For instructions on how to do that, please refer toInstall MariaDB MaxScale using a Tarball.

Building MariaDB MaxScale From Source Code

Alternatively you may download the MariaDB MaxScale source and build your own binaries. To do this, refer to the separate documentBuilding MariaDB MaxScale from Source Code

Assumptions

Memory allocation behavior

MaxScale assumes that memory allocations always succeed and in general does not check for memory allocation failures. This assumption is compatible with the Linux kernel parametervm.overcommit_memory having the value 0, which is also the default on most systems.

With vm.overcommit_memory being 0, memory allocations made by an application never fail, but instead the application may be killed by the so-called OOM (out-of-memory) killer if, by the time the application actually attempts to use the allocated memory, there is not available free memory on the system.

If the value is 2, then a memory allocation made by an application may fail and unless the application is prepared for that possibility, it will likely crash with a SIGSEGV. As MaxScale is not prepared to handle memory allocation failures, it will crash in this situation.

The current value of vm.overcommit_memory can be checked with

sysctl vm.overcommit_memory

or

cat /proc/sys/vm/overcommit_memory

Configuring MariaDB MaxScale

The MaxScale Tutorial covers the first steps in configuring your MariaDB MaxScale installation. Follow this tutorial to learn how to configure and start using MaxScale.

For a detailed list of all configuration parameters, refer to theConfiguration Guide and the module specific documents listed in the Documentation Contents.

Encrypting Passwords

Read the Encrypting Passwords section of the configuration guide to set up password encryption for the configuration file.

Administration Of MariaDB MaxScale

There are various administration tasks that may be done with MariaDB MaxScale. A command line tools is available, maxctrl, that will interact with a running MariaDB MaxScale and allow the status of MariaDB MaxScale to be monitored and give some control of the MariaDB MaxScale functionality.

The administration tutorial covers the common administration tasks that need to be done with MariaDB MaxScale.

Copying or Backing Up MaxScale

The main configuration file for MaxScale is in /etc/maxscale.cnf and additional user-created configuration files are in/etc/maxscale.cnf.d/. Objects created or modified at runtime are stored in/var/lib/maxscale/maxscale.cnf.d/. Some modules also store internal data in/var/lib/maxscale/ named after the module or the configuration object.

The simplest way to back up the configuration and runtime data of a MaxScale installation is to create an archive from the following files and directories:

• /etc/maxscale.cnf

• /etc/maxscale.cnf.d/

• /var/lib/maxscale/

This can be done with the following command:

tar -caf maxscale-backup.tar.gz /etc/maxscale.cnf /etc/maxscale.cnf.d/ /var/lib/maxscale/

If MaxScale is configured to store data in custom locations, these should be included in the backup as well.

_{This page is licensed: CC BY-SA / Gnu FDL}

WEBINAR

New innovations in MaxScale 25.01 and Enterprise Platform

Watch Now

Before upgrading to MariaDB MaxScale, it is critical to review the changes. This guide outlines new features, altered parameters, and deprecated functionality to ensure a smooth transition.

For more information about what has changed, please refer to theChangeLog and to the release notes.

Before starting the upgrade, any existing configuration files should be backed up.

Upgrading MariaDB MaxScale from 24.02 to 25.01

Readwritesplit

reuse_prepared_statements

The reuse_prepared_statements parameter has been replaced with the use of the PsReuse filter module.

The functionality that previously was enabled with:

[My-Readwritesplit]
type=service
router=readwritesplit
reuse_prepared_statements=true

Should now be implemented with:

[PsReuse]
type=filter
module=psreuse

[My-Readwritesplit]
type=service
router=readwritesplit
filters=PsReuse

optimistic_trx

The optimistic_trx parameter has been replaced with the use of theOptimisticTrx filter module.

The functionality that previously was enabled with:

[My-Readwritesplit]
type=service
router=readwritesplit
optimistic_trx=true

Should now be implemented with:

[OptimisticTrx]
type=filter
module=optimistictrx

[My-Readwritesplit]
type=service
router=readwritesplit
transaction_replay=true
filters=OptimisticTrx

Upgrading MariaDB MaxScale from 23.08 to 24.02

Downgrading to older major versions

The MaxScale packaging has been modified in 24.02 to include all of the necessary files in the package itself. This removes the need for a post-installation script that installs them while also clearly stating what's included in the package.

However, as a result of this change, downgrades from 24.02 to older major versions may cause the removal of necessary directories, namely the /var/cache/maxscale/ directory.

To downgrade from MaxScale 24.02 to an older MaxScale major release:

• Remove MaxScale 24.02 (e.g. dnf remove maxscale or apt -y remove maxscale)

• Install the older MaxScale version

Upgrading MariaDB MaxScale from 23.02 to 23.08

MariaDB Monitor switchover requires an additional grant on MariaDB Server 10.5 and later. See Cluster Manipulation Grants for more information.

Upgrading MariaDB MaxScale from 22.08 to 23.02

Removed Features

• The csmon and auroramon monitors have been removed.

• The obsolete maxctrl drain command has been removed.

• The maxctrl cluster commands have been removed.

Upgrading MariaDB MaxScale from 21.06 to 22.08

Removed Features

• The support for legacy encryption keys generated with maxkeys from pre-2.5 versions has been removed. This feature was deprecated in MaxScale 2.5 when the new key storage format was introduced. To migrate to the new key storage format, create a new key file with maxkeys and re-encrypt the passwords withmaxpasswd.

• The deprecated Database Firewall filter has been removed.

Upgrading MariaDB MaxScale from 2.5 to 21.06

Duration Type Parameters

Using duration type parameters without an explicit suffix has been deprecated in MaxScale 2.4. In MaxScale 6 they are no longer allowed when used with the REST API or MaxCtrl. This means that any create or alter commands in MaxCtrl that use a duration type parameter must explicitly specify the suffix of the unit.

For example, the following command:

maxctrl alter service My-Service connection_keepalive 30000

should be replaced with:

maxctrl alter service My-Service connection_keepalive 30000ms

Duration type parameters can still be defined in the configuration file without an explicit suffix but this behavior is deprecated. The recommended approach is to add explicit suffixes to all duration type parameters when upgrading to MaxScale 6.

Changed Parameters

threads

The default value of threads was changed to auto.

Removed Parameters

Core Parameters

The following deprecated core parameters have been removed:

• thread_stack_size

Schemarouter

The deprecated aliases for the schemarouter parameters ignore_databases andignore_databases_regex have been removed. They can be replaced withignore_tables and ignore_tables_regex.

In addition, the preferred_server parameter that was deprecated in 2.5 has also been removed.

mariadbmon

• MariaDBMonitor settings ignore_external_masters, detect_replication_lagdetect_standalone_master, detect_stale_master and detect_stale_slave have been removed. The first two were ineffective, the latter three are replaced by master_conditions and slave_conditions.

Session Command History

The prune_sescmd_history, max_sescmd_history and disable_sescmd_history have been made into generic service parameters that are shared between all routers that support it.

The default value of prune_sescmd_history was changed from false totrue. This was done as most MaxScale installations either benefit from it being enabled or are not affected by it.

Upgrading MariaDB MaxScale from 2.4 to 2.5

MaxAdmin

The deprecated MaxAdmin interface has been removed in 2.5.0 in favor of the REST API and the MaxCtrl command line client. The cli and maxscaled modules can no longer be used.

Authentication

The credentials used by services now require additional grants. For a full list of required grants, refer to the protocol documentation.

MariaDB-Monitor

The settings detect_stale_master, detect_standalone_master anddetect_stale_slave are replaced by master_conditions andslave_conditions. The old settings may still be used, but will be removed in a later version.

Password encryption

The encrypted passwords feature has been updated to be more secure. Users are recommended to generate a new encryption key and re-encrypt their passwords using the maxkeys and maxpasswd utilities. Old passwords still work.

Default Server State

The default state of servers in 2.4 was Running and in 2.5 it is nowDown. This was done to prevent newly added servers from being accidentally used before they were monitored.

Columnstore Monitor

It is now mandatory to specify in the configuration what version the monitored Columnstore cluster is.

[CSMonitor]
type=monitor
module=csmon
version=1.5
...

New binlog router

The binlog router delivered with MaxScale 2.5 is completely new and not 100% backward compatible with the binlog router delivered with earlier MaxScale versions. If you use the binlog router, carefully assess whether the functionality provided by the new one fulfills your requirements, before upgrading MaxScale.

Tee Filter

The tee filter parameter service has been deprecated in favor of the target parameter. All usages of service can be replaced with target.

Upgrading MariaDB MaxScale from 2.3 to 2.4

Section Names

Reserved Names

Section and object names starting with @@ are now reserved for internal use by MaxScale.

In case such names have been used, they must manually be changed in all configuration files of MaxScale, before MaxScale 2.4 is started.

Those files are:

• The main configuration file; typically /etc/maxscale.cnf.

• All nested configuration files; typically /etc/maxscale.cnf.d/*.

• All dynamic configuration files; typically /var/lib/maxscale/maxscale.cnd.d/*.

Whitespace in Names

Whitespace in section names that was deprecated in MaxScale 2.2 will now be rejected, which will cause the startup of MaxScale to fail.

To prevent that, section names like

[My Server]
...

[My Service]
...
servers=My Server

must be changed, for instance, to

[MyServer]
...

[MyService]
...
servers=MyServer

Durations

Durations can now be specified using one of the suffixes h, m, s and ms for specifying durations in hours, minutes, seconds and milliseconds, respectively.

Not providing an explicit unit has been deprecated in MaxScale 2.4, so it is advisable to add suffixes to durations. For instance,

some_param=60s
some_param=60000ms

Improved Admin User Encryption

MaxScale 2.4 will use a SHA2-512 hash for new admin user passwords. To upgrade a user to use the better hashing algorithm, either recreate the user or use themaxctrl alter user command.

MariaDB-Monitor

The following settings have been removed and cause a startup error if defined:

• mysql51_replication

• multimaster

• allow_cluster_recovery.

ReadWriteSplit

• If multiple masters are available for a readwritesplit service, the one with the lowest connection count is selected.

• If a master server is placed into maintenance mode, all open transactions are allowed to gracefully finish before the session is closed. To forcefully close the connections, use the --force option for maxctrl set server.

• The lazy_connect feature can be used as a workaround toMXS-619. It also reduces the overall load on the system when connections are rapidly opened and closed.

• Transaction replays now have a limit on how many times a replay is attempted. The default values is five attempts and is controlled by thetransaction_replay_attempts parameter.

• If transaction replay is enabled and a deadlock occurs (SQLSTATE 40XXX), the transaction is automatically retried.

Upgrading MariaDB MaxScale from 2.2 to 2.3

Increased Memory Use

Starting with MaxScale 2.3.0 up to 40% of the memory can be used for caching parsed queries. The most noticeable change is that it improves performance in almost all cases where queries need to be parsed. Most of the time this happens when the readwritesplit router or filters are used.

The amount of memory that MaxScale uses can be controlled with thequery_classifier_cache_size parameter. For example, to limit the total memory to 1GB, add query_classifier_cache_size=1G to your configuration. To disable it, set the value to 0.

In addition to the aforementioned query classifier caching, the readwritesplit session command history is enabled by default in 2.3 but is limited to a maximum of 50 commands after which the history is disabled. This is unlikely to show in any metrics but it contributes to the increased memory footprint of MaxScale.

Unknown Global Parameters

All unknown parameters are now treated as errors. Check your configuration for errors if MaxScale fails to start after upgrading to 2.3.1.

passwd is deprecated

In the configuration file, passwords for monitors and services should be specified using password; the support for the deprecatedpasswd will be removed in the future. That is, the following

[The-Service]
type=service
passwd=some-service-password
...

[The-Monitor]
type=monitor
passwd=some-monitor-password
...

should be changed to

[The-Service]
type=service
password=some-service-password
...

[The-Monitor]
type=monitor
password=some-monitor-password
...

authenticator_options for servers is ignored

Authenticator options are now only used with listeners.

Upgrading MariaDB MaxScale from 2.1 to 2.2

Administrative Users

The file format for the administrative users used by MaxScale has been changed. Old style files are automatically upgraded and a backup of the old file is stored in /var/lib/maxscale/passwd.backup.

Regular Expression Parameters

Modules may now use a built-in regular expression string parameter type instead of a normal string when accepting patterns. The modules that use the new regex parameter type are qlafilter and tee. When inputting pattern, enclose the string in slashes, e.g. match=/^select/ defines the pattern ^select.

Binlog Server

Binlog server automatically accepts GTID connection from MariaDB 10 slave servers by saving all incoming GTIDs into a SQLite map database.

MaxCtrl Included in Main Package

In the 2.2.1 beta version MaxCtrl was in its own package whereas in 2.2.2 it is in the main maxscale package. If you have a previous installation of MaxCtrl, please remove it before upgrading to MaxScale 2.2.2.

Upgrading MariaDB MaxScale from 2.0 to 2.1

IPv6 Support

MaxScale 2.1.2 added support for IPv6 addresses. The default interface that listeners bind to was changed from the IPv4 address 0.0.0.0 to the IPv6 address ::. To bind to the old IPv4 address, add address=0.0.0.0 to the listener definition.

Persisted Configuration Files

Starting with MaxScale 2.1, any changes made with the newly added runtime configuration change will be persisted in a configuration file. These files are located in /var/lib/maxscale/maxscale.cnf.d/.

MaxScale Log Files

The name of the log file was changed from maxscaleN.log to maxscale.log. The default location for the log file is /var/log/maxscale/maxscale.log.

Rotating the log files will cause MaxScale to reopen the file instead of renaming them. This makes the MaxScale logging facility logrotate compatible.

ReadWriteSplit

The disable_sescmd_history option is now enabled by default. This means that slaves will not be recovered mid-session even if a replacement slave is available. To enable the legacy behavior, add the disable_sescmd_history=true parameter to the service definition.

Persistent Connections

The MariaDB session state is reset in MaxScale 2.1 for persistent connections. This means that any modifications to the session state (default database, user variable etc.) will not survive if the connection is put into the connection pool. For most users, this is the expected behavior.

User Data Cache

The location of the MariaDB user data cache was moved from/var/cache/maxscale/<Service> to /var/cache/maxscale/<Service>/<Listener>.

Galeramon Monitoring Algorithm

Galeramon will assign the master status only to the node which has awsrep_local_index value of 0. This will guarantee consistent writes with multiple MaxScales but it also causes slower changes of the master node.

To enable the legacy behavior, add root_node_as_master=false to the Galera monitor configuration.

MaxAdmin Editing Mode

The default editing mode was changed from vim to emacs mode. To start maxadmin in the legacy mode, use the -i option.

Upgrading MariaDB MaxScale from 1.4 to 2.0

MaxAdmin

The default way the communication between MaxAdmin and MariaDB MaxScale is handled has been changed from an internet socket to a Unix domain socket. The former alternative is still available but has been deprecated.

If no arguments are given to MaxAdmin, it will attempt to connect to MariaDB MaxScale using a Unix domain socket. After the upgrade you will need to provide at least one internet socket related flag - -h, -P,-u or -p - to force MaxAdmin to use the internet socket approach.

E.g.

user@host $ maxadmin -u admin

MySQL Monitor

The MySQL Monitor now assigns the stale state to the master server by default. In addition to this, the slave servers receive the stale slave state when they lose the connection to the master. This should not cause changes in behavior but the output of MaxAdmin will show new states when replication is broken.

Upgrading MaxScale from 1.3 to 1.4

Service user permissions

The service users now also need SELECT privileges on mysql.tables_priv. This is required for the resolution of table level grants. To grant SELECT privileges for the service user, replace the user and hostname in the following example.

GRANT SELECT ON mysql.tables_priv TO 'username'@'maxscalehost';

Password encryption

MaxScale 1.4 upgrades the used password encryption algorithms to more secure ones. This requires that the password files are recreated with the maxkeys tool. For more information about how to do this, please read the installation guide:MariaDB MaxScale Installation Guide

SSL

The SSL configuration parameters are now a part of the listeners. If a service used the old style SSL configuration parameters, the values should be moved to the listener which is associated with that service.

Here is an example of an old style configuration.

[RW-Split-Router]
type=service
router=readwritesplit
servers=server1,server2,server3,server4
user=jdoe
passwd=BD26E4139A15280CA882264AA1551C70
ssl=required
ssl_cert=/home/user/certs/server-cert.pem
ssl_key=/home/user/certs/server-key.pem
ssl_ca_cert=/home/user/certs/ca.pem
ssl_version=TLSv12

[RW-Split-Listener]
type=listener
service=RW-Split-Router
port=3306

And here is the new, 1.4 compatible configuration style.

[RW-Split-Router]
type=service
router=readwritesplit
servers=server1,server2,server3,server4
user=jdoe
passwd=BD26E4139A15280CA882264AA1551C70

[RW-Split-Listener]
type=listener
service=RW-Split-Router
port=3306
ssl=required
ssl_cert=/home/user/certs/server-cert.pem
ssl_key=/home/user/certs/server-key.pem
ssl_ca_cert=/home/user/certs/ca.pem
ssl_version=TLSv12

Please also note that the enabled SSL mode is no longer supported due to the inherent security issues with allowing SSL and non-SSL connections on the same port. In addition to this, SSLv3 is no longer supported due to vulnerabilities found in it.

Upgrading MaxScale from 1.2 to 1.3

Binlog Router

The master server details are now provided with a master.ini file located in the binlog directory and it can be changed using a CHANGE MASTER TO command issued via a MySQL connection to MaxScale.

This file, properly filled, is now mandatory and without it the binlog router cannot connect to the master database.

Before starting binlog router after MaxScale 1.3 upgrade, please add relevant information to master.ini, example:

[binlog_configuration]
master_host=127.0.0.1
master_port=3308
master_user=repl
master_password=somepass
filestem=repl-bin

Additionally, the option servers=masterdb in the service definition is no longer required.

Upgrading MaxScale from 1.1 to 1.2

This document describes upgrading MaxScale from version 1.1.1 to 1.2 and the major differences in the new version compared to the old version. The major changes can be found in the Changelog.txt file in the installation directory and the official release notes in the ReleaseNotes.txt file.

Installation

Upgrading MaxScale will copy the MaxScale.cnf file in/usr/local/mariadb-maxscale/etc/ to /etc/ and renamed to maxscale.cnf. Binary log files are not automatically copied and should be manually moved from /usr/local/mariadb-maxscale to /var/lib/maxscale/.

File location changes

MaxScale 1.2 follows the FHS-standard and installs to /usr/ and /var/ subfolders. Here are the major changes and file locations.

• Configuration files are located in /etc/ and use lowercase letters: /etc/maxscale.cnf

• Binary files are in /usr/bin/

• Libraries and modules are in /usr/lib64/maxscale/. If you are using custom modules, please make sure they are in this directory before starting MaxScale.

• Log files are in the var/log/maxscale/ folder

• MaxScale's PID file is located in /var/run/maxscale/maxscale.pid

• Data files and other persistent files are in /var/lib/maxscale/

Running MaxScale without root permissions

MaxScale can run as a non-root user with the 1.2 version. RPM and DEB packages install the maxscale user and maxscale group which are used by the init scripts and systemd configuration files. If you are installing from a binary tarball, you can run the postinst script included in it to manually create these groups.

Upgrading MaxScale from 1.0 to 1.1

This document describes upgrading MaxScale from version 1.0.5 to 1.1.0 and the major differences in the new version compared to the old version. The major changes can be found in the Changelog.txt file in the installation directory and the official release notes in the ReleaseNotes.txt file.

Installation

If you are installing MaxScale from a RPM package, we recommend you back up your configuration and log files and that you remove the old installation of MaxScale completely. If you choose to upgrade MaxScale instead of removing it and re-installing it afterwards, the init scripts in /etc/init.d folder will be missing. This is due to the RPM packaging system but the script can be re-installed by running the postinst script found in the/usr/local/mariadb-maxscale folder.

# Re-install init scripts
cd /usr/local/mariadb-maxscale
./postinst

The 1.1.0 version of MaxScale installs into /usr/local/mariadb-maxscale instead of /usr/local/skysql/maxscale. This will cause external references to MaxScale's home directory to stop working so remember to update all paths with the new version.

MaxAdmin changes

The MaxAdmin client's default password in MaxScale 1.1.0 is mariadb instead of skysql.

_{This page is licensed: CC BY-SA / Gnu FDL}

Building MariaDB MaxScale from Source Code

MariaDB MaxScale can be built on any system that meets the requirements. The main requirements are as follows:

• CMake version 3.16 or later (Packaging requires CMake 3.25.1 or later)

• GCC version 4.9 or later

• OpenSSL version 1.0.1 or later

• GNUTLS

• Node.js 14 or newer for building MaxCtrl and the GUI (webpack), Node.js 10 or newer for running MaxCtrl

• PAM

• SASL2 (cyrus-sasl)

• SQLite3 version 3.3 or later

• Tcl

• git

• jansson

• libatomic

• libcurl

• libmicrohttpd

• libuuid

• libxml2

• libssh

• pcre2

• zstd

This is the minimum set of requirements that must be met to build the MaxScale core package. Some modules in MaxScale require optional extra dependencies.

• libuuid (binlogrouter)

• boost (binlogrouter)

• Bison 2.7 or later (dbfwfilter)

• Flex 2.5.35 or later (dbfwfilter)

• librdkafka (kafkacdc, kafkaimporter and mirror)

• memcached (storage_memcached for the cache filter)

• hiredis (storage_redis for the cache filter)

Some of these dependencies are not available on all operating systems and are downloaded automatically during the build step. To skip the building of modules that need automatic downloading of the dependencies, use -DBUNDLE=N when configuring CMake.

Quickstart

This installs MaxScale as if it was installed from a package. Install git before running the following commands.

git clone https://github.com/mariadb-corporation/MaxScale
mkdir build
cd build
../MaxScale/BUILD/install_build_deps.sh
cmake ../MaxScale -DCMAKE_INSTALL_PREFIX=/usr
make
sudo make install
sudo ./postinst

Required Packages

For a definitive list of packages, consult theinstall_build_deps.sh script.

Configuring the Build

The tests and other parts of the build can be controlled via CMake arguments.

Here is a small table with the names of the most common parameters and what they control. These should all be given as parameters to the -D switch inNAME=VALUE format (e.g. -DBUILD_TESTS=Y).

Note: You can look into defaults.cmake for a list of the CMake variables.

Running unit tests

To run the MaxScale unit test suite, configure the build with -DBUILD_TESTS=Y, compile and then run the make test command.

Building MariaDB MaxScale packages

If you wish to build packages, just add -DPACKAGE=Y to the CMake invocation and build the package with make package instead of installing MaxScale withmake install. This process will create a RPM/DEB package depending on your system.

To build a tarball, add -DTARBALL=Y to the cmake invocation. This will create a maxscale-x.y.z.tar.gz file where x.y.z is the version number.

Some Debian and Ubuntu systems suffer from a bug where make package fails with errors from dpkg-shlibdeps. This can be fixed by running make beforemake package and adding the path to the libmaxscale-common.so library to the LD_LIBRARY_PATH environment variable.

make
LD_LIBRARY_PATH=$PWD/server/core/ make package

Installing optional components

The MaxScale build system is split into multiple components. The main component is the core MaxScale package which contains MaxScale and all the modules. This is the default component that is build, installed and packaged. There is also the experimental component that contains all experimental modules which are not considered as part of the core MaxScale package and are either alpha or beta quality modules.

To build the experimental modules along with the MaxScale core components, invoke CMake with -DTARGET_COMPONENT=core,experimental.

_{This page is licensed: CC BY-SA / Gnu FDL}

Installing MariaDB MaxScale using a tarball

MariaDB MaxScale is also made available as a tarball, which is named likemaxscale-x.y.z.OS.tar.gz where x.y.z is the same as the corresponding version and OS identifies the operating system, e.g. maxscale-2.5.6.centos.7.tar.gz.

In order to use the tarball, the following libraries are required:

• libcurl

• libaio

• OpenSSL

• gnutls

• libatomic

• unixODBC

The tarball has been built with the assumption that it will be installed in /usr/local. However, it is possible to install it in any directory, but in that case MariaDB MaxScale must be invoked with a flag.

Installing as root in /usr/local

If you have root access to the system you probably want to install MariaDB MaxScale under the user and group maxscale.

The required steps are as follows:

$ sudo groupadd maxscale
$ sudo useradd -g maxscale maxscale
$ cd /usr/local
$ sudo tar -xzvf maxscale-x.y.z.OS.tar.gz
$ sudo ln -s maxscale-x.y.z.OS maxscale
$ cd maxscale
$ sudo chown -R maxscale var

Creating the symbolic link is necessary, since MariaDB MaxScale has been built with the assumption that the plugin directory is /usr/local/maxscale/lib/maxscale.

The symbolic link also makes it easy to switch between different versions of MariaDB MaxScale that have been installed side by side in /usr/local; just make the symbolic link point to another installation.

In addition, the first time you install MariaDB MaxScale from a tarball you need to create the following directories:

$ sudo mkdir /var/log/maxscale
$ sudo mkdir /var/lib/maxscale
$ sudo mkdir /run/maxscale
$ sudo mkdir /var/cache/maxscale

and make maxscale the owner of them:

$ sudo chown maxscale /var/log/maxscale
$ sudo chown maxscale /var/lib/maxscale
$ sudo chown maxscale /run/maxscale
$ sudo chown maxscale /var/cache/maxscale

The following step is to create the MariaDB MaxScale configuration file /etc/maxscale.cnf. The file etc/maxscale.cnf.template can be used as a base. Please refer to Configuration Guide for details.

When the configuration file has been created, MariaDB MaxScale can be started.

$ sudo bin/maxscale --user=maxscale -d

The -d flag causes maxscale not to turn itself into a daemon, which is advisable the first time MariaDB MaxScale is started, as it makes it easier to spot problems.

If you want to place the configuration file somewhere else but in /etc you can invoke MariaDB MaxScale with the --config flag, for instance, --config=/usr/local/maxscale/etc/maxscale.cnf.

Note also that if you want to keep everything under /usr/local/maxscale you can invoke MariaDB MaxScale using the flag --basedir.

$ sudo bin/maxscale --user=maxscale --basedir=/usr/local/maxscale -d

That will cause MariaDB MaxScale to look for its configuration file in/usr/local/maxscale/etc and to store all runtime files under /usr/local/maxscale/var.

Installing in any Directory

Enter a directory where you have the right to create a subdirectory. Then do as follows.

$ tar -xzvf maxscale-x.y.z.OS.tar.gz

The next step is to create the MaxScale configuration file maxscale-x.y.z/etc/maxscale.cnf. The file maxscale-x.y.z/etc/maxscale.cnf.template can be used as a base. Please refer to Configuration Guide for details.

When the configuration file has been created, MariaDB MaxScale can be started.

$ cd maxscale-x.y.z.OS
$ bin/maxscale -d --basedir=.

With the flag --basedir, MariaDB MaxScale is told where the lib, etc and var directories are found. Unless it is specified, MariaDB MaxScale assumes the lib directory is found in /usr/local/maxscale, and the var and etc directories in /.

It is also possible to specify the directories and the location of the configuration file individually. Invoke MaxScale like

$ bin/maxscale --help

to find out the appropriate flags.

_{This page is licensed: CC BY-SA / Gnu FDL}

Introduction

This document describes how to configure MariaDB MaxScale and presents some possible usage scenarios. MariaDB MaxScale is designed with flexibility in mind, and consists of an event processing core with various support functions and plugin modules that tailor the behavior of the program.

Concepts

Glossary

Objects

Server

A server represents an individual database server to which a client can be connected via MariaDB MaxScale. The status of a server varies during the lifetime of the server and typically the status is updated by some monitor. However, it is also possible to update the status of a server manually.

For more information on how to manually set these states via MaxCtrl, read theAdministration Tutorial.

Monitor

A monitor module is capable of monitoring the state of a particular kind of cluster and making that state available to the routers of MaxScale.

Examples of monitor modules are mariadbmon that is capable of monitoring a regular primary-replica cluster and in addition of performing both switchover and failover, galeramon that is capable of monitoring a Galera cluster, and csmon that is capable of monitoring a Columnstore cluster.

Monitor modules have sections of their own in the MaxScale configuration file.

Filter

A filter module resides in front of routers in the request processing chain of MaxScale. That is, a filter will see a request before it reaches the router and before a response is sent back to the client. This allows filters to reject, handle, alter or log information about a request.

Examples of filters cache that provides query caching according to rules,regexfilter that can rewrite requests according to regular expressions, andqlafilter that logs information about requests.

Filters have sections of their own in the MaxScale configuration file that are referred to from services.

Limitations:

• MaxScale: No limitations.

• MaxScale Lite: At most 2 filters can be created.

Router

A router module is capable of routing requests to backend servers according to the characteristics of a request and/or the algorithm the router implements. Examples of routers are readconnroute that provides connection &#xNAN;routing, that is, the server is chosen according to specified rules when the session is created and all requests are subsequently routed to that server, and readwritesplit that provides statement routing, that is, each individual request is routed to the most appropriate server.

Routers do not have sections of their own in the MaxScale configuration file, but are referred to from services.

Service

A service abstracts a set of databases and makes them appear as a single one to the client. Depending on what router (e.g. readconnroute orreadwritesplit) the service uses, the servers are used in some particular way. If the service uses filters, then all requests will be pre-processed in some way before they reach the router.

Services have sections of their own in the MaxScale configuration file.

Limitations:

• MaxScale: No limitations.

• MaxScale Lite: At most 1 service can be created.

Listener

A listener defines a port MaxScale listens on. Connection requests arriving on that port will be forwarded to the service the listener is associated with. A listener may be associated with a single service, but several listeners may be associated with the same service.

Listeners have sections of their own in the MaxScale configuration file.

Include

An include section defines common parameters used in other configuration sections.

Administration

The administration of MaxScale can be divided in two parts:

• Writing the MaxScale configuration file, which is described in the followingsection.

• Performing runtime modifications using MaxCtrl

For detailed information about MaxCtrl please refer to the specific documentation referred to above. In the following it will only be explained how MaxCtrl relate to each other, as far as user credentials go.

Note: By default all runtime configuration changes are saved on disk and loaded on startup. Refer to theDynamic Configuration section for more details on how it works and how to disable it.

MaxCtrl can connect using TCP/IP sockets. When connecting with MaxCtrl using TCP/IP sockets, the user and password must be provided and are checked against a separate user credentials database. By default, that database contains the useradmin whose password is mariadb.

Note that if MaxCtrl is invoked without explicitly providing a user and password then it will by default use admin and mariadb. That means that when the default user is removed, the credentials must always be provided.

Administration audit file

The REST API calls to MaxScale can be logged by enabling admin_audit.

For more detail see the admin audit configuration values admin_audit,admin_audit_file and admin_audit_exclude_methods below and Administration Tutorial.

Static Configuration Parameters

The following list of global configuration parameters can NOT be changed at runtime and can only be defined in a configuration file:

• admin_auth

• admin_enabled

• admin_gui

• admin_host

• admin_pam_readonly_service

• admin_pam_readwrite_service

• admin_readonly_hosts

• admin_readwrite_hosts

• admin_port

• admin_secure_gui

• admin_ssl_ca

• admin_ssl_version

• admin_jwt_algorithm

• admin_jwt_key

• admin_jwt_issuer

• auto_tune

• cachedir

• connector_plugindir

• core_file

• datadir

• debug

• execdir

• language

• libdir

• load_persisted_configs

• persist_runtime_changes

• local_address

• log_augmentation

• log_warn_super_user

• logdir

• module_configdir

• persistdir

• piddir

• query_retries

• secretsdir

• sharedir

• sql_mode

• substitute_variables

• threads_max

All other parameters that relate to objects can be altered at runtime or can be changed by destroying and recreating the object in question.

Configuration

MaxScale by default reads configuration from the file /etc/maxscale.cnf. If the command line argument --configdir=<path> is given, maxscale.cnf is searched for in <path> instead. If the argument --config=<file> is given, configuration is read from the file <file>.

MaxScale also looks for a directory with the same name as the configuration file, followed by ".d" (for example /etc/maxscale.cnf.d). If found, MaxScale recursively reads all files with the ".cnf" suffix in the directory hierarchy. Other files are ignored.

After loading normal configuration files, MaxScale reads runtime-generated configuration files, if any, from thepersisted configuration files directory.

Different configuration sections can be arranged with little restrictions. Global path settings such as logdir, piddir and datadir are only read from the main configuration file. Other global settings are also best left in the main file to ensure they are read before other configuration sections are parsed.

The configuration file format used isINI, similar to the MariaDB Server. The files contain sections and each section can contain multiple key-value pairs.

Comments are defined by prefixing a row with a hash (#). Trailing comments are not supported.

# This is a comment before a parameter
some_parameter=123

A parameter can be defined on multiple lines as shown below. A value spread over multiple lines is simply concatenated. The additional lines of the value definition need to have at least one whitespace character in the beginning.

[MyService]
type=service
router=readconnroute
servers=server1,
        server2,
        server3

Names

Section names may not contain whitespace and must not start with the characters@@.

As the object names are used to form URLs in the MaxScale REST API, they must be safe for use in URLs. This means that only alphanumeric characters (i.e. a-zA-Z and 0-9) and the special characters _.~- can be used.

Dynamic Configuration

By default all changes done at runtime via the MaxScale GUI, MaxCtrl or the REST API will be saved on disk, inside the persistdir directory. The changes done at runtime will override the configuration found in the static configuration files for that particular object.

This means that if an object that is found in /etc/maxscale.cnf is modified at runtime, all future changes to it must also be done at runtime. Any modifications done to /etc/maxscale.cnf after a runtime change has been made are ignored for that object.

To prevent the saving of runtime changes and to make all runtime changes volatile, add persist_runtime_changes=false andload_persisted_configs=false under the [maxscale] section. This will make MaxScale behave like the MariaDB server does: any changes done with SET GLOBAL statements are lost if the process is restarted.

Special Parameter Types

Booleans

Boolean type parameters interpret the values true, yes, on and 1 astrue values and false, no, off and 0 as false values. Starting with MaxScale 23.02, the REST API also accepts the same boolean values for boolean type parameters.

Sizes

Where specifically noted, a number denoting a size can be suffixed by a subset of the IEC binary prefixes or the SI prefixes. In the former case the number will be interpreted as a certain multiple of 1024 and in the latter case as a certain multiple of 1000. The supported IEC binary suffixes are Ki, Mi, Gi and Ti and the supported SI suffixes are k, M, G and T. In both cases, the matching is case-insensitive.

For instance, the following entries

max_size=1099511628000
max_size=1073741824Ki
max_size=1048576Mi
max_size=1024Gi
max_size=1Ti

are equivalent, as are the following

max_size=1000000000000
max_size=1000000000k
max_size=1000000M
max_size=1000G
max_size=1T

Durations

A number denoting a duration can be suffixed by one of the case-insensitive suffixes h, m or min, s and ms, for specifying durations in hours, minutes, seconds and milliseconds, respectively.

For instance, the following entries

soft_ttl=1h
soft_ttl=60m
soft_ttl=60min
soft_ttl=3600s
soft_ttl=3600000ms

are equivalent.

Note that if an explicit unit is not specified, then it is specific to the configuration parameter whether the duration is interpreted as seconds or milliseconds.

Not providing an explicit unit has been deprecated in MaxScale 2.4.

Percent

A number denoting a percent must be suffixed with %.

For instance

some_param=42%

Regular Expressions

Many modules have settings which accept a regular expression. In most cases, these settings are named either match or exclude, and are used to filter users or queries. MaxScale uses the PCRE2-library for matching regular expressions.

When writing a regular expression (regex) type parameter to a MaxScale configuration file, the pattern string should be enclosed in slashes e.g. ^select -> match=/^select/. This clarifies where the pattern begins and ends, even if it includes whitespace. Without slashes the configuration loader trims the pattern from the ends. The slashes are removed before compiling the pattern. For backwards compatibility, the slashes are not yet mandatory. Omitting them is, however, deprecated and will be rejected in a future release of MaxScale. Currently, binlogfilter, ccrfilter, qlafilter, tee and avrorouter accept parameters in this type of regular expression form. Some other modules may not handle the slashes yet correctly.

PCRE2 supports a complicated regular expressionsyntax. MaxScale typically uses regular expressions simply, only checking whether the pattern and subject match at some point. For example, using the QLAFilter and setting match=/SELECT/ causes the filter to accept any query with the text "SELECT" somewhere within. To force the pattern to only match at the beginning of the query, set match=/^SELECT/. To only match the end, setmatch=/SELECT$/.

Modules which accept regular expression parameters also often accept options which affect how the patterns are compiled. Typically, this setting is called options and accepts values such as ignorecase, case and extended.

• ignorecase: Causes the regular expression matcher to ignore letter case, and is often on by default. When enabled, /SELECT/ would match both SELECT andselect.

• extended: Ignores whitespace and # comments in the pattern. Note that this is not the same as the extended regular expression syntax that for examplegrep -E uses.

• case: Turns on case-sensitive matching. This means that /SELECT/ will not match select.

These settings can also be defined in the pattern itself, so they can be used even in modules without pattern compilation settings. The pattern settings are (?i) for ignorecase and (?x) for extended. See thePCRE2 syntax documentation for more information.

Standard regular expression settings for filters

Many filters use the settings match, exclude and options. Since these settings are used in a similar way across these filters, the settings are explained here. The documentation of the filters link here and describe any exceptions to this generalized explanation.

These settings typically limit the queries the filter module acts on. match andexclude define PCRE2 regular expression patterns while options affects how both of the patterns are compiled. options works as explained above, accepting the valuesignorecase, case and extended, with ignorecase being the default.

The queries are matched as they arrive to the filter on their way to a routing module. Ifmatch is defined, the filter only acts on queries matching that pattern. If match is not defined, all queries are considered to match.

If exclude is defined, the filter only acts on queries not matching that pattern. Ifexclude is not defined, nothing is excluded.

If both are defined, the query needs to match match but not match exclude.

Even if a filter does not act on a query, the query is not lost. The query is simply passed on to the next module in the processing chain as if the filter was not there.

Enumerations

Enumeration type parameters have a pre-defined set of accepted values. For types declared as enum, only one value is accepted. For enum_mask types, multiple values can be defined by separating them with commas. All enumeration values in MaxScale are case-sensitive.

For example the router_options parameter in the readconnroute router is a mask type enumeration:

router_options=master,slave

Path Lists

A pathlist type parameter expects one or more filesystem paths separated by colons. The value must not include space between the separators.

Here is an example path list parameter that points to /tmp/something.log and/var/log/maxscale/maxscale.log:

path_list_parameter=/tmp/something.log:/var/log/maxscale/maxscale.log

Global Settings

The global settings, in a section named [MaxScale], allow various parameters that affect MariaDB MaxScale as a whole to be tuned. This section must be defined in the root configuration file which by default is /etc/maxscale.cnf.

core_file

• Type: boolean

• Default: true

• Dynamic: No

This parameter specifies whether a core file should be generated if MaxScale crashes. The default is true although usually a core file is not needed, as MaxScale is capable of logging the full strack trace of all threads when it crashes.

auto_tune

• Type: string list

• Values: all or list of auto tunable parameters, separated by ,

• Default: No

• Mandatory: No

• Dynamic: No

An auto tunable parameter is a parameter whose value can be derived from a particular server variable. With this parameter it can be specified whetherall or a specific set of parameters should automatically be set.

The current auto tunable parameters are:

The values of the server variables are collected by monitors, which means that if the servers of a service are not monitored by a monitor, then the parameters of that service will not be auto tuned.

Note that even if auto_tune is set to all, the auto tunable parameters can still be set in the configuration file and modified with maxctrl. However, the specified value will be overwritten at the next auto tuning round, but only if the servers of the service are monitored by a monitor.

threads

• Type: number or auto

• Mandatory: No

• Dynamic: No

• Default: auto

This parameter controls the number of worker threads that are used for routing client traffic. The default is auto which uses as many threads as there are virtual CPU cores available to MaxScale, rounded up to the nearest integer. If no limitations have been set using CPU affinities or cgroup CPU quotas, this will be the same as the number of CPU cores. In general, as of 24.08, MaxScale will use the appropriate number of threads, also when it is running in a container.

The maximum value for threads is specified by threads_max.

# Valid options are:
#       threads=[<number of threads> | auto ]

[MaxScale]
threads=auto

From 23.02 onwards it is possible to change the number threads at runtime. Please see Threads for more details.

Additional threads will be created to execute other internal services within MariaDB MaxScale. This setting is used to configure the number of threads that will be used to manage the user connections.

threads_max

• Type: positive integer

• Default: 256

• Dynamic: No

This parameter specifies the hard limit for the number of worker threads, which is specified using threads.

At startup, if the value of threads is larger than that of threads_max, the value of threads will be reduced to that. At runtime, an attempt to increase the value of threads beyond that of threads_max is an error.

rebalance_period

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 0s

This duration parameter controls how often the load of the worker threads should be checked. The default value is 0, which means that no checks and no rebalancing will be performed.

rebalance_period=10s

Note that the value of rebalance_period should not be smaller than the value of rebalance_window whose default value is 10.

If the value of rebalance_period is significantly shorter than that of rebalance_window, it may lead to oscillation where work is constantly moved from one thread to another.

rebalance_threshold

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: 20

This integer parameter controls at which point MaxScale should start moving work from one worker thread to another.

If the difference in load between the thread with the maximum load and the thread with the minimum load is larger than the value of this parameter, then work will be moved from the former to the latter.

Although the load of a thread can vary between 0 and 100, the value of this parameter must be between 5 and 100.

rebalance_threshold=15

Note that rebalancing will not be performed unless rebalance_period has been specified.

rebalance_window

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: 10

This integer parameter controls how many seconds of load should be taken into account when deciding whether work should be moved from one thread to another.

The default value is 10, which means that the load during the last 10 seconds is considered when deciding whether work should be moved.

The minimum value is 1 and the maximum 60.

skip_name_resolve

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

This parameter controls whether reverse domain name lookups are made to convert client IP addresses to hostnames. If enabled, client IP addresses will not be resolved to hostnames during authentication or for the REST API even if requested.

If you have database users that use a hostname in the host part of the user (i.e. 'user'@'my-hostname.org'), a reverse lookup on the client IP address is done to see if it matches the host. Reverse DNS lookups can be very slow which is why it is recommended that they are disabled and that users are defined using an IP address.

host_cache_size

• Type: integer

• Default: 128

• Dynamic: Yes

How many hostname entries are stored in the reverse name lookup cache. Each thread in MaxScale has a cache for the reverse name resolution of client IP addresses to hostnames. Whenever the client authentication requires that a hostname lookup is done, the cache is consulted first. If an entry is found and it was updated less than 300 seconds ago, the cached result is used.

With host_cache_size=0, the cache is disabled and a fresh reverse name lookup is always done.

auth_connect_timeout

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 10s

Duration, default 10s. This setting defines the connection timeout when attempting to fetch MariaDB/MySQL/Clustrix users from a backend server. The same value is also used for read and write timeouts. Increasing this value causes MaxScale to wait longer for a response from a server before user fetching fails. Other servers may then be attempted.

auth_connect_timeout=10s

The value is given as a duration. If no explicit unit is provided, the value is interpreted as seconds. In subsequent versions a value without a unit may be rejected. Since the granularity of the timeout is seconds, a timeout specified in milliseconds will be rejected even if the given value is longer than a second.

auth_read_timeout

Deprecated and ignored as of MaxScale 2.5.0. See auth_connect_timeout above.

auth_write_timeout

Deprecated and ignored as of MaxScale 2.5.0. See auth_connect_timeout above.

query_retries

• Type: number

• Mandatory: No

• Dynamic: No

• Default: 1

The number of times an interrupted internal query will be retried. The default is to retry the query once. This feature was added in MaxScale 2.1.10 and was disabled by default until MaxScale 2.3.0.

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. Internal queries are only used to retrieve authentication data and monitor the servers.

query_retry_timeout

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 10s

The total timeout in seconds for any retried queries. The default value is 5 seconds.

An interrupted query is retried for either the configured amount of attempts or until the configured timeout is reached.

The value is specified as documented here. If no explicit unit is provided, the value is interpreted as seconds in MaxScale 2.4. In subsequent versions a value without a unit may be rejected. Note that since the granularity of the timeout is seconds, a timeout specified in milliseconds will be rejected, even if the duration is longer than a second.

passive

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

Deprecated since MariaDB MaxScale 25.01. Usecooperative monitoring instead.

Controls whether MaxScale is a passive node in a cluster of multiple MaxScale instances.

This parameter is intended to be used with multiple MaxScale instances that use failover functionality to manipulate the cluster in some form. Passive nodes only observe the clusters being monitored and take no direct actions.

The following functionality is disabled when passive mode is enabled:

• Automatic failover in the mariadbmon module

• Automatic rejoin in the mariadbmon module

• Launching of monitor scripts

NOTE: Even if MaxScale is in passive mode, it will still accept clients and route any traffic sent to it. The only operations affected by the passive mode are the ones listed above.

ms_timestamp

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

Enable or disable the high precision timestamps in logfiles. Enabling this adds millisecond precision to all logfile timestamps.

syslog

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

Log messages to the system journal. This logs messages using the native SystemD journal interface. The logs can be viewed with journalctl.

MaxScale 22.08 changed the default value of syslog from true tofalse. This was done to remove the redundant logging that it caused as bothsyslog and maxlog were enabled by default. This caused each message to be logged twice: once into the system journal and once into MaxScale's own logfile.

maxlog

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: true

Log messages to MariaDB MaxScale's log file. The name of the log file ismaxscale.log and it is located in the directory pointed by logdir.

log_warning

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: true

Log messages whose syslog priority is warning.

MaxScale logs warning level messages whenever a condition is encountered that the user should be notified of but does not require immediate action or it indicates a minor problem.

log_notice

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: true

Log messages whose syslog priority is notice.

These messages contain information that is helpful for the user and they usually do not indicate a problem. These are logged whenever something worth nothing happens in either MaxScale or in the servers it monitors.

log_info

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

Log messages whose syslog priority is info.

These messages provide detailed information about the internal workings of MariaDB MaxScale. These messages should only be enabled when there is a need to inspect the internal logic of MaxScale. A common use-case is to see why a particular query was handled in a certain way. Almost all modules log some messages on the info level and this can be very helpful when trying to solve routing related problems.

log_debug

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

Log messages whose syslog priority is debug.

These messages are intended for development purposes and are disabled by default. These are rarely useful outside of debugging core MaxScale issues.

Note: If MariaDB MaxScale has been built in release mode, then debug messages are excluded from the build and this setting will not have any effect. If an attempt to enable these is made, a warning is logged.

trace_file_dir

• Type: path

• Mandatory: No

• Dynamic: No

Path to a directory where trace files will be generated to.

The trace logging offers a low overhead alternative to log_info that is designed to be placed on a local in-memory file system. By placing the files in a location that is not persistent, the overhead of writing to the files is minimal while still allowing the trace logs to be processed as normal log files.

If this parameter is defined along with trace_file_size, MaxScale will write all log messages from all log levels into a set of trace files located in this directory. The files are named maxscale.trace.N where N is an increasing number and whenever a new file is created the oldest one is removed if there are more than 10 trace files.

Starting with MaxScale 24.08.1, the maxscale.trace symlink will be created inthe log directory that will point to the latest log file. This symlink can be used with tail -F to interactively monitor the trace stream or to copy the trace output directly into a compressed file:

# Note: to get a clean compressed file, kill the 'tail' process and instead of
# using Ctrl+C to kill 'gzip'.
tail -F /var/log/maxscale/maxscale.trace | gzip > maxscale.trace.gz

The trace files differ from the normal log file written by MaxScale in that they do not contain the local timestamp and instead contain a raw fractional UNIX timestamp. The format of the trace file is subject to change and it may in the future be identical to the normal log generated by MaxScale.

trace_file_size

• Type: size

• Mandatory: No

• Dynamic: Yes

The desired amount of log data to keep in the trace files. Each individual trace file will be one tenth the size of trace_file_size and once they exceed this amount, a trace log rotation will occur. For example withtrace_file_size=100Mi, roughly 100MiB of log data is kept in 10 files with about 10MiB of data in each file.

Individual trace files may sometimes exceed this limit and under heavy load the system may end up temporarily using more space than is intended.

log_warn_super_user

• Type: boolean

• Mandatory: No

• Dynamic: No

• Default: false

When enabled, a warning is logged whenever a client with SUPER-privilege successfully authenticates. This also applies to COM_CHANGE_USER-commands. The setting is intended for diagnosing situations where a client interferes with a primary server switchover. Super-users bypass the read_only-flag which switchover uses to block writes to the primary.

log_augmentation

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: 0

Enable or disable the augmentation of messages. If this is enabled, then each logged message is appended with the name of the function where the message was logged. This is primarily for development purposes and hence is disabled by default.

# Valid options are:
#       log_augmentation=<0|1>
log_augmentation=1

To disable the augmentation use the value 0 and to enable it use the value 1.

log_throttling

• Type: number, duration, duration

• Mandatory: No

• Dynamic: Yes

• Default: 10, 1000ms, 10000ms

It is possible that a particular error (or warning) is logged over and over again, if the cause for the error persistently remains. To prevent the log from flooding, it is possible to specify how many times a particular error may be logged within a time period, before the logging of that error is suppressed for a while.

# A valid value looks like
#       log_throttling = X, Y, Z
#
# where the first value X is a positive integer and means the number of times
# a specific error may be logged within a duration of Y, before the logging
# of that error is suppressed for a duration of Z.
log_throttling=8, 2s, 15000ms

In the example above, the logging of a particular error will be suppressed for 15 seconds if the error has been logged 8 times in 2 seconds.

The default is 10, 1000ms, 10000ms, which means that if the same error is logged 10 times in one second, the logging of that error is suppressed for the following 10 seconds.

Whenever an error message that is being throttled is logged within the triggering window (the second argument), the suppression window is extended. This continues until there is a pause in the messages that is longer than the triggering window.

For example, with the default configuration the messages must pause for at least one second in order for the throttling to eventually stop. This mechanism prevents long-lasting error conditions from slowly filling up the log with short bursts of messages.

To disable log throttling, add an entry with an empty value

log_throttling=

or one where any of the integers is 0.

log_throttling=0, 0, 0

The durations can be specified as documented here. If no explicit unit is provided, the value is interpreted as milliseconds in MaxScale 2.4. In subsequent versions a value without a unit may be rejected.

Note that notice, info and debug messages are never throttled.

logdir

• Type: path

• Mandatory: No

• Dynamic: No

• Default: /var/log/maxscale

Set the directory where the logfiles are stored. The folder needs to be both readable and writable by the user running MariaDB MaxScale.

logdir=/var/log/maxscale/

datadir

• Type: path

• Mandatory: No

• Dynamic: No

• Default: /var/lib/maxscale

Set the directory where the data files used by MariaDB MaxScale are stored. Modules can write to this directory and for example the binlogrouter uses this folder as the default location for storing binary logs.

This is also the directory where the password encryption key is read from that is generated by maxkeys.

datadir=/var/lib/maxscale/

secretsdir

• Type: path

• Mandatory: No

• Dynamic: No

• Default: ""

The location where the .secrets file is read from. If secretsdir is not defined, the file is read from datadir.

This parameter was added in MaxScale 6.4.16, 22.08.13, 23.02.10, 23.08.6 and 24.02.2.

libdir

• Type: path

• Mandatory: No

• Dynamic: No

• Default: OS Dependent

Set the directory where MariaDB MaxScale looks for modules. The library directory is the only directory that MariaDB MaxScale uses when it searches for modules. If you have custom modules for MariaDB MaxScale, make sure you have them in this folder.

The default value depends on the operating system. For RHEL versions the value is /usr/lib64/maxscale/. For Debian and Ubuntu it is/usr/lib/x86_64-linux-gnu/maxscale/

libdir=/usr/lib64/maxscale/

sharedir

• Type: path

• Mandatory: No

• Dynamic: No

• Default: /usr/share/maxscale

Sets the directory where static data assets are loaded.

The MaxScale GUI static files are located in the gui/ subdirectory. If the GUI files have been manually moved somewhere else, this path must be configured to point to the parent directory of the gui/ subdirectory.

The MaxScale REST API only serves files for the GUI that are located in thegui/ subdirectory of the configured sharedir. Any files whose real path resolves to outside of this directory are not served by the MaxScale GUI: this is done to prevent other files from being accessible via the MaxScale REST API. This means that path to the GUI source directory can contain symbolic links but all parts after the /gui/ directory must reside inside it.

cachedir

• Type: path

• Mandatory: No

• Dynamic: No

• Default: /var/cache/maxscale

Configure the directory MariaDB MaxScale uses to store cached data.

cachedir=/var/cache/maxscale/

piddir

• Type: path

• Mandatory: No

• Dynamic: No

• Default: /run/maxscale

Configure the directory for the PID file for MariaDB MaxScale. This file contains the Process ID for the running MariaDB MaxScale process.

MaxScale versions before 24.08.1 used the path /var/run/maxscale/ for the PID files. This was a legacy path according to the Filesystem Hierarchy Standard and starting with MaxScale 24.08.1, the appropriate modern PID file path is used.

execdir

• Type: path

• Mandatory: No

• Dynamic: No

• Default: /usr/bin

Configure the directory where the executable files reside. All internal processes which are launched will use this directory to look for executable files.

execdir=/usr/bin/

connector_plugindir

• Type: path

• Mandatory: No

• Dynamic: No

• Default: OS Dependent

Location of the MariaDB Connector-C plugin directory. The MariaDB Connector-C used in MaxScale can use this directory to load authentication plugins. The versions of the plugins must be binary compatible with the connector version that MaxScale was built with.

Starting with version 6.2.0, the plugins are bundled with MaxScale and the default value now points to the bundled plugins. The location where the plugins are stored depends on the operating system. For RHEL versions the value is/usr/lib64/maxscale/plugin/. For Debian and Ubuntu it is/usr/lib/x86_64-linux-gnu/maxscale/plugin/.

Older versions of MaxScale used /usr/lib/mysql/plugin/ as the default value.

connector_plugindir=/usr/lib64/maxscale/plugin/

persistdir

• Type: path

• Mandatory: No

• Dynamic: No

• Default: /var/lib/maxscale/maxscale.cnf.d/

Configure the directory where persisted configurations are stored. When a new object is created via MaxCtrl, it will be stored in this directory. Do not use this directory for normal configuration files, use /etc/maxscale.cnf.d/ instead. The user MaxScale is running as must be able to write into this directory.

persistdir=/var/lib/maxscale/maxscale.cnf.d/

module_configdir

• Type: path

• Mandatory: No

• Dynamic: No

• Default: /etc/maxscale.modules.d/

Configure the directory where module configurations are stored. Path arguments are resolved relative to this directory. This directory should be used to store module specific configurations.

Any configuration parameter that is not an absolute path will be interpreted as a relative path. The relative paths use the module configuration directory as the working directory.

For example, the configuration parameter file=my_file.txt would be interpreted as /etc/maxscale.modules.d/my_file.txt whereas file=/home/user/my_file.txt would be interpreted as /home/user/my_file.txt.

module_configdir=/etc/maxscale.modules.d/

language

• Type: path

• Mandatory: No

• Dynamic: No

• Default: /var/lib/maxscale/

Set the folder where the errmsg.sys file is located in. MariaDB MaxScale will look for the errmsg.sys file installed with MariaDB MaxScale from this folder.

language=/var/lib/maxscale/

query_classifier

Deprecated since MariaDB MaxScale 23.08.

query_classifier_cache_size

• Type: size

• Mandatory: No

• Dynamic: Yes

• Default: System Dependent

Specifies the maximum size of the query classifier cache. The default limit is 15% of available system memory. The available system memory may be less than the total system memory, if MaxScale is running in a container whose resources have been limited.

When the query classifier cache has been enabled, MaxScale will, after a statement has been parsed, store the classification result using the canonicalized version of the statement as the key.

If the classification result for a statement is needed, MaxScale will first canonicalize the statement and check whether the result can be found in the cache. If it can, the statement will not be parsed at all but the cached result is used.

The configuration parameter takes one integer that specifies the maximum size of the cache. The size of the cache can be specified as explained here.

# 1MB query classifier cache
query_classifier_cache_size=1MB

Note that MaxScale uses a separate cache for each worker thread. To obtain the amount of memory available for each thread, divide the cache size with the value of threads. If statements are evicted from the cache (visible in the diagnostic output), consider increasing the cache size.

Note also that limit is not a hard limit, but an approximate one. Namely, although the memory needed for storing the canonicalized statement and the classification result is correctly accounted for, there is additional overhead whose size is not exactly known and over which we do not have direct control.

Using maxctrl show threads it is possible to check what the actual size of the cache is and to see performance statistics.

query_classifier_args

Deprecated since MariaDB MaxScale 23.08.

substitute_variables

• Type: boolean

• Mandatory: No

• Dynamic: No

• Default: false

Enable or disable the substitution of environment variables in the MaxScale configuration file. If the substitution of variables is enabled and a configuration line like

some_parameter=$SOME_VALUE

is encountered, then $SOME_VALUE will be replaced with the actual value of the environment variable SOME_VALUE. Note:Variable substitution will be made only if '$' is the first character &#xNAN;of the value. Everything following '$' is interpreted as the name of the environment variable.

• Referring to a non-existing environment variable is a fatal error.

substitute_variables=true

The setting of substitute_variables will have an effect on all parameters in the all other sections, irrespective of where the [maxscale] section is placed in the configuration file. However, in the [maxscale] section, to ensure that substitution will take place, place thesubstitute_variables=true line first.

sql_mode

• Type: enum

• Mandatory: No

• Dynamic: No

• Values: default, oracle

• Default: default

Specifies whether the query classifier parser should initially expect MariaDB or PL/SQL kind of SQL.

The allowed values are:default: The parser expects regular MariaDB SQL.oracle : The parser expects PL/SQL.

sql_mode=oracle

NOTE If sql_mode is set to oracle, then MaxScale will also assume that autocommit initially is off.

At runtime, MariaDB MaxScale will recognize statements like

set sql_mode=oracle;

and

set sql_mode=default;

and change mode accordingly.

NOTE If set sql_mode=oracle; is encountered, then MaxScale will also behave as if autocommit had been turned off and conversely, ifset sql_mode=default; is encountered, then MaxScale will also behave as if autocommit had been turned on.

Note that MariaDB MaxScale is not explicitly aware of the sql mode of the server, so the value of sql_mode should reflect the sql mode used when the server is started.

local_address

• Type: string

• Mandatory: No

• Dynamic: No

• Default: ""

What specific local address/interface to use when connecting to servers.

This can be used for ensuring that MaxScale uses a particular interface when connecting to servers, in case the computer MaxScale is running on has multiple interfaces.

local_address=192.168.1.254

If given as a hostname, MaxScale will perform name lookup on the address when starting and reuse the result.

users_refresh_time

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 30s

How often, in seconds, MaxScale at most may refresh the users from the backend server.

MaxScale will at startup load the users from the backend server, but if the authentication of a user fails, MaxScale assumes it is because a new user has been created and will thus refresh the users. By default, MaxScale will do that at most once per 30 seconds and with this configuration option that can be changed. A value of 0 allows infinite refreshes and a negative value disables the refreshing entirely.

users_refresh_time=120s

The value is specified as documented here. If no explicit unit is provided, the value is interpreted as seconds in MaxScale 2.4. In subsequent versions a value without a unit may be rejected. Note that since the granularity of the timeout is seconds, a timeout specified in milliseconds will be rejected, even if the duration is longer than a second.

In MaxScale 2.3.9 and older versions, the minimum allowed value was 10 seconds but, due to a bug, the default value was 0 which allowed infinite refreshes.

users_refresh_interval

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 0s

How often, in seconds, MaxScale will automatically refresh the users from the backend server.

This configuration is used to periodically refresh the backend users, making sure they are up to date. The default value for this setting is 0, meaning the users are not periodically refreshed. However, they can still be refreshed in case of failed authentication depending on users_refresh_time.

users_refresh_interval=2h

retain_last_statements

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: 0

How many statements MaxScale should store for each session. This is for debugging purposes, as in case of problems it is often of value to be able to find out exactly what statements were sent before a particular problem turned up.

Note: See also dump_last_statements using which the actual dumping of the statements is enabled. Unless both of the parameters are defined, the statement dumping mechanism doesn't work.

retain_last_statements=20

dump_last_statements

• Type: enum

• Mandatory: No

• Dynamic: Yes

• Values: on_close, on_error, never

• Default: never

With this configuration item it is specified in what circumstances MaxScale should dump the last statements that a client sent. The allowed values arenever, on_error and on_close. With never the statements are never logged, with on_error they are logged if the client closes the connection improperly, and with on_close they are always logged when a client session is closed.

dump_last_statements=on_error

Note that you need to specify with retain_last_statements how many statements MaxScale should retain for each session. Unless it has been set to another value than 0, this configuration setting will not have an effect.

session_trace

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: 0

How many log entries are stored in the session specific trace log. This log is written to disk when a session ends abnormally and can be used for debugging purposes. Currently the session trace log is written to the log in the following situations:

• When MaxScale receives a fatal signal and is about to crash.

• Whenever an unexpected response is read from a server

• If the session is not closed gracefully (i.e. client doesn't send a COM_QUIT packet)

• Whenever readwritesplit receives a response that is was not expecting.

It would be good to enable this if a session is disconnected and the log is not detailed enough. In this case the info log might reveal the true cause of why the connection was closed.

session_trace=20

Default is 0.

The session trace log is also exposed by REST API and is shown withmaxctrl show sessions.

The order in which the session trace messages are logged into the log changed in MaxScale 6.4.9 (MXS-4716). Newer versions will log the messages in the "normal log order" of older events coming first and newer events appearing later in the file. Older versions of MaxScale logged the trace dump in the reverse order with the newest messages first and oldest ones last.

session_trace_match

• Type: regex

• Mandatory: No

• Dynamic: Yes

• Default: None

If both session_trace and session_trace_match are defined, and a trace log entry of a session matches the regular expression, the trace log is written to disk. The check for the match is done when the session is stopping.

The most effective way to debug MaxScale related issues is to turn on log_info and observe the events written into the MaxScale log. The only problem with this approach is that it can cause a severe performance bottleneck and can easily fill up the disk as the amount of data written to it is significant. Withsession_trace and session_trace_match, the content that actually gets logged can be filtered to only what is needed.

For example, the following configuration would only log the trace log messages from sessions that execute SQL queries with syntax errors:

session_trace=1000
session_trace_match=/You have an error in your SQL syntax/

This could be used to easily identify which applications execute the queries without having to gather the info level log output from all the sessions that connect to MaxScale. For every session that ends up logging a syntax error message, the last 1000 lines of log output done by that session is written into the MaxScale log.

writeq_high_water

• Type: size

• Mandatory: No

• Dynamic: Yes

• Default: 65536

High water mark for network write buffer. When the size of the outbound network buffer in MaxScale for a single connection exceeds this value, network traffic throtting for that connection is started. The parameter accepts size type values. The default value was 16777216 bytes before 22.08.4.

More specifically, if the client side write queue is above this value, it will block traffic coming from backend servers. If the backend side write queue is above this value, it will block traffic from client.

The buffer that this parameter controls is the buffer internal to MaxScale and is not the kernel TCP send buffer. This means that the total amount of buffered data is determined by both the kernel TCP buffers and the value ofwriteq_high_water.

Network throttling is only enabled when writeq_high_water is non-zero. In MaxScale 23.02 and earlier, also writeq_low_water had to be non-zero.

writeq_low_water

• Type: size

• Mandatory: No

• Dynamic: Yes

• Default: 1024

Low water mark for network write buffer. Once the traffic throttling is enabled, it will only be disabled when the network write buffer is belowwriteq_low_water bytes. The parameter accepts size type values. The default value was 8192 bytes before 22.08.4.

The value of writeq_high_water must always be greater than the value ofwriteq_low_water.

persist_runtime_changes

• Type: boolean

• Default: true

• Dynamic: No

Persist changes done at runtime. This parameter was added in MaxScale 22.08.0.

When persist_runtime_changes is enabled, runtime configuration changes done with the GUI, MaxCtrl or via the REST API cause a new configuration file to be saved in /var/lib/maxscale/maxscale.cnf.d/. If load_persisted_configs is enabled, these files will be applied on top of any existing values found in static configuration files whenever MaxScale is starting up.

load_persisted_configs

• Type: boolean

• Mandatory: No

• Dynamic: No

• Default: true

Load persisted runtime changes on startup. This parameter was added in MaxScale 2.3.6.

All runtime configuration changes are persisted in generated configuration files located by default in /var/lib/maxscale/maxscale.cnf.d/ and are loaded on startup after main configuration files have been read. To make runtime configurations volatile (i.e. they are lost when maxscale is restarted), useload_persisted_configs=false. All changes are still persisted since it stores the current runtime state of MaxScale. This makes problem analysis easier if an unexpected outage happens.

max_auth_errors_until_block

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: 10

The maximum number of authentication failures that are tolerated before a host is temporarily blocked. The default value is 10 failures. After a host is blocked, connections from it are rejected for 60 seconds. To disable this feature, set the value to 0.

Note that the configured value is not a hard limit. The number of tolerated failures is between max_auth_errors_until_block and threads * max_auth_errors_until_block where max_auth_errors_until_block is the configured value of this parameter and threads is the number of configured threads.

debug

• Type: string

• Mandatory: No

• Dynamic: No

• Default: ""

Define debug options from the --debug command line option. Either the command line option or the parameter should be used, not both. The debug options are only for testing purposes and are not to be used in production.

REST API Configuration

The MaxScale REST API is an HTTP interface that provides JSON format data intended to be consumed by monitoring applications and visualization tools.

The following options must be defined under the [maxscale] section in the configuration file.

admin_host

• Type: string

• Mandatory: No

• Dynamic: No

• Default: "127.0.0.1"

The network interface where the REST API listens on. The default value is the IPv4 address 127.0.0.1 which only listens for local connections.

admin_port

• Type: number

• Mandatory: No

• Dynamic: No

• Default: 8989

The port where the REST API listens on. The default value is port 8989.

admin_auth

• Type: boolean

• Mandatory: No

• Dynamic: No

• Default: true

Enable REST API authentication using HTTP Basic Access authentication. This is not a secure method of authentication without HTTPS but it does add a small layer of security.

For more information, read the REST API documentation.

admin_ssl_key

• Type: path

• Mandatory: No

• Dynamic: No

• Default: ""

The path to the TLS private key in PEM format for the admin interface.

If the admin_ssl_key and admin_ssl_cert options are all defined, the admin interface will use encrypted HTTPS instead of plain HTTP.

admin_ssl_cert

• Type: path

• Mandatory: No

• Dynamic: No

• Default: ""

The path to the TLS public certificate in PEM format. See admin_ssl_key documentation for more details.

admin_ssl_ca_cert

Deprecated since MariaDB MaxScale 22.08. See admin_ssl_ca.

admin_ssl_ca

• Type: path

• Mandatory: No

• Dynamic: No

• Default: ""

The path to the TLS CA certificate in PEM format. If defined, the client certificate, if provided, will be validated against it. This parameter is optional starting with MaxScale 2.3.19.

NOTE Up until MariaDB MaxScale 6, the parameter was called admin_ssl_ca_cert, which is still accepted as an alias for admin_ssl_ca.

admin_ssl_version

• Type: enum_mask

• Mandatory: No

• Dynamic: No

• Values: MAX, TLSv1.0, TLSv1.1, TLSv1.2, TLSv1.3, TLSv10, TLSv11, TLSv12, TLSv13

• Default: MAX

This parameter controls the enabled TLS versions in the REST API. Accepted values are:

• TLSv10

• TLSv11

• TLSv12

• TLSv13 (not supported on OpenSSL 1.0)

• MAX

MaxScale versions 6.4.16, 22.08.13, 23.02.10, 23.08.6, 24.02.2 and all newer releases accept also the following alias values:

• TLSv1.0

• TLSv1.1

• TLSv1.2

• TLSv1.3 (not supported on OpenSSL 1.0)

The default value is MAX which negotiates the highest level of encryption that both the client and server support. The list of supported TLS versions depends on the operating system and what TLS versions the GnuTLS library supports.

For example, to enable only TLSv1.1 and TLSv1.3, useadmin_ssl_version=TLSv1.1,TLSv1.3.

This parameter was added in MaxScale 2.5.7.

Older versions of MaxScale interpreted admin_ssl_version as the minimum allowed TLS version. In those versions, admin_ssl_version=TLSv1.2 allowed both TLSv1.2 and TLSv1.3. In MaxScale 6.4.16, 22.08.13, 23.02.10, 23.08.6, 24.02.2 and all newer versions, the value is a enumeration of accepted TLS protocol versions. In these versions, admin_ssl_version=TLSv1.2 only allows TLSv1.2. To retain the old behavior, specify all the accepted values withadmin_ssl_version=TLSv1.2,TLSv1.3

admin_ssl_cipher

• Type: string

• Mandatory: No

• Dynamic: No

Additional TLS cipher settings. The configured value is prepended toadmin_ssl_version and the resulting string is given as is tognutls_priority_init. If left undefined, NORMAL is used.

Adding unrecognized elements to this setting will cause REST-API startup to fail with the error:

REST API HTTP daemon error: Setting priorities to ... failed: The request is invalid.

The value should typically start with a collection of ciphersuites, such as "NORMAL" or "SECURE256". Then, add or remove algorithms with more specific cipher definitions such as "+AES-128-GCM" or "-AES-128-GCM".

admin_ssl_cipher=SECURE256:-ECDHE-RSA:-AES-256-CCM:+AES-128-GCM

admin_enabled

• Type: boolean

• Mandatory: No

• Dynamic: No

• Default: true

Enable or disable the admin interface. This allows the admin interface to be completely disabled to prevent access to it.

admin_gui

• Type: boolean

• Mandatory: No

• Dynamic: No

• Default: true

Enable or disable the admin graphical user interface.

MaxScale provides a GUI for administrative operations via the REST API. When the GUI is enabled, the root REST API resource (i.e. http://localhost:8989/) will serve the GUI. When disabled, the REST API will respond with a 200 OK to the request. By disabling the GUI, the root resource can be used as a low overhead health check.

admin_secure_gui

• Type: boolean

• Mandatory: No

• Dynamic: No

• Default: true

Whether to serve the GUI only over secure HTTPS connections.

To be secure by default, the GUI is only served over HTTPS connections as it uses a token authentication scheme. This also controls whether the/auth endpoint requires an encrypted connection.

To allow use of the GUI without having to configure TLS certificates for the MaxScale REST API, set this parameter to false.

admin_log_auth_failures

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: true

Log authentication failures for the admin interface.

admin_pam_readwrite_service

• Type: string

• Mandatory: No

• Dynamic: No

• Default: ""

Use Pluggable Authentication Modules (PAM) for REST API authentication. This setting and admin_pam_readonly_service accept a PAM service name which is used during authentication if normal authentication fails.admin_pam_readwrite_service should accept users who can do any MaxCtrl/REST-API-operation. admin_pam_readonly_service should accept users who can only do read operations. Because REST-API does not support back and forth communication between the client and MaxScale, the PAM services must be simple. They should only ask for the password and nothing else.

If only admin_pam_readwrite_service is configured, both read and write operations can be authenticated by PAM. If only admin_pam_readonly_service is configured, only read operations can be authenticated by PAM. If both are set, the service used is determined by the requested operation. Leave or set both empty to disable PAM for REST-API.

admin_pam_readonly_service

• Type: string

• Mandatory: No

• Dynamic: No

• Default: ""

See admin_pam_readwrite_service.

admin_readwrite_hosts

• Type: string

• Mandatory: No

• Dynamic: No

• Default: %

Limit REST-API logins to specific source addresses/hosts. Supports a comma-separated list of addresses and hostnames. Addresses can be given in CIDR-notation. Admin clients still need to supply credentials as usual. By default, all source addresses are allowed. admin_readwrite_hosts lists the hosts from which any operation is allowed.

admin_readwrite_hosts=192.168.1.1,127.0.0.1/21

When listing hostnames, % and _ act as wildcards, similar to the hostname component in MariaDB Server user accounts. localhost is a reserved hostname and will not match any connection (use 127.0.0.1 for loopback connections).

When checking the source host of the incoming REST-API client, MaxScale first compares against addresses and address masks. If a match was not found and the setting values contain hostnames, reverse name lookup is performed on the client address. The lookup can take a while in rare cases. To prevent such slowdown, use only IP-addresses in the host lists.

skip_name_resolve cannot be enabled if admin_readwrite_hosts oradmin_readonly_hosts includes hostname patterns, as these would not work.

admin_readonly_hosts

Works similar to admin_readwrite_hosts. Lists the hosts from which only read operations are allowed. An admin client can do a read operation if their source address matches either admin_readwrite_hosts or admin_readonly_hosts.

admin_readonly_hosts=mydomain%.com

admin_jwt_algorithm

• Type: enum

• Mandatory: No

• Dynamic: No

• Values: auto, HS256, HS384, HS512, RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, ED25519, ED448

• Default: auto

The signature algorithm used by the MaxScale REST API when generating JSON Web Tokens.

For more information about the tokens and how they work, refer to the REST API documentation.

If a symmetric algorithm is used (i.e. HS256, HS384 or HS512), MaxScale will generate a random encryption key on startup and use that to sign the messages. The symmetric key can also be retrieved from an Encryption Key Manager if the admin_jwt_key parameter is defined.

If an asymmetric algorithm (i.e. public key authentication) is used, both theadmin_ssl_cert and admin_ssl_key parameters must be defined and they must contain a private key and a public certificate of the correct type. If the wrong key type, key length or elliptic curve is used, MaxScale will refuse to start.

Asymmetric key algorithms make it possible for the clients of the REST API to validate that the token was indeed generated by the correct entity.

Symmetric algorithms make it easy to share the same tokens between multiple MaxScale instances as the shared secret can be stored in a key management system.

The possible values for this parameter are:

• auto

• MaxScale will attempt to detect the best algorithm to use for signatures. The algorithm used depends on the private key type: RSA keys usePS256, EC keys use the ES256, ES384 or ES512 depending on the curve, Ed25519 keys use ED25519 and Ed448 keys uses ED448. If MaxScale cannot auto-detect the key type, it falls back to HS256 as the default algorithm.

• HS256, HS384 or HS512

• HMAC with SHA-2 Functions. Ifadmin_jwt_key is not defined, uses a random encryption key of the correct size.

• RS256, RS384 or RS512

• Digital Signature with RSASSA-PKCS1-v1_5. Requires at least a 2048-bit RSA key.

• PS256, PS384 or PS512

• Digital Signature with RSASSA-PSS. Requires at least a 2048-bit RSA key.

• ES256, ES384 or ES512

• Digital Signature with ECDSA. Requires an EC key with the correct curve: P-256 for ES256, P-384 for ES384 and P-512 for ES512.

• ED25519 or ED448

• Edwards-curve Digital Signature Algorithm (EdDSA). Requires a Ed25519 key for ED25519 or a Ed448 key for ED448.

admin_jwt_key

• Type: string

• Mandatory: No

• Dynamic: No

• Default: ""

The ID for the encryption key used to sign the JSON Web Tokens. If configured, an Encryption Key Manager must also be configured and it must contain the key with the given ID. If no key is defined, MaxScale will use a random encryption key whenever a symmetric signature algorithm is used.

Currently, the encryption key is only read on startup. This means that the tokens will be signed by the latest key version that is available on startup: rotating the encryption key in the key management system will not cause the JWTs to be signed with newer versions of the key.

admin_jwt_max_age

• Type: duration

• Mandatory: No

• Dynamic: No

• Default: 24h

The maximum lifetime of a token generated by the /auth endpoint.

If a client requests for a token with a lifetime that exceeds the configured value, the token lifetime is silently truncated to this value. This can be used to control the maximum length of a MaxGUI session.

This also acts as the effective maximum age of any database connection created from the /sql endpoint.

admin_oidc_url

• Type: string

• Mandatory: No

• Dynamic: No

• Default: ""

The URL to a OpenID Connect server that is used for JWT validation.

If defined, any tokens signed by this server are accepted as valid bearer tokens for the MaxScale REST API. The "sub" field of the token is assumed to be the username of an administrative user in MaxScale and the "account" claim is assumed to be the type of the user: "admin" for administrative users with full access to the REST-API and "basic" for users with read-only access to the REST-API. This means that all users must be first created with maxctrl create user before the tokens are accepted if the OIDC provider is not able to add the"account" claim.

If this URL is changed at runtime, the new certificates will not be fetched until a maxctrl reload tls command is executed.

admin_verify_url

• Type: string

• Mandatory: No

• Dynamic: No

• Default: ""

URL to a server to which the REST API token verification is delegated.

If the URL is defined, any tokens passed to the REST API will be validated by doing a GET request to the URL with the client's token as a bearer token. TheReferer header of the request is set to the URL being requested by the client and the custom X-Referrer-Method header is set to the HTTP method being used (PUT, GET etc.).

Note: When admin_verify_url is used and the remote server cannot be accessed, all REST API access that uses tokens will be disabled. The only way to use the REST API with tokens is to remove admin_verify_url from the configuration which requires restarting MaxScale. The REST API still accepts HTTP Basic Access authentication even if the remote server cannot be reached.

By delegating the authentication and authorization of the REST API to an external server, users can implement custom access control systems for the MaxScale REST API.

admin_jwt_issuer

• Type: string

• Mandatory: No

• Dynamic: No

• Default: maxscale

The issuer ("iss") claim of all JWTs generated by MaxScale. This can be set to a custom value to uniquely identify which MaxScale issued a JWT. This is especially useful for cases where the MaxScale GUI is used from behind a reverse proxy.

admin_audit

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

Enable logging of incoming REST API calls.

admin_audit_file

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: /var/log/maxscale/admin_audit.csv

The file where the REST API auditing information is logged.

If a non-default value is used, the directory where the file resides must exist. For example, with /var/log/maxscale/audit_files/audit.csv, the directory /var/log/maxscale/audit_files must exist.

admin_audit_exclude_methods

• Type: enum

• Mandatory: No

• Dynamic: Yes

• Values: GET, PUT, POST, PATCH, DELETE, HEAD, OPTIONS, CONNECT, TRACE

• Default: No exclusions

List of comma separated HTTP methods to exclude from logging Currently MaxScale does not use CONNECT or TRACE.

Resetting to log all methods can be done in the configuration file by writing admin_audit_exclude_methods= or at runtime withmaxctrl alter maxscale admin_audit_exclude_methods=. Remember that once a runtime change has been made, the entry for that setting is ignored in the main configuration file (usually maxscale.cnf).

config_sync_cluster

• Type: monitor

• Mandatory: No

• Dynamic: Yes

• Default: None

This parameter controls which cluster (i.e. monitor) is used to synchronize configuration changes between MaxScale instances. The first server labeledMaster will be used for the synchronization.

By default configuration synchronization is not enabled and it must be explicitly enabled by defining a monitor name for config_sync_cluster.

When config_sync_cluster is defined, config_sync_user andconfig_sync_password must also be defined.

For a detailed description of this feature, refer to the Configuration Synchronization section.

config_sync_user

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: None

The username for the account that is used to synchronize configuration changes across MaxScale instances. Both this parameter and config_sync_password are required if config_sync_cluster is configured.

This account must have the following grants:

GRANT SELECT, INSERT, UPDATE, CREATE ON `mysql`.`maxscale_config`

The mysql.maxscale_config table can be pre-created in which case the CREATE grant is not needed by the user configured in config_sync_user. The following SQL is used to create the table.

CREATE TABLE IF NOT EXISTS mysql.maxscale_config(
  cluster VARCHAR(256) PRIMARY KEY,
  version BIGINT NOT NULL,
  config JSON NOT NULL,
  origin VARCHAR(254) NOT NULL,
  nodes JSON NOT NULL
) ENGINE=InnoDB;

If the database where the table is created is changed with config_sync_db, the grants must be adjusted to target that database instead.

config_sync_password

• Type: password

• Mandatory: No

• Dynamic: Yes

• Default: None

The password for config_sync_user. Both this parameter and config_sync_user are required if config_sync_cluster is configured. This password can optionally be encrypted using maxpasswd.

config_sync_db

• Type: string

• Mandatory: No

• Dynamic: No

• Default: mysql

The database where the maxscale_config table is created. By default the table is created in the mysql database. This parameter was added in MaxScale versions 6.4.6 and 22.08.5.

As tables in the mysql database cannot have triggers on them, the database must be changed to a user-created one in order to create triggers on the table. An example use-case for triggers on this table is to track all configuration changes done to MaxScale by inserting them into a separate table.

config_sync_interval

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 5s

How often to synchronize the configuration with the cluster.

As the synchronization involves selecting the configuration version from the database, this value should not be set to an unreasonably low value. The default value of 5 second should provide a good compromise between responsiveness and how much load it places on the database.

config_sync_timeout

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 10s

Timeout for all SQL operations done during the configuration synchronization. If an operation exceeds this timeout, the configuration change is treated as failed and an error is reported to the client that did the change.

key_manager

• Type: enum

• Dynamic: Yes

• Values: none, file, kmip, vault

• Default: none

The encryption key manager to use. The available encryption key managers are:

• none - No key manager, encryption keys are not available.

• file - File-based key manager

• kmip - KMIP key manager

• vault - HashiCorp Vault key manager. This key manager is only included on systems with GCC 9 or newer which means it cannot be used on Ubuntu 18.04.

Refer to the Encryption Key Managers section for more information on how to configure the key managers. The key managers each have their configuration in their own namespace and must have their name as a prefix.

For example to configure the file key manager, the following must be used:

key_manager=file
file.keyfile=/path/to/keyfile

Events

MaxScale logs warnings and errors for various reasons and often it is self- evident and generally applicable whether some occurrence should warrant a warning or an error, or perhaps just an info-level message.

However, there are events whose seriousness is not self-evident. For instance, in some environments an authentication failure may simply indicate that someone has made a typo, while in some other environment that can only happen in case there has been a security breech.

To handle events like these, MaxScale defines events whose logging facility and level can be controlled by the administrator. Given an eventX, its facility and level are controlled in the following manner:

event.X.facility=LOG_LOCAL0
event.X.level=LOG_ERR

The above means that if event X occurs, then that is logged using the facility LOG_LOCAL0 and the level LOG_ERR.

The valid values of facilityare the facility values reported byman syslog, e.g.LOG_AUTH,LOG_LOCAL0andLOG_USER. Likewise, the valid values forlevelare the ones also reported byman syslog, e.g.LOG_WARNING,LOG_ERRandLOG_CRIT`.

Note that MaxScale does not act upon the level, that is, even if the level of a particular event is defined to be LOG_EMERG, MaxScale will not shut down if that event occurs.

The default facility is LOG_USER and the default level is LOG_WARNING.

Note that you may also have to configure rsyslog to ensure that the event can be logged to the intended log file. For instance, if the facility is chosen to be LOG_AUTH, then /etc/rsyslog.conf should contain a line like

auth,authpriv.*                 /var/log/auth.log

for the logged events to end up in /var/log/auth.log, where the initialauth is the relevant entry.

The available events are:

'authentication_failure'

This event occurs when there is an authentication failure.

event.authentication_failure.facility=LOG_AUTH
event.authentication_failure.level=LOG_CRIT

Service

A service represents the database service that MariaDB MaxScale offers to the clients. In general a service consists of a set of backend database servers and a routing algorithm that determines how MariaDB MaxScale decides to send statements or route connections to those backend servers.

A service may be considered as a virtual database server that MariaDB MaxScale makes available to its clients.

Several different services may be defined using the same set of backend servers. For example a connection based routing service might be used by clients that already performed internal read/write splitting, whilst a different statement based router may be used by clients that are not written with this functionality in place. Both sets of applications could access the same data in the same databases.

A service is identified by a service name, which is the name of the configuration file section and a type parameter of service.

[Test-Service]
type=service

In order for MariaDB MaxScale to forward any requests it must have at least one service defined within the configuration file. The definition of a service alone is not enough to allow MariaDB MaxScale to forward requests however, the service is merely present to link together the other configuration elements.

router

• Type: router

• Mandatory: Yes

• Dynamic: No

The router parameter of a service defines the name of the router module that will be used to implement the routing algorithm between the client of MariaDB MaxScale and the backend databases. Additionally routers may also be passed a comma separated list of options that are used to control the behavior of the routing algorithm. The two parameters that control the routing choice are router and router_options. The router options are specific to a particular router and are used to modify the behavior of the router. The read connection router can be passed options of master, slave or synced, an example of configuring a service to use this router and limiting the choice of servers to those in slave state would be as follows.

router=readconnroute
router_options=slave

To change the router to connect on to servers in the master state as well as slave servers, the router options can be modified to include the master state.

router=readconnroute
router_options=master,slave

A more complete description of router options and what is available for a given router is included with the documentation of the router itself.

filters

• Type: filter list

• Mandatory: No

• Dynamic: Yes

• Default: None

The filters option allow a set of filters to be defined for a service; requests from the client are passed through these filters before being sent to the router for dispatch to the backend server. The filters parameter takes one or more filter names, as defined within the filter definition section of the configuration file. Multiple filters are separated using the | character.

filters=counter | QLA

The requests pass through the filters from left to right in the order defined in the configuration parameter.

targets

• Type: target list

• Mandatory: No

• Dynamic: Yes

• Default: None

The targets parameter is a comma separated list of server and/or service names that comprise the routing targets of the service. This parameter was added in MaxScale 2.5.0.

targets=My-Service,server2

This parameter allows nested service configurations to be defined without having to configure listeners for all services. For example, one use-case is to use multiple readwritesplit services behind a schemarouter service to have both the sharding of schemarouter with the high-availability of readwritesplit.

NOTE: The targets parameter is mutually exclusive with the cluster andservers parameters.

servers

• Type: server list

• Mandatory: No

• Dynamic: Yes

• Default: None

The servers parameter in a service definition provides a comma separated list of the backend servers that comprise the service. The server names are those used in the name section of a block with a type parameter of server (see below).

servers=server1,server2,server3

NOTE: The servers parameter is mutually exclusive with the cluster andtargets parameters.

cluster

• Type: monitor

• Mandatory: No

• Dynamic: Yes

• Default: None

The servers the service uses are defined by the monitor specified as value of this configuration parameter.

cluster=TheMonitor

NOTE: The cluster parameter is mutually exclusive with the servers andtargets parameters.

user

• Type: string

• Mandatory: Yes

• Dynamic: Yes

This setting defines the user the service uses to fetch user account information from backends. A password is specified using password.

user=maxscale
password=Mhu87p2D

See MySQL protocol authentication documentation for more information (such as required grants) and troubleshooting tips regarding user account management and client authentication.

password

• Type: string

• Mandatory: Yes

• Dynamic: Yes

This settings defines the password the service uses to fetch user account information from backends. The password may be either a plain text password or an encrypted password. The user is specified using user.

user=maxscale
password=Mhu87p2D

See MySQL protocol authentication documentation for more information (such as required grants) and troubleshooting tips regarding user account management and client authentication.

From 23.08.0 onwards, MaxScale will remember the previous password when the password is changed. If the fetching of the user account information fails using the new password, it will be attempted using the previous one. The purpose of this change is to make it a smoother operation to change the password of the service user. The steps are as follows:

1. $ maxctrl alter service MyService password=TheNewPassword

2. MariaDB [(none)]> set password for TheServiceUser = password('TheNewPassword');

Since the old password is remembered and used if the new password does not work, it is no longer necessary to perform those steps simultaneously.

enable_root_user

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

This parameter controls the ability of the root user to connect to MariaDB MaxScale and hence onwards to the backend servers via MariaDB MaxScale.

localhost_match_wildcard_host

Deprecated and ignored.

version_string

• Type: string

• Mandatory: No

• Dynamic: No

• Default: None

This parameter sets a custom version string that is sent in the MySQL Handshake from MariaDB MaxScale to clients.

Example:

version_string=10.11.2-MariaDB-RWsplit

If not set, MaxScale will attempt to use a version string from the backend databases by selecting the version string of the database with the lowest version number. If the selected version is from the MariaDB 10 series, a 5.5.5- prefix will be added to it similarly to how the MariaDB 10 series versions added it.

If MaxScale has not been able to connect to a single database and the versions are unknown, the default value of 5.5.5-10.4.32 <MaxScale version>-maxscale is used where <MaxScale version> is the version of MaxScale.

auth_all_servers

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

This parameter controls whether only a single server or all of the servers are used when loading the users from the backend servers.

By default MaxScale uses the first server labeled as Master as the source of the authentication data. When this option is enabled, the authentication data is loaded from all the servers and combined into one big data set.

Note: This parameter was deprecated in MaxScale 24.02.0 but it was then un-deprecated as there were still uses for it. Modules that required this to function correctly (e.g. schemarouter) now automatically enable it.

strip_db_esc

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: true

Note: This parameter has been deprecated in MaxScale 23.08. The stripping of escape characters is in all known cases the correct thing to do.

This setting controls whether escape characters (\) are removed from database names when loading user grants from a backend server. When enabled, a grant such as grant select on test_.* to 'user'@'%'; is read as grant select on test_.* to 'user'@'%';

This setting has no effect on database-level grants fetched from a MariaDB Server. The database names of a MariaDB Server are compared using the LIKE operator to properly handle wildcards and escaped wildcards. This setting may affect database names in table and column level grants, although these typically do not contain backlashes.

Some visual database management tools automatically escape some characters and this might cause conflicts when MaxScale tries to authenticate users.

log_auth_warnings

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: true

Enable or disable the logging of authentication failures and warnings. If enabled, messages about failed authentication attempts will be logged with details about who tried to connect to MariaDB MaxScale and from where.

log_warning

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

When enabled, this allows a service to log warning messages even if the global log level configuration disables them.

Note that disabling the service level logging does not override the global logging configuration: with log_warning=false in the service andlog_warning=true globally, warnings will still be logged for all services.

log_notice

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

When enabled, this allows a service to log notice messages even if the global log level configuration disables them.

log_info

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

When enabled, this allows a service to log info messages even if the global log level configuration disables them.

log_debug

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

When enabled, this allows a service to log debug messages even if the global log level configuration disables them.

Debug messages are only enabled for debug builds. Enabling log_debug in a release build does nothing.

wait_timeout

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 28800s (>= MaxScale 24.02.5, 25.01.2), 0s (<= MaxScale 24.02.4, 25.01.1)

• Auto tune: Yes

The wait_timeout parameter is used to disconnect sessions to MariaDB MaxScale that have been idle for too long. The session timeout is set to 28800 seconds by default. A value of zero is interpreted as no timeout.

This parameter used to be called connection_timeout and this name is still accepted as an alias for wait_timeout. The old name has been deprecated in MaxScale 23.08.

The default value of wait_timeout changed from 0s to 28800s in MaxScale versions 24.02.5 and 25.01.2 to match the default value of MariaDB (MXS-5530).

Note that since the granularity of the timeout is seconds, a timeout specified in milliseconds will be rejected, even if the duration is longer than a second.

This parameter only takes effect in top-level services. A top-level service is the service where the listener that the client connected to points (i.e. the value of service in the listener). If a service defines other services in itstargets parameter, the wait_timeout for those is not used.

The value of wait_timeout in MaxScale should be lower than the lowestwait_timeout value on the backend servers. This way idle clients are disconnected by MaxScale before the backend servers have to close them. Any client-side idle timeouts (e.g. maximum lifetime for connection pools) should be lower than wait_timeout in both MaxScale and MariaDB. This way the client application will end up closing the connection itself which most of the time results in better and more helpful error messages.

Warning: If a connection is idle for longer than the configured connection timeout, it will be forcefully disconnected and a warning will be logged in the MaxScale log file.

Example:

[Test-Service]
wait_timeout=300s

max_connections

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: 0 in MaxScale, 15 in MaxScale Lite.

• Minimum: 0 in MaxScale, 1 in MaxScale Lite.

• Maximum: Unlimited in MaxScale, 15 in MaxScale Lite.

The maximum number of simultaneous connections MaxScale should permit to this service. Any attempt to make more connections after the limit is reached will result in a "Too many connections" error being returned.

A value of 0 means no limit, which is the default for MaxScale. MaxScale Lite is limited to a maximum of 15 connections per service.

Warning: In MaxScale 2.5, it is possible that the number of concurrent connections temporarily exceeds the value of max_connections. This has been fixed in MaxScale 6.

Example:

[Test-Service]
max_connections=100

session_track_trx_state

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

*Note: This parameter has been deprecated in MaxScale 23.08 as the feature is now used automatically if needed. In addition, the session tracking no longer needs to be enabled in MariaDB for the transaction state tracking to work correctly.

Enable transaction state tracking by offloading it to the backend servers. Getting the transaction state from the server will be more accurate for stored procedures or multi-statement SQL that modifies the transaction state non-atomically.

In general, it is better to avoid using this type of SQL as tracking the transaction state via the server responses is not compatible with features such as transaction_replay in readwritesplit. session_track_trx_state should only be enabled if the default transaction tracking done by MaxScale does not produce the desired outcome.

This is only supported by MariaDB versions 10.3 or newer. The following must be configured in the MariaDB server in order for this feature to work. Not configuring the MariaDB server with it can result in the transaction state being wrong in MaxScale which can result in data inconsistency.

session_track_state_change = ON
session_track_transaction_info = CHARACTERISTICS

retain_last_statements

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: -1

How many statements MaxScale should store for each session of this service. This overrides the value of the global setting with the same name. Ifretain_last_statements has been specified in the global section of the MaxScale configuration file, then if it has not been explicitly specified for the service, the global value holds, otherwise the service specific value rules. That is, it is possible to enable the setting globally and turn it off for a specific service, or just enable it for specific services.

The value of this parameter can be changed at runtime using maxctrl and the new value will take effect for sessions created thereafter.

maxctrl alter service MyService retain_last_statements 5

connection_keepalive

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 300s

• Auto tune: Yes

Keep idle connections alive by sending pings to backend servers. This feature was introduced in MaxScale 2.5.0 where it was changed from a readwritesplit-specific feature to a generic service feature. The default value for this parameter is 300 seconds. To disable this feature, set the value to 0.

The keepalive interval is specified as documented here. If no explicit unit is provided, the value is interpreted as seconds in MaxScale 2.5. In subsequent versions a value without a unit may be rejected. Note that since the granularity of the keepalive is seconds, a keepalive specified in milliseconds will be rejected, even if the duration is longer than a second.

The parameter value is the interval in seconds between each keepalive ping. A keepalive ping will be sent to a backend server if the connection has been idle for longer than the configured keepalive interval.

Starting with MaxScale 2.5.21 and 6.4.0, the keepalive pings are not sent if the client has been idle for longer than the configured value ofconnection_keepalive. Older versions of MaxScale sent the keepalive pings regardless of the client state.

This parameter only takes effect in top-level services. A top-level service is the service where the listener that the client connected to points (i.e. the value of service in the listener). If a service defines other services in itstargets parameter, the connection_keepalive for those is not used.

If the value of connection_keepalive is changed at runtime, the change in the value takes effect immediately.

As the connection keepalive pings must be done only when there's no ongoing query, all requests and responses must be tracked by MaxScale. In the case ofreadconnroute, this will incur a small drop in performance. For routers that rely on result tracking (e.g. readwritesplit and schemarouter), the performance will be the same with or without connection_keepalive.

If you want to avoid the performance cost and you don't need the connection keepalive feature, you can disable it with connection_keepalive=0s.

force_connection_keepalive

• Type: boolean

• Mandatory No

• Dynamic: Yes

• Default: false

By default, connection keepalive pings are only sent if the client is either executing a query or has been idle for less than the duration configured inconnection_keepalive. When this parameter is enabled, keepalive pings are unconditionally sent to any backends that have been idle for longer thanconnection_keepalive seconds. This option was added in MaxScale 6.4.9 and can be used to emulate the pre-2.5.21 behavior if long-lived application connections rely on the old unconditional keepalive pings.

Note: if force_connection_keepalive is enabled and connection_keepalive in MaxScale is set to a lower value than the wait_timeout on the database, the client idle timeouts that wait_timeout control are no longer effective. This happens because MaxScale unconditionally sends the pings which make the client behave like it is not idle and thus the connections will never be killed due towait_timeout.

net_write_timeout

• Type: durations

• Mandatory No

• Dynamic: Yes

• Default: 0s

This parameter controls how long a network write to the client can stay buffered. This feature is disabled by default.

When net_write_timeout is configured and data is buffered on the client network connection, if the time since the last successful network write exceeds the configured limit, the client connection will be disconnected.

The value is specified as documented here. If no explicit unit is provided, the value is interpreted as seconds in MaxScale 2.4. In subsequent versions a value without a unit may be rejected. Note that since the granularity of the timeout is seconds, a timeout specified in milliseconds will be rejected, even if the duration is longer than a second.

max_sescmd_history

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: 50

max_sescmd_history sets a limit on how many distinct session commands are stored in the session command history. When the history limit is exceeded, the history is either pruned to the last max_sescmd_history command (whenprune_sescmd_history is enabled) or the history is disabled and server reconnections are no longer possible.

The required history size can be estimated by counting the total number of session state modifying commands (e.g SET NAMES) that are used by a client. Note that connectors usually add some commands that aren't visible to the application developer which means a safety margin should be added. A good rule of thumb is to count the expected number of statements and double that number. The default value of 50 is a value that'll work for most applications that do not rely heavily on user variables.

Starting with MaxScale versions 21.06.18, 22.08.15, 23.02.12, 23.08.8, 24.02.4 and 24.08.1, binary protocol prepared statements do not count towards themax_sescmd_history limit. In practice this means that all binary protocol prepared statements opened by the client are also kept open by MaxScale and are restored whenever a reconnection to a server happens. The limits imposed bymax_sescmd_history apply to other text protocol commands e.g. SET NAMES. Note that text protocol prepared statements count as text protocol commands and are thus potentially pruned when history pruning happens. If an application uses a lot of PREPARE stmt FROM <sql> commands, it is recommended that the value ofmax_sescmd_history is increased accordingly.

In older versions of MaxScale, binary protocol prepared statements were limited by max_sescmd_history and were also pruned by prune_sescmd_history but this caused problems when the binary protocol prepared statment were pruned while they were still open from the client's point of view. In older versions, the recommended value of max_sescmd_history is the number of state modifying commands plus the maximum number of open prepared statments that any application may use.

This parameter was moved into the MaxScale core in MaxScale 6.0. The parameter can be configured for all routers that support the session command history. Currently only readwritesplit and schemarouter support it.

In addition to limiting the number of commands to store, it also acts as a hard limit on the number of packets that may be queued up on a backend before it is closed. Packets are queued while the TCP socket is being opened and when prepared statements are being prepared. In certain rare cases, a slow server may fall behind and not catch up to the rest of the cluster and a backlog of packets forms. In these cases, if more than max_sescmd_history packets are queued, the connection to the server is closed.

prune_sescmd_history

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: true

This option enables pruning of the session command history when it exceeds the value configured in max_sescmd_history. When this option is enabled, only a set number of statements are stored in the history. This limits the per-session memory use while still allowing safe reconnections.

This parameter is intended to be used with pooled connections that remain in use for a very long time. Most connection pool implementations do not reset the session state and instead re-initialize it with new values. This causes the session command history to grow at roughly a constant rate for the lifetime of the pooled connection.

Starting with MaxScale 23.08, the session command history is also simplified before being stored. The simplification is done by removing repeated occurrences of the same command and only executing the latest one of them. The order in which the commands are executed still remains the same but inter-dependencies between commands are not preserved.

For example, the following set of commands demonstrates how the history simplification works and how inter-dependencies can be lost.

SET @my_planet='Earth';                            -- This command will be removed by history simplification
SET @my_home='My home is: ' || @my_planet;         -- Command #1 in the history
SET @my_planet='Earth';                            -- Command #2 in the history

In the example, the value of @my_home has a dependency on the value of@my_planet which is lost when the same statement is executed again and the history simplification removes the earlier one.

This same problem can occur even in older versions of MaxScale that used a sliding window of the history when the window moves past the statement that later statement depended on. If inter-dependent session commands are being used, the history pruning should be disabled.

Each client-side session that uses a pooled connection only executes a finite amount of session commands. By retaining a shorter history that encompasses all session commands the individual clients execute, the session state of a pooled connection can be accurately recreated on another server.

When the session command history pruning is enabled, there is a theoretical possibility that upon server reconnection the session states of the connections are inconsistent. This can only happen if the length of the stored history is shorter than the list of relevant statements that affect the session state. In practice the default value of 50 session commands is a fairly reasonable value and the risk of inconsistent session state is relatively low.

In case the default history length is too short for safe pruning, set the value of max_sescmd_history to the total number of commands that affect the session state plus a safety margin of 10. The safety margin reserves some extra space for new commands that might be executed due to changes in the client side application.

Starting with MaxScale 24.02.1, the execution of simple session commands done with binary protocol prepared statements are also stored in the history. A simple session command in the binary protocol is one that:

• Takes no parameters

• Modifies the session state

• Is executed while the original prepared statement is still in the history

The same limitations that apply to the text protocol session commands apply to the binary protocol session commands.

This parameter was moved into the MaxScale core in MaxScale 6.0. The parameter can be configured for all routers that support the session command history. Currently only readwritesplit and schemarouter support it.

disable_sescmd_history

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

This option disables the session command history. This way no history is stored and if a replica server fails, the router will not try to replace the failed replica. Disabling session command history will allow long-lived connections without causing a constant growth in the memory consumption.

This parameter should only be used when either the memory footprint must be as small as possible or when the pruning of the session command history is not acceptable.

This parameter was moved into the MaxScale core in MaxScale 6.0. The parameter can be configured for all routers that support the session command history. Currently only readwritesplit and schemarouter support it.

user_accounts_file

• Type: path

• Mandatory: No

• Dynamic: No

• Default: ""

Defines path to a file with additional user accounts for incoming clients. Default value is empty, which disables the feature.

user_accounts_file=/home/root/users.json

In addition to querying the backends, MaxScale can read users from a file. This feature is useful when backends have limitations on the type of users that can be created, or if MaxScale needs to allow users to log in even when backends are down (e.g. binlog router). The users read from the file are only present on MaxScale, so logging into backends can still fail. The format of the file is protocol-specific. The following only applies to MariaDB-protocol, which is also the only protocol supporting this feature.

The file contains json text. Three objects are read from it: user, db androles_mapping, none of which are mandatory. These objects must be arrays which contain user information similar to the mysql.user, mysql.db andmysql.roles_mapping tables on the server. Each array element must define at least the string fields user and host, which define the user account to add or modify.

The elements in the user-array may contain the following additional fields. If a field is not defined, it is assumed either empty (string) or false (boolean).

• password: String. Password hash, similar to the equivalent column on server.

• plugin: String. Authentication plugin used by client, similar to server.

• authentication_string: String. Additional authentication info, similar to server.

• default_role: String. Default role of user, similar to server.

• super_priv: Boolean. True if user has SUPER grant.

• global_db_priv: Boolean. True if user can access any database on login.

• proxy_priv: Boolean. True if user has a PROXY grant.

• is_role: Boolean. True if user is a role.

The elements in the db-array must contain the following additional field:

• db: String. Database which the user can access. Can contain % and _ wildcards.

The elements in the roles_mapping-array must contain the following additional field:

• role: String. Role the user can access.

When users are read from both servers and the file, the server takes priority. That is, if user 'joe'@'%' is defined on both, the file-version is discarded. The file can still affect the database grants and roles of 'joe'@'%', as thedb and roles_mapping-arrays are read separately and added to existing grant and role lists.

An example users file is below.

{
    "user": [
        {
            "user": "test1",
            "host": "%",
            "global_db_priv": true
        },
        {
            "user": "test2",
            "host": "127.0.0.1",
            "password": "*032169CDF0B90AF8C00992D43D354E29A2EACB42",
            "plugin": "mysql_native_password",
            "default_role": "role2"
        },
        {
            "user": "",
            "host": "%",
            "plugin": "pam",
            "proxy_priv": true
        }
    ],
    "db": [
        {
            "user": "test2",
            "host": "127.0.0.1",
            "db": "test"
        }
    ],
    "roles_mapping": [
        {
            "user": "test2",
            "host": "127.0.0.1",
            "role": "role2"
        }
    ]
}

user_accounts_file_usage

• Type: enum

• Mandatory: No

• Dynamic: No

• Values: add_when_load_ok, file_only_always

• Default: add_when_load_ok

Defines when user_accounts_file is read. The value is an enum, either "add_when_load_ok" (default) or "file_only_always".

"add_when_load_ok" means that the file is only read when users are successfully read from a server. The file contents are then added to the server-based data. If reading from server fails (e.g. servers are down), the file is ignored.

"file_only_always" means that users are not read from the servers at all and the file contents is all that matters. The state of the servers is ignored. This mode can be useful with the binlog router, as it allows clients to log in and fetch binary logs from MaxScale even when backend servers are down.

user_accounts_file_usage=file_only_always

idle_session_pool_time

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: -1s

Normally, MaxScale only pools backend connections when a session is closed (controlled by server settings persistpoolmax andpersistmaxtime). Other sessions can use the pooled connections instead of creating new connections to backends. If connection sharing is enabled, MaxScale can pool backend connections also from running sessions, and re-attach a pooled connection when a session is doing a query. This effectively allows multiple sessions to share backend connections.

idle_session_pool_time defines the amount of time a session must be idle before its backend connections may be pooled. To enable connection sharing, setidle_session_pool_time to zero or greater. The value can be given in seconds or milliseconds.

This feature has a significant drawback: when a backend connection is reused, it needs to be restored to the correct state. This means reauthenticating and replaying session commands. This can add a significant delay before the connection is actually ready for a query. If the session command history size exceeds the value of max_sescmd_history, connection sharing is disabled for the session.

This feature should only be used when limiting the backend connection count is a priority, even at the cost of query delay and throughput. This feature only works when the following server settings are also set in MaxScale configuration:

1. max_routing_connections

2. persistpoolmax

3. persistmaxtime

Since reusing a backend connection is an expensive operation, MaxScale only pools connections when another session requires them. idle_session_pool_time thus effectively limits the frequency at which a connection can be moved from one session to another. Setting idle_session_pool_time=0ms causes MaxScale to move connections as soon as possible.

idle_session_pool_time=900ms

See below for more information on configuring connection sharing.

Details, limitations and suggestions for connection sharing

As noted above, when a connection is pooled and reused its state is lost. Although session variables and prepared statements are restored by replaying session commands, some state information cannot be transferred.

The most common such state is a transaction. When a transaction is on, connection sharing is disabled for that session until the transaction completes. Other similar situations may not be properly detected, and it's the responsibility of the user to avoid introducing such state to the session when using connection sharing. This means that the following should not be used:

• Statements such as LOCK TABLES and GET LOCK or any other statement that introduces state into the connection.

• Temporary tables and some problematic user or session variables such asLAST_INSERT_ID(). For LAST_INSERT_ID(), the value returned by the connector must be used instead of the variable.

• Stored procedures that cause session level side-effects.

Several settings affect connection sharing and its effectiveness. Reusing a connection is an expensive operation so its frequency should be minimized. The important configuration settings in addition to idle_session_pool_time are MaxScale server settingspersistpoolmax,persistmaxtime andmax_routing_connections. The service settings max_sescmd_history,prune_sescmd_history andmultiplex_timeout also have an effect. These settings should be tuned according to the use case.

persistpoolmax limits how many connections can be kept in a pool for a given server. If the pool is full, no more connections are detached from sessions even if they are idle and required. The pool size should be large enough to contain any connections being transferred between sessions, but not be greater thanmax_routing_connections. Using the value of max_routing_connections is a reasonable starting point.

persistmaxtime limits the time a connection may stay in the pool. This should be high enough so that pooled connections are not unnecessarily closed. Cleaning up clearly unneeded connections from the pool may be useful whenmax_routing_connections is restrictively tuned. Because each MaxScale routing thread has its own connection pool, one thread can monopolize access to a server. For example, if the pool of thread 1 has 100 connections to ServerA with max_routing_connections=100, other threads can no longer connect to the server. In such a situation, reducing persistmaxtime of ServerA may help as it would cause unneeded connections in the pool to be closed faster. Such connection slots then become available to other routing threads. Reducing the number of routing threads may also help, as it reduces pool fragmentation. This may reduce overall throughput, though. When using connection sharing, backend connections are only in the pool momentarily. Consequently,persistmaxtime can be set quite low, e.g. 10s.

If a client session exceeds max_sescmd_history (default 50), pooling is disabled for that session. If many sessions do this andmax_routing_connections is set, other sessions will stall as they cannot find a backend connection. This can be avoided with prune_sescmd_history. However, pruning means that old session commands will not be replayed when a pooled connection is reused. If the pruned commands are important (e.g. statement preparations), the session may fail later on.

If the number of clients actively running queries is greater thanmax_routing_connections, query throughput will suffer as clients will need to take turns. In this situation, it's imperative to minimize the number of backend connections a single session uses. The settings to achieve this depend on the router. For ReadWriteSplit the following should be used:

max_slave_connections=1
lazy_connect=1
transaction_replay=true

The above settings mean that MaxScale can process roughly (number of replica servers X max_routing_connections) read queries simultaneously. Write queries will still need to take turns as there is only one primary server.

The following configuration snippet shows example server and service configurations for connection sharing with ReadWriteSplit.

[server1]
type=server
max_routing_connections=1000 #this should be based on MariaDB Server capacity
persistpoolmax=1000 #same as above
persistmaxtime=10
#other server settings...

[myservice]
type=service
max_slave_connections=1
transaction_replay=true
idle_session_pool_time=500ms
lazy_connect=1
#other service settings...

multiplex_timeout

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 60s

When connection sharing (as described above) is on, clients may have to wait for their turn to use a backend connection. If too much time passes without a connection becoming available, MaxScale returns an error to the client, usually also ending the session. multiplex_timeout sets this timeout. Increase it if queries are failing with "Timed out when waiting for a connection". Decrease it if failing early is preferable to stalling.

multiplex_timeout=33s

Server

Server sections define the backend database servers MaxScale uses. A server is identified by its section name in the configuration file. The only mandatory parameter of a server is type, but address and port are also usually defined. A server may be a member of one or more services. A server may only be monitored by at most one monitor.

[MyMariaDBServer1]
type=server
address=127.0.0.1
port=3000

Limitations:

• MaxScale: No limitations.

• MaxScale Lite: At most 3 servers can be created.

address

• Type: string

• Mandatory: Yes, if socket is not provided.

• Dynamic: Yes

• Default: ""

The IP-address or hostname of the machine running the database server. MaxScale uses this address to connect to the server.

Either address or socket must be defined, but not both. If the address is given as a hostname, MaxScale will perform name lookup on the hostname when starting and update the result every minute and when the address changes.

port

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: 3306

The port the backend server listens on for incoming connections. MaxScale uses this port to connect to the server.

socket

• Type: string

• Mandatory: Yes, if address is not provided.

• Dynamic: Yes

• Default: ""

The absolute path to a UNIX domain socket the MariaDB server is listening on.

private_address

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: ""

Alternative IP-address or hostname for the server. This is currently only used by MariaDB Monitor to detect and set up replication. SeeMariaDB Monitor documentation for more information.

monitoruser

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: None

This setting together with monitorpasswd define server-specific credentials for monitoring the server. Monitors typically use the credentials in their own configuration sections to connect to all servers. If server-specific settings are given, the monitor uses those instead.

monitoruser=mymonitoruser
monitorpw=mymonitorpasswd

monitorpw

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: None

This setting together with monitoruser define server-specific credentials for monitoring the server. Monitors typically use the credentials in their own configuration sections to connect to all servers. If server-specific settings are given, the monitor uses those instead.

monitoruser=mymonitoruser
monitorpw=mymonitorpasswd

monitorpw may be either a plain text password or an encrypted password. See the section encrypting passwords for more information.

extra_port

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: 0