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

Merge branch '2.1' into develop

Browse Source
This commit is contained in:
Johan Wikman 2017-04-27 09:11:02 +03:00
commit deb11ae6eb
51 changed files with 2233 additions and 3313 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
Documentation/About/Limitations.md
View File

@ -10,6 +10,39 @@ In versions 2.1.2 and earlier, the configuration files are limited to 1024
characters per line. This limitation was increased to 16384 characters in
MaxScale 2.1.3.
## Security limitiations
### MariaDB 10.2
The parser of MaxScale correctly parses `WITH` statements, but fails to
collect columns, functions and tables used in the `SELECT` defining the
`WITH` clause.
Consequently, the database firewall will **not** block `WITH` statements
where the `SELECT` of the `WITH` clause refers to forbidden columns.
## Prepared Statements
For its proper functioning, MaxScale needs in general to be aware of the
transaction state and _autocommit_ mode. In order to be that, MaxScale
parses statements going through it.
However, if a transaction is commited or rolled back, or the autocommit
mode is changed using a prepared statement, MaxScale will miss that and its
internal state will be incorrect, until the transaction state or autocommit
mode is changed using an explicit statement.
For instance, after the following sequence of commands, MaxScale will still
think _autocommit_ is on:
```
set autocommit=1
PREPARE hide_autocommit FROM "set autocommit=0"
EXECUTE hide_autocommit
```
To ensure that MaxScale functions properly, do not commit or rollback a
transaction or change the autocommit mode using a prepared statement.
## Protocol limitations
### Limitations with MySQL Protocol support (MySQLClient)
@ -85,6 +118,17 @@ Read queries are routed to the master server in the following situations:
* if there are multiple statements inside one query e.g. `INSERT INTO ... ; SELECT
LAST_INSERT_ID();`
#### JDBC Batched Statements
Readwritesplit does not support execution of JDBC batched statements with
non-INSERT statements mixed in it. This is caused by the fact that
readwritesplit expects that the protocol is idle before another command is sent.
Most clients conform to this expectation but some JDBC drivers send multiple
requests without waiting for the protocol to be idle. If you are using the
MariaDB Connector/J, add `useBatchMultiSend=false` to the JDBC connection string
to disable batched statement execution.
#### Backend write timeout handling
The backend connections opened by readwritesplit will not be kept alive if they

100
Documentation/About/Support-for-10.2.md Normal file
View File

