hcq/MaxScale
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'release-1.2'

Browse Source 
Conflicts:
	Documentation/Documentation-Contents.md
This commit is contained in:
Markus Makela
2015-07-15 16:34:27 +03:00
parent 0d516789bf 124ad82de4
commit 4bb776f4e5
157 changed files with 7804 additions and 3134 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
Documentation/About/SETUP.md
View File

@ -1,37 +1,25 @@
Installation and startup
Untar the binary distribution in the desired location,
e.g. /usr/local/mariadb
e.g. /usr/local/mariadb-maxscale
Alternatively build from the source code using the instructions
in the README file and execute make install.
in the [Building MaxScale from Source Code](../Getting-Started/Building-MaxScale-from-Source-Code.md) document.
Simply set the environment variable MAXSCALE_HOME to point to the
MaxScale directory, found inside the path into which the files have been copied,
e.g. MAXSCALE_HOME=/usr/local/mariadb-maxscale
Also you will need to optionally set LD_LIBRARY_PATH to include the 'lib' folder,
found inside the path into which the files have been copied,
e.g. LD_LIBRARY_PATH=/usr/local/mariadb-maxscale/lib
Because we need the libmysqld library for parsing we must create a
valid my.cnf file to enable the library to be used. Copy the my.cnf
to $MAXSCALE_HOME/mysql/my.cnf.
To start MaxScale execute the command 'maxscale' from the bin folder,
e.g. /usr/local/mariadb-maxscale/bin/maxscale
You can start MaxScale using `service maxscale start` or `systemctl start maxscale` if you installed the init.d scripts
or by manually starting the process from the bin folder of the installation directory.
Configuration
You need to edit the file MaxScale.cnf in $MAXSCALE_HOME/etc, you should
define the set of server definitions you require, with the addresses
and ports of those servers. Also define the listening ports for your
various services.
You need to create or edit the maxscale.cnf file in the /etc folder.
Define the services you wish to provide, the set of server definitions
you require, with the addresses and ports of those servers and also
define the listening ports for your various services.
In order to view the internal activity of the gateway you can telnet to
In order to view the internal activity of MaxScale you can either use
the maxadmin client interface with the cli routing module or telnet to
the port defined for the telnet listener. Initially you may login with
the user name of "admin" and the password "mariadb". Once connected type
help for an overview of the commands and help <command> for the more
detailed help on commands. Use the add user command to add a new user,
this will also remove the admin/mariadb user.
this will also remove the admin/mariadb user. For a detailed guide about using the MaxAdmin interface, take a look at the [MaxAdmin](../Reference/MaxAdmin.md) guide.

43
Documentation/Documentation-Contents.md
View File

@ -5,7 +5,7 @@
## About MaxScale
- [About MaxScale](About/About-MaxScale.md)
- [Release Notes 1.1](Release-Notes/MaxScale-1.1-Release-Notes.md)
- [MaxScale 1.2.0 Release Notes](Release-Notes/MaxScale-1.2.0-Release-Notes.md)
- [Changelog](Changelog.md)
- [Limitations](About/Limitations.md)
- [COPYRIGHT](About/COPYRIGHT.md)
@ -13,20 +13,23 @@
## Getting Started
- [Getting Started with MaxScale](Getting-Started/Getting-Started-With-MaxScale.md)
- [MariaDB MaxScale Installation Guide](Getting-Started/MariaDB-MaxScale-Installation-Guide.md)
- [Building MaxScale from Source Code](Getting-Started/Building-MaxScale-from-Source-Code.md)
- [Configuration Guide](Getting-Started/Configuration-Guide.md)
## Upgrading MaxScale
- [Upgrading MaxScale to 1.1.0](Upgrading-To-MaxScale-1.1.0.md)
- [Upgrading MaxScale from 1.1.1 to 1.2.0](Upgrading-To-MaxScale-1.2.0.md)
- [Upgrading MaxScale from 1.0.5 to 1.1.0](Upgrading-To-MaxScale-1.1.0.md)
## Reference
- [MaxAdmin](Reference/MaxAdmin.md)
- [MaxScale HA with Corosync-Pacemaker](Reference/MaxScale-HA-with-Corosync-Pacemaker.md)
- [MaxScale HA with Lsyncd](Reference/MaxScale-HA-with-lsyncd.md)
- [How Errors are Handled in MaxScale](Reference/How-errors-are-handled-in-MaxScale.md)
- [Debug and Diagnostic Support](Reference/Debug-And-Diagnostic-Support.md)
- [Routing Hints](Reference/Hint-Syntax.md)
## Tutorials
@ -41,30 +44,35 @@
- [Replication Proxy with the Binlog Router Tutorial](Tutorials/Replication-Proxy-Binlog-Router-Tutorial.md)
- [RabbitMQ Setup and MaxScale Integration Tutorial](Tutorials/RabbitMQ-Setup-And-MaxScale-Integration.md)
- [Nagios Plugins for MaxScale Tutorial](Tutorials/Nagios-Plugins.md)
- [Simple Schema Sharding Tutorial](Tutorials/Simple-Sharding-Tutorial.md)
## Routers
- [Read Write Split](routers/ReadWriteSplit.md)
- [Schemarouter](routers/SchemaRouter.md)
- [Read Write Split](Routers/ReadWriteSplit.md)
- [Read Connnection Router](Routers/ReadConnRoute.md)
- [Schemarouter](Routers/SchemaRouter.md)
## Filters
Here are detailed documents about the filters MaxScale offers. They contain configuration guides and example use cases. Before reading these,you should have read the filter tutorial so that you know how they work and how to configure them.
- [Query Log All](filters/Query-Log-All-Filter.md)
- [Regex Filter](filters/Regex-Filter.md)
- [Tee Filter](filters/Tee-Filter.md)
- [Top N Filter](filters/Top-N-Filter.md)
- [Database Firewall Filter](filters/Database-Firewall-Filter.md)
- [RabbitMQ Filter](filters/RabbitMQ-Filter.md)
- [Query Log All](Filters/Query-Log-All-Filter.md)
- [Regex Filter](Filters/Regex-Filter.md)
- [Tee Filter](Filters/Tee-Filter.md)
- [Top N Filter](Filters/Top-N-Filter.md)
- [Database Firewall Filter](Filters/Database-Firewall-Filter.md)
- [RabbitMQ Filter](Filters/RabbitMQ-Filter.md)
- [Named Server Filter](Filters/Named-Server-Filter.md)
## Monitors
- [MySQL Monitor](Monitors/MySQL-Monitor.md)
- [Galera Monitor](Monitors/Galera-Monitor.md)
- [Multi-Master Monitor](Monitors/MM-Monitor.md)
- [MySQL Cluster Monitor](Monitors/NDB-Cluster-Monitor.md)
## Utilities
- [RabbitMQ Consumer Client](filters/RabbitMQ-Consumer-Client.md)
## Routers
- [Simple Schema Sharding Router](routers/SchemaRouter.md)
- [RabbitMQ Consumer Client](Filters/RabbitMQ-Consumer-Client.md)
## Design Documents
@ -81,4 +89,7 @@ Here are detailed documents about the filters MaxScale offers. They contain conf
- [MaxScale 1.0 Release Notes](Release-Notes/MaxScale-1.0-Release-Notes.md)
- [MaxScale 1.0.1 Release Notes](Release-Notes/MaxScale-1.0.1-Release-Notes.md)
- [MaxScale 1.0.3 Release Notes](Release-Notes/MaxScale-1.0.3-Release-Notes.md)
- [MaxScale 1.1.0 Release Notes](Release-Notes/MaxScale-1.1-Release-Notes.md)
- [MaxScale 1.1.1 Release Notes](Release-Notes/MaxScale-1.1.1-Release-Notes.md)
- [MaxScale 1.2.0 Release Notes](Release-Notes/MaxScale-1.2.0-Release-Notes.md)

2
Documentation/filters/Database-Firewall-Filter.md → Documentation/Filters/Database-Firewall-Filter.md
View File

@ -5,7 +5,7 @@ The database firewall filter is used to block queries that match a set of rules.
## Configuration
The database firewall filter only requires minimal configuration in the MaxScale.cnf file. The actual rules of the database firewall filter are located in a separate text file. The following is an example of a database firewall filter configuration in MaxScale.cnf.
The database firewall filter only requires minimal configuration in the maxscale.cnf file. The actual rules of the database firewall filter are located in a separate text file. The following is an example of a database firewall filter configuration in maxscale.cnf.
```
[DatabaseFirewall]

92
Documentation/Filters/Named-Server-Filter.md Normal file
View File

@ -0,0 +1,92 @@
Named Server Filter
# Overview
The **namedserverfilter** is a filter module for MaxScale which is able to route queries to servers based on regular expression matches.
# Configuration
The configuration block for the Named Server filter requires the minimal filter options in it’s section within the maxscale.cnf file, stored in /etc/maxscale.cnf.
```
[NamedServerFilter]
type=filter
module=namedserverfilter
match=some string
server=server2
[MyService]
type=service
router=readwritesplit
servers=server1,server2
user=myuser
passwd=mypasswd
filters=NamedServerFilter
```
## Filter Options
The named server filter accepts the options ignorecase or case. These define if the pattern text should take the case of the string it is matching against into consideration or not.
## Filter Parameters
The named server filter requires two mandatory parameters to be defined.
### `match`
A parameter that can be used to match text in the SQL statement which should be replaced.
```
match=TYPE[ ]*=
```
If the filter option ignorecase is used all regular expressions are evaluated with the option to ignore the case of the text, therefore a match option of select will match both type, TYPE and any form of the word with upper or lowercase characters.
### `server`
This is the server where matching queries will be router. The server should be in use by the service which uses this filter.
```
server=server2
```
### `source`
The optional source parameter defines an address that is used to match against the address from which the client connection to MaxScale originates. Only sessions that originate from this address will have the match and replacement applied to them.
```
source=127.0.0.1
```
### `user`
The optional user parameter defines a user name that is used to match against the user from which the client connection to MaxScale originates. Only sessions that are connected using this username will have the match and replacement applied to them.
```
user=john
```
## Examples
### Example 1 - Route queries targeting a specific table to a server
This will route all queries matching the regular expression ` *from *users` to the server named *server2*. The filter will ignore character case in queries.
A query like `SELECT * FROM users` would be routed to server2 where as a query like `SELECT * FROM accounts` would be routed according to the normal rules of the router.
```
[NamedServerFilter]
type=filter
module=namedserverfilter
match= *from *users
options=ignorecase
server=server2
[MyService]
type=service
router=readwritesplit
servers=server1,server2
user=myuser
passwd=mypasswd
filters=NamedServerFilter
```

2
Documentation/filters/Query-Log-All-Filter.md → Documentation/Filters/Query-Log-All-Filter.md
View File

@ -6,7 +6,7 @@ The Query Log All (QLA) filter is a filter module for MaxScale that is
## Configuration
The configuration block for the QLA filter requires the minimal filter options in it's section within the MaxScale.cnf file, stored in $MAXSCALE_HOME/etc/MaxScale.cnf.
The configuration block for the QLA filter requires the minimal filter options in it's section within the maxscale.cnf file, stored in /etc/maxscale.cnf.
```
[MyLogFilter]
type=filter

0
Documentation/filters/RabbitMQ-Consumer-Client.md → Documentation/Filters/RabbitMQ-Consumer-Client.md
View File

4
Documentation/filters/RabbitMQ-Filter.md → Documentation/Filters/RabbitMQ-Filter.md
View File

@ -5,9 +5,9 @@ This filter is designed to extract queries and transform them into a canonical f
## Configuration
The configuration block for the **mqfilter** filter requires the minimal filter options in it’s section within the MaxScale.cnf file, stored in $MAXSCALE_HOME/etc/MaxScale.cnf. Although the filter will start, it will use the default values which only work with a freshly installed RabbitMQ server and use its default values. This setup is mostly intended for testing the filter.
The configuration block for the **mqfilter** filter requires the minimal filter options in it’s section within the maxscale.cnf file, stored in /etc/maxscale.cnf. Although the filter will start, it will use the default values which only work with a freshly installed RabbitMQ server and use its default values. This setup is mostly intended for testing the filter.
The following is an example of a mqfilter configuration in the MaxScale.cnf file used for actual logging of queries to a RabbitMQ broker on a different host.
The following is an example of a mqfilter configuration in the maxscale.cnf file used for actual logging of queries to a RabbitMQ broker on a different host.
```
[RabbitMQ]

2
Documentation/filters/Regex-Filter.md → Documentation/Filters/Regex-Filter.md
View File

@ -6,7 +6,7 @@ The regex filter is a filter module for MaxScale that is able to rewrite query c
# Configuration
The configuration block for the Regex filter requires the minimal filter options in it’s section within the MaxScale.cnf file, stored in $MAXSCALE_HOME/etc/MaxScale.cnf.
The configuration block for the Regex filter requires the minimal filter options in it’s section within the maxscale.cnf file, stored in /etc/maxscale.cnf.
```
[MyRegexFilter]

2
Documentation/filters/Tee-Filter.md → Documentation/Filters/Tee-Filter.md
View File

@ -6,7 +6,7 @@ The tee filter is a filter module for MaxScale is a "plumbing" fitting in the Ma
# Configuration
The configuration block for the TEE filter requires the minimal filter parameters in it’s section within the MaxScale.cnf file, stored in $MAXSCALE_HOME/etc/MaxScale.cnf, that defines the filter to load and the service to send the duplicates to. Currently the tee filter does not support multi-statements.
The configuration block for the TEE filter requires the minimal filter parameters in it’s section within the maxscale.cnf file, stored in /etc/maxscale.cnf, that defines the filter to load and the service to send the duplicates to. Currently the tee filter does not support multi-statements.
```
[DataMartFilter]

2
Documentation/filters/Top-N-Filter.md → Documentation/Filters/Top-N-Filter.md
View File

@ -6,7 +6,7 @@ The top filter is a filter module for MaxScale that monitors every SQL statement
# Configuration
The configuration block for the TOP filter requires the minimal filter options in it’s section within the MaxScale.cnf file, stored in $MAXSCALE_HOME/etc/MaxScale.cnf.
The configuration block for the TOP filter requires the minimal filter options in it’s section within the maxscale.cnf file, stored in /etc/maxscale.cnf.
```
[MyLogFilter]

52
Documentation/Getting-Started/Building-MaxScale-from-Source-Code.md
View File

