README

/** \mainpage MaxScale by SkySQL

The SkySQL MaxScale is an intelligent proxy that allows forwarding of
database statements to one or more database servers using complex rules,
a semantic understanding of the database statements and the roles of
the various servers within the backend cluster of databases.

MaxScale is designed to provide load balancing and high availability
functionality transparantly to the applications. In addition it provides
a highly scalable and flexibile architecture, with plugin components to
support different protocols and routing decissions.

MaxScale is implemented in C and makes entensive use of the
asynchronous I/O capabilities of the Linux operating system. The epoll
system is used to provide the event driven framework for the input and
output via sockets.

The protocols are implemented as external shared object modules which
can be loaded at runtime. These modules support a fixed interface,
communicating the entries points via a structure consisting of a set of
function pointers. This structure is called the "module object".

The code that routes the queries to the database servers is also loaded
as external shared objects and are referred to as routing modules.

An Google Group exists for MaxScale that can be used to discuss ideas,
issues and communicate with the MaxScale community.
	[maxscale@googlegroups.com]: mailto:maxscale@googlegroups.com
	
Bugs can be reported in the SkySQL bugs database
	[bug.skysql.com]: http://bugs.skysql.com

\section Building Building MaxScale

Edit the file build_gateway.inc in your MaxScale directory and set
the ROOT_PATH to the directory in which you have installed the
MaxScale source code. Set the MYSQL_ROOT/MYSQL_HEADERS variables
to the location in which you have installed the developer package
for MariaDB or checked out the source code of MariaDB and the
location of your MariaDB include files.

The include files, static embedded library and other files may come
from the RPMs packages:

MariaDB-5.5.34-centos6-x86_64-common.rpm
MariaDB-5.5.34-centos6-x86_64-compat.rpm
MariaDB-5.5.34-centos6-x86_64-devel.rpm

Please backup any existent my.cnf file before installing the RPMs

Install the RPM files using:

	rpm -i --force --relocate=/usr/=$PREFIX/usr/ MariaDB-5.5.34-centos6-x86_64-common.rpm MariaDB-5.5.34-centos6-x86_64-compat.rpm MariaDB-5.5.34-centos6-x86_64-devel.rpm

This README assumes $PREFIX = $HOME.

MaxScale may be built with the embedded MariaDB library either linked
dynamically or statically.

To build with the embedded libmysqld linked dynamically from an
existent MariaDB setup

set DYNLIB := Y
copy the libmysqld.so in $(HOME)/usr/lib64/dynlib

To build with the embedded libmysqld linked statically

If DYNLIB is not set MaxScale will be built using the static library
found in $(HOME)/usr/lib64

This libmysqld.a comes from the RPM or it is copied from an existing
MariaDB setup. The file embedded_priv.h is not available in the RPM
packages, please get it from an existing MariaDB setup and copy it
to one of the path in MYSQL_HEADERS


The ERRMSG variable points to the errmsg.sys file that is required
by the embedded library.

Example:

	ERRMSG := $(HOME)/usr/share/mysql


Please note the errmsg.sys file is NOT included in the RPMs at the
curent time, it must be taken from an existing MariaDB setup. The
version of the errmsg.sys file must match the version of the developer
package you are using. A version mismatch will cause the library to fail
to initialise.

You may get the one in the 'english' folder:

Example /usr/local/mariadb/share/english/errmsg.sys


Go to the MaxScale directory and do:

	make depend

to update all the dependency files and then do:

	make

	make install

You may set the DEST variable for the target install location, example:

	make DEST=/some/path

	make DEST=/some/path install


If DEST is not set the default install location is:

	DEST=$(HOME)/usr/local/skysql

This should get you all the things built that you need.

Other make targets are available

clean	- Removes compiled code and shared objects
install - Installs the binary and the modules in the location defined by the
make variable DEST

ctags - Build tags files for the vi editor

documentation - Build the doxygen documentation

depend - Update the dependencies used by the makefiles

Two files are required for the libmysqld library that is used within MaxScale,
errmsg,sys and a my.cnf file with the following:

External libraries/packages required:

openssl and openssl-devel
libaio

Note: on CentOS 6 do:

ln -s /lib64/libaio.so.1 /lib64/libaio.so

[mysqld]
max_connections=4096

Please check errmsg.sys is found in the MaxScale install_dir DEST/MaxScale/mysql

\section Running  Running MaxScale

MaxScale consists of a core executable and a number of modules that implement
the different protocols and routing algorithms. These modules are built as
shared objects that are loaded on demand. In order for MaxScale to find these
modules it will search using a predescribed search path. The rules are:

1. Look in the current directory for the module

2. Look in $MAXSCALE_HOME/modules

3. Look in /usr/local/skysql/MaxScale/modules

Configuration is read by default from the file
$MAXSCALE_HOME/etc/MaxScale.cnf, /etc/MaxScale.cnf, an example file
is included in the root of the source tree. The default value of
MAXSCALE_HOME can be overriden by use of the -c flag on the command
line. This should be immediately followed by the path to the MaxScale
home directory.

The -f flag can be used to set the name and the location of the configuration 
file. Without path expression the file is read from $MAXSCALE_HOME/etc directory.
*/