Merge branch '2.1' into develop
This commit is contained in:
Johan Wikman
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
Reference in New Issue
Block a user