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

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).