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

Additional documentation cleanup for 2.1

Browse Source 
Mostly just reflow text (=linebreaks) for better diffs. Some small changes.
Remove Debug-And-Diagnostic-Support.md.
This commit is contained in:
Esa Korhonen
2017-04-21 11:29:58 +03:00
parent 2cc3382a46
commit f1efe72f66
12 changed files with 604 additions and 2276 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,8 +1,9 @@
# MariaDB MaxScale Administration Tutorial
## Common Administration Tasks
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.
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)
@ -13,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 install 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 using 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 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.
<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
@ -82,36 +118,38 @@ It is possible to use the maxadmin command to obtain statistics about the servic
MaxScale>
```
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.
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
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`.
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 handle a client session,
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. 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.
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 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.
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
@ -125,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,19 +190,27 @@ To determine what client are currently connected to MariaDB MaxScale, you can us
```
<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. 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.
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.
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
```
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.
@ -170,8 +220,11 @@ The maxscale log can also be flushed explicitly.
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 as follows.
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/maxscale.log {
monthly
@ -190,15 +243,15 @@ endscript
**Note**:
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:
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'
`
`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/maxscale.log {
@ -213,28 +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.
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.
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.

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

@ -2,11 +2,13 @@
## Overview
The document covers the MySQL Cluster 7.2.17 setup and MariaDB MaxScale configuration for 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:
@ -19,7 +21,8 @@ The MySQL Cluster 7.2.17 setup is based on two virtual servers with Linux Centos
* 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]
@ -45,7 +48,8 @@ hostname=178.62.38.199
hostname=162.243.90.81
```
Note that it’s possible to specify all node id:s 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:
@ -70,9 +74,12 @@ 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, then the data nodes, and finally 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
@ -96,14 +103,16 @@ Each cluster node process must be started separately, and on the host where it r
## 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.
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 as shown here, although you might see some slight
differences in the output depending upon the exact version of MySQL in use:
```
[root@server1 ~]# ndb_mgm
[root@server1 ~]# ndb_mgm
-- NDB Cluster -- Management Client --
@ -131,10 +140,11 @@ 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
@ -254,7 +264,8 @@ Assuming MariaDB MaxScale is installed in server1, start it.
[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
@ -297,7 +308,8 @@ 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:
@ -321,7 +333,8 @@ It’s now possible to run basic tests with the read connection load balancing
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"

108
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 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.
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, the configuration file for MariaDB MaxScale can be written.
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 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.
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 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.
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 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.
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 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.
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 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.
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, use the `maxpasswd` command 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 in plain text, are stored in the service section.
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 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.
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 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`.
```
[dbserv1]
type=server
@ -107,7 +149,11 @@ port=3306
protocol=MySQLBackend
```
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.
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
```
Similarly to the password definition in the server either a plain text or an encrypted password 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 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.
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,16 +186,25 @@ socket=default
# Starting MariaDB MaxScale
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.
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
@ -199,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, 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).
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).