This document is designed as a quick introduction to setting up MariaDB MaxScale.
The installation and configuration of the MariaDB Server is not covered in this document.
See the following MariaDB documentation articles for more information on setting up a
primary-replica-cluster or a Galera-cluster:
and
.
This tutorial assumes that one of the standard MaxScale binary distributions is used and
that MaxScale is installed using default options.
Building from source code in GitHub is covered in Building from Source.
Installing MaxScale
The precise installation process varies from one distribution to another. Details on
package installation can be found in the .
Creating a user account for MaxScale
MaxScale checks that incoming clients are valid. To do this, MaxScale needs to retrieve
user authentication information from the backend databases. Create a special user
account for this purpose by executing the following SQL commands on the primary server of
your database cluster. The following tutorials will use these credentials.
MariaDB versions 10.2.2 to 10.2.10 also require GRANT SELECT ON mysql.* TO 'maxscale'@'%';
Creating client user accounts
Because MariaDB MaxScale sits between the clients and the backend databases, the backend
databases will see all clients as if they were connecting from MaxScale's address. This
usually means that two sets of grants for each user are required.
For example, assume that the user 'jdoe'@'client-host' exists and MaxScale is located at_maxscale-host_. If 'jdoe'@'client-host' needs to be able to connect through MaxScale,
another user, 'jdoe'@'maxscale-host', must be created. The second user must have the
same password and similar grants as 'jdoe'@'client-host'.
The quickest way to do this is to first create the new user:
Then do a SHOW GRANTS query:
Then copy the same grants to the 'jdoe'@'maxscale-host' user.
An alternative to generating two separate accounts is to use one account with a wildcard
host ('jdoe'@'%') which covers both hosts. This is more convenient but less secure than
having specific user accounts as it allows access from all hosts.
Creating the configuration file
MaxScale reads its configuration from /etc/maxscale.cnf. A template configuration is
provided with the MaxScale installation.
A global maxscale section is included in every MaxScale configuration file. This section
sets the values of various global parameters, such as the number of threads MaxScale uses
to handle client requests. To set thread count to the number of available cpu cores, set
the following.
Configuring the servers
Read the mini-tutorial for server
configuration instructions.
Configuring the monitor
The type of monitor used depends on the type of cluster used. For a primary-replica cluster
read .
For a Galera cluster read .
Configuring the services and listeners
This part is covered in two different tutorials. For a fully automated
read-write-splitting setup, read the .
For a simple connection based setup, read the .
Starting MaxScale
After configuration is complete, MariaDB MaxScale is ready to start. For systems that
use systemd, use the systemctl command.
For older SysV systems, use the service command.
If MaxScale fails to start, check the error log in /var/log/maxscale/maxscale.log to see
if any errors are detected in the configuration file.
Checking MaxScale status with MaxCtrl
The maxctrl-command can be used to confirm that MaxScale is running and the services,
listeners and servers have been correctly configured. The following shows expected output
when using a read-write-splitting configuration.
MariaDB MaxScale is now ready to start accepting client connections and route queries to
the backend cluster.
More options can be found in the , and .
For more information about MaxCtrl and how to secure it, see the .
This page is licensed: CC BY-SA / Gnu FDL