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

Clean up connection routing tutorials

Browse Source 
Wrapped lines to 80 characters, fixed minor differences and reworded
sections so that they are identical.
This commit is contained in:
Markus Mäkelä
2018-03-09 11:04:54 +02:00
parent 944d47167f
commit b7d19a6670
2 changed files with 148 additions and 99 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@ -2,43 +2,41 @@
# Environment & Solution Space # Environment & Solution Space
The object of this tutorial is to have a system that has two ports available, one for The object of this tutorial is to have a system that has two ports available,
write connections to the database cluster and the other for read connections to the database. one for write connections to the database cluster and the other for read
connections to the database.
## Setting up MariaDB MaxScale ## Setting up MariaDB MaxScale
The first part of this tutorial is covered in [MariaDB MaxScale Tutorial](MaxScale-Tutorial.md). 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 Please read it and follow the instructions for setting up MariaDB MaxScale with
type of cluster you want to use. the type of cluster you want to use.
Once you have MariaDB MaxScale installed and the database users created, we can create Once you have MariaDB MaxScale installed and the database users created, we can
the configuration file for MariaDB MaxScale. create the configuration file for MariaDB MaxScale.
## Creating Your MariaDB MaxScale Configuration ## Creating Your MariaDB MaxScale Configuration
MariaDB MaxScale configuration is held in an ini file that is located in the file maxscale.cnf MariaDB MaxScale reads its configuration from `/etc/maxscale.cnf`. A template
in the directory /etc, if you have installed in the default location then this file configuration is provided with the MaxScale installation.
is available in /etc/maxscale.cnf. This is not created as part of the installation process
and must be manually created. A template file does exist within the /usr/share/maxscale directory
that may be use as a basis for your configuration.
A global, maxscale, section is included within every MariaDB MaxScale configuration file; A global, `[maxscale]`, section is included within every MariaDB MaxScale
this is used to set the values of various MariaDB MaxScale wide parameters, perhaps configuration file; this is used to set the values of various MariaDB MaxScale
the most important of these is the number of threads that MariaDB MaxScale will use wide parameters, perhaps the most important of these is the number of threads
to execute the code that forwards requests and handles responses for clients. that MariaDB MaxScale will use to handle client requests.
``` ```
[maxscale] [maxscale]
threads=4 threads=4
``` ```
Since we are using Galera Cluster and connection routing we want a single to which Since we are using Galera Cluster and connection routing we want a single to
the client application can connect; MariaDB MaxScale will then route connections to which the client application can connect; MariaDB MaxScale will then route
this port onwards to the various nodes within the Galera Cluster. To achieve this connections to this port onwards to the various nodes within the Galera
within MariaDB MaxScale we need to define a service in the ini file. Create a section Cluster. To achieve this within MariaDB MaxScale we need to define a service in
for each in your MariaDB MaxScale configuration file and set the type to service, the ini file. Create a section for each in your MariaDB MaxScale configuration
the section name is the names of the service and should be meaningful to file and set the type to service, the section name is the names of the service
the administrator. Names may contain whitespace. and should be meaningful to the administrator. Names may contain whitespace.
``` ```
[Galera Service] [Galera Service]
@ -46,9 +44,9 @@ type=service
``` ```
The router for this section the readconnroute module, also the service should be The router for this section the readconnroute module, also the service should be
provided with the list of servers that will be part of the cluster. The server names provided with the list of servers that will be part of the cluster. The server
given here are actually the names of server sections in the configuration file and not names given here are actually the names of server sections in the configuration
the physical hostnames or addresses of the servers. file and not the physical hostnames or addresses of the servers.
``` ```
[Galera Service] [Galera Service]
@ -57,12 +55,13 @@ router=readconnroute
servers=dbserv1, dbserv2, dbserv3 servers=dbserv1, dbserv2, dbserv3
``` ```
In order to instruct the router to which servers it should route we must add router In order to instruct the router to which servers it should route we must add
options to the service. The router options are compared to the status that the monitor router options to the service. The router options are compared to the status
collects from the servers and used to restrict the eligible set of servers to which that that the monitor collects from the servers and used to restrict the eligible set
service may route. In our case we use the option that restricts us to servers that are of servers to which that service may route. In our case we use the option that
fully functional members of the Galera cluster which are able to support SQL operations restricts us to servers that are fully functional members of the Galera cluster
on the cluster. To achieve this we use the router option synced. which are able to support SQL operations on the cluster. To achieve this we use
the router option synced.
``` ```
[Galera Service] [Galera Service]
@ -72,29 +71,28 @@ router_options=synced
servers=dbserv1, dbserv2, dbserv3 servers=dbserv1, dbserv2, dbserv3
``` ```
The final step in the service section is to add the username and password that will be The final step in the services section is to add the username and password that
used to populate the user data from the database cluster. There are two options for will be used to populate the user data from the database cluster. There are two
representing the password, either plain text or encrypted passwords may be used. options for representing the password, either plain text or encrypted passwords
In order to use encrypted passwords a set of keys must be generated that will be used may be used. In order to use encrypted passwords a set of keys must be
by the encryption and decryption process. To generate the keys use the maxkeys command generated that will be used by the encryption and decryption process. To
and pass the name of the secrets file in which the keys are stored. generate the keys use the `maxkeys` command and pass the name of the secrets
file in which the keys are stored.
``` ```
% maxkeys /var/lib/maxscale/.secrets maxkeys /var/lib/maxscale/.secrets
%
``` ```
Once the keys have been created the maxpasswd command can be used to generate Once the keys have been created the maxpasswd command can be used to generate
the encrypted password. the encrypted password.
``` ```
% maxpasswd plainpassword maxpasswd plainpassword
96F99AA1315BDC3604B006F427DD9484 96F99AA1315BDC3604B006F427DD9484
%
``` ```
The username and password, either encrypted or plain text, are stored in the service The username and password, either encrypted or plain text, are stored in the
section using the user and passwd parameters. service section using the user and passwd parameters.
``` ```
[Galera Service] [Galera Service]
@ -106,12 +104,12 @@ user=maxscale
passwd=96F99AA1315BDC3604B006F427DD9484 passwd=96F99AA1315BDC3604B006F427DD9484
``` ```
This completes the definitions required by the service, however listening ports must This completes the definitions required by the services, however listening ports
be associated with a service in order to allow network connections. This is done by must be associated with the services in order to allow network connections. This
creating a series of listener sections. These sections again are named for the convenience is done by creating a series of listener sections. These sections again are
of the administrator and should be of type listener with an entry labeled service which named for the convenience of the administrator and should be of type listener
contains the name of the service to associate the listener with. with an entry labeled service which contains the name of the service to
Each service may have multiple listeners. associate the listener with. Each service may have multiple listeners.
``` ```
[Galera Listener] [Galera Listener]
@ -131,27 +129,27 @@ protocol=MariaDBClient
port=4306 port=4306
``` ```
An address parameter may be given if the listener is required to bind to a particular An address parameter may be given if the listener is required to bind to a
network address when using hosts with multiple network addresses. particular network address when using hosts with multiple network addresses. The
The default behavior is to listen on all network interfaces. default behavior is to listen on all network interfaces.
## Configuring the Monitor and Servers ## Configuring the Monitor and Servers
The next step is the configuration of the monitor and the servers that the The next step is the configuration of the monitor and the servers that the
service uses. This is process described in the service uses. This is process described in the
[Configuring Galera Monitor](Configuring-Galera-Monitor.md) [Configuring Galera Monitor](Configuring-Galera-Monitor.md) document.
document.
## Configuring the Administrative Interface ## Configuring the Administrative Interface
The final stage in the configuration is to add the option service which is used by The final stage in the configuration is to add the option service which is used
the maxadmin command to connect to MariaDB MaxScale for monitoring and by the maxadmin command to connect to MariaDB MaxScale for monitoring and
administration purposes. This creates a service section and a listener section. administration purposes. This creates a service section and a listener section.
``` ```
[CLI] [CLI]
type=service type=service
router=cli router=cli
[CLI Listener] [CLI Listener]
type=listener type=listener
service=CLI service=CLI
@ -162,26 +160,25 @@ socket=default
## Starting MariaDB MaxScale ## Starting MariaDB MaxScale
Upon completion of the configuration process MariaDB MaxScale is ready to be Upon completion of the configuration process MariaDB MaxScale is ready to be
started for the first time. This may either be done manually by running the started for the first time. For newer systems that use systemd, use the _systemctl_ command.
maxscale command or via the service interface.
``` ```
% maxscale sudo systemctl start maxscale
``` ```
or For older SysV systems, use the _service_ command.
``` ```
% service maxscale start sudo service maxscale start
``` ```
Check the error log in /var/log/maxscale to see if any errors are detected in If MaxScale fails to start, check the error log in `/var/log/maxscale/` to see
the configuration file and to confirm MariaDB MaxScale has been started. if any errors are detected in the configuration file. The `maxadmin` command may
Also the maxadmin command may be used to confirm that MariaDB MaxScale is running be used to confirm that MariaDB MaxScale is running and the services, listeners
and the services, listeners etc have been correctly configured. etc have been correctly configured.
``` ```
% maxadmin list services % sudo maxadmin list services
Services. Services.
--------------------------+----------------------+--------+--------------- --------------------------+----------------------+--------+---------------
@ -190,7 +187,7 @@ Service Name | Router Module | #Users | Total Sessions
Galera Service | readconnroute | 1 | 1 Galera Service | readconnroute | 1 | 1
CLI | cli | 2 | 2 CLI | cli | 2 | 2
--------------------------+----------------------+--------+--------------- --------------------------+----------------------+--------+---------------
% maxadmin list servers % sudo maxadmin list servers
Servers. Servers.
-------------------+-----------------+-------+-------------+------------------- -------------------+-----------------+-------+-------------+-------------------
Server | Address | Port | Connections | Status Server | Address | Port | Connections | Status
@ -211,7 +208,7 @@ mechanism of the Galera Monitor module. For more details,
read the [Galera Monitor](../Monitors/Galera-Monitor.md) documentation. read the [Galera Monitor](../Monitors/Galera-Monitor.md) documentation.
``` ```
% maxadmin list listeners % sudo maxadmin list listeners
Listeners. Listeners.
---------------------+--------------------+-----------------+-------+-------- ---------------------+--------------------+-----------------+-------+--------
@ -224,9 +221,9 @@ CLI | maxscaled | localhost | 6603 | Running
``` ```
MariaDB MaxScale is now ready to start accepting client connections and routing MariaDB MaxScale is now ready to start accepting client connections and routing
them to the master or slaves within your cluster. Other configuration options are them to the cluster. More options may be found in the
available that can alter the criteria used for routing, such as using weights to [Configuration Guide](../Getting-Started/Configuration-Guide.md)
obtain unequal balancing operations. and in the router module documentation.
These options may be found in the MariaDB MaxScale Configuration Guide.
More detail on the use of maxadmin can be found in the document More detail on the use of `maxadmin` can be found in the
["MaxAdmin - The MariaDB MaxScale Administration & Monitoring Client Application"](../Reference/MaxAdmin.md). [MaxAdmin](../Reference/MaxAdmin.md) document.

