July 10, 2014

Installing newest MaxScale from scratch - the builder's edition

IMPORTANT NOTE: The instructions in this article are deprecated. For the most up to date information on MaxScale please see the Documentation section in the MaxScale GitHub repository or check out the MaxScale forum on Google Groups

What is MaxScale?

MaxScale is an open-source, database-centric router that currently works with MariaDB and MySQL. It has a pluggable architecture designed to increase flexibility and aid customisation as well as a lightweight, high-speed networking core designed to facilitate throughput. MaxScale runs between the client application and the database cluster and currently offers connection and statement-based load balancing, query filtering, rewriting and logging facilities.

I've put together these instructions so that anyone having one spare host and a MySQL replication cluster (Master replicating to a handful of slaves) could fetch the sources, build, install and run MaxScale in ten minutes.

If you want to hear more of what MaxScale is and what you can do with it, I recommend to visit Mark Riddoch’s blog about the ideas behind MaxScale and newest features of it.

Installing MaxScale with this guide

The need for this post became obvious after receiving an increasing amount of questions which were related to linking, library versions and paths in MaxScale. Moreover, I know that there are many who want to make things with their bare hands so it is good to have something which hopefully makes the whole process smoother.

The host MaxScale will be installed is assumed to be fresh, CentOS6.5 which has nothing but the operating system installed. It is especially important that there is nothing from other MySQL installations left in the host because everything in what follows, is installed carelessly to system directories. Using headers, libraries or error files from different versions leads almost certainly to unplanned behavior.

Setting up MySQL replication cluster (or any other cluster types MaxScale supports) is not covered here. So I assume you already have a master/slave replication successfully set up.

The text refers to source branches by their names. Same instructions should apply to other branches as well as to the one used here.

Get sources

yum install git
mkdir src ; cd src
mkdir git ; cd git
mkdir release-1.0beta ; cd release-1.0beta

git init
git remote -v add maxscale https://github.com/skysql/MaxScale
git pull -v maxscale master
git checkout -b release-1.0beta
git pull -v maxscale release-1.0beta

Get and set up MariaDB

vi /etc/yum.repos.d/mariadb.repo

add :

[mariadb]
	name = MariaDB
	baseurl = http://yum.mariadb.org/5.5/centos6-amd64
	gpgkey=https://yum.mariadb.org/RPM-GPG-KEY-MariaDB
	gpgcheck=1

and save.

yum install MariaDB-server
yum install MariaDB-devel

Build MaxScale

yum -y install make gcc gcc-c++ ncurses-devel bison glibc-devel openssl-devel libaio libaio-devel telnet

edit build_gateway.inc in the root directory and set :

ROOT_PATH := $(HOME)/src/git/release-1.0beta
INC_PATH := /usr/include
ERRMSG := /usr/share/mysql/english/

mkdir ~/usr
mkdir ~/usr/lib64
ln -s /usr/lib64/libmysqld.a ~/usr/lib64/

make DYNLIB=N DEST=~/bin/release-1.0beta clean depend all install

Configure

cp ~/bin/release-1.0beta/etc/MaxScale_template.cnf ~/bin/release-1.0beta/etc/MaxScale.cnf

In the configuration file ~/bin/release-1.0beta/MaxScale.cnf , set correct values to at least to the following sections :

[MySQL Monitor]
user=myuser
passwd=mypwd

[RW Split Router]
user=myuser
passwd=mypwd

[Read Connection Router]
user=myuser
passwd=mypwd

[server1]
address=(ip #1)
port=3306

[server2]
address=(ip #2)
port=3306

[server3]
address=(ip #3)
port=3306

Backend database servers

Start three mariadb servers - 1 Master and 2 Slaves. Execute the following in each:

GRANT ALL PRIVILEGES ON *.* TO myuser@(ip #1) IDENTIFIED BY 'mypwd' WITH GRANT OPTION
GRANT ALL PRIVILEGES ON *.* TO myuser@'%' IDENTIFIED BY 'mypwd' WITH GRANT OPTION

Start MaxScale

cd ~/bin/release-1.0beta/bin
./maxkeys ~/bin/release-1.0beta/etc/.secrets
./maxscale -d -c ../

Time

from 0..compiled 8:50:72 (almost nine minutes) from compiled to running 11:46:23

Troubleshooting

If you have taken all the steps listed above and have trouble getting MaxScale started or you encounter some unexpected behavior, you may find help from error and message logs.

When MaxScale starts it prints essential information to the terminal window, which helps in problem resolution.

SkySQL MaxScale 1.0.0   Fri Jul  4 16:05:32 2014
------------------------------------------------------
Info : MaxScale will be run in the terminal process.
 See the log from the following log files :

Error log 	: /home/raatikka/bin/release-1.0beta/log/skygw_err1.log
Message log   : /home/raatikka/bin/release-1.0beta/log/skygw_msg1.log
Trace log 	: /home/raatikka/bin/release-1.0beta/log/skygw_trace1.log
Debug log 	: /home/raatikka/bin/release-1.0beta/log/skygw_debug1.log

Home directory 	: /home/raatikka/bin/release-1.0beta
Configuration file : /home/raatikka/bin/release-1.0beta/etc/MaxScale.cnf
Data directory 	: /home/raatikka/bin/release-1.0beta/data22732

MaxScale PID 22732 in pidfile /home/raatikka/bin/release-1.0beta/log/maxscale.pid
Listening MySQL connections at 0.0.0.0:4004
Listening MySQL connections at 0.0.0.0:4006
Listening MySQL connections at 0.0.0.0:4008
Listening http connections at 0.0.0.0:6444
Listening telnet connections at 0.0.0.0:4442

Refer to The Configuration and Usage Scenarios document for further information about different setups you can come up with.

Summary

My goal in this post was to make it easier to build your own MaxScale router and get it running during your next coffee break. Hope you’ll find interest to see what’s it capable of. More resources and discussion can be found from #maxscale channel on freenet, and through the links below.

Resources

About Vilho Raatikka

Vilho is a Senior Software Engineer working mainly on MaxScale. Vilho has worked with databases server technologies since the year 2000 for IBM, Solid Information Technology and Helsinki University as software engineer, teaching assistant and researcher.

Read all posts by Vilho Raatikka