@ -4,7 +4,7 @@ You will need a number of tools and libraries in order to achieve this.
* cmake version 2.8.12 or later
* gcc recommended version 4.4.7 or later
* gcc recommended version 4.4.7 or later (MariaDB 10 libraries require gcc 4.7 or newer)
* libaio
@ -22,13 +22,13 @@ After following the instructions on that site you should have a working MariaDB
The full list of dependencies for the most common distributions is provided in this section. If your system is not listed here, MaxScale building isn't guaranteed to be compatible but might still be successful.
## RHEL, CentOS and Fedora
## RHEL and CentOS
You will need to install all of the following packages for all versions of RHEL, CentOS and Fedora.
You will need to install all of the following packages for all versions of RHEL and CentOS.
```
gcc gcc-c++ ncurses-devel bison glibc-devel cmake libgcc perl make libtool
openssl-devel libaio libaio-devel librabbitmq-devel
openssl-devel libaio libaio-devel librabbitmq-devel libcurl-devel pcre-devel
```
In addition, if you wish to to build an RPM package include:
@ -39,7 +39,7 @@ rpm-build
There are also some version specific packages you need to install.
#### RHEL 6, 7, CentOS 6, 7, Fedora:
#### RHEL 6, 7, CentOS 6, 7:
```
libedit-devel
@ -51,24 +51,18 @@ libedit-devel
mariadb-devel mariadb-embedded-devel
```
#### RHEL 5, 6, CentOS 5, 6, Fedora 19, 20
#### RHEL 5, 6, CentOS 5, 6
```
MariaDB-devel MariaDB-server
```
#### Fedora 19, 20
```
systemtap-sdt-devel
```
## Ubuntu and Debian
These packages are required on all versions of Ubuntu and Debian.
```
build-essential libssl-dev libaio-dev ncurses-dev bison
cmake perl libtool librabbitmq-dev
cmake perl libtool librabbitmq-dev libcurl-dev libpcre3-dev
```
If you want to build a DEB package, you will also need:
@ -87,16 +81,13 @@ You will also need some version specific packages.
#### Earlier versions of Ubuntu or Debian
For these, you will need to obtain the MariaDB embedded library. It has to be manually extracted from the tarball. But first ascertain what version of glibc is installed. Run the command:
For these, you will need to obtain the MariaDB embedded library. It has to be manually extracted from the tarballs at the MariaDB site. But first ascertain what version of glibc is installed. Run the command:
```
dpkg -l | grep libc6
```
which will show the version number. If the version is less than 2.14 you should obtain the library from:
[https://downloads.mariadb.org/interstitial/mariadb-5.5.41/bintar-linux-x86_64/mariadb-5.5.41-linux-x86_64.tar.gz](https://downloads.mariadb.org/interstitial/mariadb-5.5.41/bintar-linux-x86_64/mariadb-5.5.41-linux-x86_64.tar.gz).
Otherwise, from:
[https://downloads.mariadb.org/interstitial/mariadb-5.5.41/bintar-linux-glibc_214-x86_64/mariadb-5.5.41-linux-glibc_214-x86_64.tar.gz](https://downloads.mariadb.org/interstitial/mariadb-5.5.41/bintar-linux-glibc_214-x86_64/mariadb-5.5.41-linux-glibc_214-x86_64.tar.gz)
which will show the version number. For versions older than 2.14 you should obtain the library which supports GLIBC versions older than 2.14 and for newer versions, the library which supports newer GLIBC versions should be used.
The suggested location for extracting the tarball is `/usr` so the operation can be done by the following commands:
@ -107,22 +98,6 @@ The suggested location for extracting the tarball is `/usr` so the operation can
where /path/to/mariadb.library.tar.gz is replaced by the actual path and name of the downloaded tarball.
## OpenSUSE
At the time this guide was written, the MariaDB development packages for OpenSUSE were broken and the build failed.
The packages required are:
```
gcc gcc-c++ ncurses-devel bison glibc-devel cmake libgcc_s1 perl
make libtool libopenssl-devel libaio libaio-devel
libedit-devel librabbitmq-devel
MariaDB-devel MariaDB-client MariaDB-server
```
If zypper ask which MariaDB client should be installed `MariaDB-client` or `mariadb-client`
please select `MariaDB-client`. This is the package provided by the MariaDB repository.
# Obtaining the MaxScale Source Code
Now clone the GitHub project to your machine either via the web interface, your favorite graphical interface or the git command line
@ -152,16 +127,15 @@ wipe the build directory clean without the danger of deleting important files wh
something goes wrong. Building 'out-of-source' also allows you to have multiple
configurations of MaxScale at the same time.
The default values that CMake uses can be found in the 'macros.cmake' file.
If you wish to change these, edit the 'macros.cmake' file or define the
variables manually at configuration time.
The default values that MaxScale uses for CMake can be found in the 'macros.cmake' file under the `cmake` folder.
If you wish to change these, edit the 'macros.cmake' file or define the variables manually at configuration time.
To display all CMake variables with their descriptions:
```
cmake .. -LH
```
This is a useful command if you have your libraries installed in non-standard locations.
This is a useful command if you have your libraries installed in non-standard locations and need to provide them manually.
When you are ready to run cmake, provide the following command:
@ -241,7 +215,7 @@ $ make install
This will result in an installation being created which is identical to that which would be achieved by installing the binary package.
By default, MaxScale installs to `/usr/local/mariadb-maxscale` and places init.d scripts and ldconfig files into their folders. Change the `CMAKE_INSTALL_PREFIX` variable to your desired installation directory and set `WITH_SCRIPTS=N` to prevent the init.d script and ldconfig file installation.
When building from source, MaxScale installs to `/usr/local/` and places init.d scripts and ldconfig files into their folders. Change the `CMAKE_INSTALL_PREFIX` variable to your desired installation directory and set `WITH_SCRIPTS=N` to prevent the init.d script and ldconfig file installation.
Other useful targets for Make are `documentation`, which generates the Doxygen documentation, and `uninstall` which uninstall MaxScale binaries after an install.

155
Documentation/Getting-Started/Configuration-Guide.md
View File

@ -27,16 +27,16 @@ connection failover| When a connection currently being used between MaxScale and
The MaxScale configuration is read from a file which can be located in a number of placing, MaxScale will search for the configuration file in a number of locations.
1. If the environment variable `MAXSCALE_HOME` is set then MaxScale will look for a configuration file called `MaxScale.cnf` in the directory `$MAXSCALE_HOME/etc`.
1. Location given with the --configdir=<path> command line argument
2. If `MAXSCALE_HOME` is not set or the configuration file is not in the location above MaxScale will look for a file in `/etc/MaxScale.cnf`.
Alternatively MaxScale can be started with the `-c` flag and the path of the MaxScale home directory tree.
2. MaxScale will look for a configuration file called `maxscale.cnf` in the directory `/etc/maxscale.cnf`
An explicit path to a configuration file can be passed by using the `-f` option to MaxScale.
The configuration file itself is based on the ".ini" file format and consists of various sections that are used to build the configuration, these sections define services, servers, listeners, monitors and global settings.
Please see the section about [Protocol Modules](#protocol-modules) for more details about MaxScale and the default directories where modules will be searched for.
### Global Settings
The global settings, in a section named `[MaxScale]`, allow various parameters that affect MaxScale as a whole to be tuned. Currently the only setting that is supported is the number of threads to use to handle the network traffic. MaxScale will also accept the section name of `[gateway]` for global settings. This is for backward compatibility with versions prior to the naming of MaxScale.
@ -101,6 +101,54 @@ log_debug=1
To disable the log use the value 0 and to enable it use the value 1.
#### `logdir`
Set the directory where the logfiles are stored. The folder needs to be both readable and writable by the user running MaxScale.
```
logdir=/tmp/
```
#### `datadir`
Set the directory where the data files used by 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.
```
datadir=/home/user/maxscale_data/
```
#### `libdir`
Set the directory where MaxScale looks for modules. The library directory is the only directory that MaxScale uses when it searches for modules. If you have custom modules for MaxScale, make sure you have them in this folder.
```
libdir=/home/user/lib64/
```
#### `cachedir`
Configure the directory MaxScale uses to store cached data. An example of cached data is the authentication data fetched from the backend servers. MaxScale stores this in case a connection to the backend server is not possible.
```
cachedir=/tmp/maxscale_cache/
```
#### `piddir`
Configure the directory for the PID file for MaxScale. This file contains the Process ID for the running MaxScale process.
```
piddir=/tmp/maxscale_cache/
```
#### `language`
Set the folder where the errmsg.sys file is located in. MaxScale will look for the errmsg.sys file installed with MaxScale from this folder.
```
language=/home/user/lang/
```
### Service
A service represents the database service that MaxScale offers to the clients. In general a service consists of a set of backend database servers and a routing algorithm that determines how MaxScale decides to send statements or route connections to those backend servers.
@ -193,7 +241,7 @@ Query OK, 0 rows affected (0.00 sec)
#### `passwd`
The passwd parameter provides the password information for the above user and may be either a plain text password or it may be an encrypted password. See the section on encrypting passwords for use in the MaxScale.cnf file. This user must be capable of connecting to the backend database and executing these SQL statements to load database names and grants from the backends:
The passwd parameter provides the password information for the above user and may be either a plain text password or it may be an encrypted password. See the section on encrypting passwords for use in the maxscale.cnf file. This user must be capable of connecting to the backend database and executing these SQL statements to load database names and grants from the backends:
* `SELECT user, host, password,Select_priv FROM mysql.user`.
* `SELECT user, host, db FROM mysql.db`
@ -278,6 +326,62 @@ Example:
connection_timeout=300
```
### Service and SSL
This section describes configuration parameters for services that control the SSL/TLS encryption method and the various certificate files involved in it. To enable SSL, you must configure the `ssl` parameter with either `enabled` or `required` and provide the three files for `ssl_cert`, `ssl_key` and `ssl_ca_cert`. After this, MySQL connections to this service can be encrypted with SSL.
#### `ssl`
This enables SSL connections to the service. If this parameter is set to either `required` or `enabled` and the three certificate files can be found (these are explained afterwards), then client connections will be encrypted with SSL. If the parameter is `enabled` then both SSL and non-SSL connections can connect to this service. If the parameter is set to `required` then only SSL connections can be used for this service and non-SSL connections will get an error when they try to connect to the service.
#### `ssl_key`
The SSL private key the service should use. This will be the private key that is used as the server side private key during a client-server SSL handshake. This is a required parameter for SSL enabled services.
#### `ssl_cert`
The SSL certificate the service should use. This will be the public certificate that is used as the server side certificate during a client-server SSL handshake. This is a required parameter for SSL enabled services.
#### `ssl_ca_cert`
This is the Certificate Authority file. It will be used to verify that both the client and the server certificates are valid. This is a required parameter for SSL enabled services.
### `ssl_version`
This parameter controls the level of encryption used. Accepted values are:
* SSLv3
* TLSv10
* TLSv11
* TLSv12
* MAX
### `ssl_cert_verification_depth`
The maximum length of the certificate authority chain that will be accepted. Accepted values are positive integers.
```
# Example
ssl_cert_verification_depth=10
```
Example SSL enabled service configuration:
```
[ReadWriteSplitService]
type=service
router=readwritesplit
servers=server1,server2,server3
user=myuser
passwd=mypasswd
ssl=required
ssl_cert=/home/markus/certs/server-cert.pem
ssl_key=/home/markus/certs/server-key.pem
ssl_ca_cert=/home/markus/certs/ca.pem
ssl_version=TLSv12
```
This configuration requires all connections to be encrypted with SSL. It also specifies that TLSv1.2 should be used as the encryption method. The paths to the server certificate files and the Certificate Authority file are also provided.
### Server
Server sections are used to define the backend database servers that can be formed into a service. A server may be a member of one or more services within MaxScale. Servers are identified by a server name which is the section name in the configuration file. Servers have a type parameter of server, plus address port and protocol parameters.
@ -318,7 +422,7 @@ The monitor has a username and password that is used to connect to all servers f
monitorpw=mymonitorpasswd
```
The monpasswd parameter may be either a plain text password or it may be an encrypted password. See the section on encrypting passwords for use in the MaxScale.cnf file.
The monpasswd parameter may be either a plain text password or it may be an encrypted password. See the section on encrypting passwords for use in the maxscale.cnf file.
### Listener
@ -467,7 +571,7 @@ Individual servers may define override values for the user and password the moni
#### `passwd`
The password parameter may be either a plain text password or it may be an encrypted password. See the section on encrypting passwords for use in the `MaxScale.cnf` file.
The password parameter may be either a plain text password or it may be an encrypted password. See the section on encrypting passwords for use in the `maxscale.cnf` file.
#### `monitor_interval`
@ -540,7 +644,7 @@ Default value is `2`. Write Timeout is the timeout in seconds for each attempt t
## Protocol Modules
The protocols supported by MaxScale are implemented as external modules that are loaded dynamically into the MaxScale core. These modules reside in the directory `$MAXSCALE_HOME/modules`, if the environment variable `$MAXSCALE_HOME` is not set it defaults to `/usr/local/mariadb-maxscale`. It may also be set by passing the `-c` option on the MaxScale command line.
The protocols supported by MaxScale are implemented as external modules that are loaded dynamically into the MaxScale core. These modules reside in the directory `/usr/lib64/maxscale`. The location can be overridden with the `libdir=PATH` parameter under the `[maxscale]` section. It may also be set by passing the `-B PATH` or `--libdir=PATH` option on the MaxScale command line.
### MySQLClient
@ -1024,7 +1128,7 @@ MariaDB [mysql]> grant REPLICATION CLIENT on *.* to 'maxscalemon'@'maxscalehost'
Query OK, 0 rows affected (0.00 sec)
```
MySQL monitor fetches the `@@server_id` variable and other informations from `SHOW SLAVE STATUS` in order to compute the replication topology tree that may include intermediate master servers, called relay servers.
MySQL monitor fetches the `@@server_id` variable and other information from `SHOW SLAVE STATUS` in order to compute the replication topology tree that may include intermediate master servers, called relay servers.
The *Master* server used by router modules is the so called "root master": a server that has the `SERVER_MASTER` status bit set and it's at the lowest level of the replication depth.
@ -1036,7 +1140,7 @@ Please note, those two options are not enabled by default.
### galeramon
The Galeramon monitor is a simple router designed for use with MySQL Galera cluster. To execute the galeramon monitor an entry as shown below should be added to the MaxScale configuration file.
The Galeramon monitor is a simple monitor designed for use with MySQL Galera cluster. To execute the galeramon monitor an entry as shown below should be added to the MaxScale configuration file.
```
[Galera Monitor]
@ -1259,7 +1363,7 @@ before being sent to the server. Note that the text in the match string is case-
The **tee** filter is a filter module for MaxScale that acts as a "plumbing" fitting in the MaxScale filter toolkit. It can be used in a filter pipeline of a service to make a copy of requests from the client and dispatch a copy of the request to another service within MaxScale.
The configuration block for the **tee** filter requires the minimal filter parameters in its section within the `MaxScale.cnf` file that defines the filter to load and the service to send the duplicates to.
The configuration block for the **tee** filter requires the minimal filter parameters in its section within the `maxscale.cnf` file that defines the filter to load and the service to send the duplicates to.
```
[ArchiveFilter]
@ -1274,7 +1378,7 @@ In addition parameters may be added to define patterns to match against to eithe
The top filter is a filter module for MaxScale that monitors every SQL statement that passes through the filter. It measures the duration of that statement, the time between the statement being sent and the first result being returned. The top N times are kept, along with the SQL text itself and a list sorted on the execution times of the query is written to a file upon closure of the client session.
The configuration block for the **top** filter requires the minimal filter options in its section within the `MaxScale.cnf` file, stored in `$MAXSCALE_HOME/etc/MaxScale.cnf`.
The configuration block for the **top** filter requires the minimal filter options in its section within the `maxscale.cnf` file, stored in `/etc/maxscale.cnf`.
```
[MyLogFilter]
@ -1286,31 +1390,6 @@ count=10
In addition parameters may be added to define patterns to match against to either include or exclude particular SQL statements to be duplicated. You may also define that the filter is only active for connections from a particular source or when a particular user is connected.
## Encrypting Passwords
Passwords stored in the MaxScale.cnf file may optionally be encrypted for added security. This is done by creation of an encryption key on installation of MaxScale. Encryption keys may be created manually by executing the maxkeys utility with the argument of the filename to store the key.
maxkeys $MAXSCALE_HOME/etc/.secrets
Changing the encryption key for MaxScale will invalidate any currently encrypted keys stored in the MaxScale.cnf file.
### Creating Encrypted Passwords
Encrypted passwords are created by executing the maxpasswd command with the password you require to encrypt as an argument. The environment variable `MAXSCALE_HOME` must be set, or MaxScale must be installed in the default location before maxpasswd can be executed.
maxpasswd MaxScalePw001
61DD955512C39A4A8BC4BB1E5F116705
The output of the maxpasswd command is a hexadecimal string, this should be inserted into the MaxScale.cnf file in place of the ordinary, plain text, password. MaxScale will determine this as an encrypted password and automatically decrypt it before sending it the database server.
```
[Split Service]
type=service
router=readwritesplit
servers=server1,server2,server3,server4
user=maxscale
password=61DD955512C39A4A8BC4BB1E5F116705
```
## Reloading Configuration
@ -1382,7 +1461,7 @@ and short notations
## Error Reporting
MaxScale is designed to be executed as a service, therefore all error reports, including configuration errors, are written to the MaxScale error log file. MaxScale will log to a set of files in the directory `$MAXSCALE_HOME/log`, the only exception to this is if the log directory is not writable, in which case a message is sent to the standard error descriptor.
MaxScale is designed to be executed as a service, therefore all error reports, including configuration errors, are written to the MaxScale error log file. By default, MaxScale will log to a set of files in the directory `/var/log/maxscale`, the only exception to this is if the log directory is not writable, in which case a message is sent to the standard error descriptor.
### Troubleshooting

76
Documentation/Getting-Started/Getting-Started-With-MaxScale.md → Documentation/Getting-Started/MariaDB-MaxScale-Installation-Guide.md
View File

@ -1,4 +1,4 @@
# Getting Started With MariaDB MaxScale
# MariaDB MaxScale Installation Guide
## First Steps With MaxScale
@ -8,23 +8,31 @@ In this introduction to MaxScale the aim is to take the reader from the point of
The simplest way to install MaxScale is to use one of the binary packages that are available for download from the MariaDB website.
* Simply go to [www.mariadb.com](http://www.mariadb.com)
* Simply go to [http://www.mariadb.com/my_portal/download](http://www.mariadb.com/my_portal/download)
* Select the Downloads option from the Resources menu
* Sign in to MariaDB.com
* Find and click on the button "Download MariaDB MaxScale Binaries"
* Follow the instructions at the top of the page.
* Find the section on that page entitled MariaDB MaxScale
![image alt text](images/getting_started.png)
* Select your operating system from the drop down box
If you want to install only MaxScale, futher down you will find the product specific download pages. Click on the MariaDB MaxScale link and follow the distribution specific instructions.
* Instructions that are specific for your operating system will then appear
![image alt text](images/getting_started2.png)
![image alt text](images/image_1.png)
After you have installed MaxScale, you can start it.
* Follow these instructions to install MaxScale on your machine
```
systemctl start maxscale.service
```
Upon successful completion of the installation process you have a version of MaxScale that is missing only a configuration file before it can be started.
If your system does not support systemd you can start MaxScale using the installed init.d script.
```
service maxscale start
```
An example configuration file is installed into the `/etc/` folder. This file should be changed according to your needs.
## Building MaxScale From Source Code
@ -34,6 +42,8 @@ Alternatively you may download the MaxScale source and build your own binaries.
The first step in configuring your MaxScale is to determine what it is you want to achieve with your MaxScale and what environment it will run in. The later is probably the easiest starting point for choosing which configuration route you wish to take. There are two distinct database environments which the first GA release of MaxScale supports; MySQL Master/Slave Replication clusters and Galera Cluster.
For more details, refer to the [Configuration Guide](Configuration-Guide.md).
### Master/Slave Replication Clusters
There are two major configuration options available to use MaxScale with a MySQL Replication cluster; connection routing with separate read and write connections, or read/write splitting with a single connection. A separate tutorial is available for each of these configurations that describes how to build the configuration file for MaxScale that will work with your environment.
@ -54,21 +64,51 @@ It is also possible to use the Read/Write Splitter with Galera. Although it is n
As well as the four major configuration choices outlined above there are also other configurations sub-options that may be mixed with those to provide a variety of different configuration and functionality. The MaxScale filter concept allows the basic configurations to be built upon in a large variety of ways. A separate filter tutorial is available that discusses the concept and gives some examples of ways to use filters.
## Encrypting Passwords
Passwords stored in the maxscale.cnf file may optionally be encrypted for added security. This is done by creation of an encryption key on installation of MaxScale. Encryption keys may be created manually by executing the maxkeys utility with the argument of the filename to store the key. The default location MaxScale stores the keys is `/var/lib/maxscale`.
```
# Usage: maxkeys [PATH]
maxkeys /var/lib/maxscale/
```
Changing the encryption key for MaxScale will invalidate any currently encrypted keys stored in the maxscale.cnf file.
### Creating Encrypted Passwords
Encrypted passwords are created by executing the maxpasswd command with the location of the .secrets file and the password you require to encrypt as an argument.
```
# Usage: maxpasswd PATH PASSWORD
maxpasswd /var/lib/maxscale/ MaxScalePw001
61DD955512C39A4A8BC4BB1E5F116705
```
The output of the maxpasswd command is a hexadecimal string, this should be inserted into the maxscale.cnf file in place of the ordinary, plain text, password. MaxScale will determine this as an encrypted password and automatically decrypt it before sending it the database server.
```
[Split Service]
type=service
router=readwritesplit
servers=server1,server2,server3,server4
user=maxscale
password=61DD955512C39A4A8BC4BB1E5F116705
```
## 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:
modules it will search using a configurable search path. The priority of these paths are:
1. Look in the current directory for the module
2. Look in $MAXSCALE_HOME/modules
3. Look in /usr/local/mariadb-maxscale/modules
Configuration is read by default from the file $MAXSCALE_HOME/etc/MaxScale.cnf, /etc/MaxScale.cnf. An example file is included in in the installation and can be found in the etc/ folder within the MaxScale installation. The default value of MAXSCALE_HOME can be overridden by using 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 on the command line to set the name and the location of the configuration file. Without path expression the file is read from \$MAXSCALE_HOME/etc directory.
1. Look in the directory defined with --libdir=PATH during startup
2. Look in the directory defined with libdir=PATH in the configuration file under the [maxscale] section
3. Look in default directory in /usr/lib64/maxscale
Configuration is read by default from the file /etc/maxscale.cnf. An example file is included in in the installation and can be found in the /usr/share/maxscale folder within the MaxScale installation. The -f flag can be used on the command line to set the name and the location of the configuration file. The -C flag can be used to set the directory where the configuration file is searched for. Without the -f or -C flags, the file is read from the /etc directory.
## Administration Of MaxScale
There are various administration tasks that may be done with MaxScale, a client command, maxadmin, is available that will interact with a running MaxScale and allow the status of MaxScale to be monitored and give some control of the MaxScale functionality. There is a separate reference guide for the maxadmin utility and also a short administration tutorial that covers the common administration tasks that need to be done with MaxScale.
There are various administration tasks that may be done with MaxScale, a client command, maxadmin, is available that will interact with a running MaxScale and allow the status of MaxScale to be monitored and give some control of the MaxScale functionality. There is [a separate reference guide](../Reference/MaxAdmin.md) for the maxadmin utility and also [a short administration tutorial](../Tutorials/Administration-Tutorial.md) that covers the common administration tasks that need to be done with MaxScale.

BIN
Documentation/Getting-Started/images/getting_started.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 72 KiB

BIN
Documentation/Getting-Started/images/getting_started2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 73 KiB

120
Documentation/Monitors/Galera-Monitor.md Normal file
View File

@ -0,0 +1,120 @@
# Galera Monitor
## Overview
The Galera Monitor is a monitoring module for MaxScale that monitors a Galera cluster. It detects whether nodes are a part of the cluster and if they are in sync with the rest of the cluster. It can also assign master and slave roles inside MaxScale, allowing Galera clusters to be used with modules designed for traditional master-slave clusters.
## Configuration
A minimal configuration for a monitor requires a set of servers for monitoring and a username and a password to connect to these servers. The user requires the REPLICATION CLIENT privilege to successfully monitor the state of the servers.
```
[Galera Monitor]
type=monitor
module=galeramon
servers=server1,server2,server3
user=myuser
passwd=mypwd
```
## Optional parameters for all monitors
Here are optional parameters that are common for all the monitors.
### `monitor_interval`
This is the time the monitor waits between each cycle of monitoring. The default value of 10000 milliseconds (10 seconds) should be lowered if you want a faster response to changes in the server states. The value is defined in milliseconds and the smallest possible value is 100 milliseconds.
```
monitor_interval=2500
```
### `backend_connect_timeout`
This parameter controls the timeout for connecting to a monitored server. It is in seconds and the minimum value is 1 second. The default value for this parameter is 3 seconds.
```
backend_connect_timeout=6
```
### `backend_write_timeout`
This parameter controls the timeout for writing to a monitored server. It is in seconds and the minimum value is 1 second. The default value for this parameter is 2 seconds.
```
backend_write_timeout=4
```
### `backend_read_timeout`
This parameter controls the timeout for reading from a monitored server. It is in seconds and the minimum value is 1 second. The default value for this parameter is 1 seconds.
```
backend_read_timeout=2
```
## Galera Monitor optional parameters
These are optional parameters specific to the Galera Monitor.
### `disable_master_failback`
If a node marked as master inside MaxScale happens to fail and the master status is assigned to another node MaxScale will normally return the master status to the original node after it comes back up. With this option enabled, if the master status is assigned to a new node it will not be reassigned to the original node for as long as the new master node is running.
```
disable_master_failback=true
```
### `available_when_donor`
This option only has an effect if there is a single Galera node being backed up an XtraBackup instance. This causes the initial node to go into Donor state which would normally prevent if from being marked as a valid server inside MaxScale. If this option is enabled, a single node in Donor state where the method is XtraBackup will be kept in Synced state.
```
available_when_donor=true
```
### `disable_master_role_setting`
This disables the assignment of master and slave roles to the Galera cluster nodes. If this option is enabled, Synced is the only status assigned by this monitor.
```
disable_master_role_setting=true
```
### `script`
This script will be executed when a server changes its state. The parameter should be an absolute path to the script or it should be in the executable path.
```
script=/home/user/script.sh
```
### `events`
A list of event names which cause the script to be executed. If this option is not defined, all events cause the script to be executed. The list must contain a comma separated list of event names.
```
events=master_down,slave_down
```
## Script events
Here is a table of all possible event types and their descriptions.
Event Name|Description
----------|----------
master_down|A Master server has gone down
master_up|A Master server has come up
slave_down|A Slave server has gone down
slave_up|A Slave server has come up
server_down|A server with no assigned role has gone down
server_up|A server with no assigned role has come up
synced_down|A synced Galera node has come up
synced_up|A synced Galera node has gone down
lost_master|A server lost Master status
lost_slave|A server lost Slave status
lost_synced|A Galera node lost synced status
new_master|A new Master was detected
new_slave|A new Slave was detected
new_synced|A new synced Galera node was detected

107
Documentation/Monitors/MM-Monitor.md Normal file
View File

@ -0,0 +1,107 @@
# Multi-Master Monitor
## Overview
The Multi-Master Monitor is a monitoring module for MaxScale that monitors Master-Master replication. It assigns master and slave roles inside MaxScale based on whether the read_only parameter on a server is set to off or on.
## Configuration
A minimal configuration for a monitor requires a set of servers for monitoring and a username and a password to connect to these servers. The user requires the REPLICATION CLIENT privilege to successfully monitor the state of the servers.
```
[Multi-Master Monitor]
type=monitor
module=mmmon
servers=server1,server2,server3
user=myuser
passwd=mypwd
```
## Optional parameters for all monitors
Here are optional parameters that are common for all the monitors.
### `monitor_interval`
This is the time the monitor waits between each cycle of monitoring. The default value of 10000 milliseconds (10 seconds) should be lowered if you want a faster response to changes in the server states. The value is defined in milliseconds and the smallest possible value is 100 milliseconds.
```
monitor_interval=2500
```
### `backend_connect_timeout`
This parameter controls the timeout for connecting to a monitored server. It is in seconds and the minimum value is 1 second. The default value for this parameter is 3 seconds.
```
backend_connect_timeout=6
```
### `backend_write_timeout`
This parameter controls the timeout for writing to a monitored server. It is in seconds and the minimum value is 1 second. The default value for this parameter is 2 seconds.
```
backend_write_timeout=4
```
### `backend_read_timeout`
This parameter controls the timeout for reading from a monitored server. It is in seconds and the minimum value is 1 second. The default value for this parameter is 1 seconds.
```
backend_read_timeout=2
```
## Multi-Master Monitor optional parameters
These are optional parameters specific to the Multi-Master Monitor.
### `detect_stale_master`
Allow previous master to be available even in case of stopped or misconfigured replication. This allows services that depend on master and slave roles to continue functioning as long as the master server is available.
This is a situation which can happen if all slave servers are unreachable or the replication breaks for some reason.
```
detect_stale_master=true
```
### `script`
This script will be executed when a server changes its state. The parameter should be an absolute path to the script or it should be in the executable path.
```
script=/home/user/script.sh
```
This script will be called with the following command line arguments.
```
<name of the script> --event=<event type> --initiator=<server whose state changed> --nodelist=<list of all servers>
```
### `events`
A list of event names which cause the script to be executed. If this option is not defined, all events cause the script to be executed. The list must contain a comma separated list of event names.
```
events=master_down,slave_down
```
## Script events
Here is a table of all possible event types and their descriptions.
Event Name|Description
----------|----------
master_down|A Master server has gone down
master_up|A Master server has come up
slave_down|A Slave server has gone down
slave_up|A Slave server has come up
server_down|A server with no assigned role has gone down
server_up|A server with no assigned role has come up
lost_master|A server lost Master status
lost_slave|A server lost Slave status
new_master|A new Master was detected
new_slave|A new Slave was detected

155
Documentation/Monitors/MySQL-Monitor.md Normal file
View File

@ -0,0 +1,155 @@
# MySQL Monitor
## Overview
The MySQL Monitor is a monitoring module for MaxScale that monitors a Master-Slave replication cluster. It assigns master and slave roles inside MaxScale according to the actual replication tree in the cluster.
## Configuration
A minimal configuration for a monitor requires a set of servers for monitoring and a username and a password to connect to these servers. The user requires the REPLICATION CLIENT privilege to successfully monitor the state of the servers.
```
[MySQL Monitor]
type=monitor
module=mysqlmon
servers=server1,server2,server3
user=myuser
passwd=mypwd
```
## Optional parameters for all monitors
Here are optional parameters that are common for all the monitors.
### `monitor_interval`
This is the time the monitor waits between each cycle of monitoring. The default value of 10000 milliseconds (10 seconds) should be lowered if you want a faster response to changes in the server states. The value is defined in milliseconds and the smallest possible value is 100 milliseconds.
```
monitor_interval=2500
```
### `backend_connect_timeout`
This parameter controls the timeout for connecting to a monitored server. It is in seconds and the minimum value is 1 second. The default value for this parameter is 3 seconds.
```
backend_connect_timeout=6
```
### `backend_write_timeout`
This parameter controls the timeout for writing to a monitored server. It is in seconds and the minimum value is 1 second. The default value for this parameter is 2 seconds.
```
backend_write_timeout=4
```
### `backend_read_timeout`
This parameter controls the timeout for reading from a monitored server. It is in seconds and the minimum value is 1 second. The default value for this parameter is 1 seconds.
```
backend_read_timeout=2
```
## MySQL Monitor optional parameters
These are optional parameters specific to the MySQL Monitor.
### `detect_replication_lag`
Detect replication lag between the master and the slaves. This allows the routers to route read queries to only slaves that are up to date.
```
detect_replication_lag=true
```
### `detect_stale_master`
Allow previous master to be available even in case of stopped or misconfigured
replication. This allows services that depend on master and slave roles to continue functioning as long as the master server is available.
This is a situation which can happen if all slave servers are unreachable or the replication breaks for some reason.
```
detect_stale_master=true
```
### `script`
This script will be executed when a server changes its state. The parameter should be an absolute path to the script or it should be in the executable path.
```
script=/home/user/script.sh
```
This script will be called with the following command line arguments.
```
<name of the script> --event=<event type> --initiator=<server whose state changed> --nodelist=<list of all servers>
```
### `events`
A list of event names which cause the script to be executed. If this option is not defined, all events cause the script to be executed. The list must contain a comma separated list of event names.
```
events=master_down,slave_down
```
### `mysql51_replication`
Enable support for MySQL 5.1 replication monitoring. This is needed if a MySQL server older than 5.5 is used as a slave in replication.
```
mysql51_replication=true
```
## Script events
Here is a table of all possible event types and their descriptions.
Event Name|Description
----------|----------
master_down|A Master server has gone down
master_up|A Master server has come up
slave_down|A Slave server has gone down
slave_up|A Slave server has come up
server_down|A server with no assigned role has gone down
server_up|A server with no assigned role has come up
lost_master|A server lost Master status
lost_slave|A server lost Slave status
new_master|A new Master was detected
new_slave|A new Slave was detected
## Example 1 - Monitor script
Here is an example shell script which sends an email to an admin when a server goes down.
```
#!/usr/bin/env bash
#This script assumes that the local mail server is configured properly
#The second argument is the event type
event=${$2/.*=/}
server=${$3/.*=/}
message="A server has gone down at `date`."
echo $message|mail -s "The event was $event for server $server." admin@my.org
```
Here is a monitor configuration that only triggers the script when a master or a slave server goes down.
```
[Database Monitor]
type=monitor
module=mysqlmon
servers=server1,server2
script=mail_to_admin.sh
events=master_down,slave_down
```
When a master or a slave server goes down, the script is executed, a mail is sent and the administrator will be immediately notified of any possible problems.
This is just a simple example showing what you can do with MaxScale and monitor scripts.

102
Documentation/Monitors/NDB-Cluster-Monitor.md Normal file
View File

@ -0,0 +1,102 @@
# NDB Cluster Monitor
## Overview
The MySQL Cluster Monitor is a monitoring module for MaxScale that monitors a MySQL Cluster. It assigns a NDB status for the server if it is a part of a MySQL Cluster.
## Configuration
A minimal configuration for a monitor requires a set of servers for monitoring and a username and a password to connect to these servers. The user requires the REPLICATION CLIENT privilege to successfully monitor the state of the servers.
```
[MySQL Cluster Monitor]
type=monitor
module=ndbclustermon
servers=server1,server2,server3
user=myuser
passwd=mypwd
```
## Optional parameters for all monitors
Here are optional parameters that are common for all the monitors.
### `monitor_interval`
This is the time the monitor waits between each cycle of monitoring. The default value of 10000 milliseconds (10 seconds) should be lowered if you want a faster response to changes in the server states. The value is defined in milliseconds and the smallest possible value is 100 milliseconds.
```
monitor_interval=2500
```
### `backend_connect_timeout`
This parameter controls the timeout for connecting to a monitored server. It is in seconds and the minimum value is 1 second. The default value for this parameter is 3 seconds.
```
backend_connect_timeout=6
```
### `backend_write_timeout`
This parameter controls the timeout for writing to a monitored server. It is in seconds and the minimum value is 1 second. The default value for this parameter is 2 seconds.
```
backend_write_timeout=4
```
### `backend_read_timeout`
This parameter controls the timeout for reading from a monitored server. It is in seconds and the minimum value is 1 second. The default value for this parameter is 1 seconds.
```
backend_read_timeout=2
```
## MySQL Cluster Monitor optional parameters
These are optional parameters specific to the MySQL Cluster Monitor.
### `script`
This script will be executed when a server changes its state. The parameter should be an absolute path to the script or it should be in the executable path.
```
script=/home/user/script.sh
```
This script will be called with the following command line arguments.
```
<name of the script> --event=<event type> --initiator=<server whose state changed> --nodelist=<list of all servers>
```
### `events`
A list of event names which cause the script to be executed. If this option is not defined, all events cause the script to be executed. The list must contain a comma separated list of event names.
```
events=master_down,slave_down
```
## Script events
Here is a table of all possible event types and their descriptions that the MySQL Cluster monitor can be called with.
Event Name|Description
----------|----------
master_down|A Master server has gone down
master_up|A Master server has come up
slave_down|A Slave server has gone down
slave_up|A Slave server has come up
server_down|A server with no assigned role has gone down
server_up|A server with no assigned role has come up
ndb_down|A MySQL Cluster node has gone down
ndb_up|A MySQL Cluster node has come up
lost_master|A server lost Master status
lost_slave|A server lost Slave status
lost_ndb|A MySQL Cluster node lost node membership
new_master|A new Master was detected
new_slave|A new Slave was detected
new_ndb|A new MySQL Cluster node was found

14
Documentation/Reference/Debug-And-Diagnostic-Support.md
View File

@ -1679,7 +1679,7 @@ Loaded 34 users.
## Reload config
The reload config command can be used to force MaxScale to re-read the MaxScale.cnf and update itself to the latest configuration defined in that configuration file. It is also possible to force the reading of the configuration file by sending a HangUp signal (SIGHUP) to the maxscale process.
The reload config command can be used to force MaxScale to re-read the maxscale.cnf and update itself to the latest configuration defined in that configuration file. It is also possible to force the reading of the configuration file by sending a HangUp signal (SIGHUP) to the maxscale process.
**MaxScale>** reload config
@ -1711,7 +1711,7 @@ User admin already exists.
**MaxScale>**** **
If you should forget or lose the the account details you may simply remove the passwd file in $MAXSCALE_HOME/etc and the system will revert to the default behavior with admin/mariadb as the account.
If you should forget or lose the the account details you may simply remove the passwd file in /var/cache/maxscale and the system will revert to the default behavior with admin/mariadb as the account.
## Enable/disable log
@ -1745,7 +1745,7 @@ MaxScale generates output of its behavior to four distinct logs, error, messages
## Log contents
By default all log files are located in : $MAXSCALE_HOME/log and named as :
By default all log files are located in : /var/log/maxscale and named as :
skygw_errW.log, skygw_msgX.log, skygw_traceY.log and skygw_debugZ.log
@ -1789,7 +1789,7 @@ MariaDB Corporation MaxScale /home/jdoe/bin/develop/log/skygw_msg1.log Tue Dec
2014-12-09 14:47:05 Log directory : /home/jdoe/bin/develop/log
2014-12-09 14:47:05 Configuration file : /home/jdoe/bin/develop/etc/MaxScale.cnf
2014-12-09 14:47:05 Configuration file : /home/jdoe/bin/develop/etc/maxscale.cnf
2014-12-09 14:47:05 Initialise CLI router module V1.0.0.
@ -1837,7 +1837,7 @@ MariaDB Corporation MaxScale /home/jdoe/bin/develop/log/skygw_msg1.log Tue Dec
### Trace log
Trace log includes information about available servers and their states, client sessions, queries being executed, routing decisions and other routing related data. Trace log can be found from the same directory with other logs but it is physically stored elsewhere, to OSs shared memory to reduce the latency caused by logging. The location of physical file is : /dev/shm/<pid>/skygw_traceX.log where ‘X’ is the same sequence number as in the file name in the $MAXSCALE_HOME/log directory.
Trace log includes information about available servers and their states, client sessions, queries being executed, routing decisions and other routing related data. Trace log can be found from the same directory with other logs but it is physically stored elsewhere, to OSs shared memory to reduce the latency caused by logging. The location of physical file is : /dev/shm/<pid>/skygw_traceX.log where ‘X’ is the same sequence number as in the file name in the /var/log/maxscale directory.
Individual trace log entry looks similar to those in other logs but there is some difference too. Some log entries include a number within square brackets to specify which client session they belong to. For example:
@ -1923,11 +1923,11 @@ In the log, session’s life cycle is covered by annotating its beginning and th
The log files are located in
$MAXSCALE_HOME/log
/var/log/maxscale
by default. If, however, trace and debug logs are enabled, only a soft link is created there. MaxScale process creates a directory under
/dev/shm/<pid>
/dev/shm/maxscale.<pid>
where it stores the physical trace and debug log files. Link and physical files share the same name. These logs consume the main memory of the host they run on so it is important to archive or remove them periodically to avoid unnecessary main-memory consumption.

83
Documentation/Reference/Hint-Syntax.md
View File

@ -1,42 +1,97 @@
# Hint Syntax
Use either ’-- ’ (notice the whitespace) or ’#’ after the semicolon or ’/* .. */’ before
the semicolon.
## Enabling routing hints
The MySQL manual doesn’t specify if comment blocks, i.e. ’/* .. */’, should contain a w
hitespace character before or after the tags.
To enable routing hints for a service, the hintfilter module needs to be configured and the filter needs to be applied to the service.
All hints must start with the ’maxscale tag’:
-- maxscale <hint>
The hints right now have two types, ones that route to a server and others that contain
Here is an example service which has the hint filter configured and applied.
```
[Read Service]
type=service
router=readconnroute
router_options=master
servers=server1
user=maxuser
passwd=maxpwd
filter=Hint
[Hint]
type=filter
module=hintfilter
```
## Comments and comment types
The client connection will need to have comments enabled. For example the `mysql` command line client has comments disabled by default.
For comment types, use either `-- ` (notice the whitespace) or `#` after the semicolon or `/* .. */` before the semicolon. All comment types work with routing hints.
The MySQL manual doesn`t specify if comment blocks, i.e. `/* .. */`, should contain a w
hitespace character before or after the tags, so adding whitespace at both the start and the end is advised.
## Hint body
All hints must start with the `maxscale` tag.
```
-- maxscale <hint body>
```
The hints have two types, ones that route to a server and others that contain
name-value pairs.
Routing queries to a server:
###Routing destination hints
These hints will instruct the router to route a query to a certain type of a server.
```
-- maxscale route to [master | slave | server <server name>]
```
The name of the server is the same as in MaxScale.cnf
A `master` value in a routing hint will route the query to a master server. This can be used to direct read queries to a master server for a up-to-date result with no replication lag. A `slave` value will route the query to a slave server. A `server` value will route the query to a named server. The value of <server name> needs to be the same as the server section name in maxscale.cnf.
Creating a name-value pair:
### Name-value hints
These control the behavior and affect the routing decisions made by the router.
```
-- maxscale <param>=<value>
```
Currently the only accepted parameter is
’max_slave_replication_lag’
Currently the only accepted parameter is `max_slave_replication_lag`. This will route the query to a server with lower replication lag then what is defined in the hint value.
## Hint stack
Hints can be either single-use hints, which makes them affect only one query, or named
hints, which can be pushed on and off a stack of active hints.
Defining named hints:
```
-- maxscale <hint name> prepare <hint content>
```
Pushing a hint onto the stack:
```
-- maxscale <hint name> begin
```
Popping the topmost hint off the stack:
```
-- maxscale end
```
You can define and activate a hint in a single command using the following:
```
-- maxscale <hint name> begin <hint content>
```
You can also push anonymous hints onto the stack which are only used as long as they are on the stack:
-- maxscale begin <hint content>
```
-- maxscale begin <hint content>
```

8
Documentation/Reference/MaxAdmin.md
View File

@ -591,7 +591,7 @@ Some monitors provide a replication heartbeat mechanism that monitors the delay
MaxScale> enable heartbeat "MySQL Monitor"
MaxScale>
Please note that changes made via this interface will not persist across restarts of MaxScale. To make a permanent change edit the MaxScale.cnf file.
Please note that changes made via this interface will not persist across restarts of MaxScale. To make a permanent change edit the maxscale.cnf file.
Enabling the replication heartbeat mechanism will add the display of heartbeat information in the show server output
@ -786,11 +786,11 @@ Two commands are provided to change the logging levels within MaxScale, disable
MaxScale> disable log debug
MaxScale>
Please note that changes made via this interface will not persist across restarts of MaxScale. To make a permanent change edit the MaxScale.cnf file.
Please note that changes made via this interface will not persist across restarts of MaxScale. To make a permanent change edit the maxscale.cnf file.
## Reloading The Configuration
A command, reload config, is available that will cause MaxScale to reload the MaxScale.cnf configuration file.
A command, reload config, is available that will cause MaxScale to reload the maxscale.cnf configuration file.
## Shutting Down MaxScale
@ -798,7 +798,7 @@ The MaxScale server may be shutdown using the shutdown maxscale command.
# Configuring MaxScale to Accept MaxAdmin Connections
In order to allow the use of the MaxAdmin client interface the service must be added to the MaxScale.cnf file of the Maxscale server. The CLI service itself must be added and a listener for the maxscaled protocol.
In order to allow the use of the MaxAdmin client interface the service must be added to the maxscale.cnf file of the Maxscale server. The CLI service itself must be added and a listener for the maxscaled protocol.
The default entries required are shown below.

184
Documentation/Reference/MaxScale-HA-with-lsyncd.md Normal file
View File

@ -0,0 +1,184 @@
# MaxScale HA with Lsyncd
***This guide was written for lsyncd 2.1.5.***
This document guides you in setting up multiple MaxScale instances and synchronizing the configuration files with lsyncd. Lsyncd is a rsync wrapper which can synchronize files across the network. The lsyncd daemon uses a configuration file to control the files to synchronize and the remote targets where these files are synchronized to.
Copying the configuration file and running the lsyncd daemon on all the hosts keeps all the configuration files in sync. Modifications in the configuration file on one of the hosts will be copied on the other hosts. This allows adinistrators to easily provide a highly available, disaster resistant MaxScale installation with up-to-date configuration files on all the hosts.
### Requirements
You will need:
* Access to the remote hosts.
* MaxScale installed on all systems
* Configured maxscale.cnf file in /etc
* SSH daemon and clients installed on all hosts
The installation and configuration of MaxScale is covered in other documents.
## Creating SSH keys
For lsyncd to work, we will need to either use an existing set of SSH keys or to create a new set of keys. The creation and copying of keys needs to be repeated on all of the hosts.
If you already have a SSH key generated, you can skip this next step and go to the Copying Keys part.
### Generating keys
To generate a new set of SSH keys, we will use `ssh-keygen`.
```
[root@localhost ~]# ssh-keygen
Generating public/private rsa key pair.
Enter file in which to save the key (/root/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /root/.ssh/id_rsa.
Your public key has been saved in /root/.ssh/id_rsa.pub.
The key fingerprint is:
f4:99:0a:cc:d4:ac:ea:ed:ff:0d:bb:e5:87:3e:38:df root@localhost.localdomain
The key's randomart image is:
+--[ RSA 2048]----+
| |
| o |
| . + |
| + o . o |
| = S + |
| . . . |
| . . .... |
| . . o*o.. |
| ..o...+==oE |
+-----------------+
```
The keys will be generated in the .ssh folder and will automatically be used by ssh.
### Copying keys
To copy the SSH keys to the remote host we will use `ssh-copy-id`.
Use the username and host of the remote server you wish to synchronize MaxScale's configuration files to. For example, if the server's address is 192.168.122.100 and the user we use for synchronization us `user` we can use the following command.
```
ssh-copy-id user@192.168.122.100
```
Repeat the last command with the usernames and addresses of all the remote hosts you want to synchronize the configuration files to.
## Installing lsyncd
You will need to install lsyncd on all of the hosts for changes in the configuration file on one of the nodes to be synchronized to the other nodes.
You can install lsyncd with either a package manager or by building from source code. This guide demonstrates installation using a package manager and those looking to build lsyncd from source should refer to its documentation: https://github.com/axkibe/lsyncd/wiki/Manual-to-Lsyncd-2.1.x
Installing with Yum:
```
yum install lsyncd
```
Installing with Apt:
```
apt-get install lsyncd
```
## Creating the Lsyncd configuration file
Lsyncd uses a configuration file to determine where to read files from and where to synchronize them if changes in them occur. Lsyncd is written in Lua and the configuration file is also valid Lua code.
Here is an example configuration file with descriptions on the meaning of the values in it.
```
-- Lsyncd will log to these two files.
settings{
logfile = "/var/log/maxscale/maxscale-ha.log",
statusFile = "/var/log/maxscale/maxscale-ha-status.log"
}
-- Copy and paste the sync section and change the host value to add new remote targets.
sync{
default.rsyncssh,
-- This is where the maxscale.cnf file is copied from.
source="/etc",
-- This is the user and host where the maxscale.cnf is copied to.
-- Change this to the user and destination host where you want maxscale.cnf to be synchronized to.
host="user@192.168.122.100",
-- This is where the maxscale.cnf is copied to on the remote host.
targetdir="/etc",
-- This is an optional section which defines a custom SSH port. Uncomment to enable.
-- ssh={port=2222},
-- These are values passed to rsync. Only change these if you know what you are doing.
rsync={
compress=true,
_extra = {[[--filter=+ *maxscale.cnf]],
[[--filter=- **]]
}
}
}
```
The most important part is the `sync` section which defines a target for synchronization. The `default.rsyncssh` tells lsyncd to synchronize files using SSH.
The `source` parameter tells lsyncd where to read the files from. This should be the location of the maxscale.cnf file. The `host` parameter defines the host where the files should be synchronized to and the user account lsyncd should use when synchronizing the files. The `targetdir` parameter defines the local directory on the remote target where the files should be synchronized to. This value should be the location on the remote host where the maxscale.cnf file is searched from. By default, this is the `/etc` folder.
The optional `ssh` parameter and its sub-parameter `port`define a custom port for the SSH connection. Most users do not need this parameterer. The `rsycn` parameter contains an arra of options that are passed to the rsycn executable. These should not be changed unless you specifically know what you are doing. For more information on the options passed to rsync read the rsync(1) manpage.
You can add multiple remote targets by defining multiple `sync` sections. Here is an example with two sync sections defining different hosts that have MaxScale installed and whose configuration files should be kep in sync.
```
settings{
logfile = "/var/log/maxscale/maxscale-ha.log",
statusFile = "/var/log/maxscale/maxscale-ha-status.log"
}
sync{
default.rsyncssh,
source="/etc",
host="maxuser@192.168.0.50",
targetdir="/etc",
rsync={
compress=true,
_extra = {[[--filter=+ *maxscale.cnf]],
[[--filter=- **]]
}
}
}
sync{
default.rsyncssh,
source="/etc",
host="syncuser@192.168.122.105",
targetdir="/etc",
rsync={
compress=true,
_extra = {[[--filter=+ *maxscale.cnf]],
[[--filter=- **]]
}
}
}
```
## Starting Lsyncd
Starting lsyncd can be done from the command line or through a init script. To start syncd from the command like, execute the `lsyncd` command and pass the configuration file as the only parameter.
By default lsyncd will search for the configuration file in `/etc/lsyncd.conf`. By placing the configuration file we created in the `/etc` folder, we can start lsyncd with the following command.
```
service lsyncd start
```
Here is an example which start lsyncd and reads the configuration options from the `lsyncd.cnf` file.
```
lsyncd lsyncd.cnf
```
For more information on the lsyncd executable and its options, please see the --help output of lsyncd or the lsyncd(1) manpage.

15
Documentation/Reference/MaxScale-and-SSL.md Normal file
View File

@ -0,0 +1,15 @@
# MaxScale and SSL
MaxScale supports client side SSL connections. Enabling is done on a per service basis and each service has its own set of certificates.
## SSL Options
Here are the options which relate to SSL and certificates.
Parameter|Values |Description
---------|-----------|--------
ssl | disabled, enabled, required |`disable` disables SSL, `enabled` enables SSL for client connections but still allows non-SSL connections and `required` requires SSL from all client connections. With the `required` option, client connections that do not use SSL will be rejected.
ssl_cert | path to file |Path to server certificate
ssl_key | path to file |Path to server private key
ssl_ca_cert | path to file |Path to Certificate Authority file
ssl_version|SSLV3,TLSV10,TLSV11,TLSV12,MAX| The SSL method level, defaults to highest available encryption level which is TLSv1.2
ssl_cert_verify_depth|integer|Certificate authority certificate verification depth, default is 100.

2
Documentation/Release-Notes/MaxScale-0.5-Release-Notes.md
View File

@ -1,4 +1,4 @@
MaxScale Release Notes
# MariaDB MaxScale 0.5 Alpha Release Notes
0.5 Alpha

2
Documentation/Release-Notes/MaxScale-0.6-Release-Notes.md
View File

@ -1,4 +1,4 @@
MaxScale Release Notes
# MariaDB MaxScale 0.6 Alpha Release Notes
0.6 Alpha

2
Documentation/Release-Notes/MaxScale-0.7-Release-Notes.md
View File

@ -1,4 +1,4 @@
MaxScale Release Notes
# MariaDB MaxScale 0.7 Alpha Release Notes
0.7 Alpha

2
Documentation/Release-Notes/MaxScale-1.0-Release-Notes.md
View File

@ -1,4 +1,4 @@
MaxScale Release Notes
# MariaDB MaxScale 1.0 Beta Release Notes
1.0 Beta

6
Documentation/Release-Notes/MaxScale-1.0.1-Release-Notes.md
View File

@ -1,4 +1,4 @@
MaxScale Release Notes
# MariaDB MaxScale 1.0.1 Beta Release Notes
1.0.1 Beta
@ -107,11 +107,11 @@ A number of bug fixes have been applied between the 1.0 beta release and this re
</tr>
<tr>
<td>479</td>
<td>Undefined filter reference in MaxScale.cnf causes a crash</td>
<td>Undefined filter reference in maxscale.cnf causes a crash</td>
</tr>
<tr>
<td>410</td>
<td>MaxScale.cnf server option is not parsed for spaces</td>
<td>maxscale.cnf server option is not parsed for spaces</td>
</tr>
<tr>
<td>417</td>

2
Documentation/Release-Notes/MaxScale-1.0.3-Release-Notes.md
View File

@ -1,4 +1,4 @@
MaxScale Release Notes
# MariaDB MaxScale 1.0.3 Release Notes
1.0.3 GA

2
Documentation/Release-Notes/MaxScale-1.0.4-Release-Notes.md
View File

@ -1,4 +1,4 @@
# MaxScale Release Notes
# MariaDB MaxScale 1.0.4 Release Notes
1.0.4 GA

2
Documentation/Release-Notes/MaxScale-1.0.5-Release-Notes.md
View File

@ -1,4 +1,4 @@
MaxScale Release Notes 1.0.5 GA
# MariaDB MaxScale 1.0.5 Release Notes
This document details the changes in version 1.0.5 since the release of the 1.0.4 GA of the MaxScale product.

2
Documentation/Release-Notes/MaxScale-1.1-Release-Notes.md
View File

@ -1,4 +1,4 @@
# MaxScale Release Notes
# MariaDB MaxScale 1.1 Release Notes
## 1.1 GA

4
Documentation/Release-Notes/MaxScale-1.1.1-Release-Notes.md
View File

@ -1,6 +1,6 @@
# MaxScale Release Notes
# MariaDB MaxScale 1.1.1 Release Notes
## 1.1 GA
## 1.1.1 GA
MaxScale 1.1 is the current stable (GA) release of MaxScale. Version 1.1.1 is mainly a bug fix release introducing fixes, but also introduces some improvements to existing functionality.

99
Documentation/Release-Notes/MaxScale-1.2.0-Release-Notes.md Normal file
View File

@ -0,0 +1,99 @@
# MariaDB MaxScale 1.2 Release Notes
## 1.2 GA
This document details the changes in version 1.2 since the release of the 1.1.1 GA Release of the MaxScale product.
###***PLEASE NOTICE: MaxScale installation directories have changed in this version***
The 1.2 version of MaxScale differs from previos versions in its installation layout. Please take great care when upgrading MaxScale from previous versions to version 1.2. An automatic upgrade will not work due to the severe changes in the installation layout.
## New Features
### Non-root MaxScale
You can now run MaxScale as any user. The standard installation of a MaxScale package now creates the maxscale user and the maxscale group.
### FHS-compliant installation
The 1.2 version of MaxScale now complies to the Filesystem Hierarchy Standard. This means that MAXSCALE_HOME is no longer necessary and directories can be moved to different locations.
A quick list of changes in installation directories and file names:
* Binaries go into `/usr/bin`
* Configuration files to `/etc` and the configuration file is now lower case: `maxscale.cnf`
* Logs to `/var/log/maxscale`
* The module and library directory have been combined into a single directory in `/usr/lib64/maxscale`. If you have custom modules please make sure they are located there.
* Data directory is `/var/lib/maxscale`. This is the default location for MaxScale-specific data.
* PID file can be found at `/var/run/maxscale`
### Client side SSL encryption
MaxScale now supports SSL/TLS encrypted connections to MaxScale.
### Launchable scripts
Now you can configure MaxScale monitor module to automatically launch a script when it detects change in the state of a backend server. The script can be any customer script defined by you to take diagnostic or reporting action. With this you can easily customize MaxScale's behavior.
### Lsyncd configuration guide
A new tutorial has beed added which helps you keep MaxScale's configuration files in sync across multiple hosts. This allows for easier HA setups with MaxScale and guarantees up-to-date configuration files on all nodes. The tutorial can be found [here](../Reference/MaxScale-HA-with-lsyncd.md).
## Bug fixes
Here is a list of bugs fixed since the release of MaxScale 1.1.1.
* [MXS-24](https://mariadb.atlassian.net/browse/MXS-24): bugzillaId-604: Module load path documentation issues ...
* [MXS-40](https://mariadb.atlassian.net/browse/MXS-40): Display logged in users
* [MXS-113](https://mariadb.atlassian.net/browse/MXS-113): MaxScale seems to fail if built against MariaDB 10.0 libraries
* [MXS-116](https://mariadb.atlassian.net/browse/MXS-116): Do not run maxscale as root.
* [MXS-117](https://mariadb.atlassian.net/browse/MXS-117): Allow configuration of the log file directory
* [MXS-125](https://mariadb.atlassian.net/browse/MXS-125): inconsistency in maxkeys/maxpassword output and parameters
* [MXS-128](https://mariadb.atlassian.net/browse/MXS-128): cyclic dependency utils -> log_manager -> utils
* [MXS-136](https://mariadb.atlassian.net/browse/MXS-136): Check for MaxScale replication heartbeat table existence before creating
* [MXS-137](https://mariadb.atlassian.net/browse/MXS-137): cannot get sql for queries with length >= 0x80
* [MXS-139](https://mariadb.atlassian.net/browse/MXS-139): Schemarouter authentication for wildcard grants fails without optimize_wildcard
* [MXS-140](https://mariadb.atlassian.net/browse/MXS-140): strip_db_esc does not work without auth_all_servers
* [MXS-162](https://mariadb.atlassian.net/browse/MXS-162): Fix Incorrect info in Configuration Guide
* [MXS-165](https://mariadb.atlassian.net/browse/MXS-165): Concurrency issue while incrementing sessions in qlafilter
* [MXS-166](https://mariadb.atlassian.net/browse/MXS-166): Memory leak when creating a new event
* [MXS-171](https://mariadb.atlassian.net/browse/MXS-171): Allow reads on master for readwritesplit
* [MXS-176](https://mariadb.atlassian.net/browse/MXS-176): Missing dependencies in documentation
* [MXS-179](https://mariadb.atlassian.net/browse/MXS-179): Keep configuration changes in synch across MaxScale Mate Nodes
* [MXS-180](https://mariadb.atlassian.net/browse/MXS-180): MariaDB10 binlog router compatibilty
* [MXS-181](https://mariadb.atlassian.net/browse/MXS-181): Poor performance on TCP connection due to Nagle's algoritm
* [MXS-182](https://mariadb.atlassian.net/browse/MXS-182): SHOW SLAVE STATUS and maxadmin "show services" for binlog router needs updated when used with MariaDB 10 Master
* [MXS-212](https://mariadb.atlassian.net/browse/MXS-212): Stopped services accept connections
* [MXS-225](https://mariadb.atlassian.net/browse/MXS-225): RPM Debug build packages have no debugging symbols
* [MXS-227](https://mariadb.atlassian.net/browse/MXS-227): Memory leak in Galera Monitor
* [MXS-244](https://mariadb.atlassian.net/browse/MXS-244): Memory leak when using prepared statements without arguments
## Known Issues and Limitations
There are a number bugs and known limitations within this version of MaxScale, the most serious of this are listed below.
* MaxScale can not manage authentication that uses wildcard matching in hostnames in the mysql.user table of the backend database. The only wildcards that can be used are in IP address entries.
* When users have different passwords based on the host from which they connect MaxScale is unable to determine which password it should use to connect to the backend database. This results in failed connections and unusable usernames in MaxScale.
* LONGBLOB are currently not supported.
* Galera Cluster variables, such as @@wsrep_node_name, are not resolved by the embedded MariaDB parser.
* The Database Firewall filter does not support multi-statements. Using them will result in an error being sent to the client.
## Packaging
Both RPM and Debian packages are available for MaxScale in addition to the tar based releases previously distributed we now provide
* CentOS/RedHat 5
* CentOS/RedHat 6
* CentOS/RedHat 7
* Debian 6
* Debian 7
* Ubuntu 12.04 LTS
* Ubuntu 14.04 LTS
* SuSE Linux Enterprise 11
* SuSE Linux Enterprise 12

104
Documentation/Routers/ReadConnRoute.md Normal file
View File

@ -0,0 +1,104 @@
# Readconnroute
This document provides anoverview of the **readconnroute** router module and its intended use case scenarios. It also displays all router configuration parameters with their descriptions.
## Overview
The readconnroute router provides simple and lightweight load balancing across a set of servers. The router can also be configured to balance connections based on a weighting parameter defined in the server's section.
## Configuration
Readconnroute router-specific settings are specified in the configuration file of MaxScale in its specific section. The section can be freely named but the name is used later as a reference from listener section.
The configuration consists of mandatory and optional parameters.
## Mandatory parameters
**`type`** specifies the type of service. For readconnroute module the type is `router`:
type=router
**`router`** specifies the router module to be used. For readconnroute the value is `readconnroute`:
router=readconnroute
**`servers`** provides a list of servers, which the router will connect to:
servers=server1,server2,server3
**NOTE: Each server on the list must have its own section in the configuration file where it is defined.**
**`user`** is the username the router session uses for accessing backends in order to load the content of the `mysql.user` table (and `mysql.db` and database names as well) and optionally for creating, and using `maxscale_schema.replication_heartbeat` table.
**`passwd`** specifies corresponding password for the user. Syntax for user and passwd is:
```
user=<username>
passwd=<password>
```
## Optional parameters
The **`weightby`** parameter defines the name of the value which is used to calculate the weights of the servers. Here is an example server configuration with the `serv_weight` parameter used as the weighting parameter.
```
[server1]
type=server
address=127.0.0.1
port=3000
protocol=MySQLBackend
serv_weight=3
[server2]
type=server
address=127.0.0.1
port=3001
protocol=MySQLBackend
serv_weight=1
[Read Service]
type=service
router=readconnroute
servers=server1,server2
weightby=serv_weight
```
With this configuration and a heavy query load, the server *server1* will get most of the connections and about a third of the remaining queries are routed to the second server. With server weights, you can assing secondary servers that are only used when the primary server is under heavy load.
Without the weightby parameter, each connection counts as a single connection. With a weighting parameter, a single connection received its weight from the server's own weighting parameter divided by the sum of all weighting parameters in all the configured servers.
If we use the previous configuration as an example, the sum of the `serv_weight` parameter is 4. Server1 would receive a weight of `3/4=75%` and server2 would get `1/4=25%`. This means that server1 would get 75% of the connections and server2 would get 25% of the connections.
**`router_options`** can contain a list of valid server roles. These roles are used as the valid types of servers the router will form connections to when new sessions are created.
```
router_options=slave
```
Here is a list of all possible values for the `router_options`.
Role|Description
------|---------
master|A server assigned as a master by one of MaxScale monitors. Depending on the monitor implementation, this could be a master server of a Master-Slave replication cluster or a Write-Master of a Galera cluster.
slave|A server assigned as a slave of a master.
synced| A Galera cluster node which is in a synced state with the cluster.
ndb|A MySQL Replication Cluster node
running|A server that is up and running. All servers that MaxScale can connect to are labeled as running.
If no `router_options` parameter is configured in the service definition, the router will use the default value of `running`. This means that it will load balance connections across all running servers defined in the `servers` parameter of the service.
## Examples
The most common use for the readconnroute is to provide either a read or write port for an application. This provides a more lightweight routing solution than the more complex readwritesplit router but requires the application to be able to use distinct write and read ports.
To configure a read-only service that tolerates master failures, we first need to add a new section in to the configuration file.
```
[Read Service]
type=service
router=readconnroute
servers=slave1,slave2,slave3
router_options=slave
```
Here the `router_options`designates slaves as the only valid server type. With this configuration, the queries are load balanced across the slave servers.
For more complex examples of the readconnroute router, take a look at the examples in the [Tutorials](../Tutorials) folder.

19
Documentation/routers/ReadWriteSplit.md → Documentation/Routers/ReadWriteSplit.md
View File

@ -4,7 +4,9 @@ This document provides a short overview of the **readwritesplit** router module
## Overview
The **readwritesplit** router is designed to be used with a Master-Slave replication cluster. It automatically detects changes in the master server and will use the current master server of the cluster. With a Galera cluster, one can achieve a resilient setup and easy master failover by using one of the Galera nodes as a Write-Master node, where are write queries are routed, and spreading the read load over all the nodes.
The **readwritesplit** router is designed to increase the read-only processing capability of a cluster while maintaining consistency. This is achieved by splitting the query load into read and write queries. Read queries, which do not modify data, are spread across multiple nodes while all write queries will be sent to a single node.
The router is designed to be used with a traditional Master-Slave replication cluster. It automatically detects changes in the master server and will use the current master server of the cluster. With a Galera cluster, one can achieve a resilient setup and easy master failover by using one of the Galera nodes as a Write-Master node, where all write queries are routed, and spreading the read load over all the nodes.
## Configuration
@ -18,9 +20,9 @@ The configuration consists of mandatory and optional parameters.
type=router
**`service`** specifies the router module to be used. For **readwritesplit** the value is `readwritesplit`:
**`router`** specifies the router module to be used. For **readwritesplit** the value is `readwritesplit`:
service=readwritesplit
router=readwritesplit
**`servers`** provides a list of servers, which must include one master and available slaves:
@ -91,6 +93,17 @@ disable_sescmd_history=true
disable_slave_recovery=true
```
**`master_accept_reads`** allows the master server to be used for reads. This is a useful option to enable if you are using a small number of servers and wish to use the master for reads as well.
```
# Use the master for reads
master_accept_reads=true
```
### Routing hints
The readwritesplit router supports routing hints. For a detailed guide on hint syntax and functionality, please see [this](../Reference/Hint-Syntax.md) document.
## Limitations
In Master-Slave replication cluster also read-only queries are routed to master too in the following situations:

0
Documentation/routers/SchemaRouter.md → Documentation/Routers/SchemaRouter.md
View File

130
Documentation/Tutorials/Administration-Tutorial.md
View File

@ -15,54 +15,33 @@ The purpose of this tutorial is to introduce the MaxScale Administrator to a few
### Starting MaxScale
There are several ways to start MaxScale, the most convenient mechanism is probably using the Linux service interface. When a MaxScale package is installed the package manager will also installed a script in /etc/init.d which may be used to start and stop MaxScale either directly or via the service interface.
```
$ service maxscale start
```
or
```
$ /etc/init.d/maxscale start
It is also possible to start MaxScale by executing the maxscale command itself, in this case you must ensure that the environment is correctly setup or command line options are passed. The major elements to consider are the correct setting of the MAXSCALE\_HOME directory and to ensure that LD\_LIBRARY\_PATH. The LD\_LIBRARY\_PATH should include the lib directory that was installed as part of the MaxScale installation, the MAXSCALE\_HOME should point to /usr/local/mariadb-maxscale if a default installation has been created or to the directory this was relocated to. Running the executable $MAXSCALE\_HOME/bin/maxscale will result in MaxScale running as a daemon process, unattached to the terminal in which it was started and using configuration files that it finds in the $MAXSCALE\_HOME directory.
```
It is also possible to start MaxScale by executing the maxscale command itself. Running the executable /usr/bin/maxscale will result in MaxScale running as a daemon process, unattached to the terminal in which it was started and using configuration files that it finds in the /etc directory.
Options may be passed to the MaxScale binary that alter this default behavior, this options are documented in the table below.
<table>
<tr>
<td>Switch</td>
<td>Long Option</td>
<td>Description</td>
</tr>
<tr>
<td>-d</td>
<td>--nodaemon</td>
<td>Run MaxScale attached to the terminal rather than as a daemon process. This is useful for debugging purposes.</td>
</tr>
<tr>
<td>-c</td>
<td>--homedir=</td>
<td>Ignore the environment variable MAXSCALE_HOME and use the supplied argument instead.</td>
</tr>
<tr>
<td>-f</td>
<td>--config=</td>
<td>Use the filename passed as an argument instead of looking in $MAXSCALE_HOME/etc/MaxScale.cnf</td>
</tr>
<tr>
<td>-l<file>|<shm>|<stdout></td>
<td>--log=</td>
<td>Control where logs are written for the debug and trace level log messages. the default is to write these to a shared memory device, however using the -lfile or --log=file option will forced these to be written to regular files. Using -lstdout or --log=stdout will use the standard output for all enabled logs.</td>
</tr>
<tr>
<td>-v</td>
<td>--version</td>
<td>Print version information for MaxScale</td>
</tr>
<tr>
<td>-?</td>
<td>--help</td>
<td>Print usage information for MaxScale</td>
</tr>
</table>
Switch|Long Option|Description
------|-----------|-----------
`-d`|`--nodaemon`|enable running in terminal process (default:disabled)
`-f FILE`|`--config=FILE`|relative or absolute pathname of MaxScale configuration file (default:/etc/maxscale.cnf)
`-l[file shm]`|`--log=[file shm]`|log to file or shared memory (default: shm)
`-L PATH`|`--logdir=PATH`|path to log file directory (default: /var/log/maxscale)
`-D PATH`|`--datadir=PATH`|path to data directory, stored embedded mysql tables (default: /var/cache/maxscale)
`-C PATH`|`--configdir=PATH`|path to configuration file directory (default: /etc/)
`-B PATH`|`--libdir=PATH`|path to module directory (default: /usr/lib64/maxscale)
`-A PATH`|`--cachedir=PATH`|path to cache directory (default: /var/cache/maxscale)
`P PATH`|`--piddir=PATH`|PID file directory
`-U USER`|`--user=USER`|run MaxScale as another user. The user ID and group ID of this user are used to run MaxScale.
`-s [yes no]`|`--syslog=[yes no]`|log messages to syslog (default:yes)
`-S [yes no]`|`--maxscalelog=[yes no]`|log messages to MaxScale log (default: yes)
`-v`|`--version`|print version info and exit
`-?`|`--help`|show this help
<a name="stopping"></a>
### Stopping MaxScale
@ -70,26 +49,27 @@ Options may be passed to the MaxScale binary that alter this default behavior, t
There are numerous ways in which MaxScale can be stopped; using the service interface, killing the process or by use of the maxadmin utility.
Stopping MaxScale with the service interface is simply a case of using the service stop command or calling the init.d script with the stop argument.
```
$ service maxscale stop
```
or
```
$ /etc/init.d/maxscale stop
MaxScale will also stop gracefully if it received a hangup signal, to find the process id of the MaxScale server use the ps command or read the contents of the maxscale.pid file located in the same directory as the logs.
$ kill -HUP `cat $MAXSCALE_HOME/log/maxscale.pid`
```
MaxScale will also stop gracefully if it received a terminate signal, to find the process id of the MaxScale server use the ps command or read the contents of the maxscale.pid file located in the /var/run/maxscale directory.
```
$ kill `cat /var/run/maxscale/maxscale.pid`
```
In order to shutdown MaxScale using the maxadmin command you may either connect with maxadmin in interactive mode or pass the "shutdown maxscale" command you wish to execute as an argument to maxadmin.
```
$ maxadmin -pmariadb shutdown maxscale
```
<a name="checking"></a>
### Checking The Status Of The MaxScale Services
It is possible to use the maxadmin command to obtain statistics regarding the services that are configured within your MaxScale configuration file. The maxadmin command "list services" will give very basic information regarding the services that are define. This command may be either run in interactive mode or passed on the maxadmin command line.
```
$ maxadmin -pmariadb
MaxScale> list services
@ -110,6 +90,7 @@ It is possible to use the maxadmin command to obtain statistics regarding the se
--------------------------+----------------------+--------+---------------
MaxScale>
```
It should be noted that network listeners count as a user of the service, therefore there will always be one user per network port in which the service listens. More detail can be obtained by use of the "show service" command which is passed a service name.
@ -117,7 +98,7 @@ It should be noted that network listeners count as a user of the service, theref
### What Clients Are Connected To MaxScale
To determine what client are currently connected to MaxScale you can use the "list clients" command within maxadmin. This will give you IP address and the ID’s of the DCB and session for that connection. As with any maxadmin command this can be passed on the command line or typed interactively in maxadmin.
```
$ maxadmin -pmariadb list clients
Client Connections
@ -133,28 +114,27 @@ To determine what client are currently connected to MaxScale you can use the "li
-----------------+------------------+----------------------+------------
$
```
<a name="rotating"></a>
### Rotating Log Files
MaxScale write log data into four log files with varying degrees of detail. With the exception of the error log, which can not be disabled, these log files may be enabled and disabled via the maxadmin interface or in the configuration file. The default behavior of MaxScale is to grow the log files indefinitely, the administrator must take action to prevent this.
It is possible to rotate either a single log file or all the log files with a single command. When the logfile is rotated, the current log file is closed and a new log file, with an increased sequence number in its name, is created. Log file rotation is achieved by use of the "flush log" or “flush logs” command in maxadmin.
```
$ maxadmin -pmariadb flush logs
```
Flushes all of the logs, whereas an individual log may be flushed with the "flush log" command.
```
$ maxadmin -pmariadb
MaxScale> flush log error
MaxScale> flush log trace
MaxScale>
```
This may be integrated into the Linux logrotate mechanism by adding a configuration file to the /etc/logrotate.d directory. If we assume we want to rotate the log files once per month and wish to keep 5 log files worth of history, the configuration file would look like the following.
<table>
<tr>
<td>/usr/local/mariadb-maxscale/log/*.log {
```
/var/log/maxscale/*.log {
monthly
rotate 5
missingok
@ -163,30 +143,26 @@ sharedscripts
postrotate
\# run if maxscale is running
if test -n "`ps acx|grep maxscale`"; then
/usr/local/mariadb-maxscale/bin/maxadmin -pmariadb flush logs
/usr/bin/maxadmin -pmariadb flush logs
fi
endscript
}</td>
</tr>
</table>
}
```
One disadvantage with this is that the password used for the maxadmin command has to be embedded in the log rotate configuration file. MaxScale will also rotate all of its log files if it receives the USR1 signal. Using this the logrotate configuration script can be rewritten as
<table>
<tr>
<td>/usr/local/mariadb-maxscale/log/*.log {
```
/var/log/maxscale/*.log {
monthly
rotate 5
missingok
nocompress
sharedscripts
postrotate
kill -USR1 `cat /usr/local/mariadb-maxscale/log/maxscale.pid`
kill -USR1 `cat /var/run/maxscale/maxscale.pid`
endscript
}</td>
</tr>
</table>
}
```
<a name="outofuse"></a>
### Taking A Database Server Out Of Use
@ -194,16 +170,16 @@ endscript
MaxScale supports the concept of maintenance mode for servers within a cluster, this allows for planned, temporary removal of a database from the cluster within the need to change the MaxScale configuration.
To achieve the removal of a database server you can use the set server command in the maxadmin utility to set the maintenance mode flag for the server. This may be done interactively within maxadmin or by passing the command on the command line.
```
MaxScale> set server dbserver3 maintenance
MaxScale>
```
This will cause MaxScale to stop routing any new requests to the server, however if there are currently requests executing on the server these will not be interrupted.
To bring the server back into service use the "clear server" command to clear the maintenance mode bit for that server.
```
MaxScale> clear server dbserver3 maintenance
MaxScale>
```
Note that maintenance mode is not persistent, if MaxScale restarts when a node is in maintenance mode a new instance of MaxScale will not honour this mode. If multiple MaxScale instances are configured to use the node them maintenance mode must be set within each MaxScale instance. However if multiple services within one MaxScale instance are using the server then you only need set the maintenance mode once on the server for all services to take note of the mode change.

6
Documentation/Tutorials/Galera-Cluster-Connection-Routing-Tutorial.md
View File

@ -60,7 +60,7 @@ If you wish to use two different usernames for the two different roles of monito
### Creating Your MaxScale Configuration
MaxScale configuration is held in an ini file that is located in the file MaxScale.cnf in the directory $MAXSCALE_HOME/etc, if you have installed in the default location then this file is available in /usr/local/mariadb-maxscale/etc/MaxScale.cnf. This is not created as part of the installation process and must be manually created. A template file does exist within this directory that may be use as a basis for your configuration.
MaxScale configuration is held in an ini file that is located in the file maxscale.cnf in the directory /etc, if you have installed in the default location then this file is available in /etc/maxscale.cnf. This is not created as part of the installation process and must be manually created. A template file does exist within the /usr/share/maxscale directory that may be use as a basis for your configuration.
A global, maxscale, section is included within every MaxScale configuration file; this is used to set the values of various MaxScale wide parameters, perhaps the most important of these is the number of threads that MaxScale will use to execute the code that forwards requests and handles responses for clients.
@ -89,7 +89,7 @@ In order to instruct the router to which servers it should route we must add rou
The final step in the service section is to add the username and password that will be used to populate the user data from the database cluster. There are two options for representing the password, either plain text or encrypted passwords may be used. In order to use encrypted passwords a set of keys must be generated that will be used by the encryption and decryption process. To generate the keys use the maxkeys command and pass the name of the secrets file in which the keys are stored.
% maxkeys /usr/local/mariadb-maxscale/etc/.secrets
% maxkeys /var/lib/maxscale/.secrets
%
Once the keys have been created the maxpasswd command can be used to generate the encrypted password.
@ -178,7 +178,7 @@ or
% service maxscale start
Check the error log in /usr/local/mariadb-maxscale/log to see if any errors are detected in the configuration file and to confirm MaxScale has been started. Also the maxadmin command may be used to confirm that MaxScale is running and the services, listeners etc have been correctly configured.
Check the error log in /var/log/maxscale to see if any errors are detected in the configuration file and to confirm MaxScale has been started. Also the maxadmin command may be used to confirm that MaxScale is running and the services, listeners etc have been correctly configured.
% maxadmin -pmariadb list services

6
Documentation/Tutorials/Galera-Cluster-Read-Write-Splitting-Tutorial.md
View File

@ -62,7 +62,7 @@ If you wish to use two different usernames for the two different roles of monito
### Creating Your MaxScale Configuration
MaxScale configuration is held in an ini file that is located in the file MaxScale.cnf in the directory $MAXSCALE_HOME/etc, if you have installed in the default location then this file is available in /usr/local/mariadb-maxscale/etc/MaxScale.cnf. This is not created as part of the installation process and must be manually created. A template file does exist within this directory that may be use as a basis for your configuration.
MaxScale configuration is held in an ini file that is located in the file maxscale.cnf in the directory /etc, if you have installed in the default location then this file is available in /etc/maxscale.cnf. This is not created as part of the installation process and must be manually created. A template file does exist within the /usr/share/maxscale directory that may be use as a basis for your configuration.
A global, maxscale, section is included within every MaxScale configuration file; this is used to set the values of various MaxScale wide parameters, perhaps the most important of these is the number of threads that MaxScale will use to execute the code that forwards requests and handles responses for clients.
@ -83,7 +83,7 @@ The router for we need to use for this configuration is the readwritesplit modul
The final step in the service sections is to add the username and password that will be used to populate the user data from the database cluster. There are two options for representing the password, either plain text or encrypted passwords may be used. In order to use encrypted passwords a set of keys must be generated that will be used by the encryption and decryption process. To generate the keys use the maxkeys command and pass the name of the secrets file in which the keys are stored.
% maxkeys /usr/local/mariadb-maxscale/etc/.secrets
% maxkeys /var/lib/maxscale/.secrets
%
Once the keys have been created the maxpasswd command can be used to generate the encrypted password.
@ -183,7 +183,7 @@ or
% service maxscale start
Check the error log in /usr/local/mariadb-maxscale/log to see if any errors are detected in the configuration file and to confirm MaxScale has been started. Also the maxadmin command may be used to confirm that MaxScale is running and the services, listeners etc have been correctly configured.
Check the error log in /var/log/maxscale to see if any errors are detected in the configuration file and to confirm MaxScale has been started. Also the maxadmin command may be used to confirm that MaxScale is running and the services, listeners etc have been correctly configured.
% maxadmin -pmariadb list services

55
Documentation/Tutorials/MaxScale-Information-Schema.md
View File

@ -5,54 +5,65 @@ The plugin is capable of returning data in one of two ways, either as MySQL resu
# Configuration
The plugin is configured in the MaxScale.cnf plugin in much the same way as any other router service is configured, there needs to be a service section in the configuration file and also listeners defined for that service. The service does not however require any backend servers to be associated with it, or any monitors.
The plugin is configured in the maxscale.cnf plugin in much the same way as any other router service is configured, there needs to be a service section in the configuration file and also listeners defined for that service. The service does not however require any backend servers to be associated with it, or any monitors.
The service entry needs to define the service name, the type as service and the router module to load.
The specified user, with the password (plain or encrypted via maxpassword utility) is allowed to connect via MySQL protocol.
Currently the user can connect to maxinfo from any remote IP and to localhost as well.
```
[MaxInfo]
type=service
router=maxinfo
user=monitor
passwd=EBD2F49C3B375812A8CDEBA632ED8BBC
```
The listener section defines the protocol, port and other information needed to create a listener for the service. To listen on a port using the MySQL protocol a section as shown below should be added to the configuration file.
```
[MaxInfo Listener]
type=listener
service=MaxInfo
protocol=MySQLClient
port=9003
```
To listen with the HTTP protocol and hence return JSON documents a section as should below is required.
```
[MaxInfo JSON Listener]
type=listener
service=MaxInfo
protocol=HTTPD
port=8003
```
If both the MySQL and JSON responses are required then a single service can be configured with both types of listener.
As with any other listeners within MaxScale the listeners can be bound to a particular interface by use of the address= parameter. This allows the access to the maxinfo data to be limited to the localhost by adding an address=localhost parameter in the configuration file.
```
[MaxInfo Listener]
type=listener
service=MaxInfo
protocol=MySQLClient
address=localhost
port=9003
```
# MySQL Interface to maxinfo
The maxinfo supports a small subset of SQL statements in addition to the MySQL status and ping requests. These may be used for simple monitoring of MaxScale.
```
% mysqladmin -hmaxscale.mariadb.com -P9003 -umonitor -pxyz ping
mysqld is alive
% mysqladmin -hmaxscale.mariadb.com -P9003 -umonitor -pxyz status
Uptime: 72 Threads: 1 Sessions: 11
%
```
The SQL command used to interact with maxinfo is the show command, a variety of show commands are available and will be described in the following sections.
@ -60,6 +71,7 @@ The SQL command used to interact with maxinfo is the show command, a variety of
The show variables command will display a set of name and value pairs for a number of MaxScale system variables.
```
mysql> show variables;
+--------------------+-------------------------+
| Variable_name | Value |
@ -77,9 +89,11 @@ The show variables command will display a set of name and value pairs for a numb
9 rows in set (0.02 sec)
mysql>
```
The show variables command can also accept a limited like clause. This like clause must either be a literal string to match, a pattern starting with a %, a pattern ending with a % or a string with a % at both the start and the end.
```
mysql> show variables like 'version';
+---------------+----------------+
| Variable_name | Value |
@ -116,11 +130,13 @@ The show variables command can also accept a limited like clause. This like clau
3 rows in set (0.02 sec)
mysql>
```
## Show status
The show status command displays a set of status counters, as with show variables the show status command can be passed a simplified like clause to limit the values returned.
```
mysql> show status;
+---------------------------+-------+
| Variable_name | Value |
@ -151,11 +167,13 @@ The show status command displays a set of status counters, as with show variable
22 rows in set (0.02 sec)
mysql>
```
## Show services
The show services command will return a set of basic statistics regarding each of the configured services within MaxScale.
```
mysql> show services;
+----------------+----------------+--------------+----------------+
| Service Name | Router Module | No. Sessions | Total Sessions |
@ -172,6 +190,7 @@ The show services command will return a set of basic statistics regarding each o
8 rows in set (0.02 sec)
mysql>
```
The show services command does not accept a like clause and will ignore any like clause that is given.
@ -179,6 +198,7 @@ The show services command does not accept a like clause and will ignore any like
The show listeners command will return a set of status information for every listener defined within the MaxScale configuration file.
```
mysql> show listeners;
+----------------+-----------------+-----------+------+---------+
| Service Name | Protocol Module | Address | Port | State |
@ -196,6 +216,7 @@ The show listeners command will return a set of status information for every lis
9 rows in set (0.02 sec)
mysql>
```
The show listeners command will ignore any like clause passed to it.
@ -203,6 +224,7 @@ The show listeners command will ignore any like clause passed to it.
The show sessions command returns information on every active session within MaxScale. It will ignore any like clause passed to it.
```
mysql> show sessions;
+-----------+---------------+----------------+---------------------------+
| Session | Client | Service | State |
@ -222,11 +244,13 @@ The show sessions command returns information on every active session within Max
11 rows in set (0.02 sec)
mysql>
```
## Show clients
The show clients command reports a row for every client application connected to MaxScale. Like clauses are not available of the show clients command.
```
mysql> show clients;
+-----------+---------------+---------+---------------------------+
| Session | Client | Service | State |
@ -237,11 +261,13 @@ The show clients command reports a row for every client application connected to
2 rows in set (0.02 sec)
mysql>
```
## Show servers
The show servers command returns data for each backend server configured within the MaxScale configuration file. This data includes the current number of connections MaxScale has to that server and the state of that server as monitored by MaxScale.
```
mysql> show servers;
+---------+-----------+------+-------------+---------+
| Server | Address | Port | Connections | Status |
@ -254,11 +280,13 @@ The show servers command returns data for each backend server configured within
4 rows in set (0.02 sec)
mysql>
```
## Show modules
The show modules command reports the information on the modules currently loaded into MaxScale. This includes the name type and version of each module. It also includes the API version the module has been written against and the current release status of the module.
```
mysql> show modules;
+----------------+-------------+---------+-------------+----------------+
| Module Name | Module Type | Version | API Version | Status |
@ -277,12 +305,13 @@ The show modules command reports the information on the modules currently loaded
10 rows in set (0.02 sec)
mysql>
```
## Show monitors
The show monitors command reports each monitor configured within the system and the state of that monitor.
```
mysql> show monitors;
+---------------+---------+
| Monitor | Status |
@ -292,12 +321,13 @@ The show monitors command reports each monitor configured within the system and
1 row in set (0.02 sec)
mysql>
```
## Show eventTimes
The show eventTimes command returns a table of statistics that reflect the performance of the event queuing and execution portion of the MaxScale core.
```
mysql> show eventTimes;
+---------------+-------------------+---------------------+
| Duration | No. Events Queued | No. Events Executed |
@ -336,6 +366,7 @@ The show eventTimes command returns a table of statistics that reflect the perfo
30 rows in set (0.02 sec)
mysql>
```
Each row represents a time interval, in 100ms increments, with the counts representing the number of events that were in the event queue for the length of time that row represents and the number of events that were executing of the time indicated by the row.
@ -347,6 +378,7 @@ The simplified JSON interface takes the URL of the request made to maxinfo and m
The /variables URL will return the MaxScale variables, these variables can not be filtered via this interface.
```
$ curl http://maxscale.mariadb.com:8003/variables
[ { "Variable_name" : "version", "Value" : "1.0.6-unstable"},
{ "Variable_name" : "version_comment", "Value" : "MariaDB MaxScale"},
@ -358,11 +390,13 @@ The /variables URL will return the MaxScale variables, these variables can not b
{ "Variable_name" : "MAXSCALE_UPTIME", "Value" : 3948},
{ "Variable_name" : "MAXSCALE_SESSIONS", "Value" : 12}]
$
```
## Status
Use of the /status URI will return the status information that would normally be returned by the show status command. No filtering of the status information is available via this interface
```
$ curl http://maxscale.mariadb.com:8003/status
[ { "Variable_name" : "Uptime", "Value" : 3831},
{ "Variable_name" : "Uptime_since_flush_status", "Value" : 3831},
@ -387,11 +421,13 @@ Use of the /status URI will return the status information that would normally be
{ "Variable_name" : "Max_event_queue_time", "Value" : 0},
{ "Variable_name" : "Max_event_execution_time", "Value" : 1}]
$
```
## Services
The /services URI returns the data regarding the services defined within the configuration of MaxScale. Two counters are returned, the current number of sessions attached to this service and the total number connected since the service started.
```
$ curl http://maxscale.mariadb.com:8003/services
[ { "Service Name" : "Test Service", "Router Module" : "readconnroute", "No. Sessions" : 1, "Total Sessions" : 1},
{ "Service Name" : "Split Service", "Router Module" : "readwritesplit", "No. Sessions" : 1, "Total Sessions" : 1},
@ -402,11 +438,13 @@ The /services URI returns the data regarding the services defined within the con
{ "Service Name" : "CLI", "Router Module" : "cli", "No. Sessions" : 1, "Total Sessions" : 1},
{ "Service Name" : "MaxInfo", "Router Module" : "maxinfo", "No. Sessions" : 5, "Total Sessions" : 20}]
$
```
## Listeners
The /listeners URI will return a JSON array with one entry per listener, each entry is a JSON object that describes the configuration and state of that listener.
```
$ curl http://maxscale.mariadb.com:8003/listeners
[ { "Service Name" : "Test Service", "Protocol Module" : "MySQLClient", "Address" : "*", "Port" : 4006, "State" : "Running"},
{ "Service Name" : "Split Service", "Protocol Module" : "MySQLClient", "Address" : "*", "Port" : 4007, "State" : "Running"},
@ -418,11 +456,13 @@ The /listeners URI will return a JSON array with one entry per listener, each en
{ "Service Name" : "MaxInfo", "Protocol Module" : "MySQLClient", "Address" : "*", "Port" : 9003, "State" : "Running"},
{ "Service Name" : "MaxInfo", "Protocol Module" : "HTTPD", "Address" : "*", "Port" : 8003, "State" : "Running"}]
$
```
## Modules
The /modules URI returns data for each plugin that has been loaded into MaxScale. The plugin name, type and version are returned as is the version of the plugin API that the plugin was built against and the release status of the plugin.
```
$ curl http://maxscale.mariadb.com:8003/modules
[ { "Module Name" : "HTTPD", "Module Type" : "Protocol", "Version" : "V1.0.1", "API Version" : "1.0.0", "Status" : "In Development"},
{ "Module Name" : "maxscaled", "Module Type" : "Protocol", "Version" : "V1.0.0", "API Version" : "1.0.0", "Status" : "GA"},
@ -435,11 +475,13 @@ The /modules URI returns data for each plugin that has been loaded into MaxScale
{ "Module Name" : "cli", "Module Type" : "Router", "Version" : "V1.0.0", "API Version" : "1.0.0", "Status" : "GA"},
{ "Module Name" : "maxinfo", "Module Type" : "Router", "Version" : "V1.0.0", "API Version" : "1.0.0", "Status" : "Alpha"}]
$
```
## Sessions
The /sessions URI returns a JSON array with an object for each active session within MaxScale.
```
$ curl http://maxscale.mariadb.com:8003/sessions
[ { "Session" : "0x1a8e9a0", "Client" : "80.176.79.245", "Service" : "MaxInfo", "State" : "Session ready for routing"},
{ "Session" : "0x1a8e6d0", "Client" : "80.240.130.35", "Service" : "MaxInfo", "State" : "Session ready for routing"},
@ -453,32 +495,38 @@ The /sessions URI returns a JSON array with an object for each active session wi
{ "Session" : "0x1a5c530", "Client" : , "Service" : "Split Service", "State" : "Listener Session"},
{ "Session" : "0x19ac1c0", "Client" : , "Service" : "Test Service", "State" : "Listener Session"}]
$
```
## Clients
The /clients URI is a limited version of the /sessions, in this case it only returns an entry for a session that represents a client connection.
```
$ curl http://maxscale.mariadb.com:8003/clients
[ { "Session" : "0x1a90be0", "Client" : "80.176.79.245", "Service" : "MaxInfo", "State" : "Session ready for routing"},
{ "Session" : "0x1a8e9a0", "Client" : "127.0.0.1", "Service" : "MaxInfo", "State" : "Session ready for routing"},
{ "Session" : "0x1a8e6d0", "Client" : "80.240.130.35", "Service" : "MaxInfo", "State" : "Session ready for routing"}]
$
```
## Servers
The /servers URI is used to retrieve information for each of the servers defined within the MaxScale configuration. This information includes the connection count and the current status as monitored by MaxScale. The connection count is only those connections made by MaxScale to those servers.
```
$ curl http://maxscale.mariadb.com:8003/servers
[ { "Server" : "server1", "Address" : "127.0.0.1", "Port" : 3306, "Connections" : 0, "Status" : "Running"},
{ "Server" : "server2", "Address" : "127.0.0.1", "Port" : 3307, "Connections" : 0, "Status" : "Down"},
{ "Server" : "server3", "Address" : "127.0.0.1", "Port" : 3308, "Connections" : 0, "Status" : "Down"},
{ "Server" : "server4", "Address" : "127.0.0.1", "Port" : 3309, "Connections" : 0, "Status" : "Down"}]
$
```
## Event Times
The /event/times URI returns an array of statistics that reflect the performance of the event queuing and execution portion of the MaxScale core. Each element is an object that represents a time bucket, in 100ms increments, with the counts representing the number of events that were in the event queue for the length of time that row represents and the number of events that were executing of the time indicated by the object.
```
$ curl http://maxscale.mariadb.com:8003/event/times
[ { "Duration" : "< 100ms", "No. Events Queued" : 64, "No. Events Executed" : 63},
{ "Duration" : " 100 - 200ms", "No. Events Queued" : 0, "No. Events Executed" : 0},
@ -510,3 +558,4 @@ The /event/times URI returns an array of statistics that reflect the performance
{ "Duration" : "2700 - 2800ms", "No. Events Queued" : 0, "No. Events Executed" : 0},
{ "Duration" : "2800 - 2900ms", "No. Events Queued" : 0, "No. Events Executed" : 0},
{ "Duration" : "> 3000ms", "No. Events Queued" : 0, "No. Events Executed" : 0}]
```

4
Documentation/Tutorials/MySQL-Cluster-Setup.md
View File

@ -207,7 +207,7 @@ The SQL node is referenced here as [mysqld(API)], which reflects the fact that t
## Configuring MaxScale for connection load balancing of SQL nodes
Add these sections in MaxScale.cnf config file:
Add these sections in maxscale.cnf config file:
[Cluster Service]
type=service
@ -249,7 +249,7 @@ Add these sections in MaxScale.cnf config file:
Assuming MaxScale is installed in server1, start it
[root@server1 ~]# cd /usr/local/mariadb-maxscale/bin
[root@server1 ~]# cd /usr/bin
[root@server1 bin]# ./maxscale -c ../

121
Documentation/Tutorials/MySQL-Replication-Connection-Routing-Tutorial.md
View File

@ -36,6 +36,7 @@ The first user required must be able to select data from the table mysql.user, t
2. Create the user, substituting the username, password and host on which maxscale runs within your environment
```
MariaDB [(none)]> create user '*username*'@'*maxscalehost*' identified by '*password*';
**Query OK, 0 rows affected (0.00 sec)**
@ -45,9 +46,11 @@ MariaDB [(none)]> create user '*username*'@'*maxscalehost*' identified by '*pass
MariaDB [(none)]> grant SELECT on mysql.user to '*username*'@'*maxscalehost*';
**Query OK, 0 rows affected (0.03 sec)**
```
Additionally, GRANT SELECT on the mysql.db table and SHOW DATABASES privileges are required in order to load databases name and grants suitable for database name authorization.
```
MariaDB [(none)]> GRANT SELECT ON mysql.db TO 'username'@'maxscalehost';
**Query OK, 0 rows affected (0.00 sec)**
@ -55,9 +58,11 @@ MariaDB [(none)]> GRANT SELECT ON mysql.db TO 'username'@'maxscalehost';
MariaDB [(none)]> GRANT SHOW DATABASES ON *.* TO 'username'@'maxscalehost';
**Query OK, 0 rows affected (0.00 sec)**
```
The second user is used to monitored the state of the cluster. This user, which may be the same username as the first, requires permissions to access the various sources of monitoring data. In order to monitor a replication cluster this user must be granted the roles REPLICATION SLAVE and REPLICATION CLIENT
```
MariaDB [(none)]> grant REPLICATION SLAVE on *.* to '*username*'@'*maxscalehost*';
**Query OK, 0 rows affected (0.00 sec)**
@ -65,220 +70,174 @@ MariaDB [(none)]> grant REPLICATION SLAVE on *.* to '*username*'@'*maxscalehost*
MariaDB [(none)]> grant REPLICATION CLIENT on *.* to '*username*'@'*maxscalehost*';
**Query OK, 0 rows affected (0.00 sec)**
```
If you wish to use two different usernames for the two different roles of monitoring and collecting user information then create a different username using the first two steps from above.
## Creating Your MaxScale Configuration
MaxScale configuration is held in an ini file that is located in the file MaxScale.cnf in the directory $MAXSCALE_HOME/etc, if you have installed in the default location then this file is available in /usr/local/mariadb/maxscle/etc/MaxScale.cnf. This is not created as part of the installation process and must be manually created. A template file does exist within this directory that may be use as a basis for your configuration.
MaxScale configuration is held in an ini file that is located in the file maxscale.cnf in the directory /etc. This is not created as part of the installation process and must be manually created. A template file does exist in the `/usr/share/maxscale` folder that can be use as a basis for your configuration.
A global, maxscale, section is included within every MaxScale configuration file; this is used to set the values of various MaxScale wide parameters, perhaps the most important of these is the number of threads that MaxScale will use to execute the code that forwards requests and handles responses for clients.
```
[maxscale]
threads=4
```
Since we are using MySQL Replication and connection routing we want two different ports to which the client application can connect; one that will be directed to the current master within the replication cluster and another that will load balance between the slaves. To achieve this within MaxScale we need to define two services in the ini file; one for the read/write operations that should be executed on the master server and another for connections to one of the slaves. Create a section for each in your MaxScale.ini file and set the type to service, the section names are the names of the services themselves and should be meaningful to the administrator. Names may contain whitespace.
```
[Write Service]
type=service
[Read Service]
type=service
```
The router for these two sections is identical, the readconnroute module, also the services should be provided with the list of servers that will be part of the cluster. The server names given here are actually the names of server sections in the configuration file and not the physical hostnames or addresses of the servers.
```
[Write Service]
type=service
router=readconnroute
servers=dbserv1, dbserv2, dbserv3
[Read Service]
type=service
router=readconnroute
servers=dbserv1, dbserv2, dbserv3
```
In order to instruct the router to which servers it should route we must add router options to the service. The router options are compared to the status that the monitor collects from the servers and used to restrict the eligible set of servers to which that service may route. In our case we use the two options master and slave for our two services.
```
[Write Service]
type=service
router=readconnroute
router_options=master
servers=dbserv1, dbserv2, dbserv3
[Read Service]
type=service
router=readconnroute
router_options=slave
servers=dbserv1, dbserv2, dbserv3
```
The final step in the service sections is to add the username and password that will be used to populate the user data from the database cluster. There are two options for representing the password, either plain text or encrypted passwords may be used. In order to use encrypted passwords a set of keys must be generated that will be used by the encryption and decryption process. To generate the keys use the maxkeys command and pass the name of the secrets file in which the keys are stored.
% maxkeys /usr/local/mariadb-maxscale/etc/.secrets
%
```
maxkeys /var/lib/maxscale/.secrets
```
Once the keys have been created the maxpasswd command can be used to generate the encrypted password.
% maxpasswd plainpassword
```
maxpasswd plainpassword
96F99AA1315BDC3604B006F427DD9484
%
```
The username and password, either encrypted or plain text, are stored in the service section using the user and passwd parameters.
```
[Write Service]
type=service
router=readconnroute
router_options=master
servers=dbserv1, dbserv2, dbserv3
user=maxscale
passwd=96F99AA1315BDC3604B006F427DD9484
[Read Service]
type=service
router=readconnroute
router_options=slave
servers=dbserv1, dbserv2, dbserv3
user=maxscale
passwd=96F99AA1315BDC3604B006F427DD9484
```
This completes the definitions required by the services, however listening ports must be associated with the services in order to allow network connections. This is done by creating a series of listener sections. These sections again are named for the convenience of the administrator and should be of type listener with an entry labeled service which contains the name of the service to associate the listener with. Each service may have multiple listeners.
```
[Write Listener]
type=listener
service=Write Service
[Read Listener]
type=listener
service=Read Service
```
A listener must also define the protocol module it will use for the incoming network protocol, currently this should be the MySQLClient protocol for all database listeners. The listener may then supply a network port to listen on and/or a socket within the file system.
```
[Write Listener]
type=listener
service=Write Service
protocol=MySQLClient
port=4306
socket=/tmp/ClusterMaster
[Read Listener]
type=listener
service=Read Service
protocol=MySQLClient
port=4307
```
An address parameter may be given if the listener is required to bind to a particular network address when using hosts with multiple network addresses. The default behavior is to listen on all network interfaces.
The next stage is the configuration is to define the server information. This defines how to connect to each of the servers within the cluster, again a section is created for each server, with the type set to server, the network address and port to connect to and the protocol to use to connect to the server. Currently the protocol for all database connections in MySQLBackend.
```
[dbserv1]
type=server
address=192.168.2.1
port=3306
protocol=MySQLBackend
[dbserv2]
type=server
address=192.168.2.2
port=3306
protocol=MySQLBackend
[dbserv3]
type=server
address=192.168.2.3
port=3306
protocol=MySQLBackend
```
In order for MaxScale to monitor the servers using the correct monitoring mechanisms a section should be provided that defines the monitor to use and the servers to monitor. Once again a section is created with a symbolic name for the monitor, with the type set to monitor. Parameters are added for the module to use, the list of servers to monitor and the username and password to use when connecting to the the servers with the monitor.
```
[Replication Monitor]
type=monitor
module=mysqlmon
servers=dbserv1, dbserv2, dbserv3
user=maxscale
passwd=96F99AA1315BDC3604B006F427DD9484
```
As with the password definition in the server either plain text or encrypted passwords may be used.
The final stage in the configuration is to add the option service which is used by the maxadmin command to connect to MaxScale for monitoring and administration purposes. This creates a service section and a listener section.
```
[CLI]
type=service
router=cli
[CLI Listener]
type=listener
service=CLI
protocol=maxscaled
address=localhost
port=6603
```
In the case of the example above it should be noted that an address parameter has been given to the listener, this limits connections to maxadmin commands that are executed on the same machine that hosts MaxScale.
@ -286,14 +245,19 @@ In the case of the example above it should be noted that an address parameter ha
Upon completion of the configuration process MaxScale is ready to be started for the first time. This may either be done manually by running the maxscale command or via the service interface.
% maxscale
```
maxscale
```
or
% service maxscale start
```
service maxscale start
```
Check the error log in /usr/local/mariadb-maxscale/log to see if any errors are detected in the configuration file and to confirm MaxScale has been started. Also the maxadmin command may be used to confirm that MaxScale is running and the services, listeners etc have been correctly configured.
Check the error log in /var/log/lomaxscale/ to see if any errors are detected in the configuration file and to confirm MaxScale has been started. Also the maxadmin command may be used to confirm that MaxScale is running and the services, listeners etc have been correctly configured.
```
% maxadmin -pmariadb list services
Services.
@ -349,6 +313,7 @@ CLI | maxscaled | localhost | 6603 | Running
---------------------+--------------------+-----------------+-------+--------
%
```
MaxScale is now ready to start accepting client connections and routing them to the master or slaves within your cluster. Other configuration options are available that can alter the criteria used for routing, these include monitoring the replication lag within the cluster and routing only to slaves that are within a predetermined delay from the current master or using weights to obtain unequal balancing operations. These options may be found in the MaxScale Configuration Guide. More detail on the use of maxadmin can be found in the document "MaxAdmin - The MaxScale Administration & Monitoring Client Application".
MaxScale is now ready to start accepting client connections and routing them to the master or slaves within your cluster. Other configuration options are available that can alter the criteria used for routing, these include monitoring the replication lag within the cluster and routing only to slaves that are within a predetermined delay from the current master or using weights to obtain unequal balancing operations. These options may be found in the MaxScale Configuration Guide. More detail on the use of maxadmin can be found in the document [MaxAdmin - The MaxScale Administration & Monitoring Client Application](Administration-Tutorial.md).

6
Documentation/Tutorials/MySQL-Replication-Read-Write-Splitting-Tutorial.md
View File

@ -70,7 +70,7 @@ If you wish to use two different usernames for the two different roles of monito
## Creating Your MaxScale Configuration
MaxScale configuration is held in an ini file that is located in the file MaxScale.cnf in the directory $MAXSCALE_HOME/etc, if you have installed in the default location then this file is available in /usr/local/mariadb-maxscale/etc/MaxScale.cnf. This is not created as part of the installation process and must be manually created. A template file does exist within this directory that may be use as a basis for your configuration.
MaxScale configuration is held in an ini file that is located in the file maxscale.cnf in the directory /etc, if you have installed in the default location then this file is available in /etc/maxscale.cnf. This is not created as part of the installation process and must be manually created. A template file does exist within the /usr/share/maxscale directory that may be use as a basis for your configuration.
A global, maxscale, section is included within every MaxScale configuration file; this is used to set the values of various MaxScale wide parameters, perhaps the most important of these is the number of threads that MaxScale will use to execute the code that forwards requests and handles responses for clients.
@ -96,7 +96,7 @@ servers=dbserv1, dbserv2, dbserv3
The final step in the service sections is to add the username and password that will be used to populate the user data from the database cluster. There are two options for representing the password, either plain text or encrypted passwords may be used. In order to use encrypted passwords a set of keys must be generated that will be used by the encryption and decryption process. To generate the keys use the maxkeys command and pass the name of the secrets file in which the keys are stored.
% maxkeys /usr/local/mariadb-maxscale/etc/.secrets
% maxkeys /var/lib/maxscale/.secrets
%
@ -226,7 +226,7 @@ or
% service maxscale start
Check the error log in /usr/local/mariadb-maxscale/log to see if any errors are detected in the configuration file and to confirm MaxScale has been started. Also the maxadmin command may be used to confirm that MaxScale is running and the services, listeners etc have been correctly configured.
Check the error log in /var/log/maxscale to see if any errors are detected in the configuration file and to confirm MaxScale has been started. Also the maxadmin command may be used to confirm that MaxScale is running and the services, listeners etc have been correctly configured.
% maxadmin -pmariadb list services

6
Documentation/Tutorials/Nagios-Plugins.md
View File

@ -44,7 +44,7 @@ In order to use these scripts on your Nagios Server, you need to copy them from
MaxScale must be configured with 'maxscaled' protocol for the administration interface:
Example of MaxScale.cnf file:
Example of maxscale.cnf file:
[AdminInterface]
type=service
@ -73,9 +73,9 @@ and add (just after localhost.cfg or commnads.cfg)
- modify server IP address in server1.cfg, pointing to MaxScale server
- maxadmin executable must be in the nagios server
- default MaxScale AdminInterface port is 6603
- default maxadmin executable path is /usr/local/mariadb-maxscale/bin/maxadmin
- default maxadmin executable path is /usr/bin/maxadmin
It can be changed by -m option
- maxadmin executable could be copied from an existing maxscale installation (default location is /usr/local/mariadb-maxscale/bin/maxadmin)
- maxadmin executable could be copied from an existing maxscale installation (default location is /usr/bin/maxadmin)
This example shows configuration that needs to be done on Nagios server in order to communicate to MaxScale server that is running on host server1.
In this example we are using the check_maxscale_resource as the check command

2
Documentation/Tutorials/RabbitMQ-Setup-And-MaxScale-Integration.md
View File

@ -193,7 +193,7 @@ This generates RPM or DEB packages based on your system. These packages can then
## Step 5 - Configure new applications
The new filter needs to be configured in MaxScale.cnf.
The new filter needs to be configured in maxscale.cnf.
[Test Service]
type=service

4
Documentation/Tutorials/Replication-Proxy-Binlog-Router-Tutorial.md
View File

@ -28,7 +28,7 @@ Using MaxScale as a replication proxy is much the same as using MaxScale as a pr
## Service Configuration
As with any MaxScale configuration a good starting point is with the service definition with the MaxScale.cnf file. The service requires a name which is the section name in the ini file, a type parameter with a value of service and the name of the router plugin that should be loaded. In the case of replication proxies this router name is binlogrouter.
As with any MaxScale configuration a good starting point is with the service definition with the maxscale.cnf file. The service requires a name which is the section name in the ini file, a type parameter with a value of service and the name of the router plugin that should be loaded. In the case of replication proxies this router name is binlogrouter.
[Replication]
@ -84,7 +84,7 @@ This optional parameter allows for the administrator to define the number of the
### binlogdir
This parameter allows the location that MaxScale uses to store binlog files to be set. If this parameter is not set to a directory name then MaxScale will store the binlog files in the directory $MAXSCALE_HOME/<Service Name>.
This parameter allows the location that MaxScale uses to store binlog files to be set. If this parameter is not set to a directory name then MaxScale will store the binlog files in the directory /var/cache/maxscale/<Service Name>.
### heartbeat

4
Documentation/Tutorials/Simple-Sharding-Tutorial.md
View File

@ -32,7 +32,7 @@ Upon successful completion of the installation command you will have MaxScale in
### Creating Your MaxScale Configuration
The first step in the creation of your MaxScale.cnf file is to define the global maxscale section. This section configures the number of threads MaxScale uses. A good rule of thumb is to use at most as may threads as you have CPUs. MaxScale uses few threads for internal operations so one or two threads less than the maximum should be enough.
The first step in the creation of your maxscale.cnf file is to define the global maxscale section. This section configures the number of threads MaxScale uses. A good rule of thumb is to use at most as may threads as you have CPUs. MaxScale uses few threads for internal operations so one or two threads less than the maximum should be enough.
```
[maxscale]
@ -92,7 +92,7 @@ After this we have a fully working configuration and we can move on to starting
Upon completion of the configuration process MaxScale is ready to be started . This may either be done manually by running the maxscale command or via the service interface. The service scripts are located in the `/etc/init.d/` folder and are accessible through both the `service` and `systemctl` commands.
After starting MaxScale check the error log in /usr/local/mariadb-maxscale/log to see if any errors are detected in the configuration file. Also the maxadmin command may be used to confirm that MaxScale is running and the services, listeners etc have been correctly configured.
After starting MaxScale check the error log in /var/log/maxscale to see if any errors are detected in the configuration file. Also the maxadmin command may be used to confirm that MaxScale is running and the services, listeners etc have been correctly configured.
MaxScale is now ready to start accepting client connections and routing them. Queries are routed to the right servers based on the database they target and switching between the shards is seamless since MaxScale keeps the session state intact between servers.

24
Documentation/Upgrading-To-MaxScale-1.2.0.md Normal file
View File

@ -0,0 +1,24 @@
# 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
Before starting the upgrade, we recommend you back up your configuration, log and binary log files in `/usr/local/mariadb-maxscale/`.
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](http://www.pathname.com/fhs/) 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.

69
Documentation/maxscale.1 Normal file
View File

@ -0,0 +1,69 @@
.TH maxscale 1
.SH NAME
maxscale - The intelligent proxy
.SH SYNOPSIS
.B maxscale
[\fIOPTIONS...\fR]
.SH DESCRIPTION
The MariaDB Corporation 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 transparently to the applications. In addition it provides
a highly scalable and flexible architecture, with plugin components to
support different protocols and routing decisions.
.SH OPTIONS
.TP
.BR "-d, --nodaemon"
Run MaxScale in the terminal process
.TP
.BR -f " \fIFILE\fB, --config=\fIFILE\fR"
Relative or absolute pathname of MaxScale configuration file to load.
.TP
.BR -l "[\fIfile|shm\fB], --log=[\fIfile|shm\fB]"
Log trace and debug logs to file or shared memory. The debug and trace logs are disabled by default and if enabled, will log to shared memory.
.TP
.BR -L " \fIPATH\fB, --logdir=\fIPATH\fB"
Path to log file directory.
.TP
.BR -D " \fIPATH\fB, --datadir=\fIPATH\fB"
Path to data directory. This is where the embedded mysql tables are stored in addition to other MaxScale specific data.
.TP
.BR -C " \fIPATH\fB, --configdir=\fIPATH\fB"
Path to configuration file directory. MaxScale will look for the \fImaxscale.cnf\fR file from this folder.
.TP
.BR -B " \fIPATH\fB, --libdir=\fIPATH\fB"
Path to module directory. Modules are only searched from this folder.
.TP
.BR -A " \fIPATH\fB, --cachedir=\fIPATH\fB"
Path to cache directory. This is where MaxScale stores cached authentication data.
.TP
.BR -P " \fIPATH\fB, --piddir=\fIPATH\fB"
Location of MaxScale's PID file.
.TP
.BR -U " \fIUSER\fB, --user=\fIUSER\fB"
Run MaxScale as another user. The user ID and group ID of this user are used to run MaxScale.
.TP
.BR -s " [\fIyes\fB|\fIno\fB], --syslog=[\fIyes\fB|\fIno\fB]"
Log messages to syslog.
.TP
.BR -S " [\fIyes\fB|\fIno\fB], \fB--maxscalelog=[\fIyes\fB|\fIno\fB]"
Log messages to MaxScale's own log files.
.TP
.BR "-v, --version"
Print version information and exit.
.TP
.BR "-?, --help"
Show the help information for MaxScale and exit.
.SH EXAMPLES
Tutorials on GitHub:
.UR https://github.com/mariadb-corporation/MaxScale/blob/master/Documentation/Documentation-Contents.md#tutorials
.UE
.SH SEE ALSO
The MaxScale documentation on GitHub:
.UR https://github.com/mariadb-corporation/MaxScale/blob/master/Documentation/Documentation-Contents.md
.UE