102
Documentation/Tutorials/MariaDB-Replication-Connection-Routing-Tutorial.md
View File

@ -2,26 +2,44 @@
# Environment & Solution Space # Environment & Solution Space
The object of this tutorial is to have a system that has two ports available, one for write connections to the database cluster and the other for read connections to the database. The object of this tutorial is to have a system that has two ports available,
one for write connections to the database cluster and the other for read
connections to the database.
## Setting up MariaDB MaxScale ## Setting up MariaDB MaxScale
The first part of this tutorial is covered in [MariaDB MaxScale Tutorial](MaxScale-Tutorial.md). Please read it and follow the instructions for setting up MariaDB MaxScale with the type of cluster you want to use. The first part of this tutorial is covered in [MariaDB MaxScale Tutorial](MaxScale-Tutorial.md).
Please read it and follow the instructions for setting up MariaDB MaxScale with
the type of cluster you want to use.
Once you have MariaDB MaxScale installed and the database users created, we can create the configuration file for MariaDB MaxScale. Once you have MariaDB MaxScale installed and the database users created, we can
create the configuration file for MariaDB MaxScale.
## Creating Your MariaDB MaxScale Configuration ## Creating Your MariaDB MaxScale Configuration
MariaDB MaxScale reads its configuration from `/etc/maxscale.cnf`. A template configuration is provided with the MaxScale installation. MariaDB MaxScale reads its configuration from `/etc/maxscale.cnf`. A template
configuration is provided with the MaxScale installation.
A global, `[maxscale]`, section is included within every MariaDB MaxScale configuration file; this is used to set the values of various MariaDB MaxScale wide parameters, perhaps the most important of these is the number of threads that MariaDB MaxScale will use to handle client requests. A global, `[maxscale]`, section is included within every MariaDB MaxScale
configuration file; this is used to set the values of various MariaDB MaxScale
wide parameters, perhaps the most important of these is the number of threads
that MariaDB MaxScale will use to handle client requests.
``` ```
[maxscale] [maxscale]
threads=4 threads=4
``` ```
Since we are using MariaDB Replication and connection routing we want two different ports to which the client application can connect; one that will be directed to the current master within the replication cluster and another that will load balance between the slaves. To achieve this within MariaDB MaxScale we need to define two services in the ini file; one for the read/write operations that should be executed on the master server and another for connections to one of the slaves. Create a section for each in your MariaDB MaxScale configuration file and set the type to service, the section names are the names of the services themselves and should be meaningful to the administrator. Avoid using whitespace in the section names. Since we are using MariaDB Replication and connection routing we want two
different ports to which the client application can connect; one that will be
directed to the current master within the replication cluster and another that
will load balance between the slaves. To achieve this within MariaDB MaxScale we
need to define two services in the ini file; one for the read/write operations
that should be executed on the master server and another for connections to one
of the slaves. Create a section for each in your MariaDB MaxScale configuration
file and set the type to service, the section names are the names of the
services themselves and should be meaningful to the administrator. Avoid using
whitespace in the section names.
``` ```
[Write-Service] [Write-Service]
@ -31,7 +49,12 @@ type=service
type=service type=service
``` ```
The router for these two sections is identical, the readconnroute module, also the services should be provided with the list of servers that will be part of the cluster. The server names given here are actually the names of server sections in the configuration file and not the physical hostnames or addresses of the servers.
The router for these two sections is identical, the readconnroute module, also
the services should be provided with the list of servers that will be part of
the cluster. The server names given here are actually the names of server
sections in the configuration file and not the physical hostnames or addresses
of the servers.
``` ```
[Write-Service] [Write-Service]
@ -45,7 +68,11 @@ router=readconnroute
servers=dbserv1, dbserv2, dbserv3 servers=dbserv1, dbserv2, dbserv3
``` ```
In order to instruct the router to which servers it should route we must add router options to the service. The router options are compared to the status that the monitor collects from the servers and used to restrict the eligible set of servers to which that service may route. In our case we use the two options master and slave for our two services. In order to instruct the router to which servers it should route we must add
router options to the service. The router options are compared to the status
that the monitor collects from the servers and used to restrict the eligible set
of servers to which that service may route. In our case we use the two options
master and slave for our two services.
``` ```
[Write-Service] [Write-Service]
@ -61,20 +88,28 @@ router_options=slave
servers=dbserv1, dbserv2, dbserv3 servers=dbserv1, dbserv2, dbserv3
``` ```
The final step in the service sections is to add the username and password that will be used to populate the user data from the database cluster. There are two options for representing the password, either plain text or encrypted passwords may be used. In order to use encrypted passwords a set of keys must be generated that will be used by the encryption and decryption process. To generate the keys use the maxkeys command and pass the name of the secrets file in which the keys are stored. The final step in the services section is to add the username and password that
will be used to populate the user data from the database cluster. There are two
options for representing the password, either plain text or encrypted passwords
may be used. In order to use encrypted passwords a set of keys must be
generated that will be used by the encryption and decryption process. To
generate the keys use the `maxkeys` command and pass the name of the secrets
file in which the keys are stored.
``` ```
maxkeys /var/lib/maxscale/.secrets maxkeys /var/lib/maxscale/.secrets
``` ```
Once the keys have been created the maxpasswd command can be used to generate the encrypted password. Once the keys have been created the maxpasswd command can be used to generate
the encrypted password.
``` ```
maxpasswd plainpassword maxpasswd plainpassword
96F99AA1315BDC3604B006F427DD9484 96F99AA1315BDC3604B006F427DD9484
``` ```
The username and password, either encrypted or plain text, are stored in the service section using the user and passwd parameters. The username and password, either encrypted or plain text, are stored in the
service section using the user and passwd parameters.
``` ```
[Write-Service] [Write-Service]
@ -94,7 +129,12 @@ user=maxscale
passwd=96F99AA1315BDC3604B006F427DD9484 passwd=96F99AA1315BDC3604B006F427DD9484
``` ```
This completes the definitions required by the services, however listening ports must be associated with the services in order to allow network connections. This is done by creating a series of listener sections. These sections again are named for the convenience of the administrator and should be of type listener with an entry labeled service which contains the name of the service to associate the listener with. Each service may have multiple listeners. This completes the definitions required by the services, however listening ports
must be associated with the services in order to allow network connections. This
is done by creating a series of listener sections. These sections again are
named for the convenience of the administrator and should be of type listener
with an entry labeled service which contains the name of the service to
associate the listener with. Each service may have multiple listeners.
``` ```
[Write-Listener] [Write-Listener]
@ -124,7 +164,9 @@ protocol=MariaDBClient
port=4307 port=4307
``` ```
An address parameter may be given if the listener is required to bind to a particular network address when using hosts with multiple network addresses. The default behavior is to listen on all network interfaces. 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.
## Configuring the Monitor and Servers ## Configuring the Monitor and Servers
@ -135,7 +177,9 @@ document.
## Configuring the Administrative Interface ## Configuring the Administrative Interface
The final stage in the configuration is to add the option service which is used by the maxadmin command to connect to MariaDB MaxScale for monitoring and administration purposes. This creates a service section and a listener section. The final stage in the configuration is to add the option service which is used
by the maxadmin command to connect to MariaDB MaxScale for monitoring and
administration purposes. This creates a service section and a listener section.
``` ```
[CLI] [CLI]
@ -149,24 +193,28 @@ protocol=maxscaled
socket=default socket=default
``` ```
# Starting MariaDB MaxScale ## Starting MariaDB MaxScale
Upon completion of the configuration process MariaDB MaxScale is ready to be started for the first time. This may either be done manually by running the maxscale command or via the service interface. Upon completion of the configuration process MariaDB MaxScale is ready to be
started for the first time. For newer systems that use systemd, use the _systemctl_ command.
``` ```
maxscale sudo systemctl start maxscale
``` ```
or For older SysV systems, use the _service_ command.
``` ```
service maxscale start sudo 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. If MaxScale fails to start, check the error log in `/var/log/maxscale/` to see
if any errors are detected in the configuration file. 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 % sudo maxadmin list services
Services. Services.
--------------------------+----------------------+--------+--------------- --------------------------+----------------------+--------+---------------
@ -177,7 +225,7 @@ Write Service | readconnroute | 1 | 1
CLI | cli | 2 | 2 CLI | cli | 2 | 2
--------------------------+----------------------+--------+--------------- --------------------------+----------------------+--------+---------------
% maxadmin list servers % sudo maxadmin list servers
Servers. Servers.
-------------------+-----------------+-------+-------------+-------------------- -------------------+-----------------+-------+-------------+--------------------
@ -188,7 +236,7 @@ dbserv2 | 192.168.2.2 | 3306 | 0 | Running, Master
dbserv3 | 192.168.2.3 | 3306 | 0 | Running, Slave dbserv3 | 192.168.2.3 | 3306 | 0 | Running, Slave
-------------------+-----------------+-------+-------------+-------------------- -------------------+-----------------+-------+-------------+--------------------
% maxadmin list listeners % sudo maxadmin list listeners
Listeners. Listeners.
---------------------+--------------------+-----------------+-------+-------- ---------------------+--------------------+-----------------+-------+--------
@ -200,7 +248,11 @@ CLI | maxscaled | localhost | 6603 | Running
---------------------+--------------------+-----------------+-------+-------- ---------------------+--------------------+-----------------+-------+--------
``` ```
MariaDB MaxScale is now ready to start accepting client connections and routing them to the master or slaves within your cluster. Other configuration options are available that can alter the criteria used for routing, these include monitoring the replication lag within the cluster and routing only to slaves that are within a predetermined delay from the current master or using weights to obtain unequal balancing operations. These options may be found in the MariaDB MaxScale Configuration Guide. MariaDB MaxScale is now ready to start accepting client connections and routing
them to the cluster. More options may be found in the
[Configuration Guide](../Getting-Started/Configuration-Guide.md)
and in the router module documentation.
More detail on the use of maxadmin can be found in the document [MaxAdmin - The MariaDB MaxScale Administration & Monitoring Client Application](Administration-Tutorial.md). More detail on the use of `maxadmin` can be found in the
[MaxAdmin](../Reference/MaxAdmin.md) document.