@ -0,0 +1,100 @@
# Support for MariaDB 10.2
MariaDB 10.2 introduces a fair amount of new
[features](https://mariadb.com/kb/en/mariadb/what-is-mariadb-102/).
In the following will be explained what impact some of those features have,
when used together with MaxScale 2.1.
## [Window Functions](https://mariadb.com/kb/en/mariadb/window-functions/)
The parser of MariaDB MaxScale has not been extended with the window
function syntax (the `OVER` keyword is not recognized) and hence statements
using window functions will not be completely parsed.
Since the database firewall filter will block all statements that
cannot be completely parsed, all statements that use window functions
will be blocked, if the database firewall filter is used.
Otherwise the statements will be routed correctly.
## [SHOW CREATE USER](https://mariadb.com/kb/en/mariadb/show-create-user/)
Cannot be completely parsed by the MaxScale parser and hence will be
blocked by the database firewall filter, if it is used.
Otherwise the statements will be routed correctly.
## [CREATE USER](https://mariadb.com/kb/en/mariadb/create-user/)
The new options are not parsed by the MaxScale parser and hence any
statements using those will be blocked by the database firewall filter,
if it is used.
Otherwise the statements will be routed correctly.
## [ALTER USER](https://mariadb.com/kb/en/mariadb/alter-user/)
The new options are not parsed by the MaxScale parser and hence any
statements using those will be blocked by the database firewall filter,
if it is used.
Otherwise the statements will be routed correctly.
## [WITH](https://mariadb.com/kb/en/mariadb/with/)
The MaxScale parser correctly parses `WITH` statements such as
```
WITH t AS (SELECT a FROM t1 WHERE b >= 'c')
SELECT * FROM t2,t WHERE t2.c=t.a;
```
,
```
SELECT t1.a,t1.b FROM t1,t2
WHERE t1.a>t2.c AND
t2.c in (WITH t as (SELECT * FROM t1 WHERE t1.a<5)
SELECT t2.c FROM t2,t WHERE t2.c=t.a);
```
and
```
WITH engineers AS (
SELECT * FROM employees WHERE dept IN ('Development','Support')
)
SELECT * FROM engineers E1
WHERE NOT EXISTS (SELECT 1
FROM engineers E2
WHERE E2.country=E1.country
AND E2.name <> E1.name);
```
.
However, the MaxScale parser fails to collect columns and table names
from the `SELECT` of the `WITH` clause and consequently the database
firewall filter will **NOT** be able to block `WITH` statements where
the `SELECT` of the `WITH` clause refers to to forbidden columns.
## [CHECK CONSTRAINT](https://mariadb.com/kb/en/mariadb/constraint/)
The new options are not parsed by the MaxScale parser and hence any
statements using those will be blocked by the database firewall filter,
if it is used.
Otherwise the statements will be routed correctly.
## [DEFAULT with expressions](https://mariadb.com/kb/en/mariadb/create-table/#default)
Parsed and handled correctly.
## [EXECUTE IMMEDIATE](https://mariadb.com/kb/en/mariadb/execute-immediate/)
An `EXECUTE IMMEDIATE` statement will only be partially parsed, which means
that such statements will be blocked by the database firewall filter,
if it is used.
## [JSON functions](https://mariadb.com/kb/en/mariadb/json-functions/)
The MaxScape parser treats them as any other function.
However, as the parser is not aware of which JSON functions are strictly
_read-only_ any statement using a JSON function will always be routed to
_master_.

2
Documentation/Authenticators/GSSAPI-Authenticator.md
View File

@ -19,7 +19,7 @@ the _kadmin_ or _kadmin.local_ tools.
kadmin.local -q "addprinc -nokey mariadb/example.com@EXAMPLE.COM"
```
The _-nokey_ option will make the principal a passwordless one. This allows the
The `-nokey` option will make the principal a passwordless one. This allows the
_maxscale_ user to acquire a ticket for it without a password being prompted.
The next step is to export this principal into the Kerberos keytab file.

3
Documentation/Changelog.md
View File

@ -1,4 +1,4 @@
#Changelog
# Changelog
## MariaDB MaxScale 2.1
* MariaDB MaxScale is licensed under MariaDB BSL 1.1.
@ -21,6 +21,7 @@
* MaxScale now supports IPv6
For more details, please refer to:
* [MariaDB MaxScale 2.1.3 Release Notes](Release-Notes/MaxScale-2.1.3-Release-Notes.md)
* [MariaDB MaxScale 2.1.2 Release Notes](Release-Notes/MaxScale-2.1.2-Release-Notes.md)
* [MariaDB MaxScale 2.1.1 Release Notes](Release-Notes/MaxScale-2.1.1-Release-Notes.md)
* [MariaDB MaxScale 2.1.0 Release Notes](Release-Notes/MaxScale-2.1.0-Release-Notes.md)

24
Documentation/Design-Documents/Plugin-development-guide.md
View File

@ -8,19 +8,19 @@ on, so the APIs of these two are discussed in detail.
## Table of Contents
1. [Introduction](#introduction)
* [Module categories](#module-categories)
* [Common definitions and headers](#common-definitions-and-headers)
1. [Module information container](#module-information-container)
* [Module API](#module-api)
1. [Overview](#overview)
* [General module management](#general-module-management)
* [Protocol](#protocol)
* [Authenticator](#authenticator)
* [Filter and Router](#filter-and-router)
* [Monitor](#monitor)
* [Introduction](#introduction)
* [Module categories](#module-categories)
* [Common definitions and headers](#common-definitions-and-headers)
* [Module information container](#module-information-container)
* [Module API](#module-api)
* [Overview](#overview)
* [General module management](#general-module-management)
* [Protocol](#protocol)
* [Authenticator](#authenticator)
* [Filter and Router](#filter-and-router)
* [Monitor](#monitor)
* [Compiling, installing and running](#compiling-installing-and-running)
1. [Hands-on example: RoundRobinRouter](#hands-on-example-roundrobinrouter)
* [Hands-on example: RoundRobinRouter](#hands-on-example-roundrobinrouter)
* [Summary and conclusion](#summary-and-conclusion)
## Introduction

2
Documentation/Design-Documents/SchemaRouter-technical.md
View File

@ -1,4 +1,4 @@
#SchemaRouter Router - Technical Overview
# SchemaRouter Router - Technical Overview
This document is designed with a developer's point-of-view in mind. It explains the lifecycle of the module and details about its internal workings. It refers to the source code which can be found at [GitHub](https://github.com/mariadb-corporation/MaxScale).

50
Documentation/Documentation-Contents.md
View File

@ -1,12 +1,10 @@
[Search page for MariaDB MaxScale Documentation](http://mariadb-corporation.github.io/MaxScale/Search/)
# Contents
## About MariaDB MaxScale
- [About MariaDB MaxScale](About/About-MaxScale.md)
- [Release Notes](Release-Notes/MaxScale-2.1.1-Release-Notes.md)
- [Release Notes](Release-Notes/MaxScale-2.1.3-Release-Notes.md)
- [Changelog](Changelog.md)
- [Limitations](About/Limitations.md)
@ -18,13 +16,12 @@
## Upgrading MariaDB MaxScale
- [Upgrading MariaDB MaxScale from 2.0 to 2.1](Upgrading/Upgrading-To-MaxScale-2.1.md)
- [Upgrading MariaDB MaxScale from 1.4 to 2.0](Upgrading/Upgrading-To-MaxScale-2.0.md)
## Reference
- [MaxAdmin - Admin Interface](Reference/MaxAdmin.md)
- [How Errors are Handled in MariaDB 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)
- [MaxBinlogCheck](Reference/MaxBinlogCheck.md)
- [MaxScale REST API](REST-API/API.md)
@ -39,19 +36,25 @@ The main tutorial for MariaDB MaxScale consist of setting up MariaDB MaxScale fo
These tutorials are for specific use cases and module combinations.
- [Administration Tutorial](Tutorials/Administration-Tutorial.md)
- [Avro Router Tutorial](Tutorials/Avrorouter-Tutorial.md)
- [Filter Tutorial](Tutorials/Filter-Tutorial.md)
- [MariaDB MaxScale Information Schema Tutorial](Tutorials/MaxScale-Information-Schema.md)
- [Galera Cluster Connection Routing Tutorial](Tutorials/Galera-Cluster-Connection-Routing-Tutorial.md)
- [Galera Gluster Read Write Splitting Tutorial](Tutorials/Galera-Cluster-Read-Write-Splitting-Tutorial.md)
- [MySQL Cluster Setup](Tutorials/MySQL-Cluster-Setup.md)
- [Replication Proxy with the Binlog Router Tutorial](Tutorials/Replication-Proxy-Binlog-Router-Tutorial.md)
- [RabbitMQ Setup and MariaDB MaxScale Integration Tutorial](Tutorials/RabbitMQ-Setup-And-MaxScale-Integration.md)
- [MySQL Replication Connection Routing Tutorial](Tutorials/MySQL-Replication-Connection-Routing-Tutorial.md)
- [MySQL Replication Read Write Splitting Tutorial](Tutorials/MySQL-Replication-Read-Write-Splitting-Tutorial.md)
- [MariaDB MaxScale Information Schema Tutorial](Tutorials/MaxScale-Information-Schema.md)
- [Notification Service](Tutorials/Notification-Service.md)
- [RabbitMQ and Tee Filter Data Archiving Tutorial](Tutorials/RabbitMQ-And-Tee-Archiving.md)
- [RabbitMQ Setup and MariaDB MaxScale Integration Tutorial](Tutorials/RabbitMQ-Setup-And-MaxScale-Integration.md)
- [Replication Proxy with the Binlog Router Tutorial](Tutorials/Replication-Proxy-Binlog-Router-Tutorial.md)
- [Simple Schema Sharding Tutorial](Tutorials/Simple-Sharding-Tutorial.md)
Here are tutorials on monitoring and managing MariaDB MaxScale in cluster environments.
- [Nagios Plugins for MariaDB MaxScale Tutorial](Tutorials/Nagios-Plugins.md)
- [MariaDB MaxScale HA with Corosync-Pacemaker](Tutorials/MaxScale-HA-with-Corosync-Pacemaker.md)
- [MariaDB MaxScale HA with Lsyncd](Tutorials/MaxScale-HA-with-lsyncd.md)
- [Nagios Plugins for MariaDB MaxScale Tutorial](Tutorials/Nagios-Plugins.md)
## Routers
@ -59,32 +62,36 @@ The routing module is the core of a MariaDB MaxScale service. The router documen
contains all module specific configuration options and detailed explanations
of their use.
- [Read Write Split](Routers/ReadWriteSplit.md)
- [Read Connection Router](Routers/ReadConnRoute.md)
- [Schemarouter](Routers/SchemaRouter.md)
- [Binlogrouter](Routers/Binlogrouter.md)
- [Avrorouter](Routers/Avrorouter.md)
- [Binlogrouter](Routers/Binlogrouter.md)
- [HintRouter](Routers/HintRouter.md)
- [Read Connection Router](Routers/ReadConnRoute.md)
- [Read Write Split](Routers/ReadWriteSplit.md)
- [Schemarouter](Routers/SchemaRouter.md)
There are also two diagnostic routing modules. The CLI is for MaxAdmin and
the Debug CLI client for Telnet.
- [CLI](Routers/CLI.md)
- [Debug CLI](Routers/Debug-CLI.md)
## Filters
Here are detailed documents about the filters MariaDB 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.
- [Cache](Filters/Cache.md)
- [Consistent Critical Read Filter](Filters/CCRFilter.md)
- [Database Firewall Filter](Filters/Database-Firewall-Filter.md)
- [Insert Stream Filter](Filters/Insert-Stream-Filter.md)
- [Luafilter](Filters/Luafilter.md)
- [Masking Filter](Filters/Masking.md)
- [Maxrows Filter](Filters/Maxrows.md)
- [Named Server Filter](Filters/Named-Server-Filter.md)
- [Query Log All](Filters/Query-Log-All-Filter.md)
- [RabbitMQ Filter](Filters/RabbitMQ-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)
- [Luafilter](Filters/Luafilter.md)
- [Insert Stream Filter](Filters/Insert-Stream-Filter.md)
- [Transaction Performance Monitoring Filter](Filters/Transaction-Performance-Monitoring-Filter.md)
## Monitors
@ -94,9 +101,10 @@ Common options for all monitor modules.
Module specific documentation.
- [MySQL Monitor](Monitors/MySQL-Monitor.md)
- [Aurora Monitor](Monitors/Aurora-Monitor.md)
- [Galera Monitor](Monitors/Galera-Monitor.md)
- [Multi-Master Monitor](Monitors/MM-Monitor.md)
- [MySQL Monitor](Monitors/MySQL-Monitor.md)
- [MySQL Cluster Monitor](Monitors/NDB-Cluster-Monitor.md)
## Protocols
@ -121,8 +129,6 @@ document.
## Design Documents
- [Core Objects Design (in development)](http://mariadb-corporation.github.io/MaxScale/Design-Documents/core-objects-html-docs)
- [Binlog Router Design (in development)](http://mariadb-corporation.github.io/MaxScale/Design-Documents/binlog-router-html-docs)
- [DCB States (to be replaced in StarUML)](Design-Documents/DCB-States.pdf)
- [Schema Sharding Router Technical Documentation](Design-Documents/SchemaRouter-technical.md)
- [Plugin development guide](Design-Documents/Plugin-development-guide.md)

20
Documentation/Filters/CCRFilter.md
View File

@ -7,10 +7,10 @@ This filter was introduced in MariaDB MaxScale 2.1.
The Consistent Critical Read (CCR) filter allows consistent critical reads to be
done through MaxScale while still allowing scaleout of non-critical reads.
When the filter detects a statement that would modify the database, it attaches a
routing hint to all following statements. This routing hint guides the routing
module to route the statement to the master server where data is guaranteed to be
in a up-to-date state.
When the filter detects a statement that would modify the database, it attaches
a routing hint to all following statements. This routing hint guides the routing
module to route the statement to the master server where data is guaranteed to
be in an up-to-date state.
## Filter Options
@ -42,8 +42,8 @@ _time_. Once the timer has elapsed, all statements are routed normally. If a new
data modifying SQL statement is processed within the time window, the timer is
reset to the value of _time_.
Enabling this parameter in combination with the _count_ parameter causes both the
time window and number of queries to be inspected. If either of the two
Enabling this parameter in combination with the _count_ parameter causes both
the time window and number of queries to be inspected. If either of the two
conditions are met, the query is re-routed to the master.
### `count`
@ -51,8 +51,8 @@ conditions are met, the query is re-routed to the master.
The number of SQL statements to route to master after detecting a data modifying
SQL statement. This feature is disabled by default.
After processing a data modifying SQL statement, a counter is set to the value of
_count_ and all statements are routed to the master. Each executed statement
After processing a data modifying SQL statement, a counter is set to the value
of _count_ and all statements are routed to the master. Each executed statement
after a data modifying SQL statement cause the counter to be decremented. Once
the counter reaches zero, the statements are routed normally. If a new data
modifying SQL statement is processed, the counter is reset to the value of
@ -61,8 +61,8 @@ _count_.
### `match`
An optional parameter that can be used to control which statements trigger the
statement re-routing. The parameter value is a regular expression that is used to
match against the SQL text. Only non-SELECT statements are inspected.
statement re-routing. The parameter value is a regular expression that is used
to match against the SQL text. Only non-SELECT statements are inspected.
```
match=.*INSERT.*

6
Documentation/Filters/Cache.md
View File

@ -622,6 +622,9 @@ storage=storage_inmemory
## `storage_rocksdb`
This storage module is not built by default and is not included in the
MariaDB MaxScale packages.
This storage module uses RocksDB database for storing the cached data. The
directory where the RocksDB database will be created is by default created
into the _MaxScale cache_ directory, which usually is not on a RAM disk. For
@ -651,7 +654,8 @@ created, under which the actual instance specific cache directories are created.
Specifies whether RocksDB should collect statistics that later can be queried
using `maxadmin`. It should be noted, though, that collecting RocksDB statistics
is not without a cost. From the [RocksDB Documentation](https://github.com/facebook/rocksdb/wiki/Statistics)
is not without a cost.
From the [RocksDB Documentation](https://github.com/facebook/rocksdb/wiki/Statistics)
_The overhead of statistics is usually small but non-negligible. We usually
observe an overhead of 5%-10%._

17
Documentation/Filters/RabbitMQ-Consumer-Client.md
View File

@ -1,8 +1,10 @@
#RabbitMQ Consumer Client
# RabbitMQ Consumer Client
## Overview
This utility tool is used to read messages from a RabbitMQ broker sent by the [RabbitMQ Filter](RabbitMQ-Filter.md) and forward these messages into an SQL database as queries.
This utility tool is used to read messages from a RabbitMQ broker sent by the
[RabbitMQ Filter](RabbitMQ-Filter.md) and forward these messages into an
SQL database as queries.
## Command Line Arguments
@ -14,7 +16,9 @@ The **RabbitMQ Consumer Client** only has one command line argument.
## Installation
To install the RabbitMQ Consumer Client you ca either use the provided packages or you can compile it from source code. The source code is included as a part of the MariaDB MaxScale source code and can be found in the `rabbitmq_consumer` folder.
To install the RabbitMQ Consumer Client you can either use the provided packages
or you can compile it from source code. The source code is included as a part of the
MariaDB MaxScale source code and can be found in the `rabbitmq_consumer` folder.
## Building from source
@ -48,9 +52,12 @@ include and library directories 'in buildvars.inc'
## Configuration
The consumer client requires that the `consumer.cnf` configuration file is either be present in the `etc` folder of the installation directory or in the folder specified by the `-c` argument.
The consumer client requires that the `consumer.cnf` configuration file is either
be present in the `etc` folder of the installation directory or in the folder
specified by the `-c` argument.
The source broker, the destination database and the message log file can be configured into the separate `consumer.cnf` file.
The source broker, the destination database and the message log file can be
configured into the separate `consumer.cnf` file.
| Option | Description |
|-----------|---------------------------------------------|

26
Documentation/Filters/RabbitMQ-Filter.md
View File

@ -1,13 +1,26 @@
#RabbitMQ Filter
# RabbitMQ Filter
## Overview
This filter is designed to extract queries and transform them into a canonical form e.g. `INSERT INTO database.table VALUES ("John Doe", "Downtown",100,50.0);` turns into `INSERT INTO database.table VALUES ("?", "?",?,?);`. The filter pushes these canonicalized queries and their replies in to a RabbitMQ broker where they can later be retrieved. The retrieval can be done with your own application or the [RabbitMQ Consumer Client](RabbitMQ-Consumer-Client.md) utility tool, which reads the messages from the broker and sends the contents of those messages as SQL queries to a database.
This filter is designed to extract queries and transform them into a canonical
form e.g. `INSERT INTO database.table VALUES ("John Doe", "Downtown",100,50.0);`
turns into `INSERT INTO database.table VALUES ("?", "?",?,?);`. The filter
pushes these canonized queries and their replies into a RabbitMQ broker where
they can later be retrieved from. The retrieval can be done with a custom
application or the [RabbitMQ Consumer Client](RabbitMQ-Consumer-Client.md)
utility tool, which reads the messages from the broker and sends the contents of
those messages as SQL queries to a database.
## Configuration
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 configuration block for the **mqfilter** requires the minimal filter options
in its section within the MaxScale configuration file. 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 an mqfilter configuration used for actual logging
of queries to a RabbitMQ broker on a different host.
```
[RabbitMQ]
@ -41,7 +54,10 @@ The mqfilter filter does not support any filter options.
### Filter Parameters
The RabbitMQ filter has parameters to control which queries are logged based on either the attributes of the user or the query itself. These can be combined to to only log queries targeting a certain table in a certain database from a certain user from a certain network address.
The RabbitMQ filter has parameters to control which queries are logged based on
either the attributes of the user or the query itself. These can be combined to
to only log queries targeting a certain table in a certain database from a
certain user from a certain network address.
Option | Description | Accepted Values | Default |

51
Documentation/Filters/Tee-Filter.md
View File

@ -2,11 +2,16 @@
## Overview
The tee filter is a filter module for MariaDB MaxScale is a "plumbing" fitting in the MariaDB 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 MariaDB MaxScale.
The tee filter is a "plumbing" fitting in the MariaDB MaxScale filter toolkit.
It can be used in a filter pipeline of a service to make copies of requests from
the client and send the copies to another service within MariaDB MaxScale.
## Configuration
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.
The configuration block for the TEE filter requires the minimal filter
parameters in its section within the MaxScale configuration file. The service to
send the duplicates to must be defined. Currently the tee filter does not
support multi-statements.
```
[DataMartFilter]
@ -41,31 +46,45 @@ options=case,extended
## Filter Parameters
The tee filter requires a mandatory parameter to define the service to replicate statements to and accepts a number of optional parameters.
The tee filter requires a mandatory parameter to define the service to replicate
statements to and accepts a number of optional parameters.
### Match
An optional parameter that can be used to limit the queries that will be replicated by the tee filter. The parameter value is a regular expression that is used to match against the SQL text. Only SQL statements that matches the text passed as the value of this parameter will be sent to the service defined in the filter section.
An optional parameter used to limit the queries that will be replicated by the
tee filter. The parameter value is a regular expression that is used to match
against the SQL text. Only SQL statements that matches the text passed as the
value of this parameter will be sent to the service defined in the filter
section.
```
match=insert.*into.*order*
```
All regular expressions are evaluated with the option to ignore the case of the text, therefore a match option of select will match both insert, INSERT and any form of the word with upper or lowercase characters.
All regular expressions are evaluated with the option to ignore the case of the
text, therefore a match option of select will match both insert, INSERT and any
form of the word with upper or lowercase characters.
### Exclude
An optional parameter that can be used to limit the queries that will be replicated by the tee filter. The parameter value is a regular expression that is used to match against the SQL text. SQL statements that match the text passed as the value of this parameter will be excluded from the replication stream.
An optional parameter used to limit the queries that will be replicated by the
tee filter. The parameter value is a regular expression that is used to match
against the SQL text. SQL statements that match the text passed as the value of
this parameter will be excluded from the replication stream.
```
exclude=select
```
All regular expressions are evaluated with the option to ignore the case of the text, therefore an exclude option of select will exclude statements that contain both select, SELECT or any form of the word with upper or lowercase characters.
All regular expressions are evaluated with the option to ignore the case of the
text, therefore an exclude option of select will exclude statements that contain
both select, SELECT or any form of the word with upper or lowercase characters.
### Source
The optional source parameter defines an address that is used to match against the address from which the client connection to MariaDB MaxScale originates. Only sessions that originate from this address will be replicated.
The optional source parameter defines an address that is used to match against
the address from which the client connection to MariaDB MaxScale originates.
Only sessions that originate from this address will be replicated.
```
source=127.0.0.1
@ -73,7 +92,9 @@ 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 MariaDB MaxScale originates. Only sessions that are connected using this username are replicated.
The optional user parameter defines a user name that is used to match against
the user from which the client connection to MariaDB MaxScale originates. Only
sessions that are connected using this username are replicated.
```
user=john
@ -83,9 +104,17 @@ user=john
### Example 1 - Replicate all inserts into the orders table
Assume an order processing system that has a table called orders. You also have another database server, the datamart server, that requires all inserts into orders to be replicated to it. Deletes and updates are not however required.
Assume an order processing system that has a table called orders. You also have
another database server, the datamart server, that requires all inserts into
orders to be replicated to it. Deletes and updates are not, however, required.
Set up a service in MariaDB MaxScale, called Orders, to communicate with the order processing system with the tee filter applied to it. Also set up a service to talk the datamart server, using the DataMart service. The tee filter would have as it’s service entry the DataMart service, by adding a match parameter of "insert into orders" would then result in all requests being sent to the order processing system, and insert statements that include the orders table being additionally sent to the datamart server.
Set up a service in MariaDB MaxScale, called Orders, to communicate with the
order processing system with the tee filter applied to it. Also set up a service
to talk to the datamart server, using the DataMart service. The tee filter would
have as it’s service entry the DataMart service, by adding a match parameter of
"insert into orders" would then result in all requests being sent to the order
processing system, and insert statements that include the orders table being
additionally sent to the datamart server.
```
[Orders]

44
Documentation/Filters/Transaction-Performance-Monitoring-Filter.md
View File

@ -2,11 +2,17 @@
## Overview
The Transaction Performance Monitoring (TPM) filter is a filter module for MaxScale that monitors every SQL statement that passes through the filter. The filter groups a series of SQL statements into a transaction by detecting 'commit' or 'rollback' statements. It logs all committed transactions with necessary information, such as timestamp, client, SQL statements, latency, etc., which can be used later for transaction performance analysis.
The Transaction Performance Monitoring (TPM) filter is a filter module for MaxScale
that monitors every SQL statement that passes through the filter.
The filter groups a series of SQL statements into a transaction by detecting
'commit' or 'rollback' statements. It logs all committed transactions with necessary
information, such as timestamp, client, SQL statements, latency, etc., which
can be used later for transaction performance analysis.
## Configuration
The configuration block for the TPM filter requires the minimal filter options in it's section within the maxscale.cnf file, stored in /etc/maxscale.cnf.
The configuration block for the TPM filter requires the minimal filter
options in it's section within the maxscale.cnf file, stored in /etc/maxscale.cnf.
```
[MyLogFilter]
@ -32,7 +38,8 @@ The TPM filter accepts a number of optional parameters.
### Filename
The name of the output file created for performance logging. The default filename is **tpm.log**.
The name of the output file created for performance logging.
The default filename is **tpm.log**.
```
filename=/tmp/SqlQueryLog
@ -40,7 +47,10 @@ filename=/tmp/SqlQueryLog
### 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 be logged.
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 be logged.
```
source=127.0.0.1
@ -48,7 +58,10 @@ 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 are logged.
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 are logged.
```
user=john
@ -56,7 +69,8 @@ user=john
### Delimiter
The optional `delimiter` parameter defines a delimiter that is used to distinguish columns in the log. The default delimiter is **`:::`**.
The optional `delimiter` parameter defines a delimiter that is used to
distinguish columns in the log. The default delimiter is **`:::`**.
```
delimiter=:::
@ -64,7 +78,9 @@ delimiter=:::
### Query_delimiter
The optional `query_delimiter` defines a delimiter that is used to distinguish different SQL statements in a transaction. The default query delimiter is **`@@@`**.
The optional `query_delimiter` defines a delimiter that is used to
distinguish different SQL statements in a transaction.
The default query delimiter is **`@@@`**.
```
query_delimiter=@@@
@ -72,7 +88,11 @@ query_delimiter=@@@
### Named_pipe
**`named_pipe`** is the path to a named pipe, which TPM filter uses to communicate with 3rd-party applications (e.g., [DBSeer](http://dbseer.org)). Logging is enabled when the router receives the character '1' and logging is disabled when the router receives the character '0' from this named pipe. The default named pipe is **`/tmp/tpmfilter`** and logging is **disabled** by default.
**`named_pipe`** is the path to a named pipe, which TPM filter uses to
communicate with 3rd-party applications (e.g., [DBSeer](http://dbseer.org)).
Logging is enabled when the router receives the character '1' and logging is
disabled when the router receives the character '0' from this named pipe.
The default named pipe is **`/tmp/tpmfilter`** and logging is **disabled** by default.
named_pipe=/tmp/tpmfilter
@ -89,7 +109,8 @@ Similarly, the following command disables the logging:
### Example 1 - Log Transactions for Performance Analysis
You want to log every transaction with its SQL statements and latency for future transaction performance analysis.
You want to log every transaction with its SQL statements and latency
for future transaction performance analysis.
Add a filter with the following definition:
@ -111,7 +132,8 @@ passwd=mypasswd
filters=PerformanceLogger
```
After the filter reads the character '1' from its named pipe, the following is an example log that is generated from the above TPM filter with the above configuration:
After the filter reads the character '1' from its named pipe, the following
is an example log that is generated from the above TPM filter with the above configuration:
```
@ -120,4 +142,4 @@ After the filter reads the character '1' from its named pipe, the following is a
...
```
Note that 3 and 5 are latencies of each transaction in milliseconds.
Note that 3 and 5 are latencies of each transaction in milliseconds.

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

@ -106,7 +106,8 @@ make test
sudo make install
```
Other useful targets for Make are `documentation`, which generates the Doxygen documentation, and `uninstall` which uninstall MariaDB MaxScale binaries after an install.
Other useful targets for Make are `documentation`, which generates the Doxygen documentation,
and `uninstall` which uninstall MariaDB MaxScale binaries after an install.
**Note**: If you configure CMake multiple times, it's possible that you will run
into problems when building MaxScale. Most of the time this manifests as a

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

@ -2,11 +2,10 @@
## Introduction
The purpose of this document is to describe how to configure MariaDB MaxScale
and to discuss some possible usage scenarios for MariaDB MaxScale. MariaDB
MaxScale is designed with flexibility in mind, and consists of an event
processing core with various support functions and plugin modules that tailor
the behavior of the MariaDB MaxScale itself.
This document describes how to configure MariaDB MaxScale and presents some
possible usage scenarios. MariaDB MaxScale is designed with flexibility in mind,
and consists of an event processing core with various support functions and
plugin modules that tailor the behavior of the program.
# Table of Contents
@ -25,23 +24,22 @@ the behavior of the MariaDB MaxScale itself.
* [Authentication](#authentication)
* [Error Reporting](#error-reporting)
### Terms
## Glossary
| Term | Description
------------------- | ------------------
service | A service represents a set of databases with a specific access mechanism that is offered to clients of MariaDB MaxScale. The access mechanism defines the algorithm that MariaDB MaxScale will use to direct particular requests to the individual databases.
server | A server represents an individual database server to which a client can be connected via MariaDB MaxScale.
router | A router is a module within MariaDB MaxScale that will route client requests to the various database servers which MariaDB MaxScale provides a service interface to.
connection routing | Connection routing is a method of handling requests in which MariaDB MaxScale will accept connections from a client and route data on that connection to a single database using a single connection. Connection based routing will not examine individual requests on a connection and it will not move that connection once it is established.
statement routing | Statement routing is a method of handling requests in which each request within a connection will be handled individually. Requests may be sent to one or more servers and connections may be dynamically added or removed from the session.
protocol | A protocol is a module of software that is used to communicate with another software entity within the system. MariaDB MaxScale supports the dynamic loading of protocol modules to allow for increased flexibility.
module | A module is a separate code entity that may be loaded dynamically into MariaDB MaxScale to increase the available functionality. Modules are implemented as run-time loadable shared objects.
monitor | A monitor is a module that can be executed within MariaDB MaxScale to monitor the state of a set of database. The use of an internal monitor is optional, monitoring may be performed externally to MariaDB MaxScale.
listener | A listener is the network endpoint that is used to listen for connections to MariaDB MaxScale from the client applications. A listener is associated to a single service, however, a service may have many listeners.
connection failover| When a connection currently being used between MariaDB MaxScale and the database server fails a replacement will be automatically created to another server by MariaDB MaxScale without client intervention
backend database | A term used to refer to a database that sits behind MariaDB MaxScale and is accessed by applications via MariaDB MaxScale.
filter | A module that can be placed between the client and the MariaDB MaxScale router module. All client data passes through the filter module and may be examined or modified by the filter modules. Filters may be chained together to form processing pipelines.
Word | Description
--------------------|----------------------------------------------------
service | A service represents a set of databases with a specific access mechanism that is offered to clients of MariaDB MaxScale. The access mechanism defines the algorithm that MariaDB MaxScale will use to direct particular requests to the individual databases.
server | A server represents an individual database server to which a client can be connected via MariaDB MaxScale.
router | A router is a module within MariaDB MaxScale that will route client requests to the various database servers which MariaDB MaxScale provides a service interface to.
connection routing | Connection routing is a method of handling requests in which MariaDB MaxScale will accept connections from a client and route data on that connection to a single database using a single connection. Connection based routing will not examine individual requests on a connection and it will not move that connection once it is established.
statement routing | Statement routing is a method of handling requests in which each request within a connection will be handled individually. Requests may be sent to one or more servers and connections may be dynamically added or removed from the session.
protocol | A protocol is a module of software that is used to communicate with another software entity within the system. MariaDB MaxScale supports the dynamic loading of protocol modules to allow for increased flexibility.
module | A module is a separate code entity that may be loaded dynamically into MariaDB MaxScale to increase the available functionality. Modules are implemented as run-time loadable shared objects.
monitor | A monitor is a module that can be executed within MariaDB MaxScale to monitor the state of a set of database. The use of an internal monitor is optional, monitoring may be performed externally to MariaDB MaxScale.
listener | A listener is the network endpoint that is used to listen for connections to MariaDB MaxScale from the client applications. A listener is associated to a single service, however, a service may have many listeners.
connection failover | When a connection currently being used between MariaDB MaxScale and the database server fails a replacement will be automatically created to another server by MariaDB MaxScale without client intervention
backend database | A term used to refer to a database that sits behind MariaDB MaxScale and is accessed by applications via MariaDB MaxScale.
filter | A module that can be placed between the client and the MariaDB MaxScale router module. All client data passes through the filter module and may be examined or modified by the filter modules. Filters may be chained together to form processing pipelines.
## Configuration
@ -49,7 +47,7 @@ The MariaDB MaxScale configuration is read from a file that MariaDB MaxScale
will look for in the following places:
1. By default, the file `maxscale.cnf` in the directory `/etc`
1. The location given with the `--configdir=<path>` command line argument.
2. The location given with the `--configdir=<path>` command line argument.
MariaDB MaxScale will further look for a directory with the same name as the
configuration file, followed by `.d` (for instance `/etc/maxscale.cnf.d`) and
@ -63,10 +61,10 @@ separate configuration files for _servers_, _filters_, etc.
The configuration file itself is based on the
[.ini](https://en.wikipedia.org/wiki/INI_file) file format and consists of
various sections that are used to build the configuration; these sections
define services, servers, listeners, monitors and global settings. Parameters,
which expect a comma-separated list of values can be defined on multiple
lines. The following is an example of a multi-line definition.
various sections that are used to build the configuration; these sections define
services, servers, listeners, monitors and global settings. Parameters, which
expect a comma-separated list of values can be defined on multiple lines. The
following is an example of a multi-line definition.
```
[MyService]
@ -77,18 +75,18 @@ servers=server1,
server3
```
The values of the parameter that are not on the first line need to have at
least one whitespace character before them in order for them to be recognized
as a part of the multi-line parameter.
The values of the parameter that are not on the first line need to have at least
one whitespace character before them in order for them to be recognized as a
part of the multi-line parameter.
### Sizes
Where _specifically noted_, a number denoting a size can be suffixed by a subset of
the IEC binary prefixes or the SI prefixes. In the former case the number will be
interpreted as a certain multiple of 1024 and in the latter case as a certain multiple
of 1000. The supported IEC binary suffixes are `Ki`, `Mi`, `Gi` and `Ti` and the
supported SI suffixes are `k`, `M`, `G` and `T`. In both cases, the matching is
case insensitive.
Where _specifically noted_, a number denoting a size can be suffixed by a subset
of the IEC binary prefixes or the SI prefixes. In the former case the number
will be interpreted as a certain multiple of 1024 and in the latter case as a
certain multiple of 1000. The supported IEC binary suffixes are `Ki`, `Mi`, `Gi`
and `Ti` and the supported SI suffixes are `k`, `M`, `G` and `T`. In both cases,
the matching is case insensitive.
For instance, the following entries
```
@ -134,9 +132,9 @@ used for systems dedicated for running MariaDB MaxScale.
threads=1
```
It should be noted that additional threads will be created to execute other
internal services within MariaDB MaxScale. This setting is used to configure the
number of threads that will be used to manage the user connections.
Additional threads will be created to execute other internal services within
MariaDB MaxScale. This setting is used to configure the number of threads that
will be used to manage the user connections.
#### `auth_connect_timeout`
@ -213,8 +211,7 @@ By default logging to *syslog* is enabled.
syslog=1
```
To enable logging to syslog use the value 1 and to disable use
the value 0.
To enable logging to syslog use the value 1 and to disable use the value 0.
#### `maxlog`
@ -233,15 +230,15 @@ disable use the value 0.
#### `log_to_shm`
Enable or disable the writing of the *maxscale.log* file to shared memory.
If enabled, then the actual log file will be created under `/dev/shm` and
a symbolic link to that file will be created in the *MaxScale* log directory.
Enable or disable the writing of the *maxscale.log* file to shared memory. If
enabled, then the actual log file will be created under `/dev/shm` and a
symbolic link to that file will be created in the *MaxScale* log directory.
Logging to shared memory may be appropriate if *log_info* and/or *log_debug*
are enabled, as logging to a regular file may in that case cause performance
degradation, due to the amount of data logged. However, as shared memory is
a scarce resource, logging to shared memory should be used only temporarily
and not regularly.
Logging to shared memory may be appropriate if *log_info* and/or *log_debug* are
enabled, as logging to a regular file may in that case cause performance
degradation, due to the amount of data logged. However, as shared memory is a
scarce resource, logging to shared memory should be used only temporarily and
not regularly.
Since *MariaDB MaxScale* can log to both file and *syslog* an approach that
provides maximum flexibility is to enable *syslog* and *log_to_shm*, and to
@ -258,8 +255,8 @@ By default, logging to shared memory is disabled.
log_to_shm=1
```
To enable logging to shared memory use the value 1 and to disable use
the value 0.
To enable logging to shared memory use the value 1 and to disable use the value
0.
#### `log_warning`
@ -277,8 +274,8 @@ To disable these messages use the value 0 and to enable them use the value 1.
#### `log_notice`
Enable or disable the logging of messages whose syslog priority is *notice*.
Messages of this priority provide information about the functioning of
MariaDB MaxScale and are enabled by default.
Messages of this priority provide information about the functioning of MariaDB
MaxScale and are enabled by default.
```
# Valid options are:
@ -290,12 +287,12 @@ To disable these messages use the value 0 and to enable them use the value 1.
#### `log_info`
Enable or disable the logging of messages whose syslog priority is *info*.
These messages provide detailed information about the internal workings of
MariaDB MaxScale and should not, due to their frequency, be enabled, unless there
is a specific reason for that. For instance, from these messages it will be
evident, e.g., why a particular query was routed to the master instead of
to a slave. These informational messages are disabled by default.
Enable or disable the logging of messages whose syslog priority is *info*. These
messages provide detailed information about the internal workings of MariaDB
MaxScale and should not, due to their frequency, be enabled, unless there is a
specific reason for that. For instance, from these messages it will be evident,
e.g., why a particular query was routed to the master instead of to a slave.
These informational messages are disabled by default.
```
# Valid options are:
@ -307,9 +304,9 @@ To disable these messages use the value 0 and to enable them use the value 1.
#### `log_debug`
Enable or disable the logging of messages whose syslog priority is *debug*.
This kind of messages are intended for development purposes and are disabled
by default. Note that if MariaDB MaxScale has been built in release mode, then
Enable or disable the logging of messages whose syslog priority is *debug*. This
kind of messages are intended for development purposes and are disabled by
default. Note that if MariaDB MaxScale has been built in release mode, then
debug messages are excluded from the build and this setting will not have any
effect.
@ -346,11 +343,11 @@ To disable the augmentation use the value 0 and to enable it use the value 1.
#### `log_throttling`
In some circumstances it is possible that a particular error (or warning) is
logged over and over again, if the cause for the error persistently remains. To
prevent the log from flooding, it is possible to specify how many times a
particular error may be logged within a time period, before the logging of that
error is suppressed for a while.
It is possible that a particular error (or warning) is logged over and over
again, if the cause for the error persistently remains. To prevent the log from
flooding, it is possible to specify how many times a particular error may be
logged within a time period, before the logging of that error is suppressed for
a while.
```
# A valid value looks like
@ -393,9 +390,9 @@ logdir=/tmp/
#### `datadir`
Set the directory where the data files used by MariaDB 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.
Set the directory where the data files used by MariaDB 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/
@ -415,9 +412,9 @@ libdir=/home/user/lib64/
#### `cachedir`
Configure the directory MariaDB MaxScale uses to store cached data. An example
of cached data is the authentication data fetched from the backend
servers. MariaDB MaxScale stores this in case a connection to the backend server
is not possible.
of cached data is the authentication data fetched from the backend servers.
MariaDB MaxScale stores this in case a connection to the backend server is not
possible.
```
cachedir=/tmp/maxscale_cache/
@ -494,21 +491,23 @@ language=/home/user/lang/
The module used by MariaDB MaxScale for query classification. The information
provided by this module is used by MariaDB MaxScale when deciding where a
particular statement should be sent. The default query classifier
is _qc_sqlite_.
particular statement should be sent. The default query classifier is
_qc_sqlite_.
#### `query_classifier_args`
Arguments for the query classifier. What arguments are accepted depends
on the particular query classifier being used. The default query
classifier - _qc_sqlite_ - supports the following arguments:
Arguments for the query classifier. What arguments are accepted depends on the
particular query classifier being used. The default query classifier -
_qc_sqlite_ - supports the following arguments:
##### `log_unrecognized_statements`
An integer argument taking the following values:
* 0: Nothing is logged. This is the default.
* 1: Statements that cannot be parsed completely are logged. They may have been partially parsed, or classified based on keyword matching.
* 2: Statements that cannot even be partially parsed are logged. They may have been classified based on keyword matching.
* 1: Statements that cannot be parsed completely are logged. They may have been
partially parsed, or classified based on keyword matching.
* 2: Statements that cannot even be partially parsed are logged. They may have
been classified based on keyword matching.
* 3: Statements that cannot even be classified by keyword matching are logged.
```
@ -516,8 +515,8 @@ query_classifier=qc_sqlite
query_classifier_args=log_unrecognized_statements=1
```
This will log all statements that cannot be parsed completely. This
may be useful if you suspect that MariaDB MaxScale routes statements to the wrong
This will log all statements that cannot be parsed completely. This may be
useful if you suspect that MariaDB MaxScale routes statements to the wrong
server (e.g. to a slave instead of to a master).
### Service
@ -530,12 +529,12 @@ statements or route connections to those backend servers.
A service may be considered as a virtual database server that MariaDB MaxScale
makes available to its clients.
Several different services may be defined using the same set of backend
servers. For example a connection based routing service might be used by clients
that already performed internal read/write splitting, whilst a different
statement based router may be used by clients that are not written with this
functionality in place. Both sets of applications could access the same data in
the same databases.
Several different services may be defined using the same set of backend servers.
For example a connection based routing service might be used by clients that
already performed internal read/write splitting, whilst a different statement
based router may be used by clients that are not written with this functionality
in place. Both sets of applications could access the same data in the same
databases.
A service is identified by a service name, which is the name of the
configuration file section and a type parameter of service.
@ -581,9 +580,9 @@ router is included with the documentation of the router itself.
#### `router_options`
Option string given to the router module. The value of this parameter
should be a comma-separated list of key-value pairs. See router specific
documentation for more details.
Option string given to the router module. The value of this parameter should be
a comma-separated list of key-value pairs. See router specific documentation for
more details.
#### `filters`
@ -643,26 +642,18 @@ The account used must be able to select from the mysql.user table, the following
is an example showing how to create this user.
```
MariaDB [mysql]> CREATE USER 'maxscale'@'maxscalehost' IDENTIFIED BY 'Mhu87p2D';
Query OK, 0 rows affected (0.01 sec)
MariaDB [mysql]> GRANT SELECT ON mysql.user TO 'maxscale'@'maxscalehost';
Query OK, 0 rows affected (0.00 sec)
CREATE USER 'maxscale'@'maxscalehost' IDENTIFIED BY 'maxscale-password';
```
Additionally, `SELECT` privileges on the `mysql.db` and `mysql.tables_priv`
Additionally, `SELECT` privileges on the `mysql.user`, `mysql.db` and `mysql.tables_priv`
tables 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 'maxscale'@'maxscalehost';
Query OK, 0 rows affected (0.00 sec)
MariaDB [(none)]> GRANT SELECT ON mysql.tables_priv TO 'maxscale'@'maxscalehost';
Query OK, 0 rows affected (0.00 sec)
MariaDB [(none)]> GRANT SHOW DATABASES ON *.* TO 'maxscale'@'maxscalehost';
Query OK, 0 rows affected (0.00 sec)
GRANT SELECT ON mysql.user TO 'maxscale'@'maxscalehost';
GRANT SELECT ON mysql.db TO 'maxscale'@'maxscalehost';
GRANT SELECT ON mysql.tables_priv TO 'maxscale'@'maxscalehost';
GRANT SHOW DATABASES ON *.* TO 'maxscale'@'maxscalehost';
```
MariaDB MaxScale will execute the following query to retrieve the users. If you
@ -690,6 +681,8 @@ In versions of MySQL 5.7.6 and later, the `Password` column was replaced by
`authentication_string`. Change `user.password` above with
`user.authentication_string`.
**Note**: If authentication fails, MaxScale will try to refresh the list of
database users used by the service up to 4 times every 30 seconds.
#### `passwd`
@ -757,9 +750,10 @@ control the load balancing applied in the router in use by the service. This
allows varying weights to be applied to each server to create a non-uniform
distribution of the load amongst the servers.
An example of this might be to define a parameter for each server that represents
the amount of resource available on the server, we could call this serversize.
Every server should then have a serversize parameter set for the server.
An example of this might be to define a parameter for each server that
represents the amount of resource available on the server, we could call this
serversize. Every server should then have a serversize parameter set for the
server.
```
serversize=10
@ -767,8 +761,8 @@ serversize=10
The service would then have the parameter `weightby=serversize`. If there are 4
servers defined in the service (serverA, serverB, serverC and serverD) with the
serversize set as shown in the table below, the connections would balanced
using the percentages in this table.
serversize set as shown in the table below, the connections would balanced using
the percentages in this table.
Server |serversize|% connections
---------|----------|-------------
@ -781,8 +775,8 @@ _**Note**: If the value of the weighting parameter of an individual server is
zero or the relative weight rounds down to zero, no queries will be routed to
that server as long as a server with a positive weight is available._
Here is an excerpt from an example configuration with the `serv_weight` parameter
used as the weighting parameter.
Here is an excerpt from an example configuration with the `serv_weight`
parameter used as the weighting parameter.
```
[server1]
@ -807,19 +801,19 @@ 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 assign secondary servers
that are only used when the primary server is under heavy load.
most of the connections and about a third of the remaining queries are routed to
the second server. With server weights, you can assign 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.
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.
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.
#### `auth_all_servers`
@ -833,9 +827,9 @@ servers.
The strip_db_esc parameter strips escape characters from database names of
grants when loading the users from the backend server.
This parameter takes a boolean value and when enabled, will strip all backslash
(`\`) characters from the database names. The default value for this parameter
is true since MaxScale 2.0.1. In previous version, the default value was false.
This parameter takes a boolean value and when enabled, will strip all backslash (`\`)
characters from the database names. The default value for this parameter is true
since MaxScale 2.0.1. In previous version, the default value was false.
Some visual database management tools automatically escape some characters and
this might cause conflicts when MariaDB MaxScale tries to authenticate users.
@ -991,10 +985,9 @@ able to accept SSL connections.
#### `ssl`
This enables SSL connections to the server, when set to `required`. If that is
done, the three certificate files mentioned below must also be
supplied. MaxScale connections to this server will then be encrypted with
SSL. If this is not possible, client connection attempts that rely on the server
will fail.
done, the three certificate files mentioned below must also be supplied.
MaxScale connections to this server will then be encrypted with SSL. If this is
not possible, client connection attempts that rely on the server will fail.
#### `ssl_key`
@ -1033,10 +1026,10 @@ should be used.
#### `ssl_cert_verification_depth`
The maximum length of the certificate authority chain that will be
accepted. Legal values are positive integers. Note that if the client is to
submit an SSL certificate, the `ssl_cert_verification_depth` parameter must not
be 0. If no value is specified, the default is 9.
The maximum length of the certificate authority chain that will be accepted.
Legal values are positive integers. Note that if the client is to submit an SSL
certificate, the `ssl_cert_verification_depth` parameter must not be 0. If no
value is specified, the default is 9.
```
# Example
@ -1081,9 +1074,9 @@ The network socket where the listener listens will have a backlog of
connections. The size of this backlog is controlled by the
net.ipv4.tcp_max_syn_backlog and net.core.somaxconn kernel parameters.
Increasing the size of the backlog by modifying the kernel parameters
helps with sudden connection spikes and rejected connections. For more
information see [listen(2)](http://man7.org/linux/man-pages/man2/listen.2.html).
Increasing the size of the backlog by modifying the kernel parameters helps with
sudden connection spikes and rejected connections. For more information see
[listen(2)](http://man7.org/linux/man-pages/man2/listen.2.html).
```
[<Listener name>]
@ -1130,14 +1123,14 @@ on both the specific IP address and the Unix socket.
#### `authenticator`
The authenticator module to use. Each protocol module defines a default
authentication module which is used if no `authenticator` parameter is
found from the configuration.
authentication module which is used if no `authenticator` parameter is found
from the configuration.
#### `authenticator_options`
Option string given to the authenticator module. The value of this
parameter should be a comma-separated list of key-value pairs. See
authenticator specific documentation for more details.
Option string given to the authenticator module. The value of this parameter
should be a comma-separated list of key-value pairs. See authenticator specific
documentation for more details.
#### Available Protocols
@ -1186,9 +1179,9 @@ SSL/TLS encryption method and the various certificate files involved in it. To
enable SSL from client to MaxScale, you must configure the `ssl` parameter to
the value `required` and provide the three files for `ssl_cert`, `ssl_key` and
`ssl_ca_cert`. After this, MySQL connections to this listener will be encrypted
with SSL. Attempts to connect to the listener with a non-SSL client will
fail. Note that the same service can have an SSL listener and a non-SSL listener
if you wish, although they must be on different ports.
with SSL. Attempts to connect to the listener with a non-SSL client will fail.
Note that the same service can have an SSL listener and a non-SSL listener if
you wish, although they must be on different ports.
#### `ssl`
@ -1236,10 +1229,10 @@ TLS 1.2 is also available. MAX will use the best available version.
#### `ssl_cert_verification_depth`
The maximum length of the certificate authority chain that will be
accepted. Legal values are positive integers. Note that if the client is to
submit an SSL certificate, the `ssl_cert_verification_depth` parameter must not
be 0. If no value is specified, the default is 9.
The maximum length of the certificate authority chain that will be accepted.
Legal values are positive integers. Note that if the client is to submit an SSL
certificate, the `ssl_cert_verification_depth` parameter must not be 0. If no
value is specified, the default is 9.
```
# Example
@ -1269,7 +1262,6 @@ 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.
## Routing Modules
The main task of MariaDB MaxScale is to accept database connections from client

50
Documentation/Getting-Started/Install-MariaDB-MaxScale-Using-a-Tarball.md
View File

@ -1,6 +1,8 @@
# Installing MariaDB MaxScale using a tarball
MariaDB MaxScale is also made available as a tarball, which is named like `maxscale-x.y.z.OS.tar.gz` where `x.y.z` is the same as the corresponding version and `OS` identifies the operating system, e.g. `maxscale-2.0.1.centos.7.tar.gz`.
MariaDB MaxScale is also made available as a tarball, which is named like
`maxscale-x.y.z.OS.tar.gz` where `x.y.z` is the same as the corresponding version and `OS`
identifies the operating system, e.g. `maxscale-2.0.1.centos.7.tar.gz`.
In order to use the tarball, the following libraries are required:
@ -8,11 +10,14 @@ In order to use the tarball, the following libraries are required:
- libaio
- OpenSSL
The tarball has been built with the assumption that it will be installed in `/usr/local`. However, it is possible to install it in any directory, but in that case MariaDB MaxScale must be invoked with a flag.
The tarball has been built with the assumption that it will be installed in `/usr/local`.
However, it is possible to install it in any directory, but in that case MariaDB MaxScale
must be invoked with a flag.
## Installing as root in `/usr/local`
If you have root access to the system you probably want to install MariaDB MaxScale under the user and group `maxscale`.
If you have root access to the system you probably want to install MariaDB MaxScale under
the user and group `maxscale`.
The required steps are as follows:
@ -24,11 +29,15 @@ The required steps are as follows:
$ cd maxscale
$ sudo chown -R maxscale var
Creating the symbolic link is necessary, since MariaDB MaxScale has been built with with the assumption that the plugin directory is `/usr/local/maxscale/lib/maxscale`.
Creating the symbolic link is necessary, since MariaDB MaxScale has been built
with the assumption that the plugin directory is `/usr/local/maxscale/lib/maxscale`.
The symbolic link also makes it easy to switch between different versions of MariaDB MaxScale that have been installed side by side in `/usr/local`; just make the symbolic link point to another installation.
The symbolic link also makes it easy to switch between different versions of
MariaDB MaxScale that have been installed side by side in `/usr/local`;
just make the symbolic link point to another installation.
In addition, the first time you install MariaDB MaxScale from a tarball you need to create the following directories:
In addition, the first time you install MariaDB MaxScale from a tarball
you need to create the following directories:
$ sudo mkdir /var/log/maxscale
$ sudo mkdir /var/lib/maxscale
@ -42,21 +51,28 @@ and make `maxscale` the owner of them:
$ sudo chown maxscale /var/run/maxscale
$ sudo chown maxscale /var/cache/maxscale
The following step is to create the MariaDB MaxScale configuration file `/etc/maxscale.cnf`. The file `etc/maxscale.cnf.template` can be used as a base. Please refer to [Configuration Guide](Configuration-Guide.md) for details.
The following step is to create the MariaDB MaxScale configuration file `/etc/maxscale.cnf`.
The file `etc/maxscale.cnf.template` can be used as a base.
Please refer to [Configuration Guide](Configuration-Guide.md) for details.
When the configuration file has been created, MariaDB MaxScale can be started.
$ sudo bin/maxscale --user=maxscale -d
The `-d` flag causes maxscale _not_ to turn itself into a daemon, which is adviseable the first time MariaDB MaxScale is started, as it makes it easier to spot problems.
The `-d` flag causes maxscale _not_ to turn itself into a daemon,
which is adviseable the first time MariaDB MaxScale is started, as it makes it easier to spot problems.
If you want to place the configuration file somewhere else but in `/etc` you can invoke MariaDB MaxScale with the `--config` flag, for instance, `--config=/usr/local/maxscale/etc/maxscale.cnf`.
If you want to place the configuration file somewhere else but in `/etc`
you can invoke MariaDB MaxScale with the `--config` flag,
for instance, `--config=/usr/local/maxscale/etc/maxscale.cnf`.
Note also that if you want to keep _everything_ under `/usr/local/maxscale` you can invoke MariaDB MaxScale using the flag `--basedir`.
Note also that if you want to keep _everything_ under `/usr/local/maxscale`
you can invoke MariaDB MaxScale using the flag `--basedir`.
$ sudo bin/maxscale --user=maxscale --basedir=/usr/local/maxscale -d
That will cause MariaDB MaxScale to look for its configuration file in `/usr/local/maxscale/etc` and to store all runtime files under `/usr/local/maxscale/var`.
That will cause MariaDB MaxScale to look for its configuration file in
`/usr/local/maxscale/etc` and to store all runtime files under `/usr/local/maxscale/var`.
## Installing in any Directory
@ -64,16 +80,22 @@ Enter a directory where you have the right to create a subdirectory. Then do as
$ tar -xzvf maxscale-x.y.z.OS.tar.gz
The next step is to create the MaxScale configuration file `maxscale-x.y.z/etc/maxscale.cnf`. The file `maxscale-x.y.z/etc/maxscale.cnf.template` can be used as a base. Please refer to [Configuration Guide](Configuration-Guide.md) for details.
The next step is to create the MaxScale configuration file `maxscale-x.y.z/etc/maxscale.cnf`.
The file `maxscale-x.y.z/etc/maxscale.cnf.template` can be used as a base.
Please refer to [Configuration Guide](Configuration-Guide.md) for details.
When the configuration file has been created, MariaDB MaxScale can be started.
$ cd maxscale-x.y.z.OS
$ bin/maxscale -d --basedir=.
With the flag `--basedir`, MariaDB MaxScale is told where the `lib`, `etc` and `var` directories are found. Unless it is specified, MariaDB MaxScale assumes the `lib` directory is found in `/usr/local/maxscale`, and the `var` and `etc` directories in `/`.
With the flag `--basedir`, MariaDB MaxScale is told where the `lib`, `etc` and `var`
directories are found. Unless it is specified, MariaDB MaxScale assumes
the `lib` directory is found in `/usr/local/maxscale`,
and the `var` and `etc` directories in `/`.
It is also possible to specify the directories and the location of the configuration file individually. Invoke MaxScale like
It is also possible to specify the directories and the location of
the configuration file individually. Invoke MaxScale like
$ bin/maxscale --help

142
Documentation/Getting-Started/MariaDB-MaxScale-Installation-Guide.md
View File

@ -2,11 +2,21 @@
## First Steps With MariaDB MaxScale
In this introduction to MariaDB MaxScale the aim is to take the reader from the point of installation to making the decision as to which of the various setups that are possible with MariaDB MaxScale should be the initial configuration to use. One of the problems that new users to MariaDB MaxScale suffer is deciding exactly what they should consider as a base configuration to start exploring what MariaDB MaxScale is capable of. MariaDB MaxScale is highly configurable, with new plugins expanding the capabilities of MariaDB MaxScale, whilst this makes it a very adaptable tool it does lead to an initial hurdle in configuring MariaDB MaxScale.
In this introduction to MariaDB MaxScale the aim is to take the reader
from the point of installation to making the decision as to which of
the various setups that are possible with MariaDB MaxScale should be
the initial configuration to use. One of the problems that new users to
MariaDB MaxScale suffer is deciding exactly what they should consider
as a base configuration to start exploring what MariaDB MaxScale
is capable of. MariaDB MaxScale is highly configurable,
with new plugins expanding the capabilities of MariaDB MaxScale,
whilst this makes it a very adaptable tool it does lead to an initial
hurdle in configuring MariaDB MaxScale.
## Installation
MariaDB MaxScale can be installed either using the MariaDB Enterprise Repository or directly from a downloaded package.
MariaDB MaxScale can be installed either using the MariaDB Enterprise Repository
or directly from a downloaded package.
### Using the MariaDB Enterprise Repository
@ -40,7 +50,8 @@ $ sudo apt-get install -f
### Starting MariaDB MaxScale
Before starting MariaDB MaxScale, you need to create a configuration file for it; please see further [down](#configuring-mariadb-maxscale).
Before starting MariaDB MaxScale, you need to create a configuration file for it;
please see further [down](#configuring-mariadb-maxscale).
Once a configuration file has been created you can start MariaDB MaxScale:
@ -48,7 +59,8 @@ Once a configuration file has been created you can start MariaDB MaxScale:
systemctl start maxscale.service
```
If your system does not support systemd you can start MariaDB MaxScale using the installed init.d script.
If your system does not support systemd you can start MariaDB MaxScale using the
installed init.d script.
```
service maxscale start
@ -56,56 +68,130 @@ service maxscale start
Starting with version 2.0.3, MaxScale also supports Upstart.
An example configuration file is installed into the `/etc/` folder. This file should be changed according to your needs.
An example configuration file is installed into the `/etc/` folder.
This file should be changed according to your needs.
## Install MariaDB MaxScale Using a Tarball
MaxScale can also be installed using a tarball. That may be required if you are using a Linux distribution for which there exist no installation package or if you want to install many different MaxScale versions side by side. For instructions on how to do that, please refer to [Install MariaDB MaxScale using a Tarball](Install-MariaDB-MaxScale-Using-a-Tarball.md).
MaxScale can also be installed using a tarball.
That may be required if you are using a Linux distribution for which there
exist no installation package or if you want to install many different
MaxScale versions side by side. For instructions on how to do that, please refer to
[Install MariaDB MaxScale using a Tarball](Install-MariaDB-MaxScale-Using-a-Tarball.md).
## Building MariaDB MaxScale From Source Code
Alternatively you may download the MariaDB MaxScale source and build your own binaries. To do this, refer to the separate document [Building MariaDB MaxScale from Source Code](Building-MaxScale-from-Source-Code.md)
Alternatively you may download the MariaDB MaxScale source and build your own binaries.
To do this, refer to the separate document
[Building MariaDB MaxScale from Source Code](Building-MaxScale-from-Source-Code.md)
## Configuring MariaDB MaxScale
The first step in configuring your MariaDB MaxScale is to determine what it is you want to achieve with your MariaDB 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 MariaDB MaxScale supports; MySQL Master/Slave Replication clusters and Galera Cluster.
The first step in configuring your MariaDB MaxScale is to determine
what it is you want to achieve with your MariaDB 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 MariaDB 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 MariaDB 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 MariaDB MaxScale that will work with your environment.
There are two major configuration options available to use MariaDB 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 MariaDB MaxScale that
will work with your environment.
Using a MySQL Master/Slave Replication cluster will provide one node server within the cluster that is the master server and the remainder of the servers will be slaves. The slaves are read replicas of the master. In a replication cluster like this all write operations must be performed on the master. This can provide not just added security of your data, but also read scalability. In an application environment with a substantial proportions of read operations, directing those read operations to the slave servers can increase the total load which the system can handle by offloading the master server from the burden of these read operations.
Using a MySQL Master/Slave Replication cluster will provide one node server
within the cluster that is the master server and the remainder of the servers
will be slaves. The slaves are read replicas of the master.
In a replication cluster like this all write operations must be performed
on the master.
This can provide not just added security of your data, but also read scalability.
In an application environment with a substantial proportions of read operations,
directing those read operations to the slave servers can increase
the total load which the system can handle by offloading the master server
from the burden of these read operations.
Making the choice between these two setups is relatively simple, if you have an application that understands that there are some database servers that it can only read from and one it must send all of the writes to, then the connection routing option can be used. Applications that are not written to separate read and write statements must use a service within MariaDB MaxScale that will split the incoming stream of SQL statements into operations that can be executed on the master and those that can be set to the slave. These applications should use the statement based routing provided by the Read/Write Splitter router.
Making the choice between these two setups is relatively simple,
if you have an application that understands that there are some database servers
that it can only read from and one it must send all of the writes to,
then the connection routing option can be used.
Applications that are not written to separate read and write statements must use
a service within MariaDB MaxScale that will split the incoming stream of SQL statements
into operations that can be executed on the master and those that can be set to the slave.
These applications should use the statement based routing provided by
the Read/Write Splitter router.
### Galera Cluster
A Galera Cluster provides a true multi-master cluster option for MariaDB and MySQL database environments. In such a setup any node that is part of the cluster can be used to both execute read and write operations. MariaDB MaxScale again offers two different configurations that can be used with Galera; a connection balancing configuration or a statement splitting mechanism that can be used to isolate write operations to a single node within the cluster. Again there is a tutorial guide available for both of these major configurations.
A Galera Cluster provides a true multi-master cluster option for MariaDB and MySQL
database environments. In such a setup any node that is part of the cluster
can be used to both execute read and write operations.
MariaDB MaxScale again offers two different configurations that can be used with Galera;
a connection balancing configuration or a statement splitting mechanism that can be used
to isolate write operations to a single node within the cluster.
Again there is a tutorial guide available for both of these major configurations.
The connection based load balancing configuration is used in an environment in which you have a cluster that you want to be available to an application without the application needing to be aware of the cluster configuration or state of the database nodes. MariaDB MaxScale will monitor the nodes within the database cluster and will route connections from the application to database nodes that are active members of the cluster. MariaDB MaxScale will also keep track of the number of connections to each database node keep equal numbers of connections to each node, at the time the connection is established.
The connection based load balancing configuration is used in an environment in which
you have a cluster that you want to be available to an application without
the application needing to be aware of the cluster configuration or state of
the database nodes.
MariaDB MaxScale will monitor the nodes within the database cluster and will
route connections from the application to database nodes that
are active members of the cluster.
MariaDB MaxScale will also keep track of the number of connections to each
database node keep equal numbers of connections to each node,
at the time the connection is established.
It is also possible to use the Read/Write Splitter with Galera. Although it is not necessary to segregate the write operations to a single node, there are advantages in doing this if you have an application where the write load is not too great to be handled by a single node in the cluster. Galera Cluster uses an optimistic locking strategy that will allow transactions to progress independently on each node within the cluster. It is only when the transaction commits that the transaction is checked for conflicts with other transactions that are committing on the other nodes. At this stage the commit can fail with a deadlock detection error. This can be inconvenient for applications and, some older applications, that are not aware that the transaction can fail at this stage may not check for this failure. Using the Read/Write Splitter will allow this to be avoided since it will isolate the write to one node and no deadlock detection will occur. MariaDB MaxScale provides a monitoring module that will maintain pseudo states of master and slave for the Galera cluster that allows for this type of configuration.
It is also possible to use the Read/Write Splitter with Galera.
Although it is not necessary to segregate the write operations to a single node,
there are advantages in doing this if you have an application where the write load
is not too great to be handled by a single node in the cluster.
Galera Cluster uses an optimistic locking strategy that will allow transactions
to progress independently on each node within the cluster.
It is only when the transaction commits that the transaction is checked for conflicts
with other transactions that are committing on the other nodes.
At this stage the commit can fail with a deadlock detection error.
This can be inconvenient for applications and, some older applications,
that are not aware that the transaction can fail at this stage
may not check for this failure.
Using the Read/Write Splitter will allow this to be avoided since
it will isolate the write to one node and no deadlock detection will occur.
MariaDB MaxScale provides a monitoring module that will maintain pseudo states
of master and slave for the Galera cluster that allows for this type of configuration.
### Other MariaDB MaxScale Configuration
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 MariaDB 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.
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 MariaDB 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 MariaDB 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 MariaDB MaxScale stores the keys is `/var/lib/maxscale`.
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 MariaDB 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 MariaDB MaxScale stores
the keys is `/var/lib/maxscale`.
```
# Usage: maxkeys [PATH]
maxkeys /var/lib/maxscale/
```
Changing the encryption key for MariaDB MaxScale will invalidate any currently encrypted keys stored in the maxscale.cnf file.
Changing the encryption key for MariaDB 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.
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
@ -113,7 +199,10 @@ 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. MariaDB MaxScale will determine this as an encrypted password and automatically decrypt it before sending it the database server.
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.
MariaDB MaxScale will determine this as an encrypted password and automatically decrypt
it before sending it the database server.
```
[Split Service]
@ -135,8 +224,19 @@ modules it will search using a configurable search path. The priority of these p
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 MariaDB 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.
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 MariaDB 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 MariaDB MaxScale
There are various administration tasks that may be done with MariaDB MaxScale, a client command, maxadmin, is available that will interact with a running MariaDB MaxScale and allow the status of MariaDB MaxScale to be monitored and give some control of the MariaDB 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 MariaDB MaxScale.
There are various administration tasks that may be done with MariaDB MaxScale,
a client command, maxadmin, is available that will interact with a running
MariaDB MaxScale and allow the status of MariaDB MaxScale to be monitored and
give some control of the MariaDB 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 MariaDB MaxScale.

18
Documentation/Monitors/MM-Monitor.md
View File

@ -2,11 +2,15 @@
## 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.
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.
A minimal configuration for a monitor requires a set of servers for monitoring and an 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]
@ -20,7 +24,8 @@ passwd=mypwd
## Common Monitor Parameters
For a list of optional parameters that all monitors support, read the [Monitor Common](Monitor-Common.md) document.
For a list of optional parameters that all monitors support, read
the [Monitor Common](Monitor-Common.md) document.
## Multi-Master Monitor optional parameters
@ -28,9 +33,12 @@ 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.
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.
This is a situation which can happen if all slave servers are unreachable or the
replication breaks for some reason.
```
detect_stale_master=true

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

File diff suppressed because it is too large Load Diff

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

@ -24,11 +24,11 @@ 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.
The client connection will need to have comments enabled. For example the `mysql` command line client has comments disabled by default and they need to be enabled by passing the `-c` option.
For comment types, use either `-- ` (notice the whitespace) or `#` after the semicolon or `/* .. */` before the semicolon. All comment types work with routing hints.
For comment types, use either `-- ` (notice the whitespace after the double hyphen) or `#` after the semicolon or `/* .. */` before the semicolon.
The MySQL manual doesn`t specify if comment blocks, i.e. `/* .. */`, should contain a w
The MySQL manual doesn't specify if comment blocks, i.e. `/* .. */`, should contain a
whitespace character before or after the tags, so adding whitespace at both the start and the end is advised.
## Hint body
@ -39,10 +39,10 @@ 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
The hints have two types, ones that define a server type and others that contain
name-value pairs.
###Routing destination hints
### Routing destination hints
These hints will instruct the router to route a query to a certain type of a server.
```

56
Documentation/Reference/How-errors-are-handled-in-MaxScale.md
View File

@ -1,56 +0,0 @@
# How errors are handled in MariaDB MaxScale
This document describes how errors are handled in MariaDB MaxScale, its protocol modules and routers.
Assume a client, maxscale, and master/slave replication cluster.
An "error" can be due to failed authentication, routing error (unsupported query type etc.), or backend failure.
## Authentication error
Authentication is relatively complex phase in the beginning of session creation. Roughly speaking, client protocol has loaded user information from backend so that it can authenticate client without consulting backend. When client sends authentication data to MariaDB MaxScale data is compared against backend’s user data in the client protocol module. If authentication fails client protocol module refreshes backend data just in case it had became obsolete after last refresh. If authentication still fails after refresh, authentication error occurs.
Close sequence starts from mysql_client.c:gw_read_client_event where
1. session state is set to SESSION_STATE_STOPPING
2. dcb_close is called for client DCB
1. client DCB is removed from epoll set and state is set to DCB_STATE_NOPOLLING
2. client protocol’s close is called (gw_client_close)
* protocol struct is done’d
* router’s closeSession is called (includes calling dcb_close for backends)
3. dcb_call_callback is called for client DCB with DCB_REASON_CLOSE
4. client DCB is set to zombies list
Each call for dcb_close in closeSession repeat steps 2a-d.
## Routing errors
### Invalid capabilities returned by router
When client protocol module receives query from client the protocol state is (typically) MYSQL_IDLE. The protocol state is checked in mysql_client.c:gw_read_client_event. First place where a hard error may occur is when router capabilities are read. If router response is invalid (other than RCAP_TYPE_PACKET_INPUT and RCAP_TYPE_STMT_INPUT). In case of invalid return value from the router, error is logged, followed by session closing.
### Backend failure
When mysql_client.c:gw_read_client_event calls either route_by_statement or directly MXS_SESSION_ROUTE_QUERY script, which calls the routeQuery function of the head session’s router. routeQuery returns 1 if succeed, or 0 in case of error. Success here means that query was routed and reply will be sent to the client while error means that routing failed because of backend (server/servers/service) failure or because of side effect of backend failure.
In case of backend failure, error is replied to client and handleError is called to resolve backend problem. handleError is called with action ERRACT_NEW_CONNECTION which tells to error handler that it should try to find a replacement for failed backend. Handler will return true if there are enough backend servers for session’s needs. If handler returns false it means that session can’t continue processing further queries and will be closed. Client will be sent an error message and dcb_close is called for client DCB.
Close sequence is similar to that described above from phase #2 onward.
Reasons for "backend failure" in rwsplit:
* router has rses_closed == true because other thread has detected failure and started to close session
* master has disappeared; demoted to slave, for example
### Router error
In cases where MXS_SESSION_ROUTE_QUERY has returned successfully (=1) query may not be successfully processed in backend or even sent to it. It is possible that router fails in routing the particular query but there is no such error which would prevent session from continuing. In this case router handles error silently by creating and adding MySQL error to first available backend’s (incoming) eventqueue where it is found and sent to client (clientReply).

1071
Documentation/Reference/MaxAdmin.md
View File

File diff suppressed because it is too large Load Diff

56
Documentation/Reference/MaxBinlogCheck.md
View File

@ -1,24 +1,21 @@
# Maxbinlogcheck
# The MySQL/MariaDB binlog check utility
Massimiliano Pinto
Last Updated: 07th December 2016
# Maxbinlogcheck, the MySQL/MariaDB binlog check utility
# Overview
Maxbinlogcheck is a command line utility for checking binlogfiles downloaded by MariaDB MaxScale binlog router or the MySQL/MariaDB binlog files stored in a database server acting as a master in a replication environment.
It checks the binlog file against any corruption and incomplete transaction stored and reports a transaction summary after reading all the events.
It may optionally truncate binlog file.
Maxbinlogcheck is a command line utility for checking binlogfiles. The files may
have been downloaded by the MariaDB MaxScale binlog router or they may be
MySQL/MariaDB binlog files stored in a database server acting as a master in a
replication environment. Maxbinlogcheck checks the binlog files against any
corruption and stored incomplete transactions and reports a transaction summary
after reading all the events. It may optionally truncate the binlog file.
Maxbinlogcheck supports
Maxbinlogcheck supports:
* MariaDB 5.5 and MySQL 5.6
* MariaDB 10.0 and 10.1 with a command line option
# Running maxbinlogcheck
```
# /usr/local/bin/maxbinlogcheck /path_to_file/bin.000002
```
@ -34,29 +31,29 @@ The maxbinlogcheck command accepts a number of switches
<td>Description</td>
</tr>
<tr>
<td>-f</td>
<td>--fix</td>
<td>If the option is set the binlog file will be truncated at last safe transaction pos in case of any error</td>
<td>-f</td> <td>--fix</td> <td>If set the binlog file will be truncated at
last safe transaction pos in case of any error</td>
</tr>
<tr>
<td>-M</td>
<td>--mariadb10</td>
<td>Check the current binlog against MariaDB 10.0.x events</td>
<td>Checks the current binlog against MariaDB 10.0.x events</td>
</tr>
<tr>
<td>-d</td>
<td>--debug</td>
<td>Set the debug mode. If set the FD Events, Rotate events and opening/closing transactions are displayed.</td>
<td>Sets the debug mode. If set the FD Events, Rotate events and
opening/closing transactions are displayed.</td>
</tr>
<tr>
<td>-?</td>
<td>--help</td>
<td>Print usage information regarding maxbinlogcheck</td>
<td>Prints usage information regarding maxbinlogcheck</td>
</tr>
<tr>
<td>-V</td>
<td>--version</td>
<td>Print the maxbinlogcheck version information</td>
<td>Prints the maxbinlogcheck version information</td>
</tr>
<tr>
<td>-K</td>
@ -66,12 +63,13 @@ The maxbinlogcheck command accepts a number of switches
<tr>
<td>-A</td>
<td>--aes_algo</td>
<td>AES Algorithm for MariaDB 10.1 binlog file decryption (default=AES_CBC, AES_CTR)</td>
<td>AES Algorithm for MariaDB 10.1 binlog file decryption (default=AES_CBC,
AES_CTR)</td>
</tr>
<tr>
<td>-H</td>
<td>--header</td>
<td>Print the binlog event header</td>
<td>Prints the binlog event header</td>
</tr>
</table>
@ -175,7 +173,7 @@ The maxbinlogcheck command accepts a number of switches
This file is corrupted, as reported by the utility:
```
[root@maxscale-02 build]# /usr/local/bin/maxbinlogcheck /servers/binlogs/new-trx/bin.000002
[root@maxscale-02 build]# /usr/local/bin/maxbinlogcheck /servers/binlogs/new-trx/bin.000002
2015-09-08 10:03:16 maxbinlogcheck 1.0.0
2015-09-08 10:03:16 Checking /servers/binlogs/new-trx/bin.000002 (bin.000002), size 109498 bytes
2015-09-08 10:03:16 Event size error: size 0 at 290.
@ -183,7 +181,7 @@ This file is corrupted, as reported by the utility:
2015-09-08 10:03:16 Check retcode: 1, Binlog Pos = 245
```
The suggested safe pos is 245
The suggested safe pos is 245.
Use -f option for fix with debug:
@ -205,7 +203,7 @@ Use -f option for fix with debug:
Check it again, last pos will be 245 and no errors will be reported:
```
[root@maxscale-02 build]# /usr/local/bin/maxbinlogcheck /servers/binlogs/new-trx/bin.000002 -d
[root@maxscale-02 build]# /usr/local/bin/maxbinlogcheck /servers/binlogs/new-trx/bin.000002 -d
2015-09-08 09:56:56 maxbinlogcheck 1.0.0
2015-09-08 09:56:56 Checking /servers/binlogs/new-trx/bin.000002 (bin.000002), size 245 bytes
2015-09-08 09:56:56 - Format Description event FDE @ 4, size 241
@ -281,8 +279,10 @@ And finally big transaction is now done.
2015-09-08 10:17:16 Check retcode: 0, Binlog Pos = 590760698
```
**Note**
with current maxbinlogcheck it's not possible to fix a binlog with incomplete transaction and no other errors
**Note**
With current maxbinlogcheck it's not possible to fix a binlog with incomplete
transaction and no other errors
If that is really desired it will be possible with UNIX command line:
@ -363,8 +363,8 @@ Check result:
Key File content example: /var/binlogs/key_file.txt
First two bytes are: the encryption scheme, it must be 1, and the ';' separator.
Following bytes are the HEX representation of the key (length must be 16, 24 or 32).
The example shows a 32 bytes key in HEX format (64 bytes):
Following bytes are the HEX representation of the key (length must be 16, 24 or
32). The example shows a 32 bytes key in HEX format (64 bytes):
```
1;666f6f62617220676f657320746f207468652062617220666f7220636f66666565

18
Documentation/Reference/Module-Commands.md
View File

@ -1,14 +1,13 @@
# Module commands
Introduced in MaxScale 2.1, the module commands are special, module-specific
commands. They allow the modules to expand beyond the capabilities of the
module API. Currently, only MaxAdmin implements an interface to the module
commands.
commands. They allow the modules to expand beyond the capabilities of the module
API. Currently, only MaxAdmin implements an interface to the module commands.
All registered module commands can be shown with `maxadmin list commands` and
they can be executed with `maxadmin call command <module> <name> ARGS...` where
_<module>_ is the name of the module and _<name>_ is the name of the
command. _ARGS_ is a command specific list of arguments.
_<module>_ is the name of the module and _<name>_ is the name of the command.
_ARGS_ is a command specific list of arguments.
## Developer reference
@ -16,7 +15,8 @@ The module command API is defined in the _modulecmd.h_ header. It consists of
various functions to register and call module commands. Read the function
documentation in the header for more details.
The following example registers the module command _my_command_ for module _my_module_.
The following example registers the module command _my_command_ for module
_my_module_.
```
#include <maxscale/modulecmd.h>
@ -53,9 +53,9 @@ int main(int argc, char **argv)
}
```
The array of _modulecmd_arg_type_t_ type is used to tell what kinds of arguments
the command expects. The first argument is a SERVER which will be replaced with a
pointer to a server. The second argument is an optional string argument.
The array _my_args_ of type _modulecmd_arg_type_t_ is used to tell what kinds of
arguments the command expects. The first argument is a boolean and the second
argument is an optional string.
Arguments are passed to the parsing function as an array of void pointers. They
are interpreted as the types the command expects.

69
Documentation/Release-Notes/MaxScale-2.1.3-Release-Notes.md Normal file
View File

@ -0,0 +1,69 @@
# MariaDB MaxScale 2.1.3 Release Notes
Release 2.1.3 is a GA release.
This document describes the changes in release 2.1.3, when compared to
release [2.1.2](MaxScale-2.1.2-Release-Notes.md).
If you are upgrading from release 2.0, please also read the following
release notes:
[2.1.2](./MaxScale-2.1.2-Release-Notes.md)
[2.1.1](./MaxScale-2.1.1-Release-Notes.md)
[2.1.0](./MaxScale-2.1.0-Release-Notes.md)
For any problems you encounter, please consider submitting a bug
report at [Jira](https://jira.mariadb.org).
## MariaDB 10.2
MaxScale 2.1 has not been extended to understand all new features that
MariaDB 10.2 introduces. Please see
[Support for 10.2](About/Support-for-10.2.md)
for details.
## Changed Features
### Cache
* The storage `storage_rocksdb` is no longer built by default and is
not included in the MariaDB MaxScale package.
### Maxrows
* It can now be specified whether the _maxrows_ filter should return an
empty resultset, an error packet or an ok packet, when the limit has
been reached.
Please refer to the
[maxrows documentation](../Filters/Maxrows.md)
for details.
## Bug fixes
[Here is a list of bugs fixed since the release of MaxScale 2.1.2.](https://jira.mariadb.org/browse/MXS-1212?jql=project%20%3D%20MXS%20AND%20issuetype%20%3D%20Bug%20AND%20resolution%20in%20(Fixed%2C%20Done)%20AND%20fixVersion%20%3D%202.1.3)
* [MXS-1227](https://jira.mariadb.org/browse/MXS-1227) Nagios Plugins broken by change in output of "show monitors" in 2.1
* [MXS-1221](https://jira.mariadb.org/browse/MXS-1221) Nagios plugin scripts does not process -S option properly
* [MXS-1212](https://jira.mariadb.org/browse/MXS-1212) Excessive execution time when maxrows limit has been reached
* [MXS-1202](https://jira.mariadb.org/browse/MXS-1202) maxadmin "show service" counters overflow
* [MXS-1200](https://jira.mariadb.org/browse/MXS-1200) config file lines limited to ~1024 chars
## Known Issues and Limitations
There are some limitations and known issues within this version of MaxScale.
For more information, please refer to the [Limitations](../About/Limitations.md) document.
## Packaging
RPM and Debian packages are provided for the Linux distributions supported
by MariaDB Enterprise.
Packages can be downloaded [here](https://mariadb.com/resources/downloads).
## Source Code
The source code of MaxScale is tagged at GitHub with a tag, which is identical
with the version of MaxScale. For instance, the tag of version X.Y.Z of MaxScale
is X.Y.Z. Further, *master* always refers to the latest released non-beta version.
The source code is available [here](https://github.com/mariadb-corporation/MaxScale).

3
Documentation/Routers/Avrorouter.md
View File

@ -271,8 +271,7 @@ For more information on how to use these scripts, see the output of `cdc.py -h`
To build the avrorouter from source, you will need the [Avro C](https://avro.apache.org/docs/current/api/c/)
library, liblzma, [the Jansson library](http://www.digip.org/jansson/) and sqlite3 development headers. When
configuring MaxScale with CMake, you will need to add `-DBUILD_CDC=Y
-DBUILD_CDC=Y` to build the avrorouter and the CDC protocol module.
configuring MaxScale with CMake, you will need to add `-DBUILD_CDC=Y` to build the CDC module set.
For more details about building MaxScale from source, please refer to the
[Building MaxScale from Source Code](../Getting-Started/Building-MaxScale-from-Source-Code.md) document.

73
Documentation/Routers/Binlogrouter.md
View File

@ -13,7 +13,7 @@ replication setup where replication is high-priority.
## Mandatory Router Parameters
The binlogrouter requires the `server`, `user` and `passwd` parameters. These
The binlogrouter requires the `server`, `user` and `password` parameters. These
should be configured according to the
[Configuration Guide](../Getting-Started/Configuration-Guide.md#service).
@ -32,18 +32,20 @@ following options should be given as a value to the `router_options` parameter.
### `binlogdir`
This parameter allows the location that MariaDB MaxScale uses to store binlog
files to be set. If this parameter is not set to a directory name then MariaDB
This parameter controls the location where MariaDB MaxScale stores the binary log
files. If this parameter is not set to a directory name then MariaDB
MaxScale will store the binlog files in the directory
/var/cache/maxscale/<Service Name>. In the binlog dir there is also the 'cache'
directory that contains data retrieved from the master during registration phase
and the master.ini file which contains the configuration of current configured
master.
`/var/cache/maxscale/<Service Name>` where `<Service Name>` is the name of the
service in the configuration file. The _binlogdir_ also contains the
_cache_ subdirectory which stores data retrieved from the master during the slave
registration phase. The master.ini file also resides in the _binlogdir_. This
file keeps track of the current master configuration and it is updated when a
`CHANGE MASTER TO` query is executed.
From 2.1 onwards, the 'cache' directory is stored in the same location as other
user credential caches. This means that with the default options, the user
credential cache is stored in
/var/cache/maxscale/<Service Name>/<Listener Name>/cache/.
`/var/cache/maxscale/<Service Name>/<Listener Name>/cache/`.
Read the [MySQL Authenticator](../Authenticators/MySQL-Authenticator.md)
documentation for instructions on how to define a custom location for the user
@ -51,45 +53,45 @@ cache.
### `uuid`
This is used to set the unique uuid that the binlog router uses when it connects
to the master server. If no explicit value is given for the uuid in the
configuration file then a uuid will be generated.
This is used to set the unique UUID that the binlog router uses when it connects
to the master server. If no explicit value is given for the UUID in the
configuration file then a UUID will be generated.
### `server_id`
As with uuid, MariaDB MaxScale must have a unique _server id_ for the connection
it makes to the master. This parameter provides the value of the server id that
As with UUID, MariaDB MaxScale must have a unique _server_id_. This parameter
configures the value of the _server_id_ that
MariaDB MaxScale will use when connecting to the master.
The id can also be specified using `server-id` but that is deprecated
and will be removed in a future release of MariaDB MaxScale.
Older versions of MaxScale allowed the ID to be specified using `server-id`.
This has been deprecated and will be removed in a future release of MariaDB MaxScale.
### `master_id`
The _server id_ value that MariaDB MaxScale should use to report to the slaves
The _server_id_ value that MariaDB MaxScale should use to report to the slaves
that connect to MariaDB MaxScale. This may either be the same as the server id
of the real master or can be chosen to be different if the slaves need to be
aware of the proxy layer. The real master server id will be used if the option
aware of the proxy layer. The real master server ID will be used if the option
is not set.
The id can also be specified using `master-id` but that is deprecated
and will be removed in a future release of MariaDB MaxScale.
Older versions of MaxScale allowed the ID to be specified using `master-id`.
This has been deprecated and will be removed in a future release of MariaDB MaxScale.
### `master_uuid`
It is a requirement of replication that each slave have a unique UUID value. The
MariaDB MaxScale router will identify itself to the slaves using the uuid of the
It is a requirement of replication that each slave has a unique UUID value. The
MariaDB MaxScale router will identify itself to the slaves using the UUID of the
real master if this option is not set.
### `master_version`
The MariaDB MaxScale router will identify itself to the slaves using the server
version of the real master if this option is not set.
By default, the router will identify itself to the slaves using the server
version of the real master. This option allows the router to use a custom version string.
### `master_hostname`
The MariaDB MaxScale router will identify itself to the slaves using the server
hostname of the real master if this option is not set.
By default, the router will identify itself to the slaves using the
hostname of the real master. This option allows the router to use a custom hostname.
### `user`
@ -113,13 +115,13 @@ the router options or using the username and password defined of the service
must be granted replication privileges on the database server.
```
MariaDB> CREATE USER 'repl'@'maxscalehost' IDENTIFIED by 'password';
MariaDB> GRANT REPLICATION SLAVE ON *.* TO 'repl'@'maxscalehost';
CREATE USER 'repl'@'maxscalehost' IDENTIFIED by 'password';
GRANT REPLICATION SLAVE ON *.* TO 'repl'@'maxscalehost';
```
### `password`
The password of the above user. If the password is not explicitly given then the
The password for the user. If the password is not explicitly given then the
password in the service entry will be used. For compatibility with other
username and password definitions within the MariaDB MaxScale configuration file
it is also possible to use the parameter passwd=.
@ -167,9 +169,9 @@ incomplete transactions detection.
### `send_slave_heartbeat`
This defines whether (on | off) MariaDB MaxScale sends to the slave the
heartbeat packet when there are no real binlog events to send. The default value
if 'off', no heartbeat event is sent to slave server. If value is 'on' the
This defines whether MariaDB MaxScale sends the heartbeat packet to the slave
when there are no real binlog events to send. The default value
is 'off' and no heartbeat events are sent to slave servers. If value is 'on' the
interval value (requested by the slave during registration) is reported in the
diagnostic output and the packet is send after the time interval without any
event to send.
@ -205,6 +207,7 @@ master.ini or later via CHANGE MASTER TO. This parameter cannot be modified at
runtime, default is 9.
### `encrypt_binlog`
Whether to encrypt binlog files: the default is Off.
When set to On the binlog files will be encrypted using specified AES algorithm
@ -226,11 +229,11 @@ the binlog events positions in binlog file are the same as in the master binlog
file and there is no position mismatch.
### `encryption_algorithm`
'aes_ctr' or 'aes_cbc'
The default is 'aes_cbc'
The encryption algorithm, either 'aes_ctr' or 'aes_cbc'. The default is 'aes_cbc'
### `encryption_key_file`
The specified key file must contains lines with following format:
`id;HEX(KEY)`
@ -277,10 +280,8 @@ values may be used for all other options.
## Examples
The [Replication
Proxy](../Tutorials/Replication-Proxy-Binlog-Router-Tutorial.md) tutorial will
The [Replication Proxy](../Tutorials/Replication-Proxy-Binlog-Router-Tutorial.md) tutorial will
show you how to configure and administrate a binlogrouter installation.
Tutorial also includes SSL communication setup to the master server and SSL
client connections setup to MaxScale Binlog Server.

27
Documentation/Routers/CLI.md
View File

@ -1,13 +1,13 @@
# CLI
The command line interface as used by `maxadmin`. The _CLI_ router requires the use
of the `maxscaled` protocol.
The command line interface as used by `maxadmin`. The _CLI_ router requires the
use of the `maxscaled` protocol.
## Configuration
Two components are required in order to run the command line interface for use with
_maxadmin_; a service and a listener. The listener may either use a Unix domain socket
or an internet socket.
Two components are required to run the command line interface for _maxadmin_; a
service and a listener. The listener may either use a Unix domain socket or an
internet socket.
The default entries required are shown below.
@ -31,19 +31,20 @@ protocol=maxscaled
address=localhost
port=6603
```
In the example above, two listeners have been specified; one that listens on the
default Unix domain socket and one that listens on the default port. In the latter
case, if the `address=` entry is removed, connections are allowed from any machine
on your network.
default Unix domain socket and one that listens on the default port. In the
latter case, if the `address=` entry is removed, connections are allowed from
any machine on your network.
In the former case, if the value of `socket` is changed and in the latter case,
if the value of `port` is changed, _maxadmin_ must be invoked with the `-S` and
`-P` options respectively.
`-P` options, respectively.
Note that if Unix domain sockets are used, the connection is secure, but _maxadmin_
can only be used on the same host where MariaDB MaxScale runs. If internet sockets
are used, the connection is _inherently insecure_ but _maxadmin_ can be used from
another host than the one where MariaDB MaxScale runs.
If Unix domain sockets are used, the connection is secure, but _maxadmin_ can
only be used on the same host where MariaDB MaxScale runs. If internet sockets
are used, the connection is _inherently insecure_ but _maxadmin_ can be used
from another host than the one where MariaDB MaxScale runs.
Note that the latter approach is **deprecated** and will be removed in a future
version of MariaDB MaxScale.

36
Documentation/Routers/Debug-CLI.md
View File

@ -18,38 +18,4 @@ protocol=telnetd
port=4442
```
Connections using the telnet protocol to port 4442 of the MariaDB MaxScale host will result in a new debug CLI session. A default username and password are used for this module, new users may be created using the add user command. As soon as any users are explicitly created the default username will no longer continue to work. The default username is admin with a password of mariadb.
The debugcli supports two modes of operation, `developer` and `user`. The mode is set via the `router_options` parameter. The user mode is more suited to end-users and administrators, whilst the develop mode is explicitly targeted to software developing adding or maintaining the MariaDB MaxScale code base. Details of the differences between the modes can be found in the debugging guide for MariaDB MaxScale. The default is `user` mode. The following service definition would enable a developer version of the debugcli.
```
[Debug Service]
type=service
router=debugcli
router_options=developer
```
It should be noted that both `user` and `developer` instances of debugcli may be defined within the same instance of MariaDB MaxScale, however they must be defined as two distinct services, each with a distinct listener.
```
[Debug Service]
type=service
router=debugcli
router_options=developer
[Debug Listener]
type=listener
service=Debug Service
protocol=telnetd
port=4442
[Admin Service]
type=service
router=debugcli
[Admin Listener]
type=listener
service=Debug Service
protocol=telnetd
port=4242
```
Connections using the telnet protocol to port 4442 of the MariaDB MaxScale host will result in a new debug CLI session. A default username and password are used for this module, new users may be created using the administrative interface. As soon as any users are explicitly created the default username will no longer continue to work. The default username is `admin` with a password of `mariadb`.

4
Documentation/Routers/ReadConnRoute.md
View File

@ -8,11 +8,9 @@ The readconnroute router provides simple and lightweight load balancing across a
## Configuration
Readconnroute router-specific settings are specified in the configuration file of MariaDB MaxScale in its specific section. The section can be freely named but the name is used later as a reference from listener section.
For more details about the standard service parameters, refer to the [Configuration Guide](../Getting-Started/Configuration-Guide.md).
## Router Options
### Router Options
**`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.
```

206
Documentation/Routers/ReadWriteSplit.md
View File

@ -1,54 +1,78 @@
# Readwritesplit
This document provides a short overview of the **readwritesplit** router module and its intended use case scenarios. It also displays all router configuration parameters with their descriptions. A list of current limitations of the module is included and examples of the router's use are provided.
This document provides a short overview of the **readwritesplit** router module
and its intended use case scenarios. It also displays all router configuration
parameters with their descriptions. A list of current limitations of the module
is included and use examples are provided.
## Overview
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 **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.
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
Readwritesplit router-specific settings are specified in the configuration file of MariaDB MaxScale in its specific section. The section can be freely named but the name is used later as a reference from listener section.
Readwritesplit router-specific settings are specified in the configuration file
of MariaDB MaxScale in its specific section. The section can be freely named but
the name is used later as a reference in a listener section.
For more details about the standard service parameters, refer to the [Configuration Guide](../Getting-Started/Configuration-Guide.md).
For more details about the standard service parameters, refer to the
[Configuration Guide](../Getting-Started/Configuration-Guide.md).
## Optional parameters
### `max_slave_connections`
**`max_slave_connections`** sets the maximum number of slaves a router session uses at any moment. The default is to use all available slaves.
**`max_slave_connections`** sets the maximum number of slaves a router session
uses at any moment. The default is to use all available slaves.
max_slave_connections=<max. number, or % of available slaves>
### `max_slave_replication_lag`
**`max_slave_replication_lag`** specifies how many seconds a slave is allowed to be behind the master. If the lag is bigger than configured value a slave can't be used for routing.
**`max_slave_replication_lag`** specifies how many seconds a slave is allowed to
be behind the master. If the lag is bigger than the configured value a slave
can't be used for routing.
This feature is disabled by default.
max_slave_replication_lag=<allowed lag in seconds>
This applies to Master/Slave replication with MySQL monitor and `detect_replication_lag=1` options set.
Please note max_slave_replication_lag must be greater than monitor interval.
This applies to Master/Slave replication with MySQL monitor and
`detect_replication_lag=1` options set. max_slave_replication_lag must be
greater than the monitor interval.
This option only affects Master-Slave clusters. Galera clusters do not have a
concept of slave lag even if the application of write sets might have lag.
### `use_sql_variables_in`
**`use_sql_variables_in`** specifies where should queries, which read session variable, be routed. The syntax for `use_sql_variable_in` is:
**`use_sql_variables_in`** specifies where should queries, which read session
variable, be routed. The syntax for `use_sql_variable_in` is:
use_sql_variables_in=[master|all]
The default is to use SQL variables in all servers.
When value all is used, queries reading session variables can be routed to any available slave (depending on selection criteria). Note, that queries modifying session variables are routed to all backend servers by default, excluding write queries with embedded session variable modifications, such as:
When value `all` is used, queries reading session variables can be routed to any
available slave (depending on selection criteria). Queries modifying session
variables are routed to all backend servers by default, excluding write queries
with embedded session variable modifications, such as:
INSERT INTO test.t1 VALUES (@myid:=@myid+1)
In above-mentioned case the user-defined variable would only be updated in the master where query would be routed due to `INSERT` statement.
In above-mentioned case the user-defined variable would only be updated in the
master where the query would be routed to due to the `INSERT` statement.
**Note:** As of version 2.1 of MaxScale, all of the router options can also be
defined as parameters. The values defined in _router_options_ will have priority
@ -83,21 +107,30 @@ for a long time.
## Router options
**`router_options`** may include multiple **readwritesplit**-specific options. All the options are parameter-value pairs. All parameters listed in this section must be configured as a value in `router_options`.
**`router_options`** may include multiple **readwritesplit**-specific options.
All the options are parameter-value pairs. All parameters listed in this section
must be configured as a value in `router_options`.
Multiple options can be defined as a comma-separated list of parameter-value pairs.
Multiple options can be defined as a comma-separated list of parameter-value
pairs.
```
router_options=<option>,<option>
```
For example, to set **`slave_selection_criteria** and **`disable_sescmd_history`**, write
For example, to set **`slave_selection_criteria`** and
**`disable_sescmd_history`**, write
```
router_options=slave_selection_criteria=LEAST_GLOBAL_CONNECTIONS,disable_sescmd_history=true
```
### `slave_selection_criteria`
This option controls how the readwritesplit router chooses the slaves it connects to and how the load balancing is done. The default behavior is to route read queries to the slave server with the lowest amount of ongoing queries i.e. `LEAST_CURRENT_OPERATIONS`.
This option controls how the readwritesplit router chooses the slaves it
connects to and how the load balancing is done. The default behavior is to route
read queries to the slave server with the lowest amount of ongoing queries i.e.
`LEAST_CURRENT_OPERATIONS`.
The option syntax:
@ -112,9 +145,12 @@ Where `<criteria>` is one of the following values.
* `LEAST_BEHIND_MASTER`, the slave with smallest replication lag
* `LEAST_CURRENT_OPERATIONS` (default), the slave with least active operations
The `LEAST_GLOBAL_CONNECTIONS` and `LEAST_ROUTER_CONNECTIONS` use the connections from MariaDB MaxScale to the server, not the amount of connections reported by the server itself.
The `LEAST_GLOBAL_CONNECTIONS` and `LEAST_ROUTER_CONNECTIONS` use the
connections from MariaDB MaxScale to the server, not the amount of connections
reported by the server itself.
`LEAST_BEHIND_MASTER` does not take server weights into account when choosing a server.
`LEAST_BEHIND_MASTER` does not take server weights into account when choosing a
server.
#### Interaction Between `slave_selection_criteria` and `max_slave_connections`
@ -122,29 +158,33 @@ Depending on the value of `max_slave_connections`, the slave selection criteria
behave in different ways. Here are a few example cases of how the different
criteria work with different amounts of slave connections.
* With `slave_selection_criteria=LEAST_GLOBAL_CONNECTIONS` and `max_slave_connections=1`, each session picks
one slave and one master
* With `slave_selection_criteria=LEAST_GLOBAL_CONNECTIONS` and
`max_slave_connections=1`, each session picks one slave and one master
* With `slave_selection_criteria=LEAST_CURRENT_OPERATIONS` and `max_slave_connections=100%`, each session
picks one master and as many slaves as possible
* With `slave_selection_criteria=LEAST_CURRENT_OPERATIONS` and
`max_slave_connections=100%`, each session picks one master and as many slaves
as possible
* With `slave_selection_criteria=LEAST_CURRENT_OPERATIONS` each read is load balanced based on how many
queries are active on a particular slave
* With `slave_selection_criteria=LEAST_GLOBAL_CONNECTIONS` each read is sent to the slave with the least
amount of connections
* With `slave_selection_criteria=LEAST_CURRENT_OPERATIONS` each read is load
balanced based on how many queries are active on a particular slave
* With `slave_selection_criteria=LEAST_GLOBAL_CONNECTIONS` each read is sent to
the slave with the least amount of connections
### `max_sescmd_history`
**`max_sescmd_history`** sets a limit on how many session commands each session can execute before the session command history is disabled. The default is an unlimited number of session commands.
**`max_sescmd_history`** sets a limit on how many session commands each session
can execute before the session command history is disabled. The default is an
unlimited number of session commands.
```
# Set a limit on the session command history
router_options=max_sescmd_history=1500
```
When a limitation is set, it effectively creates a cap on the session's memory consumption. This might be useful if connection pooling is used and the sessions use large amounts of session commands.
When a limitation is set, it effectively creates a cap on the session's memory
consumption. This might be useful if connection pooling is used and the sessions
use large amounts of session commands.
### `disable_sescmd_history`
@ -157,9 +197,8 @@ This option is only intended to be enabled if the value of
`max_slave_connections` is lowered below the default value. This will allow a
failed slave to be replaced with a standby slave server.
In versions 2.0 and older, the session command history is enabled by
default. Starting with version 2.1, the session command history is disabled by
default.
In versions 2.0 and older, the session command history is enabled by default.
Starting with version 2.1, the session command history is disabled by default.
```
# Disable the session command history
@ -168,7 +207,9 @@ router_options=disable_sescmd_history=true
### `master_accept_reads`
**`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.
**`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.
By default, no reads are sent to the master.
@ -179,15 +220,17 @@ router_options=master_accept_reads=true
### `strict_multi_stmt`
When a client executes a multi-statement query, all queries after that will be routed to
the master to guarantee a consistent session state. This behavior can be controlled with
the **`strict_multi_stmt`** router option. This option is enabled by default.
When a client executes a multi-statement query, all queries after that will be
routed to the master to guarantee a consistent session state. This behavior can
be controlled with the **`strict_multi_stmt`** router option. This option is
enabled by default.
If set to false, queries are routed normally after a multi-statement query.
**Warning:** this can cause false data to be read from the slaves if the multi-statement query modifies
the session state. Only disable the strict mode if you know that no changes to the session
state will be made inside the multi-statement queries.
**Warning:** this can cause false data to be read from the slaves if the
multi-statement query modifies the session state. Only disable the strict mode
if you know that no changes to the session state will be made inside the
multi-statement queries.
```
# Disable strict multi-statement mode
@ -199,18 +242,18 @@ router_options=strict_multi_stmt=false
This option controls how the failure of a master server is handled. By default,
the router will close the client connection as soon as the master is lost.
The following table describes the values for this option and how they treat
the loss of a master server.
The following table describes the values for this option and how they treat the
loss of a master server.
|Value |Description|
| Value | Description|
|--------------|-----------|
|fail_instantly|When the failure of the master server is detected, the connection will be closed immediately.|
|fail_on_write |The client connection is closed if a write query is received when no master is available.|
|error_on_write|If no master is available and a write query is received, an error is returned stating that the connection is in read-only mode.|
|fail_instantly | When the failure of the master server is detected, the connection will be closed immediately.|
|fail_on_write | The client connection is closed if a write query is received when no master is available.|
|error_on_write | If no master is available and a write query is received, an error is returned stating that the connection is in read-only mode.|
These also apply to new sessions created after the master has failed. This means
that in _fail_on_write_ or _error_on_write_ mode, connections are accepted as long
as slave servers are available.
that in _fail_on_write_ or _error_on_write_ mode, connections are accepted as
long as slave servers are available.
**Note:** If _master_failure_mode_ is set to _error_on_write_ and the connection
to the master is lost, clients will not be able to execute write queries without
@ -218,18 +261,19 @@ reconnecting to MariaDB MaxScale once a new master is available.
### `retry_failed_reads`
This option controls whether autocommit selects are retried in case of
failure. This option is enabled by default.
This option controls whether autocommit selects are retried in case of failure.
This option is enabled by default.
When a simple autocommit select is being executed outside of a transaction
and the slave server where the query is being executed fails,
readwritesplit can retry the read on a replacement server. This makes the
failure of a slave transparent to the client.
When a simple autocommit select is being executed outside of a transaction and
the slave server where the query is being executed fails, readwritesplit can
retry the read on a replacement server. This makes the failure of a slave
transparent to the client.
## Routing hints
The readwritesplit router supports routing hints. For a detailed guide on hint
syntax and functionality, please read [this](../Reference/Hint-Syntax.md) document.
syntax and functionality, please read [this](../Reference/Hint-Syntax.md)
document.
**Note**: Routing hints will always have the highest priority when a routing
decision is made. This means that it is possible to cause inconsistencies in
@ -239,55 +283,79 @@ hints when you are sure that they can cause no harm.
## Limitations
For a list of readwritesplit limitations, please read the [Limitations](../About/Limitations.md) document.
For a list of readwritesplit limitations, please read the
[Limitations](../About/Limitations.md) document.
## Examples
Examples of the readwritesplit router in use can be found in the [Tutorials](../Tutorials) folder.
Examples of the readwritesplit router in use can be found in the
[Tutorials](../Tutorials) folder.
## Readwritesplit routing decisions
Here is a small explanation which shows what kinds of queries are routed to which type of server.
Here is a small explanation which shows what kinds of queries are routed to
which type of server.
### Routing to Master
Routing to master is important for data consistency and because majority of writes are written to binlog and thus become replicated to slaves.
Routing to master is important for data consistency and because majority of
writes are written to binlog and thus become replicated to slaves.
The following operations are routed to master:
* write statements,
* all statements within an open transaction,
* stored procedure calls, and
* user-defined function calls.
* stored procedure calls
* user-defined function calls
* DDL statements (`DROP`|`CREATE`|`ALTER TABLE` … etc.)
* `EXECUTE` (prepared) statements
* all statements using temporary tables
In addition to these, if the **readwritesplit** service is configured with the `max_slave_replication_lag` parameter, and if all slaves suffer from too much replication lag, then statements will be routed to the _Master_. (There might be other similar configuration parameters in the future which limit the number of statements that will be routed to slaves.)
In addition to these, if the **readwritesplit** service is configured with the
`max_slave_replication_lag` parameter, and if all slaves suffer from too much
replication lag, then statements will be routed to the _Master_. (There might be
other similar configuration parameters in the future which limit the number of
statements that will be routed to slaves.)
### Routing to Slaves
The ability to route some statements to *Slave*s is important because it also decreases the load targeted to master. Moreover, it is possible to have multiple slaves to share the load in contrast to single master.
The ability to route some statements to slaves is important because it also
decreases the load targeted to master. Moreover, it is possible to have multiple
slaves to share the load in contrast to single master.
Queries which can be routed to slaves must be auto committed and belong to one of the following group:
Queries which can be routed to slaves must be auto committed and belong to one
of the following group:
* read-only database queries,
* read-only queries to system, or user-defined variables,
* `SHOW` statements, and
* `SHOW` statements
* system function calls.
### Routing to every session backend
A third class of statements includes those which modify session data, such as session system variables, user-defined variables, the default database, etc. We call them session commands, and they must be replicated as they affect the future results of read and write operations, so they must be executed on all servers that could execute statements on behalf of this client.
A third class of statements includes those which modify session data, such as
session system variables, user-defined variables, the default database, etc. We
call them session commands, and they must be replicated as they affect the
future results of read and write operations. They must be executed on all
servers that could execute statements on behalf of this client.
Session commands include for example:
* `SET` statements
* `USE `*`<dbname>`*
* system/user-defined variable assignments embedded in read-only statements, such as `SELECT (@myvar := 5)`
* system/user-defined variable assignments embedded in read-only statements, such
as `SELECT (@myvar := 5)`
* `PREPARE` statements
* `QUIT`, `PING`, `STMT RESET`, `CHANGE USER`, etc. commands
**NOTE: if variable assignment is embedded in a write statement it is routed to _Master_ only. For example, `INSERT INTO t1 values(@myvar:=5, 7)` would be routed to _Master_ only.**
**NOTE**: if variable assignment is embedded in a write statement it is routed
to _Master_ only. For example, `INSERT INTO t1 values(@myvar:=5, 7)` would be
routed to _Master_ only.
The router stores all of the executed session commands so that in case of a slave failure, a replacement slave can be chosen and the session command history can be repeated on that new slave. This means that the router stores each executed session command for the duration of the session. Applications that use long-running sessions might cause MariaDB MaxScale to consume a growing amount of memory unless the sessions are closed. This can be solved by setting a connection timeout on the application side.
The router stores all of the executed session commands so that in case of a
slave failure, a replacement slave can be chosen and the session command history
can be repeated on that new slave. This means that the router stores each
executed session command for the duration of the session. Applications that use
long-running sessions might cause MariaDB MaxScale to consume a growing amount
of memory unless the sessions are closed. This can be solved by setting a
connection timeout on the application side.

8
Documentation/Routers/SchemaRouter.md
View File

@ -1,4 +1,4 @@
#SchemaRouter Router
# SchemaRouter Router
The SchemaRouter router provides an easy and manageable sharding solution by building a single logical database server from multiple separate ones. Each database is shown to the client and queries targeting unique databases are routed to their respective servers. In addition to providing simple database-based sharding, the schemarouter router also enables cross-node session variable usage by routing all queries that modify the session to all nodes.
@ -29,7 +29,7 @@ The list of databases is built by sending a SHOW DATABASES query to all the serv
If you are connecting directly to a database or have different users on some of the servers, you need to get the authentication data from all the servers. You can control this with the `auth_all_servers` parameter. With this parameter, MariaDB MaxScale forms a union of all the users and their grants from all the servers. By default, the schemarouter will fetch the authentication data from all servers.
For example, if two servers have the database 'shard' and the following rights are granted only on one server, all queries targeting the database 'shard' would be routed to the server where the grants were given.
For example, if two servers have the database `shard` and the following rights are granted only on one server, all queries targeting the database `shard` would be routed to the server where the grants were given.
```
# Execute this on both servers
@ -68,6 +68,8 @@ refresh_interval=60
## Router Options
**Note:** Router options for the Schemarouter were deprecated in MaxScale 2.1.
The following options are options for the `router_options` parameter of the
service. Multiple router options are given as a comma separated list of key
value pairs.
@ -87,7 +89,7 @@ will not be consistent anymore.
### `refresh_databases`
Enable database map refreshing mid-session. These are triggered by a failure to
change the database i.e. `USE ...``queries.
change the database i.e. `USE ...` queries.
### `refresh_interval`

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

@ -1,10 +1,9 @@
# MariaDB MaxScale Administration Tutorial
Last updated 24th June 2015
## Common Administration Tasks
The purpose of this tutorial is to introduce the MariaDB MaxScale Administrator to a few of the common administration tasks that need to be performed with MariaDB MaxScale. It is not intended as a reference to all the tasks that may be performed, more this is aimed as an introduction for administrators who are new to MariaDB MaxScale.
The purpose of this tutorial is to introduce the MariaDB MaxScale Administrator
to a few of the common administration tasks. This is intended to be an
introduction for administrators who are new to MariaDB MaxScale and not a
reference to all the tasks that may be performed.
- [Starting MariaDB MaxScale](#starting)
- [Stopping MariaDB MaxScale](#stopping)
@ -15,51 +14,86 @@ The purpose of this tutorial is to introduce the MariaDB MaxScale Administrator
- [Taking A Database Server Out Of Use](#outofuse)
<a name="starting"></a>
### Starting MariaDB MaxScale
## Starting MariaDB MaxScale
There are several ways to start MariaDB MaxScale, the most convenient mechanism
is probably using the Linux service interface. When a MariaDB MaxScale package
is installed, the package manager will also install a script in /etc/init.d
which may be used to start and stop MariaDB MaxScale either directly or via the
service interface.
There are several ways to start MariaDB MaxScale, the most convenient mechanism is probably using the Linux service interface. When a MariaDB MaxScale package is installed the package manager will also installed a script in /etc/init.d which may be used to start and stop MariaDB MaxScale either directly or via the service interface.
```
$ service maxscale start
```
or
```
$ /etc/init.d/maxscale start
```
It is also possible to start MariaDB MaxScale by executing the maxscale command itself. Running the executable /usr/bin/maxscale will result in MariaDB 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 MariaDB MaxScale binary that alter this default behavior. For a full list of all parameters, refer to the MariaDB MaxScale help output by executing `maxscale --help`.
It is also possible to start MariaDB MaxScale by executing the maxscale command
itself. Running the executable /usr/bin/maxscale will result in MariaDB 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.
Additional command line arguments can be passed to MariaDB MaxScale with a configuration file placed at `/etc/sysconfig/maxscale` on RPM installations and `/etc/default/maxscale` file on DEB installations. Set the arguments in a variable called `MAXSCALE_OPTIONS` and remember to surround the arguments with quotes. The file should only contain environment variable declarations.
Options may be passed to the MariaDB MaxScale binary that alter this default
behavior. For a full list of all parameters, refer to the MariaDB MaxScale help
output by executing `maxscale --help`.
Additional command line arguments can be passed to MariaDB MaxScale with a
configuration file placed at `/etc/sysconfig/maxscale` on RPM installations and
`/etc/default/maxscale` file on DEB installations. Set the arguments in a
variable called `MAXSCALE_OPTIONS` and remember to surround the arguments with
quotes. The file should only contain environment variable declarations.
```
MAXSCALE_OPTIONS="--logdir=/home/maxscale/logs --piddir=/tmp --syslog=no"
```
<a name="stopping"></a>
### Stopping MariaDB MaxScale
## Stopping MariaDB MaxScale
There are numerous ways in which MariaDB MaxScale can be stopped; using the service interface, killing the process or by use of the maxadmin utility.
There are numerous ways in which MariaDB MaxScale can be stopped; using the
service interface, killing the process or by using the maxadmin utility.
Stopping MariaDB 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.
Stopping MariaDB 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
```
MariaDB MaxScale will also stop gracefully if it received a terminate signal, to find the process id of the MariaDB MaxScale server use the ps command or read the contents of the maxscale.pid file located in the /var/run/maxscale directory.
MariaDB MaxScale will also stop gracefully if it received a terminate signal, to
find the process id of the MariaDB 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 MariaDB 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.
In order to shutdown MariaDB 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 shutdown maxscale
```
<a name="checking"></a>
### Checking The Status Of The MariaDB MaxScale Services
It is possible to use the maxadmin command to obtain statistics regarding the services that are configured within your MariaDB 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.
<a name="checking"></a>
## Checking The Status Of The MariaDB MaxScale Services
It is possible to use the maxadmin command to obtain statistics about the
services that are running within MaxScale. The maxadmin command "list services"
will give very basic information regarding services. This command may be either
run in interactive mode or passed on the maxadmin command line.
```
$ maxadmin
@ -84,36 +118,38 @@ 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.
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 details can be
obtained by using the "show service" command.
<a name="persistent"></a>
### Persistent Connections
## Persistent Connections
Where the clients who are accessing a database system through MariaDB MaxScale make frequent
short connections, there may be a benefit from invoking the MariaDB MaxScale Persistent
Connection feature. This is controlled by two configuration values that are specified
per server in the relevant server section of the configuration file. The configuration
options are `persistpoolmax` and `persistmaxtime`.
When clients who are accessing a database system through MariaDB MaxScale make
frequent short connections, there may be a benefit in using persistent
connections. This feature is controlled by two configuration values that are
specified per server in the relevant server section of the configuration file.
The configuration options are `persistpoolmax` and `persistmaxtime`.
Normally, when a client connection is terminated, all the related back end database
connections are also terminated. If the `persistpoolmax` options is set to a non-zero
integer, then up to that number of connections will be kept in a pool for that
server. When a new connection is requested by the system to meet a new client request,
then a connection from the pool will be used if possible.
Normally, when a client connection is terminated, all the related back end
database connections are also terminated. If the `persistpoolmax` options is set
to a non-zero integer, then up to that number of connections will be kept in a
pool for that server. When a new connection is requested by the system to handle
a client session, then a connection from the pool will be used if possible.
The connection will only be taken from the pool if it has been there for no more
than `persistmaxtime` seconds. It was also be discarded if it has been disconnected
by the back end server. Connections will be selected that match the user name and
protocol for the new request.
than `persistmaxtime` seconds. The connection will also be discarded if it has
been disconnectedby the back end server. Connections will be selected so that
they match the user name and protocol for the new request.
Starting with the 2.1 version of MaxScale, when a MySQL protocol connection is
taken from the pool the backend protocol module resets the session state. This
allows persistent connections to be used with no functional limitations.
Starting with MaxScale 2.1, when a MySQL protocol connection is taken from the
pool, the backend protocol module resets the session state. This allows
persistent connections to be used with no functional limitations.
The session state is reset when the first outgoing network transmission is
done. This _lazy initialization_ of the persistent connections allows
MaxScale to take multiple new connections into use but only initialize the
ones that it actually needs.
The session state is reset when the first outgoing network transmission is done.
This _lazy initialization_ of the persistent connections allows MaxScale to take
multiple new connections into use but only initialize the ones that it actually
needs.
**Please note** that in versions before 2.1 the persistent connections may give
a different environment when compared to a fresh connection. For example, if the
@ -127,9 +163,13 @@ It is possible to have pools for as many servers as you wish, with configuration
values in each server section.
<a name="clients"></a>
### What Clients Are Connected To MariaDB MaxScale
## What Clients Are Connected To MariaDB MaxScale
To determine what client are currently connected to MariaDB 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.
To determine what client are currently connected to MariaDB 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 list clients
@ -148,29 +188,45 @@ To determine what client are currently connected to MariaDB MaxScale you can use
$
```
<a name="rotating"></a>
### Rotating the Log File
## Rotating the Log File
MariaDB MaxScale logs messages of different priority into a single log file. With the exception if error messages that are always logged, whether messages of a particular priority should be logged or not can be enabled via the maxadmin interface or in the configuration file. By default, MaxScale keeps on writing to the same log file, so to prevent the file from growing indefinitely, the administrator must take action.
MariaDB MaxScale logs messages of different priority into a single log file.
With the exception if error messages that are always logged, whether messages of
a particular priority should be logged or not can be enabled via the maxadmin
interface or in the configuration file. By default, MaxScale keeps on writing to
the same log file. To prevent the file from growing indefinitely, the
administrator must take action.
When MaxScale is started for the first time, the name of the log file is maxscale1.log. When the log is rotated, MaxScale closes the current log file and opens a new one where the sequence number is increased by one. That is, the first time the log is rotated, the name will be maxscale2.log.
The name of the log file is maxscale.log. When the log is rotated, MaxScale
closes the current log file and opens a new one using the same name.
Log file rotation is achieved by use of the "flush log" or “flush logs” command
in maxadmin.
Log file rotation is achieved by use of the "flush log" or “flush logs” command in maxadmin.
```
$ maxadmin flush logs
```
Flushes all logs. However, as there currently is only the maxscale log, that is the only one that will be rotated.
As there currently is only the maxscale log, that is the only one that will be
rotated.
The maxscale log can also be flushed explicitly.
```
$ maxadmin
MaxScale> flush log maxscale
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.
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 as follows.
```
/var/log/maxscale/*.log {
/var/log/maxscale/maxscale.log {
monthly
rotate 5
missingok
@ -186,16 +242,19 @@ endscript
```
**Note**:
If 'root' user is no longer available for maxadmin connection and say 'user1' is one of the allowed users, the maxadmin command should be run this way:
`
su - user1 -c '/usr/bin/maxadmin flush logs'
`
If 'root' user is no longer available for maxadmin connection and for example
'user1' is one of the allowed users, the maxadmin command should be run as:
`su - user1 -c '/usr/bin/maxadmin flush logs'`
If listening socket is not the default one, /tmp/maxadmin.sock, use -S option.
MariaDB 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
MariaDB 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
```
/var/log/maxscale/*.log {
/var/log/maxscale/maxscale.log {
monthly
rotate 5
missingok
@ -207,24 +266,46 @@ endscript
}
```
*NOTE* Since MaxScale currently renames the log file, the behaviour is not fully compliant with the assumptions of logrotate and may lead to issues, depending on the used logrotate configuration file. From version 2.1 onwards, MaxScale will not itself rename the log file, but when the log is rotated, MaxScale will simply close and reopen (and truncate) the same log file. That will make the behaviour fully compliant with logrotate.
Since MaxScale currently renames the log file, the behaviour is not fully
compliant with the assumptions of logrotate and may lead to issues, depending on
the used logrotate configuration file. From version 2.1 onwards, MaxScale will
not itself rename the log file, but when the log is rotated, MaxScale will
simply close and reopen (and truncate) the same log file. That will make the
behaviour fully compliant with logrotate.
<a name="outofuse"></a>
### Taking A Database Server Out Of Use
## Taking A Database Server Out Of Use
MariaDB 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 MariaDB MaxScale configuration.
MariaDB 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 MariaDB 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.
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 MariaDB 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.
This will cause MariaDB 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 MariaDB MaxScale restarts when a node is in maintenance mode a new instance of MariaDB MaxScale will not honor this mode. If multiple MariaDB MaxScale instances are configured to use the node them maintenance mode must be set within each MariaDB MaxScale instance. However if multiple services within one MariaDB 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.
Note that maintenance mode is not persistent, if MariaDB MaxScale restarts when
a node is in maintenance mode a new instance of MariaDB MaxScale will not honor
this mode. If multiple MariaDB MaxScale instances are configured to use the node
them maintenance mode must be set within each MariaDB MaxScale instance. However
if multiple services within one MariaDB 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.

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

@ -2,33 +2,53 @@
# Environment & Solution Space
The object of this tutorial is to have a system that has two ports available, one for write connections to the database cluster and the other for read connections to the database.
The object of this tutorial is to have a system that has two ports available, one for
write connections to the database cluster and the other for read connections to the database.
## Setting up MariaDB MaxScale
The first part of this tutorial is covered in [MariaDB MaxScale Tutorial](MaxScale-Tutorial.md). Please read it and follow the instructions for setting up MariaDB MaxScale with the type of cluster you want to use.
The first part of this tutorial is covered in [MariaDB MaxScale Tutorial](MaxScale-Tutorial.md).
Please read it and follow the instructions for setting up MariaDB MaxScale with the
type of cluster you want to use.
Once you have MariaDB MaxScale installed and the database users created, we can create the configuration file for MariaDB MaxScale.
Once you have MariaDB MaxScale installed and the database users created, we can create
the configuration file for MariaDB MaxScale.
## Creating Your MariaDB MaxScale Configuration
MariaDB 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.
MariaDB 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 MariaDB MaxScale configuration file; this is used to set the values of various MariaDB MaxScale wide parameters, perhaps the most important of these is the number of threads that MariaDB MaxScale will use to execute the code that forwards requests and handles responses for clients.
A global, maxscale, section is included within every MariaDB MaxScale configuration file;
this is used to set the values of various MariaDB MaxScale wide parameters, perhaps
the most important of these is the number of threads that MariaDB MaxScale will use
to execute the code that forwards requests and handles responses for clients.
```
[maxscale]
threads=4
```
Since we are using Galera Cluster and connection routing we want a single to which the client application can connect; MariaDB MaxScale will then route connections to this port onwards to the various nodes within the Galera Cluster. To achieve this within MariaDB MaxScale we need to define a service in the ini file. Create a section for each in your MariaDB MaxScale configuration file and set the type to service, the section name is the names of the service and should be meaningful to the administrator. Names may contain whitespace.
Since we are using Galera Cluster and connection routing we want a single to which
the client application can connect; MariaDB MaxScale will then route connections to
this port onwards to the various nodes within the Galera Cluster. To achieve this
within MariaDB MaxScale we need to define a service in the ini file. Create a section
for each in your MariaDB MaxScale configuration file and set the type to service,
the section name is the names of the service and should be meaningful to
the administrator. Names may contain whitespace.
```
[Galera Service]
type=service
```
The router for this section the readconnroute module, also the service 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.
The router for this section the readconnroute module, also the service 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.
```
[Galera Service]
@ -37,7 +57,12 @@ 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 option that restricts us to servers that are fully functional members of the Galera cluster which are able to support SQL operations on the cluster. To achieve this we use the router option synced.
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 option that restricts us to servers that are
fully functional members of the Galera cluster which are able to support SQL operations
on the cluster. To achieve this we use the router option synced.
```
[Galera Service]
@ -47,14 +72,20 @@ router_options=synced
servers=dbserv1, dbserv2, dbserv3
```
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.
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 /var/lib/maxscale/.secrets
%
```
Once the keys have been created the maxpasswd command can be used to generate the encrypted password.
Once the keys have been created the maxpasswd command can be used to generate
the encrypted password.
```
% maxpasswd plainpassword
@ -62,7 +93,8 @@ Once the keys have been created the maxpasswd command can be used to generate th
%
```
The username and password, either encrypted or plain text, are stored in the service section using the user and passwd parameters.
The username and password, either encrypted or plain text, are stored in the service
section using the user and passwd parameters.
```
[Galera Service]
@ -74,7 +106,12 @@ user=maxscale
passwd=96F99AA1315BDC3604B006F427DD9484
```
This completes the definitions required by the service, however listening ports must be associated with a service 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.
This completes the definitions required by the service, however listening ports must
be associated with a service 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.
```
[Galera Listener]
@ -82,7 +119,10 @@ type=listener
service=Galera 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.
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.
```
[Galera Listener]
@ -93,9 +133,15 @@ port=4306
socket=/tmp/DB.Cluster
```
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.
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.
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]
@ -117,7 +163,12 @@ port=3306
protocol=MySQLBackend
```
In order for MariaDB 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.
In order for MariaDB 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 servers with the monitor.
```
[Galera Monitor]
@ -128,9 +179,12 @@ user=maxscale
passwd=96F99AA1315BDC3604B006F427DD9484
```
As with the password definition in the server either plain text or encrypted passwords may be used.
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 MariaDB MaxScale for monitoring and administration purposes. This creates a service section and a listener section.
The final stage in the configuration is to add the option service which is used by
the maxadmin command to connect to MariaDB MaxScale for monitoring and
administration purposes. This creates a service section and a listener section.
```
[CLI]
@ -145,7 +199,9 @@ socket=default
## Starting MariaDB MaxScale
Upon completion of the configuration process MariaDB 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.
Upon completion of the configuration process MariaDB 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
@ -157,7 +213,10 @@ or
% service maxscale start
```
Check the error log in /var/log/maxscale to see if any errors are detected in the configuration file and to confirm MariaDB MaxScale has been started. Also the maxadmin command may be used to confirm that MariaDB 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 MariaDB MaxScale has been started.
Also the maxadmin command may be used to confirm that MariaDB MaxScale is running
and the services, listeners etc have been correctly configured.
```
% maxadmin list services
@ -180,9 +239,14 @@ dbserv3 | 192.168.2.3 | 3306 | 0 | Running, Synced, Sl
-------------------+-----------------+-------+-------------+--------------------
```
A Galera Cluster is a multi-master clustering technology, however the monitor is able to impose false notions of master and slave roles within a Galera Cluster in order to facilitate the use of Galera as if it were a standard MySQL Replication setup. This is merely an internal MariaDB MaxScale convenience and has no impact on the behavior of the cluster.
A Galera Cluster is a multi-master clustering technology, however the monitor is able
to impose false notions of master and slave roles within a Galera Cluster in order to
facilitate the use of Galera as if it were a standard MySQL Replication setup.
This is merely an internal MariaDB MaxScale convenience and has no impact on the behavior of the cluster.
You can control which Galera node is the master server by using the _priority_ mechanism of the Galera Monitor module. For more details, read the [Galera Monitor](../Monitors/Galera-Monitor.md) documentation.
You can control which Galera node is the master server by using the _priority_
mechanism of the Galera Monitor module. For more details,
read the [Galera Monitor](../Monitors/Galera-Monitor.md) documentation.
```
% maxadmin list listeners
@ -197,4 +261,10 @@ CLI | maxscaled | localhost | 6603 | Running
%
```
MariaDB 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, such as using weights to obtain unequal balancing operations. These options may be found in the MariaDB MaxScale Configuration Guide. More detail on the use of maxadmin can be found in the document ["MaxAdmin - The MariaDB MaxScale Administration & Monitoring Client Application"](../Reference/MaxAdmin.md).
MariaDB 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, such as using weights to
obtain unequal balancing operations.
These options may be found in the MariaDB MaxScale Configuration Guide.
More detail on the use of maxadmin can be found in the document
["MaxAdmin - The MariaDB MaxScale Administration & Monitoring Client Application"](../Reference/MaxAdmin.md).

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

@ -12,7 +12,7 @@ Once you have MariaDB MaxScale installed and the database users created, we can
## Creating Your MariaDB MaxScale Configuration
MariaDB 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.
MariaDB 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 MariaDB MaxScale configuration file; this is used to set the values of various MariaDB MaxScale wide parameters, perhaps the most important of these is the number of threads that MariaDB MaxScale will use to execute the code that forwards requests and handles responses for clients.
@ -71,7 +71,7 @@ type=listener
service=Splitter 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.
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.
```
[Splitter Listener]
@ -84,7 +84,7 @@ socket=/tmp/ClusterMaster
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 module for all database connections in MySQLBackend.
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 module for all database connections in `MySQLBackend`.
```
[dbserv1]
@ -119,7 +119,7 @@ passwd=96F99AA1315BDC3604B006F427DD9484
As with the password definition in the server either plain text or encrypted passwords may be used.
This monitor module will assign one node within the Galera Cluster as the current master and other nodes as slave. Only those nodes that are active members of the cluster are considered when making the choice of master node. Normally the master node will be the node with the lowest value of the status variable, WSREP_LOCAL_INDEX. When cluster membership changes a new master may be elected. In order to prevent changes of the node that is currently master, a parameter can be added to the monitor that will result in the current master remaining as master even if a node with a lower value of WSREP_LOCAL_INDEX joins the cluster. This parameter is called disable_master_failback.
This monitor module will assign one node within the Galera Cluster as the current master and other nodes as slave. Only those nodes that are active members of the cluster are considered when making the choice of master node. Normally the master node will be the node with the lowest value of the status variable, `WSREP_LOCAL_INDEX`. When cluster membership changes a new master may be elected. In order to prevent changes of the node that is currently master, a parameter can be added to the monitor that will result in the current master remaining as master even if a node with a lower value of `WSREP_LOCAL_INDEX` joins the cluster. This parameter is called `disable_master_failback`.
```
[Galera Monitor]
@ -159,7 +159,7 @@ or
% service maxscale start
```
Check the error log in /var/log/maxscale to see if any errors are detected in the configuration file and to confirm MariaDB MaxScale has been started. Also the maxadmin command may be used to confirm that MariaDB 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 MariaDB MaxScale has been started. Also the maxadmin command may be used to confirm that MariaDB MaxScale is running and the services, listeners etc have been correctly configured.
```
% maxadmin list services
@ -199,4 +199,4 @@ CLI | maxscaled | localhost | 6603 | Running
---------------------+--------------------+-----------------+-------+--------
```
MariaDB 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 MariaDB MaxScale Configuration Guide. More detail on the use of maxadmin can be found in the document "MaxAdmin - The MariaDB MaxScale Administration & Monitoring Client Application".
MariaDB 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 MariaDB MaxScale Configuration Guide. More details on the use of maxadmin can be found in the document _MaxAdmin - The MariaDB MaxScale Administration & Monitoring Client Application_.

99
Documentation/Tutorials/MaxScale-HA-with-Corosync-Pacemaker.md
View File

@ -12,15 +12,15 @@ Please note the solution is a quick setup example that may not be suited for all
## Clustering Software installation
On each node in the cluster do the following steps:
On each node in the cluster do the following steps.
(1) Add clustering repos to yum
### Add clustering repos to yum
```
# vi /etc/yum.repos.d/ha-clustering.repo
```
Add the following to the file
Add the following to the file.
```
[haclustering]
@ -30,7 +30,7 @@ enabled=1
gpgcheck=0
```
(2) Install the software
### Install the software
```
# yum install pacemaker corosync crmsh
@ -44,7 +44,7 @@ Package corosync-1.4.5-2.4.x86_64
Package crmsh-2.0+git46-1.1.x86_64
```
(3) Assign hostname on each node
### Assign hostname on each node
In this example the three names used for the nodes are: node1,node,node3
@ -56,7 +56,7 @@ In this example the three names used for the nodes are: node1,node,node3
[root@server3 ~]# hostname node3
```
(4) For each node add server names in /etc/hosts
For each node, add all the server names into `/etc/hosts`.
```
[root@node3 ~]# vi /etc/hosts
@ -70,9 +70,9 @@ In this example the three names used for the nodes are: node1,node,node3
10.35.15.26 node3
```
**Please note**: add **current-node** as an alias for the current node in each of the /etc/hosts files.
**Note**: add _current-node_ as an alias for the current node in each of the /etc/hosts files.
(5) Prepare authkey for optional cryptographic use
### Prepare authkey for optional cryptographic use
On one of the nodes, say node2 run the corosync-keygen utility and follow
@ -84,7 +84,7 @@ Corosync Cluster Engine Authentication key generator. Gathering 1024 bits
After completion the key will be found in /etc/corosync/authkey.
```
(6) Prepare the corosync configuration file
### Prepare the corosync configuration file
Using node2 as an example:
@ -141,7 +141,7 @@ name: pacemaker
}
```
**Please note** in this example:
**Note**: in this example:
- unicast UDP is used
@ -149,7 +149,7 @@ name: pacemaker
- Pacemaker processes are started by the corosync daemon, so there is no need to launch it via /etc/init.d/pacemaker start
(7) copy configuration files and auth key on each of the other nodes
### Copy configuration files and auth key on each of the other nodes
```
[root@node2 ~]# scp /etc/corosync/* root@node1:/etc/corosync/
@ -157,11 +157,7 @@ name: pacemaker
[root@node2 ~]# scp /etc/corosync/* root@nodeN:/etc/corosync/
```
(8) Corosync needs port *5*405 to be opened:
- configure any firewall or iptables accordingly
For a quick start just disable iptables on each nodes:
Corosync needs port 5405 to be opened. Configure any firewall or iptables accordingly. For a quick start just disable iptables on each nodes:
```
[root@node2 ~]# service iptables stop
@ -169,7 +165,7 @@ For a quick start just disable iptables on each nodes:
[root@nodeN ~]# service iptables stop
```
(9) Start Corosyn on each node:
### Start Corosyn on each node
```
[root@node2 ~] #/etc/init.d/corosync start
@ -177,14 +173,14 @@ For a quick start just disable iptables on each nodes:
[root@nodeN ~] #/etc/init.d/corosync start
```
and check the corosync daemon is successfully bound to port 5405:
Check that the corosync daemon is successfully bound to port 5405.
```
[root@node2 ~] #netstat -na | grep 5405
udp 0 0 10.228.103.72:5405 0.0.0.0:*
```
Check if other nodes are reachable with nc utility and option UDP (-u):
Check if other nodes are reachable with nc utility and option UDP (-u).
```
[root@node2 ~] #echo "check ..." | nc -u node1 5405
@ -194,19 +190,21 @@ Check if other nodes are reachable with nc utility and option UDP (-u):
[root@node1 ~] #echo "check ..." | nc -u node3 5405
```
If the following message is displayed
If the following message is displayed, there is an issue with communication between the nodes.
**nc: Write error: Connection refused**
```
nc: Write error: Connection refused
```
There is an issue with communication between the nodes, this is most likely to be an issue with the firewall configuration on your nodes. Check and resolve issues with your firewall configuration.
This is most likely to be an issue with the firewall configuration on your nodes. Check and resolve any issues with your firewall configuration.
(10) Check the cluster status, from any node
### Check the cluster status from any node
```
[root@node3 ~]# crm status
```
After a while this will be the output:
The command should produce the following.
```
[root@node3 ~]# crm status
@ -239,9 +237,9 @@ For additional information see:
[http://clusterlabs.org/doc/](http://clusterlabs.org/doc/)
The configuration is automatically updated on every node:
The configuration is automatically updated on every node.
Check it from another node, say node1
Check it from another node, say node1:
```
[root@node1 ~]# crm configure show
@ -260,9 +258,9 @@ property cib-bootstrap-options: \
The Corosync / Pacemaker cluster is ready to be configured to manage resources.
## MariaDB MaxScale init script /etc/init.d/maxscale
## MariaDB MaxScale init script
The MariaDB MaxScale /etc/init.d./maxscale script allows to start/stop/restart and monitor MariaDB MaxScale process running in the system.
The MariaDB MaxScale init script in `/etc/init.d./maxscale` allows to start, stop, restart and monitor the MariaDB MaxScale process running on the system.
```
[root@node1 ~]# /etc/init.d/maxscale
@ -315,14 +313,11 @@ Checking MaxScale status: MaxScale (pid 25953) is running.[ OK ]
The script exit code for "status" is 0
Note: the MariaDB MaxScale script is LSB compatible and returns the proper exit code for each action:
For additional information;
Read the following for additional information about LSB init scripts:
[http://www.linux-ha.org/wiki/LSB_Resource_Agents](http://www.linux-ha.org/wiki/LSB_Resource_Agents)
After checking MariaDB MaxScale is well managed by the /etc/init.d/script is possible to configure the MariaDB MaxScale HA via Pacemaker.
After checking that the init scripts for MariaDB MaxScale work, it is possible to configure MariaDB MaxScale for HA via Pacemaker.
# Configure MariaDB MaxScale for HA with Pacemaker
@ -333,7 +328,7 @@ op start interval="0” timeout=”15s” \
op stop interval="0” timeout=”30s”
```
MaxScale resource will be started:
MaxScale resource will be started.
```
[root@node2 ~]# crm status
@ -351,11 +346,11 @@ Online: [ node1 node2 node3 ]
MaxScale (lsb:maxscale): Started node1
```
##Basic use cases:
## Basic use cases
### 1. Resource restarted after a failure:
### Resource restarted after a failure
In the example MariaDB MaxScale PID is 26114, kill the process immediately:
In the example MariaDB MaxScale PID is 26114, kill the process immediately.
```
[root@node2 ~]# kill -9 26114
@ -377,9 +372,9 @@ Failed actions:
MaxScale_monitor_15000 on node1 'not running' (7): call=19, status=complete, last-rc-change='Mon Jun 30 13:16:14 2014', queued=0ms, exec=0ms
```
**Note** the **MaxScale_monitor** failed action
**Note**: the _MaxScale_monitor_ failed action
After a few seconds it will be started again:
After a few seconds it will be started again.
```
[root@node2 ~]# crm status
@ -397,9 +392,9 @@ Online: [ node1 node2 node3 ]
MaxScale (lsb:maxscale): Started node1
```
### 2. The resource cannot be migrated to node1 for a failure:
### The resource cannot be migrated to node1 for a failure
First, migrate the the resource to another node, say node3
First, migrate the the resource to another node, say node3.
```
[root@node1 ~]# crm resource migrate MaxScale node3
@ -412,7 +407,7 @@ Failed actions:
MaxScale_start_0 on node1 'not running' (7): call=76, status=complete, last-rc-change='Mon Jun 30 13:31:17 2014', queued=2015ms, exec=0ms
```
Note the **MaxScale_start** failed action on node1, and after a few seconds
**Note**: the _MaxScale_start_ failed action on node1, and after a few seconds.
```
[root@node3 ~]# crm status
@ -434,7 +429,7 @@ Failed actions:
MaxScale_start_0 on node1 'not running' (7): call=76, status=complete, last-rc-change='Mon Jun 30 13:31:17 2014', queued=2015ms, exec=0ms
```
Successfully, MaxScale has been started on a new node: node2.
Successfully, MaxScale has been started on a new node (node2).
**Note**: Failed actions remain in the output of crm status.
@ -447,7 +442,7 @@ Cleaning up MaxScale on node2
Cleaning up MaxScale on node3
```
The cleaned status is visible from other nodes as well:
The cleaned status is visible from other nodes as well.
```
[root@node2 ~]# crm status
@ -467,25 +462,21 @@ Online: [ node1 node2 node3 ]
## Add a Virtual IP (VIP) to the cluster
It’s possible to add a virtual IP to the cluster:
It’s possible to add a virtual IP to the cluster. MariaDB MaxScale process will be only contacted via this IP. The virtual IP can move across nodes in case one of them fails.
MariaDB MaxScale process will be only contacted with this IP, that mat move across nodes with maxscale process as well.
Setup is very easy:
assuming an addition IP address is available and can be added to one of the nodes, this i the new configuration to add:
The Setup is very easy. Assuming an addition IP address is available and can be added to one of the nodes, this is the new configuration to add.
```
[root@node2 ~]# crm configure primitive maxscale_vip ocf:heartbeat:IPaddr2 params ip=192.168.122.125 op monitor interval=10s
```
MariaDB MaxScale process and the VIP must be run in the same node, so it’s mandatory to add to the configuration the group ‘maxscale_service’.
MariaDB MaxScale process and the VIP must be run in the same node, so it is mandatory to add to the configuration to the group ‘maxscale_service’.
```
[root@node2 ~]# crm configure group maxscale_service maxscale_vip MaxScale
```
The final configuration is, from another node:
The following is the final configuration.
```
[root@node3 ~]# crm configure show
@ -511,7 +502,7 @@ property cib-bootstrap-options: \
last-lrm-refresh=1404125486
```
Check the resource status:
Check the resource status.
```
[root@node1 ~]# crm status
@ -533,5 +524,5 @@ Online: [ node1 node2 node3 ]
MaxScale (lsb:maxscale): Started node2
```
With both resources on node2, now MariaDB MaxScale service will be reachable via the configured VIP address 192.168.122.125
With both resources on node2, now MariaDB MaxScale service will be reachable via the configured VIP address 192.168.122.125.

2
Documentation/Tutorials/MaxScale-HA-with-lsyncd.md
View File

@ -2,7 +2,7 @@
***This guide was written for lsyncd 2.1.5.***
This document guides you in setting up multiple MariaDB 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.
This document guides you in setting up multiple MariaDB 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 administrators to easily provide a highly available, disaster resistant MariaDB MaxScale installation with up-to-date configuration files on all the hosts.

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

@ -5,9 +5,9 @@ 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` configuration file in much the same way as any other router service is configured; there must 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 service entry should 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.
@ -196,7 +196,7 @@ mysql>
The show services command does not accept a like clause and will ignore any like clause that is given.
## Show listeners
## Show listeners
The show listeners command will return a set of status information for every listener defined within the MariaDB MaxScale configuration file.
@ -248,7 +248,7 @@ mysql> show sessions;
mysql>
```
## Show clients
## Show clients
The show clients command reports a row for every client application connected to MariaDB MaxScale. Like clauses are not available of the show clients command.
@ -284,7 +284,7 @@ mysql> show servers;
mysql>
```
## Show modules
## Show modules
The show modules command reports the information on the modules currently loaded into MariaDB 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.
@ -309,7 +309,7 @@ mysql> show modules;
mysql>
```
## Show monitors
## Show monitors
The show monitors command reports each monitor configured within the system and the state of that monitor.
@ -376,7 +376,7 @@ Each row represents a time interval, in 100ms increments, with the counts repres
The simplified JSON interface takes the URL of the request made to maxinfo and maps that to a show command in the above section.
## Variables
## Variables
The /variables URL will return the MariaDB MaxScale variables, these variables can not be filtered via this interface.
@ -460,7 +460,7 @@ $ curl http://maxscale.mariadb.com:8003/listeners
$
```
## Modules
## Modules
The /modules URI returns data for each plugin that has been loaded into MariaDB 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.
@ -479,7 +479,7 @@ $ curl http://maxscale.mariadb.com:8003/modules
$
```
## Sessions
## Sessions
The /sessions URI returns a JSON array with an object for each active session within MariaDB MaxScale.
@ -511,7 +511,7 @@ $ curl http://maxscale.mariadb.com:8003/clients
$
```
## Servers
## Servers
The /servers URI is used to retrieve information for each of the servers defined within the MariaDB MaxScale configuration. This information includes the connection count and the current status as monitored by MariaDB MaxScale. The connection count is only those connections made by MariaDB MaxScale to those servers.

81
Documentation/Tutorials/MaxScale-Tutorial.md
View File

@ -1,10 +1,21 @@
# Setting up MariaDB MaxScale
This document is designed as a quick introduction to setting up MariaDB MaxScale in an environment in which you have either a MySQL Master-Slave replication cluster with one master and multiple slave servers or a multi-node Galera cluster. The process of setting and configuring MariaDB MaxScale will be covered within this document.
This document is designed as a quick introduction to setting up MariaDB MaxScale
in an environment in which you have either a MySQL Master-Slave replication cluster
with one master and multiple slave servers or a multi-node Galera cluster.
The process of setting and configuring MariaDB MaxScale will be covered within this document.
The installation and configuration of the MySQL Replication or the Galera cluster will not be covered nor will any discussion of installation management tools to handle automated or semi-automated failover of the replication cluster. The [Setting Up Replication](https://mariadb.com/kb/en/mariadb/setting-up-replication/) article on the MariaDB knowledgebase can help you get started with replication clusters and the [Getting Started With Mariadb Galera Cluster](https://mariadb.com/kb/en/mariadb/getting-started-with-mariadb-galera-cluster/) article will help you set up a Galera cluster.
The installation and configuration of the MySQL Replication or the Galera cluster
will not be covered nor will any discussion of installation management tools
to handle automated or semi-automated failover of the replication cluster.
The [Setting Up Replication](https://mariadb.com/kb/en/mariadb/setting-up-replication/)
article on the MariaDB knowledgebase can help you get started with replication clusters
and the [Getting Started With Mariadb Galera Cluster](https://mariadb.com/kb/en/mariadb/getting-started-with-mariadb-galera-cluster/) article will help you set up a Galera cluster.
This tutorial will assume the user is running from one of the binary distributions available and has installed this in the default location. Building from source code in GitHub is covered in the [Building from Source](../Getting-Started/Building-MaxScale-from-Source-Code.md) document.
This tutorial will assume the user is running from one of the binary distributions
available and has installed this in the default location.
Building from source code in GitHub is covered in the
[Building from Source](../Getting-Started/Building-MaxScale-from-Source-Code.md) document.
## Process
@ -18,19 +29,33 @@ The steps involved in setting up MariaDB MaxScale are:
## Installation
The precise installation process will vary from one distribution to another details of what to do with the RPM and DEB packages can be found on the download site when you select the distribution you are downloading from. The process involves setting up your package manager to include the MariaDB repositories and then running the package manager for your distribution (usually yum or apt-get).
The precise installation process will vary from one distribution to another
details of what to do with the RPM and DEB packages can be found on the download
site when you select the distribution you are downloading from.
The process involves setting up your package manager to include the MariaDB repositories
and then running the package manager for your distribution (usually yum or apt-get).
Upon successful completion of the installation command you will have MariaDB MaxScale installed and ready to be run but without a configuration. You must create a configuration file before you first run MariaDB MaxScale which is covered in a later section.
Upon successful completion of the installation command you will have MariaDB MaxScale
installed and ready to be run but without a configuration.
You must create a configuration file before you first run MariaDB MaxScale
which is covered in a later section.
## Creating Database Users
MariaDB MaxScale needs to connect to the backend databases and run queries for two reasons; one to determine the current state of the database and the other to retrieve the user information for the database cluster. The first pair of credentials will be used by the monitor modules and the second is used by MariaDB MaxScale itself. This may be done either using two separate usernames or with a single user.
MariaDB MaxScale needs to connect to the backend databases and run queries for
two reasons; one to determine the current state of the database and the other to
retrieve the user information for the database cluster. The first pair of
credentials will be used by the monitor modules and the second is used by
MariaDB MaxScale itself. This may be done either using two separate usernames
or with a single user.
The first user required must be able to select data from the table mysql.user, to create this user follow the steps below.
The first user required must be able to select data from the table mysql.user,
to create this user follow the steps below.
1. Connect to the current master server in your replication tree as the root user
2. Create the user, substituting the username, password and host on which maxscale runs within your environment
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*';
@ -42,7 +67,9 @@ MariaDB [(none)]> grant SELECT on mysql.user to '*username*'@'*maxscalehost*';
**Query OK, 0 rows affected (0.03 sec)**
```
Additionally, `SELECT` privileges on the `mysql.db` and `mysql.tables_priv` tables and `SHOW DATABASES` privileges are required in order to load databases name and grants suitable for database name authorization.
Additionally, `SELECT` privileges on the `mysql.db` and `mysql.tables_priv` tables
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';
@ -56,7 +83,11 @@ 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 role REPLICATION CLIENT. This is only required by the MySQL monitor and Multi-Master monitor modules.
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 role REPLICATION CLIENT. This is only required by the MySQL monitor
and Multi-Master monitor modules.
```
MariaDB [(none)]> grant REPLICATION CLIENT on *.* to '*username*'@'*maxscalehost*';
@ -64,17 +95,32 @@ 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.
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 additional grants for users
Because MariaDB MaxScale sits between the clients and the backend databases, the backend databases will see all clients as if they were connecting from MariaDB MaxScale's address. This usually requires users to create additional grants for MariaDB MaxScale's hostname. The best way to describe this process is with an example.
Because MariaDB MaxScale sits between the clients and the backend databases,
the backend databases will see all clients as if they were connecting from
MariaDB MaxScale's address.
This usually requires users to create additional grants for MariaDB MaxScale's hostname.
The best way to describe this process is with an example.
User `'jdoe'@'192.168.0.200` has the following grant on the cluster: `GRANT SELECT, INSERT, UPDATE, DELETE ON *.* TO 'jdoe'@'192.168.0.200'`. When the user connects directly to the server it will see it as `'jdoe'@'192.168.0.200` connecting to the server and it will match the grant for `'jdoe'@'192.168.0.200`.
User `'jdoe'@'192.168.0.200` has the following grant on the cluster:
`GRANT SELECT, INSERT, UPDATE, DELETE ON *.* TO 'jdoe'@'192.168.0.200'`.
When the user connects directly to the server it will see it as
`'jdoe'@'192.168.0.200` connecting to the server and it will match
the grant for `'jdoe'@'192.168.0.200`.
If MariaDB MaxScale is at the address `192.168.0.101` and the user `jdoe` connects to this MariaDB MaxScale, the backend server will see the connection as `'jdoe'@'192.168.0.101'`. Since the backend server has no grants for `'jdoe'@'192.168.0.101'`, the connection from MariaDB MaxScale to the server will be refused.
If MariaDB MaxScale is at the address `192.168.0.101` and the user `jdoe`
connects to this MariaDB MaxScale, the backend server will see the connection as
`'jdoe'@'192.168.0.101'`. Since the backend server has no grants for
`'jdoe'@'192.168.0.101'`, the connection from MariaDB MaxScale to the server
will be refused.
We can fix this by either creating a matching grant for user `jdoe` from the MariaDB MaxScale address or by using a wildcard to cover both addresses.
We can fix this by either creating a matching grant for user `jdoe` from
the MariaDB MaxScale address or by using a wildcard to cover both addresses.
The quickest way to do this is by doing a SHOW GRANTS query:
```
@ -95,7 +141,10 @@ MariaDB [(none)]> GRANT SELECT, INSERT, UPDATE, DELETE ON *.* TO 'jdoe'@'192.168
Query OK, 0 rows affected (0.00 sec)
```
The other option is to use a wildcard grant like `GRANT SELECT, INSERT, UPDATE, DELETE ON *.* TO 'jdoe'@'%'`. This is more convenient but also less secure than having specific grants for both the client's address and MariaDB MaxScale's address.
The other option is to use a wildcard grant like
`GRANT SELECT, INSERT, UPDATE, DELETE ON *.* TO 'jdoe'@'%'`.
This is more convenient but also less secure than having specific grants
for both the client's address and MariaDB MaxScale's address.
## Creating the configuration file

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

@ -1,50 +1,28 @@
# MySQL Cluster setup and MariaDB MaxScale configuration
Massimiliano Pinto
Last Updated: 1st August 2014
## Contents
## Document History
<table>
<tr>
<td>Date</td>
<td>Change</td>
<td>Who</td>
</tr>
<tr>
<td>31st July 2014</td>
<td>Initial version</td>
<td>Massimiliano Pinto</td>
</tr>
</table>
## Overview
The document covers the MySQL Cluster 7.2.17 setup and MariaDB MaxScale configuration in order to load balancing the SQL nodes access.
The document covers the MySQL Cluster 7.2.17 setup and MariaDB MaxScale
configuration for load balancing the SQL nodes access.
## MySQL Cluster setup
The MySQL Cluster 7.2.17 setup is based on two virtual servers with Linux Centos 6.5
The MySQL Cluster 7.2.17 setup is based on two virtual servers with Linux Centos
6.5
- server1:
NDB Manager process
* NDB Manager process
* SQL data node1
* MySQL 5.5.38 as SQL node1
SQL data node1
- server2:
MySQL 5.5.38 as SQL node1
* SQL data node2
* MySQL 5.5.38 as SQL node2
- server2:
SQL data node2
MySQL 5.5.38 as SQL node2
Cluster configuration file is /var/lib/mysql-cluster/config.ini, copied on all servers
Cluster configuration file is `/var/lib/mysql-cluster/config.ini`, copied on all
servers.
```
[ndbd default]
@ -70,7 +48,8 @@ hostname=178.62.38.199
hostname=162.243.90.81
```
Note, it’s possible to specify all node ids and datadir as well for each cluster component
Note that it’s possible to specify all node id:s and `datadir` as well for each
cluster component.
Example:
@ -81,7 +60,7 @@ id=43
datadir=/usr/local/mysql/data
```
and /etc/my.cnf, copied as well in all servers
Also, `/etc/my.cnf`, copied as well in all servers.
```
[mysqld]
@ -95,33 +74,45 @@ ndb-connectstring=178.62.38.199
## Startup of MySQL Cluster
Each cluster node process must be started separately, and on the host where it resides. The management node should be started first, followed by the data nodes, and then finally by any SQL nodes:
Each cluster node process must be started separately, and on the host where it
resides. The management node should be started first, then the data nodes, and
finally any SQL nodes:
- On the management host, server1, issue the following command from the system
shell to start the management node process:
- On the management host, server1, issue the following command from the system shell to start the management node process:
```
[root@server1 ~]# ndb_mgmd -f /var/lib/mysql-cluster/config.ini
```
- On each of the data node hosts, run this command to start the ndbd process:
```
[root@server1 ~]# ndbd —-initial -—initial-start
[root@server2 ~]# ndbd —-initial -—initial-start
```
- On each SQL node start the MySQL server process:
```
[root@server1 ~]# /etc/init.d/mysql start
[root@server2 ~]# /etc/init.d/mysql start
```
## Check the cluster status
If all has gone well, and the cluster has been set up correctly, the cluster should now be operational.
If all has gone well and the cluster has been set up correctly, the cluster
should now be operational.
It’s possible to test this by invoking the ndb_mgm management node client.
It’s possible to test this by invoking the `ndb_mgm` management node client.
The output should look as shown here, although you might see some slight
differences in the output depending upon the exact version of MySQL in use:
The output should look like that shown here, although you might see some slight differences in the output depending upon the exact version of MySQL that you are using:
```
[root@server1 ~]# ndb_mgm
[root@server1 ~]# ndb_mgm
-- NDB Cluster -- Management Client --
@ -149,13 +140,16 @@ id=22 @178.62.38.199 (mysql-5.5.38 ndb-7.2.17)
id=23 @162.243.90.81 (mysql-5.5.38 ndb-7.2.17)
ndb_mgm>
ndb_mgm>
```
The SQL node is referenced here as [mysqld(API)], which reflects the fact that the mysqld process is acting as a MySQL Cluster API node.
The SQL node is referenced here as [mysqld(API)], which reflects the fact that
the mysqld process is acting as a MySQL Cluster API node.
## Working with NDBCLUSTER engine in MySQL
- First create a table with NDBCLUSTER engine:
```
[root@server1 ~]# mysql
@ -179,13 +173,17 @@ mysql> show create table t1;
1 row in set (0.01 sec)
```
- Just add a row in the table:
- Add a row in the table:
```
mysql> insert into test.t1 values(11);
Query OK, 1 row affected (0.15 sec)
```
- Select the current number of rows:
```
mysql> select count(1) from t1;
@ -197,7 +195,9 @@ mysql> select count(1) from t1;
1 row in set (0.07 sec)
```
- The same from the MySQL client pointing to SQL node on server2
- The same from the MySQL client pointing to SQL node on server2:
```
[root@server2 ~]# mysql
@ -211,9 +211,11 @@ mysql> select count(1) from test.t1;
1 row in set (0.08 sec)
```
## Configuring MariaDB MaxScale for connection load balancing of SQL nodes
Add these sections in maxscale.cnf config file:
Add these sections into the maxscale.cnf config file:
```
[Cluster Service]
type=service
@ -253,13 +255,18 @@ address=162.243.90.81
port=3306
protocol=MySQLBackend
```
Assuming MariaDB MaxScale is installed in server1, start it
Assuming MariaDB MaxScale is installed in server1, start it.
```
[root@server1 ~]# cd /usr/bin
[root@server1 bin]# ./maxscale -c ../
```
Using the debug interface it’s possible to check the status of monitored servers
Using the debug interface it’s possible to check the status of monitored
servers.
```
MaxScale> show monitors
@ -300,9 +307,12 @@ Number of connections: 0
Current no. of conns: 0
Current no. of operations: 0
```
It’s now possible to run basic tests with the read connection load balancing for the two configured SQL nodes
It’s now possible to run basic tests with the read connection load balancing
for the two configured SQL nodes.
(1) test MaxScale load balancing requesting the Ndb_cluster_node_id variable:
```
[root@server1 ~]# mysql -h 127.0.0.1 -P 4906 -u test -ptest -e "SHOW STATUS LIKE 'Ndb_cluster_node_id'"
@ -320,9 +330,12 @@ It’s now possible to run basic tests with the read connection load balancing
| Ndb_cluster_node_id | 22 |
+---------------------+-------+
```
The MariaDB MaxScale connection load balancing is working.
(2) test a select statement on an NBDBCLUSTER table, database test and table t1 created before:
(2) test a select statement on an NBDBCLUSTER table, database test and table t1
created before:
```
[root@server1 ~] mysql -h 127.0.0.1 -P 4906 -utest -ptest -e "SELECT COUNT(1) FROM test.t1"
@ -332,10 +345,13 @@ The MariaDB MaxScale connection load balancing is working.
| 1 |
+----------+
```
(3) test an insert statement
```
mysql -h 127.0.0.1 -P 4906 -utest -ptest -e "INSERT INTO test.t1 VALUES (19)"
```
(4) test again the select and check the number of rows
```

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

@ -12,34 +12,34 @@ Once you have MariaDB MaxScale installed and the database users created, we can
## Creating Your MariaDB MaxScale Configuration
MariaDB MaxScale reads its configuration from `/etc/maxscale.cnf`. 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.
MariaDB MaxScale reads its configuration from `/etc/maxscale.cnf`. A template configuration is provided with the MaxScale installation.
A global, maxscale, section is included within every MariaDB MaxScale configuration file; this is used to set the values of various MariaDB MaxScale wide parameters, perhaps the most important of these is the number of threads that MariaDB MaxScale will use to execute the code that forwards requests and handles responses for clients.
A global, `[maxscale]`, section is included within every MariaDB MaxScale configuration file; this is used to set the values of various MariaDB MaxScale wide parameters, perhaps the most important of these is the number of threads that MariaDB MaxScale will use to handle client requests.
```
[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 MariaDB 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 MariaDB MaxScale configuration 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.
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 MariaDB 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 MariaDB MaxScale configuration file and set the type to service, the section names are the names of the services themselves and should be meaningful to the administrator. Avoid using whitespace in the section names.
```
[Write Service]
[Write-Service]
type=service
[Read 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]
[Write-Service]
type=service
router=readconnroute
servers=dbserv1, dbserv2, dbserv3
[Read Service]
[Read-Service]
type=service
router=readconnroute
servers=dbserv1, dbserv2, dbserv3
@ -48,13 +48,13 @@ 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]
[Write-Service]
type=service
router=readconnroute
router_options=master
servers=dbserv1, dbserv2, dbserv3
[Read Service]
[Read-Service]
type=service
router=readconnroute
router_options=slave
@ -77,7 +77,7 @@ maxpasswd plainpassword
The username and password, either encrypted or plain text, are stored in the service section using the user and passwd parameters.
```
[Write Service]
[Write-Service]
type=service
router=readconnroute
router_options=master
@ -85,7 +85,7 @@ servers=dbserv1, dbserv2, dbserv3
user=maxscale
passwd=96F99AA1315BDC3604B006F427DD9484
[Read Service]
[Read-Service]
type=service
router=readconnroute
router_options=slave
@ -97,28 +97,28 @@ 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]
[Write-Listener]
type=listener
service=Write Service
service=Write-Service
[Read Listener]
[Read-Listener]
type=listener
service=Read Service
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]
[Write-Listener]
type=listener
service=Write Service
service=Write-Service
protocol=MySQLClient
port=4306
socket=/tmp/ClusterMaster
[Read Listener]
[Read-Listener]
type=listener
service=Read Service
service=Read-Service
protocol=MySQLClient
port=4307
```
@ -150,7 +150,7 @@ protocol=MySQLBackend
In order for MariaDB 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]
[Replication-Monitor]
type=monitor
module=mysqlmon
servers=dbserv1, dbserv2, dbserv3
@ -168,7 +168,7 @@ The final stage in the configuration is to add the option service which is used
type=service
router=cli
[CLI Listener]
[CLI-Listener]
type=listener
service=CLI
protocol=maxscaled
@ -195,59 +195,38 @@ Check the error log in /var/log/maxscale/ to see if any errors are detected in t
% maxadmin list services
Services.
--------------------------+----------------------+--------+---------------
Service Name | Router Module | #Users | Total Sessions
--------------------------+----------------------+--------+---------------
Read Service | readconnroute | 1 | 1
Write Service | readconnroute | 1 | 1
CLI | cli | 2 | 2
--------------------------+----------------------+--------+---------------
% maxadmin list servers
Servers.
-------------------+-----------------+-------+-------------+--------------------
Server | Address | Port | Connections | Status
-------------------+-----------------+-------+-------------+--------------------
dbserv1 | 192.168.2.1 | 3306 | 0 | Running, Slave
dbserv2 | 192.168.2.2 | 3306 | 0 | Running, Master
dbserv3 | 192.168.2.3 | 3306 | 0 | Running, Slave
-------------------+-----------------+-------+-------------+--------------------
% maxadmin list listeners
Listeners.
---------------------+--------------------+-----------------+-------+--------
Service Name | Protocol Module | Address | Port | State
---------------------+--------------------+-----------------+-------+--------
Read Service | MySQLClient | * | 4307 | Running
Write Service | MySQLClient | * | 4306 | Running
CLI | maxscaled | localhost | 6603 | Running
---------------------+--------------------+-----------------+-------+--------
%
```
MariaDB 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 MariaDB MaxScale Configuration Guide. More detail on the use of maxadmin can be found in the document [MaxAdmin - The MariaDB MaxScale Administration & Monitoring Client Application](Administration-Tutorial.md).
MariaDB 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 MariaDB MaxScale Configuration Guide.
More detail on the use of maxadmin can be found in the document [MaxAdmin - The MariaDB MaxScale Administration & Monitoring Client Application](Administration-Tutorial.md).

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

@ -2,19 +2,34 @@
## Environment & Solution Space
The object of this tutorial is to have a system that appears to the clients of MariaDB MaxScale as if there is a single database behind MariaDB MaxScale. MariaDB MaxScale will split the statements such that write statements will be sent to the current master server in the replication cluster and read statements will be balanced across the rest of the slave servers.
The object of this tutorial is to have a system that appears to the clients of
MariaDB MaxScale as if there was a single database behind MariaDB MaxScale.
MariaDB MaxScale will split the statements such that write statements will be
sent to the current master server in the replication cluster and read statements
will be balanced across the rest of the slave servers.
## Setting up MariaDB MaxScale
The first part of this tutorial is covered in [MariaDB MaxScale Tutorial](MaxScale-Tutorial.md). Please read it and follow the instructions for setting up MariaDB MaxScale with the type of cluster you want to use.
The first part of this tutorial is covered in
[MariaDB MaxScale Tutorial](MaxScale-Tutorial.md). Please read it and follow the
instructions for setting up MariaDB MaxScale with the type of cluster you want
to use.
Once you have MariaDB MaxScale installed and the database users created, we can create the configuration file for MariaDB MaxScale.
Once you have MariaDB MaxScale installed and the database users created, the
configuration file for MariaDB MaxScale can be written.
## Creating Your MariaDB MaxScale Configuration
MariaDB 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.
MariaDB MaxScale configuration is defined in the file `maxscale.cnf` located in
the directory `/etc`. If you have installed MaxScale in the default location the
file path should be `/etc/maxscale.cnf`. This file is not created as part of the
installation process and must be manually created. A template file, which may be
used as a basis for your configuration, exists within the `/usr/share/maxscale`
directory.
A global, maxscale, section is included within every MariaDB MaxScale configuration file; this is used to set the values of various MariaDB MaxScale wide parameters, perhaps the most important of these is the number of threads that MariaDB MaxScale will use to execute the code that forwards requests and handles responses for clients.
A global section, marked `maxscale`, is included within every MariaDB MaxScale
configuration file. The section is used to set the values of various
process-wide parameters, for example the number of worker threads.
```
[maxscale]
@ -22,14 +37,20 @@ threads=4
```
The first step is to create a service for our Read/Write Splitter. Create a section in your MariaDB MaxScale configuration 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.
The first step is to create a Read/Write Splitter service. Create a section in
your configuration file and set the type to service. The section header is the
name of the service and should be meaningful to the administrator. Names may
contain whitespace.
```
[Splitter Service]
type=service
```
The router for we need to use for this configuration is the readwritesplit 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.
The router module needed for this service is named `readwritesplit`. The service
must contain a list of backend server names. The server names are the headers of
server sections in the configuration file and not the physical hostnames or
addresses of the servers.
```
[Splitter Service]
@ -38,14 +59,20 @@ router=readwritesplit
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.
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.
To use encrypted passwords, a set of keys for encryption/decryption must be
generated. To generate the keys use the `maxkeys` command and pass the name of
the secrets file containing the keys.
```
maxkeys /var/lib/maxscale/.secrets
```
Once the keys have been created the maxpasswd command can be used to generate the encrypted password.
Once the keys have been created, use the `maxpasswd` command to generate the
encrypted password.
```
maxpasswd plainpassword
@ -54,7 +81,8 @@ maxpasswd plainpassword
```
The username and password, either encrypted or plain text, are stored in the service section using the user and passwd parameters.
The username and password, either encrypted or in plain text, are stored in the
service section.
```
[Splitter Service]
@ -65,7 +93,11 @@ user=maxscale
passwd=96F99AA1315BDC3604B006F427DD9484
```
This completes the definitions required by the service, however listening ports must be associated with the service in order to allow network connections. This is done by creating a series of listener sections. This section again is 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. A service may have multiple listeners.
This completes the service definition. To have the service accept network
connections, a listener must be associated with it. The listener is defined in
its own section. The type should be `listener` with an entry `service` defining
the name of the service the listener is listening for. A service may have
multiple listeners.
```
[Splitter Listener]
@ -73,7 +105,10 @@ type=listener
service=Splitter 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.
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.
```
[Splitter Listener]
@ -84,9 +119,16 @@ port=3306
socket=/tmp/ClusterMaster
```
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.
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 in the configuration is to define the backend servers. The
definitions include how to connect to the servers. A section is created for each
server and it contains: `type` set to `server`, the network address and port,
and the protocol to use. Currently, the protocol module for all database
connections is `MySQLBackend`.
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 module for all database connections in MySQLBackend.
```
[dbserv1]
type=server
@ -107,7 +149,11 @@ port=3306
protocol=MySQLBackend
```
In order for MariaDB 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.
For MariaDB MaxScale to monitor the servers using the correct monitoring
mechanisms a monitor section should be written. This section defines the monitor
module to use and the monitored servers. The section `type` should be set to
`monitor`. Parameters added include: the list of servers to monitor and the
username and password the monitor module should use when connecting.
```
[Replication Monitor]
@ -118,9 +164,13 @@ user=maxscale
passwd=96F99AA1315BDC3604B006F427DD9484
```
As with the password definition in the server either plain text or encrypted passwords may be used.
Similarly to the password definition in the server either a plain text or an
encrypted password 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 MariaDB MaxScale for monitoring and administration purposes. This creates a service section and a listener section.
The final stage in the configuration is to add the service which used by the
`maxadmin` command to connect to MariaDB MaxScale for monitoring and
administration purposes. The example below shows a service section and a
listener section.
```
[CLI]
@ -136,15 +186,25 @@ socket=default
# Starting MariaDB MaxScale
Upon completion of the configuration process MariaDB 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.
Upon completion of the configuration MariaDB MaxScale is ready to be started.
This may either be done manually by running the `maxscale` command or via the
service interface.
```
% maxscale
```
or
```
% service maxscale start
```
Check the error log in /var/log/maxscale to see if any errors are detected in the configuration file and to confirm MariaDB MaxScale has been started. Also the maxadmin command may be used to confirm that MariaDB 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 MariaDB MaxScale has been started. Also
the maxadmin command may be used to confirm that MariaDB MaxScale is running and
the services, listeners etc have been correctly configured.
```
% maxadmin list services
@ -198,5 +258,12 @@ CLI | maxscaled | localhost | 6603 | Running
```
MariaDB 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 MariaDB MaxScale Configuration Guide. More detail on the use of maxadmin can be found in the document [MaxAdmin - The MariaDB MaxScale Administration & Monitoring Client Application](Administration-Tutorial.md).
MariaDB MaxScale is now ready to start accepting client connections and routing
them to the master or slaves within your cluster. Other configuration options,
that can alter the criteria used for routing, are available. 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
MariaDB MaxScale Configuration Guide. More details on the use of maxadmin can be
found in the document
[MaxAdmin - The MariaDB MaxScale Administration & Monitoring Client Application](Administration-Tutorial.md).

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

@ -1,49 +1,40 @@
# MariaDB MaxScale Nagios plugins, for Nagios 3.5.1
Massimiliano Pinto
Last Updated: 12th March 2015
## Document History
<table>
<tr>
<td>Date</td>
<td>Change</td>
<td>Who</td>
</tr>
<tr>
<td>10th March 2015</td>
<td>Initial version</td>
<td>Massimiliano Pinto</td>
</tr>
<tr>
<td>20th May 2016</td>
<td>MaxAdmin uses UNIX socket only</td>
<td>Massimiliano Pinto</td>
</tr>
</table>
# Introduction
Nagios® Core™ is an Open Source system and network monitoring application. It watches hosts and services that you specify, alerting you when things go bad and when they get better.
Nagios plugins are compiled executables or scripts (Perl scripts, shell scripts, etc.) that can be run from a command line to check the status or a host or service. Nagios uses the results from plugins to determine the current status of hosts and services on your network.
Nagios core executes a plugin whenever there is a need to check the status of a service or host.
Nagios® Core™ is an Open Source system and network monitoring application.
It watches hosts and services that you specify, alerting you when things go bad
and when they get better.
Nagios plugins are compiled executables or scripts (Perl scripts, shell scripts, etc.)
that can be run from a command line to check the status or a host or service.
Nagios uses the results from plugins to determine the current status of hosts and
services on your network.
Nagios core executes a plugin whenever there is a need to check the status
of a service or host.
While MariaDB MaxScale resources and status can be monitored via CLI using maxadmin commands, Nagios Plugin provides an automated way for system administration and database administrators to monitor MariaDB MaxScale. The diagram below provides view of how Nagios and MariaDB MaxScale interact.
While MariaDB MaxScale resources and status can be monitored via CLI using
maxadmin commands, Nagios Plugin provides an automated way for system administration
and database administrators to monitor MariaDB MaxScale.
The diagram below provides view of how Nagios and MariaDB MaxScale interact.
![Nagios and MariaDB MaxScale interaction](images/HowMaxScaleWorksWithNagios.png)
There are three Nagios plugin scripts that MariaDB MaxScale provides.
1. check_maxscale_threads.pl: This command provides you the status of current running threads and events in the queue on MariaDB MaxScale Server. The Performance data associated with this command current and historic wait time for threads and events
1. check_maxscale_threads.pl: This command provides you the status of current running
threads and events in the queue on MariaDB MaxScale Server.
The Performance data associated with this command current and historic wait time for threads and events
2. check_maxscale_resources.pl: This command provides you status of various resources on MariaDB MaxScale server. The Performance data associated provides details on respective resources.
2. check_maxscale_resources.pl: This command provides you status of various resources
on MariaDB MaxScale server. The Performance data associated provides
details on respective resources.
Current resources are: modules, services, listeners, servers, sessions, filters.
3. check_maxscale_monitor.pl: This command provides you status of the configured monitor modules on MariaDB MaxScale server.
3. check_maxscale_monitor.pl: This command provides you status of the configured
monitor modules on MariaDB MaxScale server.
In order to use these scripts on your Nagios Server, you need to copy them from the MariaDB MaxScale binary package or download them from source tree on GitHub.
In order to use these scripts on your Nagios Server, you need to copy them
from the MariaDB MaxScale binary package or download them from source tree on GitHub.
# MariaDB MaxScale Nagios Plugin Requirements
@ -65,10 +56,13 @@ socket=default
## Prepare Nagios configuration files.
Assuming Nagios installed on a separated server and the plugins are in /usr/lib64/nagios/plugins and configuration files are in /etc/nagios:
Assuming Nagios installed on a separated server and the plugins are
in /usr/lib64/nagios/plugins and configuration files are in /etc/nagios:
* Copy MariaDB MaxScale plugin scripts (./nagios/plugins/check_maxscale_*.pl) to /usr/lib64/nagios/plugins on Nagios Server
* Copy New commands and server1 definition (./nagios/plugins/maxscale_commands.cfg, server1.cfg) to /etc/nagios/objects/ on Nagios Server
* Copy MariaDB MaxScale plugin scripts (./nagios/plugins/check_maxscale_*.pl)
to /usr/lib64/nagios/plugins on Nagios Server
* Copy New commands and server1 definition (./nagios/plugins/maxscale_commands.cfg, server1.cfg)
to /etc/nagios/objects/ on Nagios Server
* Edit /etc/nagios/nagios.cfg on Nagios Server
and add (just after localhost.cfg or commands.cfg)
@ -87,14 +81,18 @@ cfg_file=/etc/nagios/objects/server1.cfg
- The default maxadmin executable path is /usr/bin/maxadmin can be changed by -m option
- default maxadmin socket (/tmp/maxadmin.sock) can be changed with -S option
- maxadmin executable is no longer required to be copied in Nagios server.
- the UNIX user in ssh connection should be also admin user for MariaDB MaxScale admin. First time access or no configured users means the "root" user is the only one that can access MariaDB MaxScale admin interface via UNIX socket.
- the UNIX user in ssh connection should be also admin user for MariaDB MaxScale admin.
First time access or no configured users means the "root" user is the only one that can access
MariaDB MaxScale admin interface via UNIX socket.
Test maxadmin with proper user in maxscale server and later via SSH.
Those checks are strongly recommended before using Nagios scripts.
For additional information about Maxadmin and MariaDB MaxScale administrative interface please refer to [MaxAdmin Utility](../Reference/MaxAdmin.md)
For additional information about Maxadmin and MariaDB MaxScale administrative interface
please refer to [MaxAdmin Utility](../Reference/MaxAdmin.md)
This example shows configuration that needs to be done on Nagios server in order to communicate to MariaDB MaxScale server that is running on host server1.
This example shows configuration that needs to be done on Nagios server in order to
communicate to MariaDB MaxScale server that is running on host server1.
In this example we are using the check_maxscale_resource as the check command
```
@ -109,7 +107,8 @@ In this example we are using the check_maxscale_resource as the check command
```
### Check new running monitors
* Restart Nagios and check new monitors are running in HTTP Interface "Current Status -> Services" on Nagios Server
* Restart Nagios and check new monitors are running in HTTP Interface
"Current Status -> Services" on Nagios Server
* Look for any errors in /var/log/nagios/nagios.log or nagios.debug on Nagios Server
# Nagios Plugin command line usage
@ -127,7 +126,8 @@ In this example we are using the check_maxscale_resource as the check command
-u <user> = username to connect to maxscale host via SSH (same user is used for maxadmin authentication)
-i <identity> = identity file to use for <user> at <host>
-m <maxadmin> = /path/to/maxadmin
-S <socket> = UNIX socket path between maxadmin and maxscale (default is /tmp/maxadmin.sock)
-S <socket> = UNIX socket path between maxadmin and maxscale (default
is /tmp/maxadmin.sock)
(2) ./check_maxscale_resources.pl -h
@ -166,7 +166,10 @@ Example for 'services'
```
#./check_maxscale_resources.pl -r resources
OK: 7 services found | services1=RW_Router;readwritesplit;1;1 services2=RW_Split;readwritesplit;1;1 services3=Test Service;readconnroute;1;1 services4=Master Service;readconnroute;2;2 services5=Debug Service;debugcli;1;1 services6=CLI;cli;2;145 services7=MaxInfo;maxinfo;2;2
OK: 7 services found | services1=RW_Router;readwritesplit;1;1 services2=RW_Split;
readwritesplit;1;1 services3=Test Service;readconnroute;1;1 services4=Master Service;
readconnroute;2;2 services5=Debug Service;debugcli;1;1 services6=CLI;cli;2;145
services7=MaxInfo;maxinfo;2;2
```
Returns OK and the number of services

37
Documentation/Tutorials/Notification-Service.md
View File

@ -1,27 +1,5 @@
# MariaDB MaxScale Notification Service and Feedback Support
Massimiliano Pinto
Last Updated: 10th March 2015
## Contents
## Document History
<table>
<tr>
<td>Date</td>
<td>Change</td>
<td>Who</td>
</tr>
<tr>
<td>10th March 2015</td>
<td>Initial version</td>
<td>Massimiliano Pinto</td>
</tr>
</table>
## Overview
The purpose of Notification Service in MariaDB MaxScale is for a customer registered for the service to receive update notices, security bulletins, fixes and workarounds that are tailored to the database server configuration.
@ -30,9 +8,9 @@ The purpose of Notification Service in MariaDB MaxScale is for a customer regist
MariaDB MaxScale may collect the installed plugins and send the information's nightly, between 2:00 AM and 4:59 AM.
It tries to send data and if there is any failure (timeout, server is down, etc), the next retry is in 1800 seconds (30 minutes)
It tries to send data and if there is any failure (timeout, server is down, etc), the next retry is in 1800 seconds (30 minutes).
This feature is not enabled by default: MariaDB MaxScale must be configured in [feedback] section:
This feature is not enabled by default: MariaDB MaxScale must be configured in `[feedback]` section:
```
[feedback]
@ -41,15 +19,16 @@ feedback_url=https://enterprise.mariadb.com/feedback/post
feedback_user_info=x-y-z-w
```
The activation code that will be provided by MariaDB corp upon request by the customer and it should be put in feedback_user_info.
The activation code that will be provided by MariaDB Corporation Ab upon request by the customer and it should be put in feedback_user_info.
Example:
```
feedback_user_info=0467009f-b04d-45b1-a77b-b6b2ec9c6cf4
```
MariaDB MaxScale generates the feedback report containing following information:
-The activation code used to enable feedback
- The activation code used to enable feedback
- MariaDB MaxScale Version
- An identifier of the MariaDB MaxScale installation, i.e. the HEX encoding of SHA1 digest of the first network interface MAC address
- Operating System (i.e Linux)
@ -57,12 +36,12 @@ MariaDB MaxScale generates the feedback report containing following information:
- All the modules in use in MariaDB MaxScale and their API and version
- MariaDB MaxScale server UNIX_TIME at generation time
MariaDB MaxScale shall send the generated feedback report to a feedback server specified in feedback_url
MariaDB MaxScale shall send the generated feedback report to a feedback server specified in _feedback_url_.
## Manual Operation
If it’s not possible to send data due to firewall or security settings the report could be generated manually (feedback_user_info is required) via MaxAdmin
If it’s not possible to send data due to firewall or security settings the report could be generated manually (feedback_user_info is required) via MaxAdmin.
```
MaxScale>show feedbackreport

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

@ -1,34 +1,42 @@
# Rabbit MQ setup and MariaDB MaxScale Integration
## Introduction
A step by step guide helps installing a RabbitMQ server and testing it before MariaDB MaxScale integration.
A step by step guide helps installing a RabbitMQ server and testing it before
MariaDB MaxScale integration.
New plugin filter and a message consumer application need to be compiled and linked with an external C library, RabbitMQ-c, that provides AMQP protocol integration.
New plugin filter and a message consumer application need to be compiled and
linked with an external C library, RabbitMQ-c, that provides AMQP protocol integration.
Custom configuration, with TCP/IP and Queue parameters, is also detailed here.
The software install setup provides RPM and DEB packaging and traditional compilation steps.
## Step 1 - Get the RabbitMQ binaries
On Centos 6.5 using fedora / RHEL rpm get the rpm from [http://www.rabbitmq.com/](http://www.rabbitmq.com/ "RabbitMQ")
On Centos 6.5 using fedora / RHEL rpm get the rpm from
[http://www.rabbitmq.com/](http://www.rabbitmq.com/ "RabbitMQ")
rabbitmq-server-3.3.4-1.noarch.rpm
Please note, before installing RabbitMQ, you must install Erlang.
Example:
```
yum install erlang
Package erlang-R14B-04.3.el6.x86_64 already installed and latest version
```
## Step 2 - Install and Start the Server
Install the packages using your distribution's package manager and start the server:
```
yum install rabbitmq-server-3.3.4-1.noarch.rpm
systemctl start rabbitmq-server.service
To configure your RabbitMQ server, please refer to the RabbitMQ website: [http://www.rabbitmq.com/](http://www.rabbitmq.com/ RabbitMQ website).
```
To configure your RabbitMQ server, please refer to the RabbitMQ website:
[http://www.rabbitmq.com/](http://www.rabbitmq.com/ RabbitMQ website).
rabbitmqctl is a command line tool for managing a RabbitMQ broker. It performs all actions by connecting to one of the broker's nodes.
rabbitmqctl is a command line tool for managing a RabbitMQ broker.
It performs all actions by connecting to one of the broker's nodes.
```
rabbitmqctl list_queues
@ -87,12 +95,14 @@ make
make install
```
Please note, this will install the packages to /usr. If you do not wish to install them to this location, provide a different value for the CMAKE_INSTALL_PREFIX variable.
Please note, this will install the packages to /usr. If you do not wish to install
them to this location, provide a different value for the CMAKE_INSTALL_PREFIX variable.
### Setup using the EPEL repository
Check how to configure your distribution for the EPEL repository: [https://fedoraproject.org/wiki/EPEL](https://fedoraproject.org/wiki/EPEL EPEL)
Check how to configure your distribution for the EPEL repository:
[https://fedoraproject.org/wiki/EPEL](https://fedoraproject.org/wiki/EPEL EPEL)
Configure your repositories and install the software:
@ -114,7 +124,9 @@ yum install rabbitmq-server
### Basic tests with library
The required library librabbitmq-c is now installed and we continue with basic operations with amqp_* tools, located in the examples/ folder of the build directory, testing client server interaction.
The required library librabbitmq-c is now installed and we continue with basic
operations with amqp_* tools, located in the examples/ folder of the build directory,
testing client server interaction.
Please note, those example applications may not be included in the RPM library packages.
@ -185,7 +197,8 @@ port=5672
logging_trigger=all
```
Logging triggers define whether to log all or a subset of the incoming queries using these options:
Logging triggers define whether to log all or a subset of the incoming queries
using these options:
```
# log only some elements or all
@ -230,9 +243,13 @@ anything targeting my1 table is logged
SELECT NOW(), SELECT MD5(“xyz)” are not logged
```
Please note that if we want to log only the user ‘maxtest’ accessing the schema ‘test’ with target ‘my1’ the option logging_strict must be set to TRUE and if we want to include those selects without schema name the option logging_log_all must be set to TRUE.
Please note that if we want to log only the user ‘maxtest’ accessing the
schema ‘test’ with target ‘my1’ the option logging_strict must be set
to TRUE and if we want to include those selects without schema name the
option logging_log_all must be set to TRUE.
The mqfilter logs into the MariaDB MaxScale TRACE log information about the matched logging triggers and the message delivering:
The mqfilter logs into the MariaDB MaxScale TRACE log information about
the matched logging triggers and the message delivering:
```
2014 09/03 06:22:04 Trigger is TRG_SOURCE: user: testuser = testuser
@ -288,7 +305,9 @@ and finally we can launch it:
# ./consumer
```
If the consumer.cnf file is not in the same directory as the binary file is, you can provide the location of the folder that it is in by passing it the -c flag followed by the path:
If the consumer.cnf file is not in the same directory as the binary file is,
you can provide the location of the folder that it is in by passing
it the -c flag followed by the path:
```
# ./consumer -c path/to/file
@ -298,7 +317,8 @@ and start MariaDB MaxScale as well
## Step 5 - Test the filter and check collected data
Assuming that MariaDB MaxScale and the message consumer are successfully running let’s connect to the service with an active mqfilter:
Assuming that MariaDB MaxScale and the message consumer are successfully
running let’s connect to the service with an active mqfilter:
```
[root@maxscale-02 MaxScale]# mysql -h 127.0.0.1 -P 4506 -uxxx -pyyy
@ -347,8 +367,10 @@ MariaDB [mqpairs]> select * from pairs;
7 rows in set (0.01 sec)
```
The filter send queries to the RabbitMQ server in the canonical format, i.e select RAND(?), RAND(?).
The queries Message Queue Consumer application gets from the server are stored with a counter that quickly shows how many times that normalized query was received:
The filter send queries to the RabbitMQ server in the canonical format,
i.e select RAND(?), RAND(?).
The queries Message Queue Consumer application gets from the server
are stored with a counter that quickly shows how many times that normalized query was received:
```
| 01050106010701080109010a010b010c10d | select RAND(?), RAND(?) | Columns: 2 | 2014-09-02 11:24:37 | 2014-09-02 11:29:15 | 3 |

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

@ -1,9 +1,9 @@
# MariaDB MaxScale as a Binlog Server
MariaDB MaxScale is a dynamic data routing platform that sits between a database layer and the clients of that database, the binlog router described here is somewhat different to that original concept, moving MariaDB MaxScale down to play a role within the database layer itself.
MariaDB MaxScale is a dynamic data routing platform that sits between a database layer and the clients of that database. However, the binlog router described here is somewhat different to that original concept, moving MariaDB MaxScale down to play a role within the database layer itself.
In a traditional MySQL replication setup a single master server is created and a set of slaves MySQL instances are configured to pull the binlog files from that master to the slaves. There are some problems, however, in this setup; when the number of slaves grows an increasing load is placed on the master, to serve the binlogs to each slave. When the master server fails, some action must be performed on every slave server before a new server can become the master server.
In a traditional MySQL replication setup a single master server is created and a set of slaves MySQL instances are configured to pull the binlog files from that master to the slaves. There are some problems, however, in this setup; when the number of slaves grows, an increasing load caused by the serving of binlogs to each slave, is placed on the master. When the master server fails, some action must be performed on every slave server before a new server can become the master server.
Introducing a proxy layer between the master server and the slave servers can improve the situation, by reducing the load on the master to simply serving the proxy layer rather than all of the slaves. The slaves only need to be aware of the proxy layer and not of the real master server. Removing need for the slaves to have knowledge of the master, greatly simplifies the process of replacing a failed master within a replication environment.
Introducing a proxy layer between the master server and the slave servers can improve the situation, by reducing the load on the master to simply serving the proxy layer rather than all of the slaves. The slaves only need to be aware of the proxy layer and not of the real master server. Removing the need for the slaves to have knowledge of the actual master, greatly simplifies the process of replacing a failed master within a replication environment.
## MariaDB/MySQL as a Binlog Server
The most obvious solution to the requirement for a proxy layer within a replication environment is to use a MariaDB or MySQL database instance. The database server is designed to allow this, since a slave server is able to be configured such that it will produce binary logs for updates it has itself received via replication from the master server. This is done with the *log_slave_updates* configuration option of the server. In this case the server is known as an intermediate master, it is simultaneously a slave to the real master and a master to the other slaves in the configuration.

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

@ -1,4 +1,4 @@
#Simple Sharding with Two Servers
# Simple Sharding with Two Servers
![Schema Based Sharding](images/Simple-Sharding.png)
@ -10,25 +10,13 @@ MariaDB MaxScale will appear to the client as a database server with the combina
This document is designed as a simple tutorial on schema-based sharding using MariaDB MaxScale in an environment in which you have two servers. The object of this tutorial is to have a system that, to the client side, acts like a single MySQL database but actually is sharded between the two servers.
The process of setting and configuring MariaDB MaxScale will be covered within this document. The installation and configuration of the MySQL servers will not be covered in-depth. The users should be configured according to the configuration guide.
The database users should be configured according to [the configuration guide](../Getting-Started/Configuration-Guide.md). The [MaxScale Tutorial](MaxScale-Tutorial.md) contains easy to follow instructions on how to set up MaxScale.
This tutorial will assume the user is using of the binary distributions available and has installed this in the default location. The process of configuring MariaDB MaxScale will be covered within this document. The installation and configuration of the MySQL servers will not be covered in-depth.
This tutorial will assume the user is running from one of the binary distributions available and has installed this in the default location. Building from source code in GitHub is covered in guides elsewhere as is installing to non-default locations.
## Preparing MaxScale
## Process
The steps involved in creating a system from the binary distribution of MariaDB MaxScale are:
* Install the package relevant to your distribution
* Create the required users on your MariaDB or MySQL server
* Create a MariaDB MaxScale configuration file
### Installation
The precise installation process will vary from one distribution to another details of what to do with the RPM and DEB packages can be found on the download site when you select the distribution you are downloading from. The process involves setting up your package manager to include the MariaDB repositories and then running the package manager for your distribution, RPM or apt-get.
Upon successful completion of the installation command you will have MariaDB MaxScale installed and ready to be run but without a configuration. You must create a configuration file before you first run MariaDB MaxScale.
Follow the [MaxScale Tutorial](MaxScale-Tutorial.md) to install and prepare the required database users for MaxScale. You don't need to create the configuration file for MaxScale as it will be covered in the next section.
### Creating Your MariaDB MaxScale Configuration
@ -92,7 +80,8 @@ After this we have a fully working configuration and we can move on to starting
Upon completion of the configuration process MariaDB 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 MariaDB 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 MariaDB MaxScale is running and the services, listeners etc have been correctly configured.
MariaDB 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 MariaDB MaxScale keeps the session state intact between servers.
If MariaDB MaxScale fails to start, check the error log in `/var/log/maxscale` to see what sort of errors were detected.
**Note:** As the sharding solution in MaxScale is relatively simple, cross-database queries between two or more shards are not supported.

15
Documentation/Upgrading/Upgrading-To-MaxScale-2.1.md
View File

@ -7,6 +7,9 @@ For more information about MariaDB MaxScale 2.1, please refer to the
[ChangeLog](../Changelog.md).
For a complete list of changes in MaxScale 2.1.0, refer to the
[MaxScale 2.1.3 Release Notes](../Release-Notes/MaxScale-2.1.3-Release-Notes.md).
[MaxScale 2.1.2 Release Notes](../Release-Notes/MaxScale-2.1.2-Release-Notes.md).
[MaxScale 2.1.1 Release Notes](../Release-Notes/MaxScale-2.1.1-Release-Notes.md).
[MaxScale 2.1.0 Release Notes](../Release-Notes/MaxScale-2.1.0-Release-Notes.md).
## Installation
@ -14,6 +17,18 @@ For a complete list of changes in MaxScale 2.1.0, refer to the
Before starting the upgrade, we **strongly** recommend you back up your current
configuration file.
## IPv6 Support
MaxScale 2.1.2 added support for IPv6 addresses. The default interface that listeners bind to
was changed from the IPv4 address `0.0.0.0` to the IPv6 address `::`. To bind to the old IPv4 address,
add `address=0.0.0.0` to the listener definition.
## Persisted Configuration Files
Starting with MaxScale 2.1, any changes made with the newly added
[runtime configuration change](../Reference/MaxAdmin.md#runtime-configuration-changes)
will be persisted in a configuration file. These files are located in `/var/lib/maxscale/maxscale.cnf.d/`.
## MaxScale Log Files
The name of the log file was changed from _maxscaleN.log_ to _maxscale.log_. The

1
README.md
View File

@ -41,6 +41,7 @@ For information about installing and using MaxScale, please refer to the
documentation. The official documentation can be found on the
[MariaDB Knowledge Base](https://mariadb.com/kb/en/mariadb-enterprise/maxscale/).
- [MariaDB MaxScale 2.1 Documentation](https://mariadb.com/kb/en/mariadb-enterprise/6308/)
- [MariaDB MaxScale 2.0 Documentation](https://mariadb.com/kb/en/mariadb-enterprise/mariadb-maxscale-20-contents/)
- [MariaDB MaxScale 1.4 Documentation](https://mariadb.com/kb/en/mariadb-enterprise/mariadb-maxscale-14/maxscale-maxscale-contents/)

3
server/modules/filter/cache/storage/CMakeLists.txt vendored
View File

@ -1,2 +1,3 @@
add_subdirectory(storage_rocksdb)
#Storage RocksDB not built by default.
#add_subdirectory(storage_rocksdb)
add_subdirectory(storage_inmemory)

13
server/modules/monitor/mysqlmon/mysql_mon.c
View File

@ -519,6 +519,8 @@ static MXS_MONITOR_SERVERS *build_mysql51_replication_tree(MXS_MONITOR *mon)
MXS_MONITOR_SERVERS* database = mon->databases;
MXS_MONITOR_SERVERS *ptr, *rval = NULL;
int i;
MYSQL_MONITOR *handle = mon->handle;
while (database)
{
bool ismaster = false;
@ -559,11 +561,16 @@ static MXS_MONITOR_SERVERS *build_mysql51_replication_tree(MXS_MONITOR *mon)
/* Set the Slave Role */
if (ismaster)
{
handle->master = database;
MXS_DEBUG("Master server found at [%s]:%d with %d slaves",
database->server->name,
database->server->port,
nslaves);
monitor_set_pending_status(database, SERVER_MASTER);
database->server->depth = 0; // Add Depth 0 for Master
if (rval == NULL || rval->server->node_id > database->server->node_id)
{
rval = database;
@ -587,13 +594,17 @@ static MXS_MONITOR_SERVERS *build_mysql51_replication_tree(MXS_MONITOR *mon)
if (ptr->server->slaves[i] == database->server->node_id)
{
database->server->master_id = ptr->server->node_id;
database->server->depth = 1; // Add Depth 1 for Slave
break;
}
}
ptr = ptr->next;
}
if (database->server->master_id <= 0 && SERVER_IS_SLAVE(database->server))
if (SERVER_IS_SLAVE(database->server) &&
(database->server->master_id <= 0 ||
database->server->master_id != handle->master->server->node_id))
{
monitor_clear_pending_status(database, SERVER_SLAVE);
monitor_set_pending_status(database, SERVER_SLAVE_OF_EXTERNAL_MASTER);
}
database = database->next;