Choose the right installation method for MariaDB MaxScale. This section includes guides for building from source code and installing via tarballs for custom or non-standard deployments.
Install MariaDB MaxScale on Linux using official package repositories or RPM/DEB files. This guide details setup for RHEL, Debian, and SLES, plus essential memory and backup configuration.
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.
The recommended approach is to use 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.
Download the correct MaxScale package for your CPU architecture and operating system from the . 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.
MaxScale can also be installed using a tarball. This 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 to .
Alternatively, you may download the MariaDB MaxScale source and build your own binaries. To do this, refer to the separate document .
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 parameter 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 this command:
Alternatively, use this command:
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 the and the module specific documents found in the .
Read the section of the configuration guide to set up password encryption for the configuration file.
There are various administration tasks that may be done with MariaDB MaxScale. A command line tools is available, , that interacts with a running MariaDB MaxScale and allows the status of MariaDB MaxScale to be monitored and give some control of the MariaDB MaxScale functionality.
The covers the common administration tasks that need to be done with MariaDB 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:
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
Compile MariaDB MaxScale from source code. This guide details the build prerequisites, CMake configuration options, and steps to generate custom binary packages for your system.
GCC version 4.9 or later
OpenSSL version 1.1.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.
This installs MaxScale as if it was installed from a package. Install git before running the following commands.
For a definitive list of packages, consult the install_build_deps.sh script.
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 in NAME=VALUE format (e.g. -DBUILD_TESTS=Y).
CMAKE_INSTALL_PREFIX
Location where MariaDB MaxScale will be installed to. Set this to /usr if you want MariaDB MaxScale installed into the same place the packages are installed.
BUILD_TESTS
Build unit tests
WITH_SCRIPTS
Install systemd and init.d scripts
PACKAGE
Enable building of packages
TARGET_COMPONENT
Which component to install, default is the 'core' package. Other targets are 'experimental', which installs experimental packages and 'all' which installs all components.
TARBALL
Build tar.gz packages, requires PACKAGE=Y
Note: You can look into defaults.cmake for a list of the CMake variables.
To run the MaxScale unit test suite, configure the build with -DBUILD_TESTS=Y, compile and then run the make test command.
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.
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
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 ./postinstmake
LD_LIBRARY_PATH=$PWD/server/core/ make packagesysctl vm.overcommit_memorycat /proc/sys/vm/overcommit_memorytar -caf maxscale-backup.tar.gz /etc/maxscale.cnf /etc/maxscale.cnf.d/ /var/lib/maxscale/Install MariaDB MaxScale manually using generic tarball binaries. Learn the system requirements, directory setup, and configuration steps to run MaxScale without a package manager.
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
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.
/usr/localIf 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:
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:
and make maxscale the owner of them:
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 for details.
When the configuration file has been created, MariaDB MaxScale can be started.
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.
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.
Enter a directory where you have the right to create a subdirectory. Then do as follows.
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 for details.
When the configuration file has been created, MariaDB MaxScale can be started.
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
to find out the appropriate flags.
This page is licensed: CC BY-SA / Gnu FDL
unixODBC
$ 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$ sudo mkdir /var/log/maxscale
$ sudo mkdir /var/lib/maxscale
$ sudo mkdir /run/maxscale
$ sudo mkdir /var/cache/maxscale$ sudo chown maxscale /var/log/maxscale
$ sudo chown maxscale /var/lib/maxscale
$ sudo chown maxscale /run/maxscale
$ sudo chown maxscale /var/cache/maxscale$ sudo bin/maxscale --user=maxscale -d$ sudo bin/maxscale --user=maxscale --basedir=/usr/local/maxscale -d$ tar -xzvf maxscale-x.y.z.OS.tar.gz$ cd maxscale-x.y.z.OS
$ bin/maxscale -d --basedir=.$ bin/maxscale --help