From 1e34bd7642a14f490ca005b4249e22e88bad76c6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Markus=20M=C3=A4kel=C3=A4?= Date: Wed, 19 Apr 2017 17:04:46 +0300 Subject: [PATCH 01/29] Update Notification-Service.md Removed change history, changed company name. --- .../Tutorials/Notification-Service.md | 37 ++++--------------- 1 file changed, 8 insertions(+), 29 deletions(-) diff --git a/Documentation/Tutorials/Notification-Service.md b/Documentation/Tutorials/Notification-Service.md index 450082cc4..92f733d54 100644 --- a/Documentation/Tutorials/Notification-Service.md +++ b/Documentation/Tutorials/Notification-Service.md @@ -1,27 +1,5 @@ # MariaDB MaxScale Notification Service and Feedback Support -Massimiliano Pinto - -Last Updated: 10th March 2015 - -## Contents - -## Document History - - - - - - - - - - - - -
DateChangeWho
10th March 2015Initial versionMassimiliano Pinto
- - ## Overview The purpose of Notification Service in MariaDB MaxScale is for a customer registered for the service to receive update notices, security bulletins, fixes and workarounds that are tailored to the database server configuration. @@ -30,9 +8,9 @@ The purpose of Notification Service in MariaDB MaxScale is for a customer regist MariaDB MaxScale may collect the installed plugins and send the information's nightly, between 2:00 AM and 4:59 AM. -It tries to send data and if there is any failure (timeout, server is down, etc), the next retry is in 1800 seconds (30 minutes) +It tries to send data and if there is any failure (timeout, server is down, etc), the next retry is in 1800 seconds (30 minutes). -This feature is not enabled by default: MariaDB MaxScale must be configured in [feedback] section: +This feature is not enabled by default: MariaDB MaxScale must be configured in `[feedback]` section: ``` [feedback] @@ -41,15 +19,16 @@ feedback_url=https://enterprise.mariadb.com/feedback/post feedback_user_info=x-y-z-w ``` -The activation code that will be provided by MariaDB corp upon request by the customer and it should be put in feedback_user_info. +The activation code that will be provided by MariaDB Corporation Ab upon request by the customer and it should be put in feedback_user_info. Example: +``` feedback_user_info=0467009f-b04d-45b1-a77b-b6b2ec9c6cf4 - +``` MariaDB MaxScale generates the feedback report containing following information: - -The activation code used to enable feedback + - The activation code used to enable feedback - MariaDB MaxScale Version - An identifier of the MariaDB MaxScale installation, i.e. the HEX encoding of SHA1 digest of the first network interface MAC address - Operating System (i.e Linux) @@ -57,12 +36,12 @@ MariaDB MaxScale generates the feedback report containing following information: - All the modules in use in MariaDB MaxScale and their API and version - MariaDB MaxScale server UNIX_TIME at generation time -MariaDB MaxScale shall send the generated feedback report to a feedback server specified in feedback_url +MariaDB MaxScale shall send the generated feedback report to a feedback server specified in _feedback_url_. ## Manual Operation -If it’s not possible to send data due to firewall or security settings the report could be generated manually (feedback_user_info is required) via MaxAdmin +If it’s not possible to send data due to firewall or security settings the report could be generated manually (feedback_user_info is required) via MaxAdmin. ``` MaxScale>show feedbackreport From afe75e9006be2ab3eabe704facadd47dafe472b7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Markus=20M=C3=A4kel=C3=A4?= Date: Wed, 19 Apr 2017 17:20:09 +0300 Subject: [PATCH 02/29] Update Simple-Sharding-Tutorial.md --- .../Tutorials/Simple-Sharding-Tutorial.md | 29 ++++++------------- 1 file changed, 9 insertions(+), 20 deletions(-) diff --git a/Documentation/Tutorials/Simple-Sharding-Tutorial.md b/Documentation/Tutorials/Simple-Sharding-Tutorial.md index 62ff35323..7268ef64f 100644 --- a/Documentation/Tutorials/Simple-Sharding-Tutorial.md +++ b/Documentation/Tutorials/Simple-Sharding-Tutorial.md @@ -1,4 +1,4 @@ -#Simple Sharding with Two Servers +# Simple Sharding with Two Servers ![Schema Based Sharding](images/Simple-Sharding.png) @@ -10,25 +10,13 @@ MariaDB MaxScale will appear to the client as a database server with the combina This document is designed as a simple tutorial on schema-based sharding using MariaDB MaxScale in an environment in which you have two servers. The object of this tutorial is to have a system that, to the client side, acts like a single MySQL database but actually is sharded between the two servers. -The process of setting and configuring MariaDB MaxScale will be covered within this document. The installation and configuration of the MySQL servers will not be covered in-depth. The users should be configured according to the configuration guide. +The database users should be configured according to [the configuration guide](../Getting-Started/Configuration-Guide.md). The [MaxScale Tutorial](MaxScale-Tutorial.md) contains easy to follow instructions on how to set up MaxScale. + +This tutorial will assume the user is using of the binary distributions available and has installed this in the default location. The process of configuring MariaDB MaxScale will be covered within this document. The installation and configuration of the MySQL servers will not be covered in-depth. -This tutorial will assume the user is running from one of the binary distributions available and has installed this in the default location. Building from source code in GitHub is covered in guides elsewhere as is installing to non-default locations. +## Preparing MaxScale -## Process - -The steps involved in creating a system from the binary distribution of MariaDB MaxScale are: - -* Install the package relevant to your distribution - -* Create the required users on your MariaDB or MySQL server - -* Create a MariaDB MaxScale configuration file - -### Installation - -The precise installation process will vary from one distribution to another details of what to do with the RPM and DEB packages can be found on the download site when you select the distribution you are downloading from. The process involves setting up your package manager to include the MariaDB repositories and then running the package manager for your distribution, RPM or apt-get. - -Upon successful completion of the installation command you will have MariaDB MaxScale installed and ready to be run but without a configuration. You must create a configuration file before you first run MariaDB MaxScale. +Follow the [MaxScale Tutorial](MaxScale-Tutorial.md) to install and prepare the required database users for MaxScale. You don't need to create the configuration file for MaxScale as it will be covered in the next section. ### Creating Your MariaDB MaxScale Configuration @@ -92,7 +80,8 @@ After this we have a fully working configuration and we can move on to starting Upon completion of the configuration process MariaDB MaxScale is ready to be started . This may either be done manually by running the maxscale command or via the service interface. The service scripts are located in the `/etc/init.d/` folder and are accessible through both the `service` and `systemctl` commands. -After starting MariaDB MaxScale check the error log in /var/log/maxscale to see if any errors are detected in the configuration file. Also the maxadmin command may be used to confirm that MariaDB MaxScale is running and the services, listeners etc have been correctly configured. - MariaDB MaxScale is now ready to start accepting client connections and routing them. Queries are routed to the right servers based on the database they target and switching between the shards is seamless since MariaDB MaxScale keeps the session state intact between servers. +If MariaDB MaxScale fails to start, check the error log in `/var/log/maxscale` to see what sort of errors were detected. + +**Note:** As the sharding solution in MaxScale is relatively simple, cross-database queries between two or more shards are not supported. From 94acc9b9ab7820f96120424812a60678930d826f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Markus=20M=C3=A4kel=C3=A4?= Date: Wed, 19 Apr 2017 17:32:36 +0300 Subject: [PATCH 03/29] Update MaxScale-HA-with-Corosync-Pacemaker.md --- .../MaxScale-HA-with-Corosync-Pacemaker.md | 99 +++++++++---------- 1 file changed, 45 insertions(+), 54 deletions(-) diff --git a/Documentation/Tutorials/MaxScale-HA-with-Corosync-Pacemaker.md b/Documentation/Tutorials/MaxScale-HA-with-Corosync-Pacemaker.md index ee7d2ab5c..e41fcf559 100644 --- a/Documentation/Tutorials/MaxScale-HA-with-Corosync-Pacemaker.md +++ b/Documentation/Tutorials/MaxScale-HA-with-Corosync-Pacemaker.md @@ -12,15 +12,15 @@ Please note the solution is a quick setup example that may not be suited for all ## Clustering Software installation -On each node in the cluster do the following steps: +On each node in the cluster do the following steps. -(1) Add clustering repos to yum +### Add clustering repos to yum ``` # vi /etc/yum.repos.d/ha-clustering.repo ``` -Add the following to the file +Add the following to the file. ``` [haclustering] @@ -30,7 +30,7 @@ enabled=1 gpgcheck=0 ``` -(2) Install the software +### Install the software ``` # yum install pacemaker corosync crmsh @@ -44,7 +44,7 @@ Package corosync-1.4.5-2.4.x86_64 Package crmsh-2.0+git46-1.1.x86_64 ``` -(3) Assign hostname on each node +### Assign hostname on each node In this example the three names used for the nodes are: node1,node,node3 @@ -56,7 +56,7 @@ In this example the three names used for the nodes are: node1,node,node3 [root@server3 ~]# hostname node3 ``` -(4) For each node add server names in /etc/hosts +For each node, add all the server names into `/etc/hosts`. ``` [root@node3 ~]# vi /etc/hosts @@ -70,9 +70,9 @@ In this example the three names used for the nodes are: node1,node,node3 10.35.15.26 node3 ``` -**Please note**: add **current-node** as an alias for the current node in each of the /etc/hosts files. +**Note**: add _current-node_ as an alias for the current node in each of the /etc/hosts files. -(5) Prepare authkey for optional cryptographic use +### Prepare authkey for optional cryptographic use On one of the nodes, say node2 run the corosync-keygen utility and follow @@ -84,7 +84,7 @@ Corosync Cluster Engine Authentication key generator. Gathering 1024 bits After completion the key will be found in /etc/corosync/authkey. ``` -(6) Prepare the corosync configuration file +### Prepare the corosync configuration file Using node2 as an example: @@ -141,7 +141,7 @@ name: pacemaker } ``` -**Please note** in this example: +**Note**: in this example: - unicast UDP is used @@ -149,7 +149,7 @@ name: pacemaker - Pacemaker processes are started by the corosync daemon, so there is no need to launch it via /etc/init.d/pacemaker start -(7) copy configuration files and auth key on each of the other nodes +### Copy configuration files and auth key on each of the other nodes ``` [root@node2 ~]# scp /etc/corosync/* root@node1:/etc/corosync/ @@ -157,11 +157,7 @@ name: pacemaker [root@node2 ~]# scp /etc/corosync/* root@nodeN:/etc/corosync/ ``` -(8) Corosync needs port *5*405 to be opened: - -- configure any firewall or iptables accordingly - -For a quick start just disable iptables on each nodes: +Corosync needs port 5405 to be opened. Configure any firewall or iptables accordingly. For a quick start just disable iptables on each nodes: ``` [root@node2 ~]# service iptables stop @@ -169,7 +165,7 @@ For a quick start just disable iptables on each nodes: [root@nodeN ~]# service iptables stop ``` -(9) Start Corosyn on each node: +### Start Corosyn on each node ``` [root@node2 ~] #/etc/init.d/corosync start @@ -177,14 +173,14 @@ For a quick start just disable iptables on each nodes: [root@nodeN ~] #/etc/init.d/corosync start ``` -and check the corosync daemon is successfully bound to port 5405: +Check that the corosync daemon is successfully bound to port 5405. ``` [root@node2 ~] #netstat -na | grep 5405 udp 0 0 10.228.103.72:5405 0.0.0.0:* ``` -Check if other nodes are reachable with nc utility and option UDP (-u): +Check if other nodes are reachable with nc utility and option UDP (-u). ``` [root@node2 ~] #echo "check ..." | nc -u node1 5405 @@ -194,19 +190,21 @@ Check if other nodes are reachable with nc utility and option UDP (-u): [root@node1 ~] #echo "check ..." | nc -u node3 5405 ``` -If the following message is displayed +If the following message is displayed, there is an issue with communication between the nodes. -**nc: Write error: Connection refused** +``` +nc: Write error: Connection refused +``` -There is an issue with communication between the nodes, this is most likely to be an issue with the firewall configuration on your nodes. Check and resolve issues with your firewall configuration. +This is most likely to be an issue with the firewall configuration on your nodes. Check and resolve any issues with your firewall configuration. -(10) Check the cluster status, from any node +### Check the cluster status from any node ``` [root@node3 ~]# crm status ``` -After a while this will be the output: +The command should produce the following. ``` [root@node3 ~]# crm status @@ -239,9 +237,9 @@ For additional information see: [http://clusterlabs.org/doc/](http://clusterlabs.org/doc/) -The configuration is automatically updated on every node: +The configuration is automatically updated on every node. -Check it from another node, say node1 +Check it from another node, say node1: ``` [root@node1 ~]# crm configure show @@ -260,9 +258,9 @@ property cib-bootstrap-options: \ The Corosync / Pacemaker cluster is ready to be configured to manage resources. -## MariaDB MaxScale init script /etc/init.d/maxscale +## MariaDB MaxScale init script -The MariaDB MaxScale /etc/init.d./maxscale script allows to start/stop/restart and monitor MariaDB MaxScale process running in the system. +The MariaDB MaxScale init script in `/etc/init.d./maxscale` allows to start, stop, restart and monitor the MariaDB MaxScale process running on the system. ``` [root@node1 ~]# /etc/init.d/maxscale @@ -315,14 +313,11 @@ Checking MaxScale status: MaxScale (pid 25953) is running.[ OK ] The script exit code for "status" is 0 - -Note: the MariaDB MaxScale script is LSB compatible and returns the proper exit code for each action: - -For additional information; +Read the following for additional information about LSB init scripts: [http://www.linux-ha.org/wiki/LSB_Resource_Agents](http://www.linux-ha.org/wiki/LSB_Resource_Agents) -After checking MariaDB MaxScale is well managed by the /etc/init.d/script is possible to configure the MariaDB MaxScale HA via Pacemaker. +After checking that the init scripts for MariaDB MaxScale work, it is possible to configure MariaDB MaxScale for HA via Pacemaker. # Configure MariaDB MaxScale for HA with Pacemaker @@ -333,7 +328,7 @@ op start interval="0” timeout=”15s” \ op stop interval="0” timeout=”30s” ``` -MaxScale resource will be started: +MaxScale resource will be started. ``` [root@node2 ~]# crm status @@ -351,11 +346,11 @@ Online: [ node1 node2 node3 ] MaxScale (lsb:maxscale): Started node1 ``` -##Basic use cases: +## Basic use cases -### 1. Resource restarted after a failure: +### Resource restarted after a failure -In the example MariaDB MaxScale PID is 26114, kill the process immediately: +In the example MariaDB MaxScale PID is 26114, kill the process immediately. ``` [root@node2 ~]# kill -9 26114 @@ -377,9 +372,9 @@ Failed actions: MaxScale_monitor_15000 on node1 'not running' (7): call=19, status=complete, last-rc-change='Mon Jun 30 13:16:14 2014', queued=0ms, exec=0ms ``` -**Note** the **MaxScale_monitor** failed action +**Note**: the _MaxScale_monitor_ failed action -After a few seconds it will be started again: +After a few seconds it will be started again. ``` [root@node2 ~]# crm status @@ -397,9 +392,9 @@ Online: [ node1 node2 node3 ] MaxScale (lsb:maxscale): Started node1 ``` -### 2. The resource cannot be migrated to node1 for a failure: +### The resource cannot be migrated to node1 for a failure -First, migrate the the resource to another node, say node3 +First, migrate the the resource to another node, say node3. ``` [root@node1 ~]# crm resource migrate MaxScale node3 @@ -412,7 +407,7 @@ Failed actions: MaxScale_start_0 on node1 'not running' (7): call=76, status=complete, last-rc-change='Mon Jun 30 13:31:17 2014', queued=2015ms, exec=0ms ``` -Note the **MaxScale_start** failed action on node1, and after a few seconds +**Note**: the _MaxScale_start_ failed action on node1, and after a few seconds. ``` [root@node3 ~]# crm status @@ -434,7 +429,7 @@ Failed actions: MaxScale_start_0 on node1 'not running' (7): call=76, status=complete, last-rc-change='Mon Jun 30 13:31:17 2014', queued=2015ms, exec=0ms ``` -Successfully, MaxScale has been started on a new node: node2. +Successfully, MaxScale has been started on a new node (node2). **Note**: Failed actions remain in the output of crm status. @@ -447,7 +442,7 @@ Cleaning up MaxScale on node2 Cleaning up MaxScale on node3 ``` -The cleaned status is visible from other nodes as well: +The cleaned status is visible from other nodes as well. ``` [root@node2 ~]# crm status @@ -467,25 +462,21 @@ Online: [ node1 node2 node3 ] ## Add a Virtual IP (VIP) to the cluster -It’s possible to add a virtual IP to the cluster: +It’s possible to add a virtual IP to the cluster. MariaDB MaxScale process will be only contacted via this IP. The virtual IP can move across nodes in case one of them fails. -MariaDB MaxScale process will be only contacted with this IP, that mat move across nodes with maxscale process as well. - -Setup is very easy: - -assuming an addition IP address is available and can be added to one of the nodes, this i the new configuration to add: +The Setup is very easy. Assuming an addition IP address is available and can be added to one of the nodes, this is the new configuration to add. ``` [root@node2 ~]# crm configure primitive maxscale_vip ocf:heartbeat:IPaddr2 params ip=192.168.122.125 op monitor interval=10s ``` -MariaDB MaxScale process and the VIP must be run in the same node, so it’s mandatory to add to the configuration the group ‘maxscale_service’. +MariaDB MaxScale process and the VIP must be run in the same node, so it is mandatory to add to the configuration to the group ‘maxscale_service’. ``` [root@node2 ~]# crm configure group maxscale_service maxscale_vip MaxScale ``` -The final configuration is, from another node: +The following is the final configuration. ``` [root@node3 ~]# crm configure show @@ -511,7 +502,7 @@ property cib-bootstrap-options: \ last-lrm-refresh=1404125486 ``` -Check the resource status: +Check the resource status. ``` [root@node1 ~]# crm status @@ -533,5 +524,5 @@ Online: [ node1 node2 node3 ] MaxScale (lsb:maxscale): Started node2 ``` -With both resources on node2, now MariaDB MaxScale service will be reachable via the configured VIP address 192.168.122.125 +With both resources on node2, now MariaDB MaxScale service will be reachable via the configured VIP address 192.168.122.125. From 767ec74489d94f595a2f5a09ea8a9d9f04056e39 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Markus=20M=C3=A4kel=C3=A4?= Date: Wed, 19 Apr 2017 17:38:45 +0300 Subject: [PATCH 04/29] Update MySQL-Replication-Connection-Routing-Tutorial.md --- ...Replication-Connection-Routing-Tutorial.md | 69 +++++++------------ 1 file changed, 24 insertions(+), 45 deletions(-) diff --git a/Documentation/Tutorials/MySQL-Replication-Connection-Routing-Tutorial.md b/Documentation/Tutorials/MySQL-Replication-Connection-Routing-Tutorial.md index 597fdf717..c14ff8a5d 100644 --- a/Documentation/Tutorials/MySQL-Replication-Connection-Routing-Tutorial.md +++ b/Documentation/Tutorials/MySQL-Replication-Connection-Routing-Tutorial.md @@ -12,34 +12,34 @@ Once you have MariaDB MaxScale installed and the database users created, we can ## Creating Your MariaDB MaxScale Configuration -MariaDB MaxScale reads its configuration from `/etc/maxscale.cnf`. This is not created as part of the installation process and must be manually created. A template file does exist in the `/usr/share/maxscale` folder that can be use as a basis for your configuration. +MariaDB MaxScale reads its configuration from `/etc/maxscale.cnf`. A template configuration is provided with the MaxScale installation. -A global, maxscale, section is included within every MariaDB MaxScale configuration file; this is used to set the values of various MariaDB MaxScale wide parameters, perhaps the most important of these is the number of threads that MariaDB MaxScale will use to execute the code that forwards requests and handles responses for clients. +A global, `[maxscale]`, section is included within every MariaDB MaxScale configuration file; this is used to set the values of various MariaDB MaxScale wide parameters, perhaps the most important of these is the number of threads that MariaDB MaxScale will use to handle client requests. ``` [maxscale] threads=4 ``` -Since we are using MySQL Replication and connection routing we want two different ports to which the client application can connect; one that will be directed to the current master within the replication cluster and another that will load balance between the slaves. To achieve this within MariaDB MaxScale we need to define two services in the ini file; one for the read/write operations that should be executed on the master server and another for connections to one of the slaves. Create a section for each in your MariaDB MaxScale configuration file and set the type to service, the section names are the names of the services themselves and should be meaningful to the administrator. Names may contain whitespace. +Since we are using MySQL Replication and connection routing we want two different ports to which the client application can connect; one that will be directed to the current master within the replication cluster and another that will load balance between the slaves. To achieve this within MariaDB MaxScale we need to define two services in the ini file; one for the read/write operations that should be executed on the master server and another for connections to one of the slaves. Create a section for each in your MariaDB MaxScale configuration file and set the type to service, the section names are the names of the services themselves and should be meaningful to the administrator. Avoid using whitespace in the section names. ``` -[Write Service] +[Write-Service] type=service -[Read Service] +[Read-Service] type=service ``` The router for these two sections is identical, the readconnroute module, also the services should be provided with the list of servers that will be part of the cluster. The server names given here are actually the names of server sections in the configuration file and not the physical hostnames or addresses of the servers. ``` -[Write Service] +[Write-Service] type=service router=readconnroute servers=dbserv1, dbserv2, dbserv3 -[Read Service] +[Read-Service] type=service router=readconnroute servers=dbserv1, dbserv2, dbserv3 @@ -48,13 +48,13 @@ servers=dbserv1, dbserv2, dbserv3 In order to instruct the router to which servers it should route we must add router options to the service. The router options are compared to the status that the monitor collects from the servers and used to restrict the eligible set of servers to which that service may route. In our case we use the two options master and slave for our two services. ``` -[Write Service] +[Write-Service] type=service router=readconnroute router_options=master servers=dbserv1, dbserv2, dbserv3 -[Read Service] +[Read-Service] type=service router=readconnroute router_options=slave @@ -77,7 +77,7 @@ maxpasswd plainpassword The username and password, either encrypted or plain text, are stored in the service section using the user and passwd parameters. ``` -[Write Service] +[Write-Service] type=service router=readconnroute router_options=master @@ -85,7 +85,7 @@ servers=dbserv1, dbserv2, dbserv3 user=maxscale passwd=96F99AA1315BDC3604B006F427DD9484 -[Read Service] +[Read-Service] type=service router=readconnroute router_options=slave @@ -97,28 +97,28 @@ passwd=96F99AA1315BDC3604B006F427DD9484 This completes the definitions required by the services, however listening ports must be associated with the services in order to allow network connections. This is done by creating a series of listener sections. These sections again are named for the convenience of the administrator and should be of type listener with an entry labeled service which contains the name of the service to associate the listener with. Each service may have multiple listeners. ``` -[Write Listener] +[Write-Listener] type=listener -service=Write Service +service=Write-Service -[Read Listener] +[Read-Listener] type=listener -service=Read Service +service=Read-Service ``` A listener must also define the protocol module it will use for the incoming network protocol, currently this should be the MySQLClient protocol for all database listeners. The listener may then supply a network port to listen on and/or a socket within the file system. ``` -[Write Listener] +[Write-Listener] type=listener -service=Write Service +service=Write-Service protocol=MySQLClient port=4306 socket=/tmp/ClusterMaster -[Read Listener] +[Read-Listener] type=listener -service=Read Service +service=Read-Service protocol=MySQLClient port=4307 ``` @@ -150,7 +150,7 @@ protocol=MySQLBackend In order for MariaDB MaxScale to monitor the servers using the correct monitoring mechanisms a section should be provided that defines the monitor to use and the servers to monitor. Once again a section is created with a symbolic name for the monitor, with the type set to monitor. Parameters are added for the module to use, the list of servers to monitor and the username and password to use when connecting to the the servers with the monitor. ``` -[Replication Monitor] +[Replication-Monitor] type=monitor module=mysqlmon servers=dbserv1, dbserv2, dbserv3 @@ -168,7 +168,7 @@ The final stage in the configuration is to add the option service which is used type=service router=cli -[CLI Listener] +[CLI-Listener] type=listener service=CLI protocol=maxscaled @@ -195,59 +195,38 @@ Check the error log in /var/log/maxscale/ to see if any errors are detected in t % maxadmin list services Services. - --------------------------+----------------------+--------+--------------- - Service Name | Router Module | #Users | Total Sessions - --------------------------+----------------------+--------+--------------- - Read Service | readconnroute | 1 | 1 - Write Service | readconnroute | 1 | 1 - CLI | cli | 2 | 2 - --------------------------+----------------------+--------+--------------- % maxadmin list servers Servers. - -------------------+-----------------+-------+-------------+-------------------- - Server | Address | Port | Connections | Status - -------------------+-----------------+-------+-------------+-------------------- - dbserv1 | 192.168.2.1 | 3306 | 0 | Running, Slave - dbserv2 | 192.168.2.2 | 3306 | 0 | Running, Master - dbserv3 | 192.168.2.3 | 3306 | 0 | Running, Slave - -------------------+-----------------+-------+-------------+-------------------- % maxadmin list listeners Listeners. - ---------------------+--------------------+-----------------+-------+-------- - Service Name | Protocol Module | Address | Port | State - ---------------------+--------------------+-----------------+-------+-------- - Read Service | MySQLClient | * | 4307 | Running - Write Service | MySQLClient | * | 4306 | Running - CLI | maxscaled | localhost | 6603 | Running - ---------------------+--------------------+-----------------+-------+-------- - -% ``` -MariaDB MaxScale is now ready to start accepting client connections and routing them to the master or slaves within your cluster. Other configuration options are available that can alter the criteria used for routing, these include monitoring the replication lag within the cluster and routing only to slaves that are within a predetermined delay from the current master or using weights to obtain unequal balancing operations. These options may be found in the MariaDB MaxScale Configuration Guide. More detail on the use of maxadmin can be found in the document [MaxAdmin - The MariaDB MaxScale Administration & Monitoring Client Application](Administration-Tutorial.md). +MariaDB MaxScale is now ready to start accepting client connections and routing them to the master or slaves within your cluster. Other configuration options are available that can alter the criteria used for routing, these include monitoring the replication lag within the cluster and routing only to slaves that are within a predetermined delay from the current master or using weights to obtain unequal balancing operations. These options may be found in the MariaDB MaxScale Configuration Guide. + +More detail on the use of maxadmin can be found in the document [MaxAdmin - The MariaDB MaxScale Administration & Monitoring Client Application](Administration-Tutorial.md). From 9d56fc70f66c07c97236db0b57f6d0e37e6954c8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Markus=20M=C3=A4kel=C3=A4?= Date: Wed, 19 Apr 2017 17:42:40 +0300 Subject: [PATCH 05/29] Update SchemaRouter.md --- Documentation/Routers/SchemaRouter.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/Documentation/Routers/SchemaRouter.md b/Documentation/Routers/SchemaRouter.md index b9956d978..36bef935b 100644 --- a/Documentation/Routers/SchemaRouter.md +++ b/Documentation/Routers/SchemaRouter.md @@ -1,4 +1,4 @@ -#SchemaRouter Router +# SchemaRouter Router The SchemaRouter router provides an easy and manageable sharding solution by building a single logical database server from multiple separate ones. Each database is shown to the client and queries targeting unique databases are routed to their respective servers. In addition to providing simple database-based sharding, the schemarouter router also enables cross-node session variable usage by routing all queries that modify the session to all nodes. @@ -29,7 +29,7 @@ The list of databases is built by sending a SHOW DATABASES query to all the serv If you are connecting directly to a database or have different users on some of the servers, you need to get the authentication data from all the servers. You can control this with the `auth_all_servers` parameter. With this parameter, MariaDB MaxScale forms a union of all the users and their grants from all the servers. By default, the schemarouter will fetch the authentication data from all servers. -For example, if two servers have the database 'shard' and the following rights are granted only on one server, all queries targeting the database 'shard' would be routed to the server where the grants were given. +For example, if two servers have the database `shard` and the following rights are granted only on one server, all queries targeting the database `shard` would be routed to the server where the grants were given. ``` # Execute this on both servers @@ -68,6 +68,8 @@ refresh_interval=60 ## Router Options +**Note:** Router options for the Schemarouter were deprecated in MaxScale 2.1. + The following options are options for the `router_options` parameter of the service. Multiple router options are given as a comma separated list of key value pairs. @@ -87,7 +89,7 @@ will not be consistent anymore. ### `refresh_databases` Enable database map refreshing mid-session. These are triggered by a failure to -change the database i.e. `USE ...``queries. +change the database i.e. `USE ...` queries. ### `refresh_interval` From f2a0dbd72d56c2a8cb3e143fe60fbc454e4d6ed6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Markus=20M=C3=A4kel=C3=A4?= Date: Thu, 20 Apr 2017 09:06:00 +0300 Subject: [PATCH 06/29] Update Binlogrouter.md --- Documentation/Routers/Binlogrouter.md | 73 ++++++++++++++------------- 1 file changed, 37 insertions(+), 36 deletions(-) diff --git a/Documentation/Routers/Binlogrouter.md b/Documentation/Routers/Binlogrouter.md index fe12fd470..a0d4bc43e 100644 --- a/Documentation/Routers/Binlogrouter.md +++ b/Documentation/Routers/Binlogrouter.md @@ -13,7 +13,7 @@ replication setup where replication is high-priority. ## Mandatory Router Parameters -The binlogrouter requires the `server`, `user` and `passwd` parameters. These +The binlogrouter requires the `server`, `user` and `password` parameters. These should be configured according to the [Configuration Guide](../Getting-Started/Configuration-Guide.md#service). @@ -32,18 +32,20 @@ following options should be given as a value to the `router_options` parameter. ### `binlogdir` -This parameter allows the location that MariaDB MaxScale uses to store binlog -files to be set. If this parameter is not set to a directory name then MariaDB +This parameter controls the location where MariaDB MaxScale stores the binary log +files. If this parameter is not set to a directory name then MariaDB MaxScale will store the binlog files in the directory -/var/cache/maxscale/. In the binlog dir there is also the 'cache' -directory that contains data retrieved from the master during registration phase -and the master.ini file which contains the configuration of current configured -master. +`/var/cache/maxscale/` where `` is the name of the +service in the configuration file. The _binlogdir_ also contains the +_cache_ subdirectory which stores data retrieved from the master during the slave +registration phase. The master.ini file also resides in the _binlogdir_. This +file keeps track of the current master configuration and it is updated when a +`CHANGE MASTER TO` query is executed. From 2.1 onwards, the 'cache' directory is stored in the same location as other user credential caches. This means that with the default options, the user credential cache is stored in -/var/cache/maxscale///cache/. +`/var/cache/maxscale///cache/`. Read the [MySQL Authenticator](../Authenticators/MySQL-Authenticator.md) documentation for instructions on how to define a custom location for the user @@ -51,45 +53,45 @@ cache. ### `uuid` -This is used to set the unique uuid that the binlog router uses when it connects -to the master server. If no explicit value is given for the uuid in the -configuration file then a uuid will be generated. +This is used to set the unique UUID that the binlog router uses when it connects +to the master server. If no explicit value is given for the UUID in the +configuration file then a UUID will be generated. ### `server_id` -As with uuid, MariaDB MaxScale must have a unique _server id_ for the connection -it makes to the master. This parameter provides the value of the server id that +As with UUID, MariaDB MaxScale must have a unique _server_id_. This parameter +configures the value of the _server_id_ that MariaDB MaxScale will use when connecting to the master. -The id can also be specified using `server-id` but that is deprecated -and will be removed in a future release of MariaDB MaxScale. +Older versions of MaxScale allowed the ID to be specified using `server-id`. +This has been deprecated and will be removed in a future release of MariaDB MaxScale. ### `master_id` -The _server id_ value that MariaDB MaxScale should use to report to the slaves +The _server_id_ value that MariaDB MaxScale should use to report to the slaves that connect to MariaDB MaxScale. This may either be the same as the server id of the real master or can be chosen to be different if the slaves need to be -aware of the proxy layer. The real master server id will be used if the option +aware of the proxy layer. The real master server ID will be used if the option is not set. -The id can also be specified using `master-id` but that is deprecated -and will be removed in a future release of MariaDB MaxScale. +Older versions of MaxScale allowed the ID to be specified using `master-id`. +This has been deprecated and will be removed in a future release of MariaDB MaxScale. ### `master_uuid` -It is a requirement of replication that each slave have a unique UUID value. The -MariaDB MaxScale router will identify itself to the slaves using the uuid of the +It is a requirement of replication that each slave has a unique UUID value. The +MariaDB MaxScale router will identify itself to the slaves using the UUID of the real master if this option is not set. ### `master_version` -The MariaDB MaxScale router will identify itself to the slaves using the server -version of the real master if this option is not set. +By default, the router will identify itself to the slaves using the server +version of the real master. This option allows the router to use a custom version string. ### `master_hostname` -The MariaDB MaxScale router will identify itself to the slaves using the server -hostname of the real master if this option is not set. +By default, the router will identify itself to the slaves using the +hostname of the real master. This option allows the router to use a custom hostname. ### `user` @@ -113,13 +115,13 @@ the router options or using the username and password defined of the service must be granted replication privileges on the database server. ``` - MariaDB> CREATE USER 'repl'@'maxscalehost' IDENTIFIED by 'password'; - MariaDB> GRANT REPLICATION SLAVE ON *.* TO 'repl'@'maxscalehost'; +CREATE USER 'repl'@'maxscalehost' IDENTIFIED by 'password'; +GRANT REPLICATION SLAVE ON *.* TO 'repl'@'maxscalehost'; ``` ### `password` -The password of the above user. If the password is not explicitly given then the +The password for the user. If the password is not explicitly given then the password in the service entry will be used. For compatibility with other username and password definitions within the MariaDB MaxScale configuration file it is also possible to use the parameter passwd=. @@ -167,9 +169,9 @@ incomplete transactions detection. ### `send_slave_heartbeat` -This defines whether (on | off) MariaDB MaxScale sends to the slave the -heartbeat packet when there are no real binlog events to send. The default value -if 'off', no heartbeat event is sent to slave server. If value is 'on' the +This defines whether MariaDB MaxScale sends the heartbeat packet to the slave +when there are no real binlog events to send. The default value +is 'off' and no heartbeat events are sent to slave servers. If value is 'on' the interval value (requested by the slave during registration) is reported in the diagnostic output and the packet is send after the time interval without any event to send. @@ -205,6 +207,7 @@ master.ini or later via CHANGE MASTER TO. This parameter cannot be modified at runtime, default is 9. ### `encrypt_binlog` + Whether to encrypt binlog files: the default is Off. When set to On the binlog files will be encrypted using specified AES algorithm @@ -226,11 +229,11 @@ the binlog events positions in binlog file are the same as in the master binlog file and there is no position mismatch. ### `encryption_algorithm` -'aes_ctr' or 'aes_cbc' -The default is 'aes_cbc' +The encryption algorithm, either 'aes_ctr' or 'aes_cbc'. The default is 'aes_cbc' ### `encryption_key_file` + The specified key file must contains lines with following format: `id;HEX(KEY)` @@ -277,10 +280,8 @@ values may be used for all other options. ## Examples -The [Replication -Proxy](../Tutorials/Replication-Proxy-Binlog-Router-Tutorial.md) tutorial will +The [Replication Proxy](../Tutorials/Replication-Proxy-Binlog-Router-Tutorial.md) tutorial will show you how to configure and administrate a binlogrouter installation. - Tutorial also includes SSL communication setup to the master server and SSL client connections setup to MaxScale Binlog Server. From def475be18d889138baa66923528132abfb68517 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Markus=20M=C3=A4kel=C3=A4?= Date: Thu, 20 Apr 2017 09:10:29 +0300 Subject: [PATCH 07/29] Update Avrorouter.md --- Documentation/Routers/Avrorouter.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Documentation/Routers/Avrorouter.md b/Documentation/Routers/Avrorouter.md index dcd86c648..8676955a3 100644 --- a/Documentation/Routers/Avrorouter.md +++ b/Documentation/Routers/Avrorouter.md @@ -262,8 +262,7 @@ For more information on how to use these scripts, see the output of `cdc.py -h` To build the avrorouter from source, you will need the [Avro C](https://avro.apache.org/docs/current/api/c/) library, liblzma, [the Jansson library](http://www.digip.org/jansson/) and sqlite3 development headers. When -configuring MaxScale with CMake, you will need to add `-DBUILD_CDC=Y --DBUILD_CDC=Y` to build the avrorouter and the CDC protocol module. +configuring MaxScale with CMake, you will need to add `-DBUILD_CDC=Y` to build the CDC module set. For more details about building MaxScale from source, please refer to the [Building MaxScale from Source Code](../Getting-Started/Building-MaxScale-from-Source-Code.md) document. From 1fc4490d4092059df52039d45c16f98c30c15063 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Markus=20M=C3=A4kel=C3=A4?= Date: Thu, 20 Apr 2017 09:12:33 +0300 Subject: [PATCH 08/29] Update ReadConnRoute.md --- Documentation/Routers/ReadConnRoute.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/Documentation/Routers/ReadConnRoute.md b/Documentation/Routers/ReadConnRoute.md index b34442526..f6c20b249 100644 --- a/Documentation/Routers/ReadConnRoute.md +++ b/Documentation/Routers/ReadConnRoute.md @@ -8,11 +8,9 @@ The readconnroute router provides simple and lightweight load balancing across a ## Configuration -Readconnroute router-specific settings are specified in the configuration file of MariaDB MaxScale in its specific section. The section can be freely named but the name is used later as a reference from listener section. - For more details about the standard service parameters, refer to the [Configuration Guide](../Getting-Started/Configuration-Guide.md). -## Router Options +### Router Options **`router_options`** can contain a list of valid server roles. These roles are used as the valid types of servers the router will form connections to when new sessions are created. ``` From 03ba0391e1a9f9dd0d106730c4c30d55e6400a45 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Markus=20M=C3=A4kel=C3=A4?= Date: Thu, 20 Apr 2017 09:16:00 +0300 Subject: [PATCH 09/29] Update Debug-CLI.md --- Documentation/Routers/Debug-CLI.md | 36 +----------------------------- 1 file changed, 1 insertion(+), 35 deletions(-) diff --git a/Documentation/Routers/Debug-CLI.md b/Documentation/Routers/Debug-CLI.md index 25a0dc472..2d7251509 100644 --- a/Documentation/Routers/Debug-CLI.md +++ b/Documentation/Routers/Debug-CLI.md @@ -18,38 +18,4 @@ protocol=telnetd port=4442 ``` -Connections using the telnet protocol to port 4442 of the MariaDB MaxScale host will result in a new debug CLI session. A default username and password are used for this module, new users may be created using the add user command. As soon as any users are explicitly created the default username will no longer continue to work. The default username is admin with a password of mariadb. - -The debugcli supports two modes of operation, `developer` and `user`. The mode is set via the `router_options` parameter. The user mode is more suited to end-users and administrators, whilst the develop mode is explicitly targeted to software developing adding or maintaining the MariaDB MaxScale code base. Details of the differences between the modes can be found in the debugging guide for MariaDB MaxScale. The default is `user` mode. The following service definition would enable a developer version of the debugcli. - -``` -[Debug Service] -type=service -router=debugcli -router_options=developer -``` - -It should be noted that both `user` and `developer` instances of debugcli may be defined within the same instance of MariaDB MaxScale, however they must be defined as two distinct services, each with a distinct listener. - -``` -[Debug Service] -type=service -router=debugcli -router_options=developer - -[Debug Listener] -type=listener -service=Debug Service -protocol=telnetd -port=4442 - -[Admin Service] -type=service -router=debugcli - -[Admin Listener] -type=listener -service=Debug Service -protocol=telnetd -port=4242 -``` +Connections using the telnet protocol to port 4442 of the MariaDB MaxScale host will result in a new debug CLI session. A default username and password are used for this module, new users may be created using the administrative interface. As soon as any users are explicitly created the default username will no longer continue to work. The default username is `admin` with a password of `mariadb`. From c0b3c7eb9fc438b3c3a0d4ef01ae75dad6dd15d2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Markus=20M=C3=A4kel=C3=A4?= Date: Thu, 20 Apr 2017 09:18:29 +0300 Subject: [PATCH 10/29] Update Hint-Syntax.md --- Documentation/Reference/Hint-Syntax.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Documentation/Reference/Hint-Syntax.md b/Documentation/Reference/Hint-Syntax.md index fbebd2263..046c822f1 100644 --- a/Documentation/Reference/Hint-Syntax.md +++ b/Documentation/Reference/Hint-Syntax.md @@ -24,11 +24,11 @@ module=hintfilter ## Comments and comment types -The client connection will need to have comments enabled. For example the `mysql` command line client has comments disabled by default. +The client connection will need to have comments enabled. For example the `mysql` command line client has comments disabled by default and they need to be enabled by passing the `-c` option. -For comment types, use either `-- ` (notice the whitespace) or `#` after the semicolon or `/* .. */` before the semicolon. All comment types work with routing hints. +For comment types, use either `-- ` (notice the whitespace after the double hyphen) or `#` after the semicolon or `/* .. */` before the semicolon. -The MySQL manual doesn`t specify if comment blocks, i.e. `/* .. */`, should contain a w +The MySQL manual doesn't specify if comment blocks, i.e. `/* .. */`, should contain a whitespace character before or after the tags, so adding whitespace at both the start and the end is advised. ## Hint body @@ -39,10 +39,10 @@ All hints must start with the `maxscale` tag. -- maxscale ``` -The hints have two types, ones that route to a server and others that contain +The hints have two types, ones that define a server type and others that contain name-value pairs. -###Routing destination hints +### Routing destination hints These hints will instruct the router to route a query to a certain type of a server. ``` From 49bef4e4f0939defed9c0e482bff925e81cc3b24 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Markus=20M=C3=A4kel=C3=A4?= Date: Thu, 20 Apr 2017 09:24:28 +0300 Subject: [PATCH 11/29] Delete How-errors-are-handled-in-MaxScale.md --- .../How-errors-are-handled-in-MaxScale.md | 56 ------------------- 1 file changed, 56 deletions(-) delete mode 100644 Documentation/Reference/How-errors-are-handled-in-MaxScale.md diff --git a/Documentation/Reference/How-errors-are-handled-in-MaxScale.md b/Documentation/Reference/How-errors-are-handled-in-MaxScale.md deleted file mode 100644 index 4e212b187..000000000 --- a/Documentation/Reference/How-errors-are-handled-in-MaxScale.md +++ /dev/null @@ -1,56 +0,0 @@ -# How errors are handled in MariaDB MaxScale - -This document describes how errors are handled in MariaDB MaxScale, its protocol modules and routers. - -Assume a client, maxscale, and master/slave replication cluster. - -An "error" can be due to failed authentication, routing error (unsupported query type etc.), or backend failure. - -## Authentication error - -Authentication is relatively complex phase in the beginning of session creation. Roughly speaking, client protocol has loaded user information from backend so that it can authenticate client without consulting backend. When client sends authentication data to MariaDB MaxScale data is compared against backend’s user data in the client protocol module. If authentication fails client protocol module refreshes backend data just in case it had became obsolete after last refresh. If authentication still fails after refresh, authentication error occurs. - -Close sequence starts from mysql_client.c:gw_read_client_event where - -1. session state is set to SESSION_STATE_STOPPING - -2. dcb_close is called for client DCB - - 1. client DCB is removed from epoll set and state is set to DCB_STATE_NOPOLLING - - 2. client protocol’s close is called (gw_client_close) - - * protocol struct is done’d - - * router’s closeSession is called (includes calling dcb_close for backends) - - 3. dcb_call_callback is called for client DCB with DCB_REASON_CLOSE - - 4. client DCB is set to zombies list - -Each call for dcb_close in closeSession repeat steps 2a-d. - -## Routing errors - -### Invalid capabilities returned by router - -When client protocol module receives query from client the protocol state is (typically) MYSQL_IDLE. The protocol state is checked in mysql_client.c:gw_read_client_event. First place where a hard error may occur is when router capabilities are read. If router response is invalid (other than RCAP_TYPE_PACKET_INPUT and RCAP_TYPE_STMT_INPUT). In case of invalid return value from the router, error is logged, followed by session closing. - -### Backend failure - -When mysql_client.c:gw_read_client_event calls either route_by_statement or directly MXS_SESSION_ROUTE_QUERY script, which calls the routeQuery function of the head session’s router. routeQuery returns 1 if succeed, or 0 in case of error. Success here means that query was routed and reply will be sent to the client while error means that routing failed because of backend (server/servers/service) failure or because of side effect of backend failure. - -In case of backend failure, error is replied to client and handleError is called to resolve backend problem. handleError is called with action ERRACT_NEW_CONNECTION which tells to error handler that it should try to find a replacement for failed backend. Handler will return true if there are enough backend servers for session’s needs. If handler returns false it means that session can’t continue processing further queries and will be closed. Client will be sent an error message and dcb_close is called for client DCB. - -Close sequence is similar to that described above from phase #2 onward. - -Reasons for "backend failure" in rwsplit: - -* router has rses_closed == true because other thread has detected failure and started to close session - -* master has disappeared; demoted to slave, for example - -### Router error - -In cases where MXS_SESSION_ROUTE_QUERY has returned successfully (=1) query may not be successfully processed in backend or even sent to it. It is possible that router fails in routing the particular query but there is no such error which would prevent session from continuing. In this case router handles error silently by creating and adding MySQL error to first available backend’s (incoming) eventqueue where it is found and sent to client (clientReply). - From ce959838963f4d6ae56eb8b0f0c7d6e209ea5127 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Markus=20M=C3=A4kel=C3=A4?= Date: Thu, 20 Apr 2017 09:37:29 +0300 Subject: [PATCH 12/29] Update MaxAdmin runtime configuration documentation The example help output for the commands is now shown in the documentation. --- Documentation/Reference/MaxAdmin.md | 122 +++++++++++++++++++++++----- 1 file changed, 100 insertions(+), 22 deletions(-) diff --git a/Documentation/Reference/MaxAdmin.md b/Documentation/Reference/MaxAdmin.md index d65ebe41f..cef55223b 100644 --- a/Documentation/Reference/MaxAdmin.md +++ b/Documentation/Reference/MaxAdmin.md @@ -1229,20 +1229,21 @@ to servers are persisted meaning that they will still be in effect even after a restart. ``` -'server' - Create a new server +create server - Create a new server Usage: create server NAME HOST [PORT] [PROTOCOL] [AUTHENTICATOR] [OPTIONS] -Create a new server from the following parameters. - +Parameters: NAME Server name HOST Server host address PORT Server port (default 3306) PROTOCOL Server protocol (default MySQLBackend) AUTHENTICATOR Authenticator module name (default MySQLAuth) -OPTIONS Options for the authenticator module +OPTIONS Comma separated list of options for the authenticator -The first three parameters are required, the others are optional. +The first two parameters are required, the others are optional. + +Example: create server my-db-1 192.168.0.102 3306 ``` ### Adding Servers to Services and Monitors @@ -1256,14 +1257,17 @@ sessions will only use the servers that were a part of the service when they were created. ``` -'server' - Add a new server to a service +add server - Add a new server to a service Usage: add server SERVER TARGET... -The TARGET must be a list of service and monitor names -e.g. add server my-db my-service 'Cluster Monitor' +Parameters: +SERVER The server that is added to TARGET +TARGET List of service and/or monitor names separated by spaces A server can be assigned to a maximum of 11 objects in one command + +Example: add server my-db my-service "Cluster Monitor" ``` ### Removing Servers from Services and Monitors @@ -1274,14 +1278,17 @@ server` also apply to `remove server`. The servers will only be removed from new sessions created after the command is executed. ``` -'server' - Remove a server from a service or a monitor +remove server - Remove a server from a service or a monitor Usage: remove server SERVER TARGET... -The TARGET must be a list of service and monitor names -e.g. remove server my-db my-service 'Cluster Monitor' +Parameters: +SERVER The server that is removed from TARGET +TARGET List of service and/or monitor names separated by spaces A server can be removed from a maximum of 11 objects in one command + +Example: remove server my-db my-service "Cluster Monitor" ``` ### Altering Servers @@ -1295,8 +1302,14 @@ required SSL parameters (`ssl`, `ssl_key`, `ssl_cert` and `ssl_ca_cert`) must be given in the same command. ``` +alter server - Alter server parameters + Usage: alter server NAME KEY=VALUE ... +Parameters: +NAME Server name +KEY=VALUE List of `key=value` pairs separated by spaces + This will alter an existing parameter of a server. The accepted values for KEY are: address Server address @@ -1310,9 +1323,10 @@ ssl_ca_cert Path to SSL CA certificate ssl_version SSL version ssl_cert_verify_depth Certificate verification depth -A maximum of 11 parameters can be changed at one time. To configure SSL for a newly created server, the 'ssl', 'ssl_cert', 'ssl_key' and 'ssl_ca_cert' parameters must be given at the same time. + +Example: alter server my-db-1 address=192.168.0.202 port=3307 ``` ### Destroying Servers @@ -1322,9 +1336,14 @@ created with the `create server` command should be destroyed. A server can only be destroyed once it has been removed from all services and monitors. ``` -'server' - Destroy a server +destroy server - Destroy a server Usage: destroy server NAME + +Parameters: +NAME Server to destroy + +Example: destroy server my-db-1 ``` ## Listeners @@ -1342,16 +1361,15 @@ order for SSL to be enabled. The _default_ parameter can be used to signal that MaxScale should use a default value for the parameter in question. ``` -'listener' - Create a new listener for a service +create listener - Create a new listener for a service Usage: create listener SERVICE NAME [HOST] [PORT] [PROTOCOL] [AUTHENTICATOR] [OPTIONS] [SSL_KEY] [SSL_CERT] [SSL_CA] [SSL_VERSION] [SSL_VERIFY_DEPTH] -Create a new server from the following parameters. - +Parameters SERVICE Service where this listener is added NAME Listener name -HOST Listener host address (default 0.0.0.0) +HOST Listener host address (default [::]) PORT Listener port (default 3306) PROTOCOL Listener protocol (default MySQLClient) AUTHENTICATOR Authenticator module name (default MySQLAuth) @@ -1365,6 +1383,8 @@ SSL_VERIFY_DEPTH Certificate verification depth The first two parameters are required, the others are optional. Any of the optional parameters can also have the value 'default' which will be replaced with the default value. + +Example: create listener my-service my-new-listener 192.168.0.101 4006 ``` ### Destroying Listeners @@ -1375,9 +1395,16 @@ startup. The listener is stopped but it will remain a part of the runtime configuration until the next restart. ``` -'listener' - Destroy a listener +destroy listener - Destroy a listener Usage: destroy listener SERVICE NAME + +Parameters: +NAME Listener to destroy + +The listener is stopped and it will be removed on the next restart of MaxScale + +Example: destroy listener my-listener ``` ## Monitors @@ -1390,11 +1417,15 @@ it with the `restart monitor` command. The _user_ and _password_ parameters of the monitor must be defined before the monitor is started. ``` -'monitor' - Create a new monitor +create monitor - Create a new monitor Usage: create monitor NAME MODULE + +Parameters: NAME Monitor name MODULE Monitor module + +Example: create monitor my-monitor mysqlmon ``` ### Altering Monitors @@ -1403,13 +1434,26 @@ To alter a monitor, use the `alter monitor` command. Module specific parameters can also be altered. ``` -'monitor' - Alter monitor parameters +alter monitor - Alter monitor parameters Usage: alter monitor NAME KEY=VALUE ... +Parameters: +NAME Monitor name +KEY=VALUE List of `key=value` pairs separated by spaces + +All monitors support the following values for KEY: +user Username used when connecting to servers +password Password used when connecting to servers +monitor_interval Monitoring interval in milliseconds +backend_connect_timeout Server coneection timeout in seconds +backend_write_timeout Server write timeout in seconds +backend_read_timeout Server read timeout in seconds + This will alter an existing parameter of a monitor. To remove parameters, pass an empty value for a key e.g. 'maxadmin alter monitor my-monitor my-key=' -A maximum of 11 key-value pairs can be changed at one time + +Example: alter monitor my-monitor user=maxuser password=maxpwd ``` ### Destroying Monitors @@ -1420,9 +1464,16 @@ should be destroyed and they will remain a part of the runtime configuration until the next restart. ``` -'monitor' - Destroy a monitor +destroy monitor - Destroy a monitor Usage: destroy monitor NAME + +Parameters: +NAME Monitor to destroy + +The monitor is stopped and it will be removed on the next restart of MaxScale + +Example: destroy monitor my-monitor ``` ## Other Modules @@ -1434,6 +1485,18 @@ To list all module commands, execute `list commands` in maxadmin. This shows all commands that the modules have exposed. It also explains what they do and what sort of arguments they take. +``` +list commands - List registered commands + +Usage: list commands [MODULE] [COMMAND] + +Parameters: +MODULE Regular expressions for filtering module names +COMMAND Regular expressions for filtering module command names + +Example: list commands my-module my-command +``` + If no module commands are registered, no output will be generated. Refer to the module specific documentation for more details about module commands. @@ -1442,6 +1505,21 @@ maxadmin. The __ is the name of the module and __ is the command that should be called. The commands take a variable amount of arguments which are explained in the output of `list commands`. +``` +call command - Call module command + +Usage: call command MODULE COMMAND ARGS... + +Parameters: +MODULE The module name +COMMAND The command to call +ARGS... Arguments for the command + +To list all registered commands, run 'list commands'. + +Example: call command my-module my-command hello world! +``` + An example of this is the `dbfwfilter` module that implements a rule reloading mechanism as a module command. This command takes a filter name as a parameter. From 83f76d0655360872228cc15af6dfcd1ff961e671 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Markus=20M=C3=A4kel=C3=A4?= Date: Thu, 20 Apr 2017 10:07:58 +0300 Subject: [PATCH 13/29] Update MaxAdmin.md Updated the output of the executed commands. --- Documentation/Reference/MaxAdmin.md | 949 ++++++++++++++++------------ 1 file changed, 532 insertions(+), 417 deletions(-) diff --git a/Documentation/Reference/MaxAdmin.md b/Documentation/Reference/MaxAdmin.md index cef55223b..593e40ef1 100644 --- a/Documentation/Reference/MaxAdmin.md +++ b/Documentation/Reference/MaxAdmin.md @@ -331,34 +331,128 @@ that file. A help system is available that describes the commands available via the administration interface. To obtain a list of all commands available simply type -the command help. +the command `help`. ``` -MaxScale> help Available commands: - add [user|server] - remove [user|server] - create [server|listener|monitor] - destroy [server|listener|monitor] - alter [server|monitor] - set [server|pollsleep|nbpolls|log_throttling] - clear server - disable [heartbeat|log|log-priority|sessionlog|sessionlog-priority|root|feedback|syslog|maxlog|account] - enable [heartbeat|log|log-priority|sessionlog|sessionlog-priority|root|feedback|syslog|maxlog|account] - flush [log|logs] - list [clients|dcbs|filters|listeners|modules|monitors|services|servers|sessions|threads|commands] - reload [config|dbusers] - restart [monitor|service|listener] - shutdown [maxscale|monitor|service|listener] - show [dcblist|dcbs|dcb|dbusers|epoll|eventq|eventstats|feedbackreport|filter|filters|log_throttling|modules|monitor|monitors|persistent|server|servers|serversjson|services|service|session|sessionlist|sessions|tasks|threads|users] - sync logs - call command +add: + add user - Add insecure account for using maxadmin over the network + add server - Add a new server to a service -Type help command to see details of each command. Where commands require names -as arguments and these names contain whitespace either the \ character may be -used to escape the whitespace or the name may be enclosed in double quotes ". +remove: + remove user - Remove account for using maxadmin over the network + remove server - Remove a server from a service or a monitor -MaxScale> +create: + create server - Create a new server + create listener - Create a new listener for a service + create monitor - Create a new monitor + +destroy: + destroy server - Destroy a server + destroy listener - Destroy a listener + destroy monitor - Destroy a monitor + +alter: + alter server - Alter server parameters + alter monitor - Alter monitor parameters + +set: + set server - Set the status of a server + set pollsleep - Set poll sleep period + set nbpolls - Set non-blocking polls + set log_throttling - Set the log throttling configuration + +clear: + clear server - Clear server status + +disable: + disable log-priority - Disable a logging priority + disable sessionlog-priority - [Deprecated] Disable a logging priority for a particular session + disable root - Disable root access + disable feedback - Disable MaxScale feedback to notification service + disable syslog - Disable syslog logging + disable maxlog - Disable MaxScale logging + disable account - Disable Linux user + +enable: + enable log-priority - Enable a logging priority + enable sessionlog-priority - [Deprecated] Enable a logging priority for a session + enable root - Enable root user access to a service + enable feedback - Enable MaxScale feedback to notification service + enable syslog - Enable syslog logging + enable maxlog - Enable MaxScale logging + enable account - Activate a Linux user account for MaxAdmin use + +flush: + flush log - Flush the content of a log file and reopen it + flush logs - Flush the content of a log file and reopen it + +list: + list clients - List all the client connections to MaxScale + list dcbs - List all active connections within MaxScale + list filters - List all filters + list listeners - List all listeners + list modules - List all currently loaded modules + list monitors - List all monitors + list services - List all services + list servers - List all servers + list sessions - List all the active sessions within MaxScale + list threads - List the status of the polling threads in MaxScale + list commands - List registered commands + +reload: + reload config - Reload the configuration + reload dbusers - Reload the database users for a service + +restart: + restart monitor - Restart a monitor + restart service - Restart a service + restart listener - Restart a listener + +shutdown: + shutdown maxscale - Initiate a controlled shutdown of MaxScale + shutdown monitor - Stop a monitor + shutdown service - Stop a service + shutdown listener - Stop a listener + +show: + show dcbs - Show all DCBs + show dbusers - [deprecated] Show user statistics + show authenticators - Show authenticator diagnostics for a service + show epoll - Show the polling system statistics + show eventstats - Show event queue statistics + show feedbackreport - Show the report of MaxScale loaded modules, suitable for Notification Service + show filter - Show filter details + show filters - Show all filters + show log_throttling - Show the current log throttling setting (count, window (ms), suppression (ms)) + show modules - Show all currently loaded modules + show monitor - Show monitor details + show monitors - Show all monitors + show persistent - Show the persistent connection pool of a server + show server - Show server details + show servers - Show all servers + show serversjson - Show all servers in JSON + show services - Show all configured services in MaxScale + show service - Show a single service in MaxScale + show session - Show session details + show sessions - Show all active sessions in MaxScale + show tasks - Show all active housekeeper tasks in MaxScale + show threads - Show the status of the worker threads in MaxScale + show users - Show enabled Linux accounts + show version - Show the MaxScale version number + +sync: + sync logs - Flush log files to disk + +call: + call command - Call module command + + +Type `help COMMAND` to see details of each command. +Where commands require names as arguments and these names contain +whitespace either the \ character may be used to escape the whitespace +or the name may be enclosed in double quotes ". ``` To see more details on a particular command, and a list of the sub commands of @@ -366,54 +460,78 @@ the command, type help followed by the command name. ``` MaxScale> help list -Available options to the list command: -'clients' - List all clients +Available options to the `list` command: -List all the client connections to MaxScale +list clients - List all the client connections to MaxScale -'dcbs' - List all DCBs +Usage: list clients -List all the DCBs active within MaxScale +---------------------------------------------------------------------------- -'filters' - List all filters +list dcbs - List all active connections within MaxScale -List all the filters defined within MaxScale +Usage: list dcbs -'listeners' - List all listeners +---------------------------------------------------------------------------- -List all the listeners defined within MaxScale +list filters - List all filters -'modules' - List all currently loaded modules +Usage: list filters -List all currently loaded modules +---------------------------------------------------------------------------- -'monitors' - List all monitors +list listeners - List all listeners -List all monitors +Usage: list listeners -'services' - List all the services +---------------------------------------------------------------------------- -List all the services defined within MaxScale +list modules - List all currently loaded modules -'servers' - List all servers +Usage: list modules -List all the servers defined within MaxScale +---------------------------------------------------------------------------- -'sessions' - List all sessions +list monitors - List all monitors -List all the active sessions within MaxScale +Usage: list monitors -'threads' - List polling threads +---------------------------------------------------------------------------- -List the status of the polling threads in MaxScale +list services - List all services -'commands' - List registered commands +Usage: list services + +---------------------------------------------------------------------------- + +list servers - List all servers + +Usage: list servers + +---------------------------------------------------------------------------- + +list sessions - List all the active sessions within MaxScale + +Usage: list sessions + +---------------------------------------------------------------------------- + +list threads - List the status of the polling threads in MaxScale + +Usage: list threads + +---------------------------------------------------------------------------- + +list commands - List registered commands + +Usage: list commands [MODULE] [COMMAND] -Usage list commands [MODULE] [COMMAND] Parameters: MODULE Regular expressions for filtering module names COMMAND Regular expressions for filtering module command names +Example: list commands my-module my-command + MaxScale> ``` @@ -432,16 +550,15 @@ available within your MariaDB MaxScale configuration. ``` MaxScale> list services Services. ---------------------------+----------------------+--------+--------------- -Service Name | Router Module | #Users | Total Sessions ---------------------------+----------------------+--------+--------------- -Test Service | readconnroute | 1 | 1 -Split Service | readwritesplit | 1 | 1 -Filter Service | readconnroute | 1 | 1 -QLA Service | readconnroute | 1 | 1 -Debug Service | debugcli | 1 | 1 -CLI | cli | 2 | 24 ---------------------------+----------------------+--------+--------------- +--------------------------+-------------------+--------+----------------+------------------- +Service Name | Router Module | #Users | Total Sessions | Backend databases +--------------------------+-------------------+--------+----------------+------------------- +RWSplit | readwritesplit | 1 | 1 | server1, server2, server3, server4 +SchemaRouter | schemarouter | 1 | 1 | server1, server2, server3, server4 +RWSplit-Hint | readwritesplit | 1 | 1 | server1, server2, server3, server4 +ReadConn | readconnroute | 1 | 1 | server1 +CLI | cli | 2 | 2 | +--------------------------+-------------------+--------+----------------+------------------- MaxScale> ``` @@ -451,16 +568,15 @@ command can be used. ``` MaxScale> list listeners Listeners. ----------------------+--------------------+-----------------+-------+-------- -Service Name | Protocol Module | Address | Port | State ----------------------+--------------------+-----------------+-------+-------- -Test Service | MySQLClient | * | 4006 | Running -Split Service | MySQLClient | * | 4007 | Running -Filter Service | MySQLClient | * | 4008 | Running -QLA Service | MySQLClient | * | 4009 | Running -Debug Service | telnetd | localhost | 4242 | Running -CLI | maxscaled | localhost | 6603 | Running ----------------------+--------------------+-----------------+-------+-------- +----------------------+---------------------+--------------------+-----------------+-------+-------- +Name | Service Name | Protocol Module | Address | Port | State +----------------------+---------------------+--------------------+-----------------+-------+-------- +RWSplit-Listener | RWSplit | MySQLClient | * | 4006 | Running +SchemaRouter-Listener | SchemaRouter | MySQLClient | * | 4010 | Running +RWSplit-Hint-Listener | RWSplit-Hint | MySQLClient | * | 4009 | Running +ReadConn-Listener | ReadConn | MySQLClient | * | 4008 | Running +CLI-Listener | CLI | maxscaled | default | 0 | Running +----------------------+---------------------+--------------------+-----------------+-------+-------- MaxScale> ``` @@ -472,23 +588,37 @@ to examine as an argument. Where a service name contains spaces characters there should either be escaped or the name placed in quotes. ``` -MaxScale> show service "QLA Service" -Service 0x70c6a0 - Service: QLA Service - Router: readconnroute (0x7ffff0f7ae60) - Number of router sessions: 0 - Current no. of router sessions: 0 - Number of queries forwarded: 0 - Started: Wed Jun 25 10:08:23 2014 - Backend databases - 127.0.0.1:3309 Protocol: MySQLBackend - 127.0.0.1:3308 Protocol: MySQLBackend - 127.0.0.1:3307 Protocol: MySQLBackend - 127.0.0.1:3306 Protocol: MySQLBackend - Users data: 0x724340 - Total connections: 1 - Currently connected: 1 -MaxScale> +MaxScale> show service RWSplit + Service: RWSplit + Router: readwritesplit + State: Started + + use_sql_variables_in: all + slave_selection_criteria: LEAST_CURRENT_OPERATIONS + master_failure_mode: fail_instantly + max_slave_replication_lag: -1 + retry_failed_reads: true + strict_multi_stmt: true + disable_sescmd_history: true + max_sescmd_history: 0 + master_accept_reads: false + + Number of router sessions: 0 + Current no. of router sessions: 1 + Number of queries forwarded: 0 + Number of queries forwarded to master: 0 (0.00%) + Number of queries forwarded to slave: 0 (0.00%) + Number of queries forwarded to all: 0 (0.00%) + Started: Thu Apr 20 09:45:13 2017 + Root user access: Disabled + Backend databases: + [127.0.0.1]:3000 Protocol: MySQLBackend Name: server1 + [127.0.0.1]:3001 Protocol: MySQLBackend Name: server2 + [127.0.0.1]:3002 Protocol: MySQLBackend Name: server3 + [127.0.0.1]:3003 Protocol: MySQLBackend Name: server4 + Total connections: 1 + Currently connected: 1 +MaxScale> ``` This allows the set of backend servers defined by the service to be seen along @@ -503,9 +633,10 @@ from one of the backend databases defined for the service. The _show dbusers_ command can be used to examine the user data held by MariaDB MaxScale. ``` -MaxScale> show dbusers "Filter Service" -User names: pappo@%, rana@%, new_control@%, new_nuovo@%, uno@192.168.56.1, nuovo@192.168.56.1, pesce@%, tryme@192.168.1.199, repluser@%, seven@%, due@%, pippo@%, mmm@%, daka@127.0.0.1, timour@%, ivan@%, prova@%, changeme@127.0.0.1, uno@%, massimiliano@127.0.0.1, massim@127.0.0.1, massi@127.0.0.1, masssi@127.0.0.1, pappo@127.0.0.1, rana@127.0.0.1, newadded@127.0.0.1, newaded@127.0.0.1, pesce@127.0.0.1, repluser@127.0.0.1, seven@127.0.0.1, pippo@127.0.0.1, due@127.0.0.1, nopwd@127.0.0.1, timour@127.0.0.1, controlla@192.168.56.1, ivan@127.0.0.1, ppp@127.0.0.1, daka@%, nuovo@127.0.0.1, uno@127.0.0.1, repluser@192.168.56.1, havoc@%, tekka@192.168.1.19, due@192.168.56.1, qwerty@127.0.0.1, massimiliano@%, massi@%, massim@% -MaxScale> +MaxScale> show dbusers RWSplit +User names: @localhost @localhost.localdomain 14567USER@localhost monuser@localhost monuser@% 14609USER@localhost maxuser@localhost maxuser@% 14651USER@localhost maxtest@localhost maxtest@% 14693USER@localhost skysql@localhost skysql@% 14735USER@localhost cliuser@localhost cliuser@% repuser@localhost repuser@% +MaxScale> + ``` ## Reloading Service User Data @@ -518,8 +649,8 @@ the MariaDB MaxScale internal table. The reload dbusers command can be used to force the reloading of the user table within MariaDB MaxScale. ``` -MaxScale> reload dbusers "Split Service" -Loaded 34 database users for service Split Service. +MaxScale> reload dbusers RWSplit +Reloaded database users for service RWSplit. MaxScale> ``` @@ -531,8 +662,8 @@ already in place for a service, but will stop any new connections from being accepted. ``` -MaxScale> shutdown service "Split Service" -MaxScale> +MaxScale> shutdown service RWSplit +MaxScale> ``` ## Restart A Stopped Service @@ -540,7 +671,7 @@ MaxScale> A stopped service may be restarted by using the _restart service_ command. ``` -MaxScale> restart service "Split Service" +MaxScale> restart service RWSplit MaxScale> ``` @@ -557,15 +688,15 @@ configured within MariaDB MaxScale. ``` MaxScale> list servers Servers. --------------------+-----------------+-------+----------------------+------------ -Server | Address | Port | Status | Connections --------------------+-----------------+-------+----------------------+------------ -server1 | 127.0.0.1 | 3306 | Running | 0 -server2 | 127.0.0.1 | 3307 | Master, Running | 0 -server3 | 127.0.0.1 | 3308 | Running | 0 -server4 | 127.0.0.1 | 3309 | Slave, Running | 0 --------------------+-----------------+-------+----------------------+------------ -MaxScale> +-------------------+-----------------+-------+-------------+-------------------- +Server | Address | Port | Connections | Status +-------------------+-----------------+-------+-------------+-------------------- +server1 | 127.0.0.1 | 3000 | 0 | Master, Running +server2 | 127.0.0.1 | 3001 | 0 | Slave, Running +server3 | 127.0.0.1 | 3002 | 0 | Slave, Running +server4 | 127.0.0.1 | 3003 | 0 | Slave, Running +-------------------+-----------------+-------+-------------+-------------------- +MaxScale> ``` ## Server Details @@ -575,17 +706,20 @@ server_ command. ``` MaxScale> show server server2 -Server 0x70d460 (server2) - Server: 127.0.0.1 - Status: Master, Running - Protocol: MySQLBackend - Port: 3307 - Server Version: 5.5.25-MariaDB-log - Node Id: 124 - Number of connections: 0 - Current no. of conns: 0 - Current no. of operations: 0 -MaxScale> +Server 0x6501d0 (server2) + Server: 127.0.0.1 + Status: Slave, Running + Protocol: MySQLBackend + Port: 3001 + Server Version: 10.1.22-MariaDB + Node Id: 3001 + Master Id: 3000 + Slave Ids: + Repl Depth: 1 + Number of connections: 0 + Current no. of conns: 0 + Current no. of operations: 0 +MaxScale> ``` If the server has a non-zero value set for the server configuration item @@ -637,6 +771,7 @@ format described below in the DCB section) with a command like: ``` MaxScale> show persistent server1 +Number of persistent DCBs: 0 ``` # Working With Sessions @@ -654,38 +789,17 @@ comprehensive being the _list sessions_ command. ``` MaxScale> list sessions -Sessions. -----------------+-----------------+----------------+-------------------------- Session | Client | Service | State -----------------+-----------------+----------------+-------------------------- -0x7267a0 | 127.0.0.1 | CLI | Session ready for routing -0x726340 | | CLI | Listener Session -0x725720 | | Debug Service | Listener Session -0x724720 | | QLA Service | Listener Session -0x72a750 | | Filter Service | Listener Session -0x709500 | | Split Service | Listener Session -0x7092d0 | | Test Service | Listener Session +10 | localhost | CLI | Session ready for routing +11 | ::ffff:127.0.0.1 | RWSplit | Session ready for routing -----------------+-----------------+----------------+-------------------------- -MaxScale> + +MaxScale> ``` -This lists all the sessions for both user connections and for the service -listeners. - -The _list clients_ command will give just the subset of sessions that originate -from a client connection. - -``` -MaxScale> list clients -Client Connections ------------------+------------+----------------------+------------ - Client | DCB | Service | Session ------------------+------------+----------------------+------------ - 127.0.0.1 | 0x7274b0 | CLI | 0x727700 - 127.0.0.1 | 0x727900 | QLA Service | 0x727da0 ------------------+------------+----------------------+------------ -MaxScale> -``` +This will give a list of client connections. ## Display Session Details @@ -694,14 +808,15 @@ possible to determine more detail regarding a session by using the _show session_ command. ``` -MaxScale> show session 0x727da0 -Session 0x727da0 - State: Session ready for routing - Service: QLA Service (0x70d6a0) - Client DCB: 0x727900 - Client Address: 127.0.0.1 - Connected: Wed Jun 25 15:27:21 2014 -MaxScale> +MaxScale> show session 11 +Session 11 + State: Session ready for routing + Service: RWSplit + Client Address: maxuser@::ffff:127.0.0.1 + Connected: Thu Apr 20 09:51:31 2017 + + Idle: 82 seconds +MaxScale> ``` # Descriptor Control Blocks @@ -723,20 +838,23 @@ MaxScale server, the most straightforward being the _list dcbs_ command. ``` MaxScale> list dcbs Descriptor Control Blocks -------------+----------------------------+----------------------+---------- - DCB | State | Service | Remote -------------+----------------------------+----------------------+---------- - 0x667170 | DCB for listening socket | Test Service | - 0x71a350 | DCB for listening socket | Split Service | - 0x724b40 | DCB for listening socket | Filter Service | - 0x7250d0 | DCB for listening socket | QLA Service | - 0x725740 | DCB for listening socket | Debug Service | - 0x726740 | DCB for listening socket | CLI | - 0x7274b0 | DCB in the polling loop | CLI | 127.0.0.1 - 0x727900 | DCB in the polling loop | QLA Service | 127.0.0.1 - 0x72e880 | DCB in the polling loop | QLA Service | -------------+----------------------------+----------------------+---------- -MaxScale> +------------------+----------------------------+--------------------+---------- + DCB | State | Service | Remote +------------------+----------------------------+--------------------+---------- + 0x68c0a0 | DCB for listening socket | RWSplit | + 0x6e23f0 | DCB for listening socket | CLI | + 0x691710 | DCB for listening socket | SchemaRouter | + 0x7fffe40130f0 | DCB in the polling loop | CLI | localhost + 0x6b7540 | DCB for listening socket | RWSplit-Hint | + 0x6cd020 | DCB for listening socket | ReadConn | + 0x7fffd80130f0 | DCB in the polling loop | RWSplit | ::ffff:127.0.0.1 + 0x7fffdc014590 | DCB in the polling loop | RWSplit | + 0x7fffdc0148d0 | DCB in the polling loop | RWSplit | + 0x7fffdc014c60 | DCB in the polling loop | RWSplit | + 0x7fffdc014ff0 | DCB in the polling loop | RWSplit | +------------------+----------------------------+--------------------+---------- + +MaxScale> ``` A MariaDB MaxScale server that has activity on it will however have many more @@ -753,28 +871,49 @@ address to determine the one of interest. ## DCB Details -The details of an individual DCB can be obtained by use of the _show dcb_ +The details of DCBs can be obtained by use of the _show dcbs_ command ``` -MaxScale> show dcb 0x727900 -DCB: 0x727900 - DCB state: DCB in the polling loop - Username: somename - Protocol: MySQLBackend - Server Status: Master, running - Role: Request Handler - Connected to: 127.0.0.1 - Owning Session: 0x727da0 - Statistics: - No. of Reads: 4 - No. of Writes: 3 - No. of Buffered Writes: 0 - No. of Accepts: 0 - No. of High Water Events: 0 - No. of Low Water Events: 0 - Added to persistent pool: Jun 24 09:09:56 -MaxScale> +DCB: 0x68c0a0 + DCB state: DCB for listening socket + Service: RWSplit + Role: Service Listener + Statistics: + No. of Reads: 0 + No. of Writes: 0 + No. of Buffered Writes: 0 + No. of Accepts: 1 + No. of High Water Events: 0 + No. of Low Water Events: 0 +DCB: 0x7fffd80130f0 + DCB state: DCB in the polling loop + Service: RWSplit + Connected to: ::ffff:127.0.0.1 + Username: maxuser + Role: Client Request Handler + Statistics: + No. of Reads: 5 + No. of Writes: 0 + No. of Buffered Writes: 6 + No. of Accepts: 0 + No. of High Water Events: 0 + No. of Low Water Events: 0 +DCB: 0x7fffdc014590 + DCB state: DCB in the polling loop + Service: RWSplit + Server name/IP: 127.0.0.1 + Port number: 3000 + Protocol: MySQLBackend + Server status: Master, Running + Role: Backend Request Handler + Statistics: + No. of Reads: 4 + No. of Writes: 0 + No. of Buffered Writes: 3 + No. of Accepts: 0 + No. of High Water Events: 0 + No. of Low Water Events: 0 ``` The information Username, Protocol, Server Status are not always relevant, and @@ -832,58 +971,38 @@ within a session. First use _list sessions_ or _list clients_ to find the session of interest and then run the _show session_ command ``` -MaxScale> list clients -Client Connections ------------------+------------+----------------------+------------ - Client | DCB | Service | Session ------------------+------------+----------------------+------------ - 127.0.0.1 | 0x7361a0 | Split Service | 0x736680 - 127.0.0.1 | 0x737ec0 | Plumbing | 0x7382b0 - 127.0.0.1 | 0x73ab20 | DigitalOcean | 0x73ad90 - 127.0.0.1 | 0x7219e0 | CLI | 0x721bd0 ------------------+------------+----------------------+------------ -MaxScale> show session 0x736680 -Session 0x736680 - State: Session ready for routing - Service: Split Service (0x719f60) - Client DCB: 0x7361a0 - Client Address: 127.0.0.1 - Connected: Thu Jun 26 10:10:44 2014 - Filter: top10 - Report size 10 - Logging to file /tmp/Query.top10.1. - Current Top 10: - 1 place: - Execution time: 23.826 seconds - SQL: select sum(salary), year(from_date) from salaries s, (select distinct year(from_date) as y1 from salaries) y where (makedate(y.y1, 1) between s.from_date and s.to_date) group by y.y1 ("1988-08-01? - 2 place: - Execution time: 5.251 seconds - SQL: select d.dept_name as "Department", y.y1 as "Year", count(*) as "Count" from departments d, dept_emp de, (select distinct year(from_date) as y1 from dept_emp order by 1) y where d.dept_no = de.dept_no and (makedate(y.y1, 1) between de.from_date and de.to_date) group by y.y1, d.dept_name order by 1, 2 - 3 place: - Execution time: 2.903 seconds - SQL: select year(now()) - year(birth_date) as age, gender, avg(salary) as "Average Salary" from employees e, salaries s where e.emp_no = s.emp_no and ("1988-08-01" between from_date AND to_date) group by year(now()) - year(birth_date), gender order by 1,2 - 4 place: - Execution time: 2.138 seconds - SQL: select dept_name as "Department", sum(salary) / 12 as "Salary Bill" from employees e, departments d, dept_emp de, salaries s where e.emp_no = de.emp_no and de.dept_no = d.dept_no and ("1988-08-01" between de.from_date AND de.to_date) and ("1988-08-01" between s.from_date AND s.to_date) and s.emp_no = e.emp_no group by dept_name order by 1 - 5 place: - Execution time: 0.839 seconds - SQL: select dept_name as "Department", avg(year(now()) - year(birth_date)) as "Average Age", gender from employees e, departments d, dept_emp de where e.emp_no = de.emp_no and de.dept_no = d.dept_no and ("1988-08-01" between from_date AND to_date) group by dept_name, gender - 6 place: - Execution time: 0.662 seconds - SQL: select year(hire_date) as "Hired", d.dept_name, count(*) as "Count" from employees e, departments d, dept_emp de where de.emp_no = e.emp_no and de.dept_no = d.dept_no group by d.dept_name, year(hire_date) - 7 place: - Execution time: 0.286 seconds - SQL: select moves.n_depts As "No. of Departments", count(moves.emp_no) as "No. of Employees" from (select de1.emp_no as emp_no, count(de1.emp_no) as n_depts from dept_emp de1 group by de1.emp_no) as moves group by moves.n_depts order by 1 - 8 place: - Execution time: 0.248 seconds - SQL: select year(now()) - year(birth_date) as age, gender, count(*) as "Count" from employees group by year(now()) - year(birth_date), gender order by 1,2@ - 9 place: - Execution time: 0.182 seconds - SQL: select year(hire_date) as "Hired", count(*) as "Count" from employees group by year(hire_date) - 10 place: - Execution time: 0.169 seconds - SQL: select year(hire_date) - year(birth_date) as "Age", count(*) as Count from employees group by year(hire_date) - year(birth_date) order by 1 -MaxScale> +MaxScale> list sessions +-----------------+-----------------+----------------+-------------------------- +Session | Client | Service | State +-----------------+-----------------+----------------+-------------------------- +6 | ::ffff:127.0.0.1 | RWSplit-Top | Session ready for routing +7 | localhost | CLI | Session ready for routing +-----------------+-----------------+----------------+-------------------------- + +MaxScale> show session 6 +Session 6 + State: Session ready for routing + Service: RWSplit-Top + Client Address: maxuser@::ffff:127.0.0.1 + Connected: Thu Apr 20 09:58:38 2017 + + Idle: 9 seconds + Filter: Top + Report size 10 + Logging to file /tmp/top.1. + Current Top 10: + 1 place: + Execution time: 0.000 seconds + SQL: show tables from information_schema + 2 place: + Execution time: 0.000 seconds + SQL: show databases + 3 place: + Execution time: 0.000 seconds + SQL: show tables + 4 place: + Execution time: 0.000 seconds + SQL: select @@version_comment limit 1 ``` The data displayed varies from filter to filter, the example above is the top @@ -903,12 +1022,12 @@ command. ``` MaxScale> list monitors -+----------------------+--------------------- -| Monitor | Status -+----------------------+--------------------- -| MySQL Monitor | Running -+----------------------+--------------------- -MaxScale> +---------------------+--------------------- +Monitor | Status +---------------------+--------------------- +MySQL-Monitor | Running +---------------------+--------------------- +MaxScale> ``` ## Details Of A Particular Monitor @@ -916,62 +1035,62 @@ MaxScale> To see the details of a particular monitor use the _show monitor_ command. ``` -MaxScale> show monitor "MySQL Monitor" -Monitor: 0x71c370 - Name: MySQL Monitor - Monitor running - Sampling interval: 10000 milliseconds - MaxScale MonitorId: 24209641 - Replication lag: disabled - Monitored servers: 127.0.0.1:3306, 127.0.0.1:3307, 127.0.0.1:3308, 127.0.0.1:3309 -MaxScale> -``` +MaxScale> show monitor MySQL-Monitor +Monitor: 0x6577e0 +Name: MySQL-Monitor +State: Running +Sampling interval: 10000 milliseconds +Connect Timeout: 3 seconds +Read Timeout: 1 seconds +Write Timeout: 2 seconds +Monitored servers: [127.0.0.1]:3000, [127.0.0.1]:3001, [127.0.0.1]:3002, [127.0.0.1]:3003 +MaxScale MonitorId: 0 +Replication lag: disabled +Detect Stale Master: enabled +Server information -## Controlling Replication Heartbeat +Server: server1 +Server ID: 3000 +Read only: OFF +Slave configured: NO +Slave IO running: NO +Slave SQL running: NO +Master ID: -1 +Master binlog file: +Master binlog position: 0 -Some monitors provide a replication heartbeat mechanism that monitors the delay -for data that is replicated from a master to slaves in a tree structured -replication environment. This can be enabled or disabled using the commands -_enable heartbeat_ and _disable heartbeat_. +Server: server2 +Server ID: 3001 +Read only: OFF +Slave configured: YES +Slave IO running: YES +Slave SQL running: YES +Master ID: 3000 +Master binlog file: binlog.000001 +Master binlog position: 435 -``` -MaxScale> disable heartbeat "MySQL Monitor" -MaxScale> enable heartbeat "MySQL Monitor" -MaxScale> -``` +Server: server3 +Server ID: 3002 +Read only: OFF +Slave configured: YES +Slave IO running: YES +Slave SQL running: YES +Master ID: 3000 +Master binlog file: binlog.000001 +Master binlog position: 435 -Please note that changes made via this interface will not persist across -restarts of MariaDB MaxScale. To make a permanent change edit the maxscale.cnf -file. +Server: server4 +Server ID: 3003 +Read only: OFF +Slave configured: YES +Slave IO running: YES +Slave SQL running: YES +Master ID: 3000 +Master binlog file: binlog.000001 +Master binlog position: 435 -Enabling the replication heartbeat mechanism will add the display of heartbeat -information in the show server output -``` -MaxScale> show server server4 -Server 0x719800 (server4) - Server: 127.0.0.1 - Status: Slave, Running - Protocol: MySQLBackend - Port: 3309 - Server Version: 5.5.25-MariaDB-log - Node Id: 4 - Number of connections: 0 - Current no. of conns: 0 -MaxScale> enable heartbeat "MySQL Monitor" -MaxScale> show server server4 -Server 0x719800 (server4) - Server: 127.0.0.1 - Status: Slave, Running - Protocol: MySQLBackend - Port: 3309 - Server Version: 5.5.25-MariaDB-log - Node Id: 4 - Slave delay: 0 - Last Repl Heartbeat: Thu Jun 26 17:04:58 2014 - Number of connections: 0 - Current no. of conns: 0 -MaxScale> +MaxScale> ``` ## Shutting Down A Monitor @@ -981,14 +1100,14 @@ manual control of the status of servers using the _set server_ and _clear server_ commands. ``` -MaxScale> shutdown monitor "MySQL Monitor" +MaxScale> shutdown monitor MySQL-Monitor MaxScale> list monitors -+----------------------+--------------------- -| Monitor | Status -+----------------------+--------------------- -| MySQL Monitor | Stopped -+----------------------+--------------------- -MaxScale> +---------------------+--------------------- +Monitor | Status +---------------------+--------------------- +MySQL-Monitor | Stopped +---------------------+--------------------- +MaxScale> ``` ## Restarting A Monitor @@ -997,16 +1116,14 @@ A monitor that has been shutdown may be restarted using the _restart monitor_ command. ``` -MaxScale> restart monitor "MySQL Monitor" -MaxScale> show monitor "MySQL Monitor" -Monitor: 0x71a310 - Name: MySQL Monitor - Monitor running - Sampling interval: 10000 milliseconds - MaxScale MonitorId: 24201552 - Replication lag: enabled - Monitored servers: 127.0.0.1:3306, 127.0.0.1:3307, 127.0.0.1:3308, 127.0.0.1:3309 -MaxScale> +MaxScale> restart monitor MySQL-Monitor +MaxScale> list monitors +---------------------+--------------------- +Monitor | Status +---------------------+--------------------- +MySQL-Monitor | Running +---------------------+--------------------- +MaxScale> ``` # MaxScale Status Commands @@ -1025,17 +1142,21 @@ determine what each thread is currently being used for. ``` MaxScale> show threads Polling Threads. -Historic Thread Load Average: 1.00. -Current Thread Load Average: 1.00. -15 Minute Average: 0.48, 5 Minute Average: 1.00, 1 Minute Average: 1.00 + +Historic Thread Load Average: 1.06. +Current Thread Load Average: 0.00. +15 Minute Average: 0.10, 5 Minute Average: 0.30, 1 Minute Average: 0.67 + Pending event queue length averages: -15 Minute Average: 0.90, 5 Minute Average: 1.83, 1 Minute Average: 2.00 +15 Minute Average: 0.00, 5 Minute Average: 0.00, 1 Minute Average: 0.00 + ID | State | # fds | Descriptor | Running | Event ----+------------+--------+------------------+----------+--------------- - 0 | Processing | 1 | 0xf55a70 | < 100ms | IN|OUT - 1 | Processing | 1 | 0xf49ba0 | < 100ms | IN|OUT - 2 | Processing | 1 | 0x7f54c0030d00 | < 100ms | IN|OUT -MaxScale> + 0 | Polling | | | | + 1 | Polling | | | | + 2 | Processing | 1 | 0x6e0dd0 | <202400ms | IN|OUT + 3 | Polling | | | | +MaxScale> ``` The resultant output returns data as to the average thread utilization for the @@ -1044,27 +1165,6 @@ thread that shows what DCB that thread is currently processing events for, the events it is processing and how long, to the nearest 100ms has been send processing these events. -## The Event Queue - -At the core of MariaDB MaxScale is an event driven engine that is processing -network events for the network connections between MariaDB MaxScale and client -applications and MariaDB MaxScale and the backend servers. It is possible to see -the event queue using the _show eventq_ command. This will show the events -currently being executed and those that are queued for execution. - -``` -MaxScale> show eventq -Event Queue. -DCB | Status | Processing Events | Pending Events ------------------+------------+--------------------+------------------- -0x1e22f10 | Processing | IN|OUT | -MaxScale> -``` - -The output of this command gives the DCB’s that are currently in the event -queue, the events queued for that DCB, and events that are being processed for -that DCB. - ## The Housekeeper Tasks Internally MariaDB MaxScale has a housekeeper thread that is used to perform @@ -1075,8 +1175,8 @@ are outstanding within the housekeeper. MaxScale> show tasks Name | Type | Frequency | Next Due --------------------------+----------+-----------+------------------------- -Load Average | Repeated | 10 | Wed Nov 19 15:10:51 2014 -MaxScale> +Load Average | Repeated | 10 | Thu Apr 20 10:02:26 2017 +MaxScale> ``` # Administration Commands @@ -1089,23 +1189,25 @@ those modules the _list modules_ command can be used. ``` MaxScale> list modules Modules. -----------------+-------------+---------+-------+------------------------- -Module Name | Module Type | Version | API | Status -----------------+-------------+---------+-------+------------------------- -tee | Filter | V1.0.0 | 1.1.0 | Alpha -qlafilter | Filter | V1.1.1 | 1.1.0 | Alpha -topfilter | Filter | V1.0.1 | 1.1.0 | Alpha -MySQLBackend | Protocol | V2.0.0 | 1.0.0 | Alpha -maxscaled | Protocol | V1.0.0 | 1.0.0 | Alpha -telnetd | Protocol | V1.0.1 | 1.0.0 | Alpha -MySQLClient | Protocol | V1.0.0 | 1.0.0 | Alpha -mysqlmon | Monitor | V1.2.0 | 1.0.0 | Alpha -readconnroute | Router | V1.0.2 | 1.0.0 | Alpha -readwritesplit | Router | V1.0.2 | 1.0.0 | Alpha -debugcli | Router | V1.1.1 | 1.0.0 | Alpha -cli | Router | V1.0.0 | 1.0.0 | Alpha -----------------+-------------+---------+-------+------------------------- -MaxScale> +----------------+-----------------+---------+-------+------------------------- +Module Name | Module Type | Version | API | Status +----------------+-----------------+---------+-------+------------------------- +qc_sqlite | QueryClassifier | V1.0.0 | 1.1.0 | Beta +MySQLAuth | Authenticator | V1.1.0 | 1.1.0 | GA +MySQLClient | Protocol | V1.1.0 | 1.1.0 | GA +MaxAdminAuth | Authenticator | V2.1.0 | 1.1.0 | GA +maxscaled | Protocol | V2.0.0 | 1.1.0 | GA +MySQLBackendAuth | Authenticator | V1.0.0 | 1.1.0 | GA +MySQLBackend | Protocol | V2.0.0 | 1.1.0 | GA +mysqlmon | Monitor | V1.5.0 | 3.0.0 | GA +schemarouter | Router | V1.0.0 | 2.0.0 | Beta +readwritesplit | Router | V1.1.0 | 2.0.0 | GA +topfilter | Filter | V1.0.1 | 2.2.0 | GA +readconnroute | Router | V1.1.0 | 2.0.0 | GA +cli | Router | V1.0.0 | 2.0.0 | GA +----------------+-----------------+---------+-------+------------------------- + +MaxScale> ``` This command provides important version information for the module. Each module @@ -1143,14 +1245,12 @@ $ kill -SIGUSR1 $ # MaxScale closes the file (i.e. maxscale1.log) and reopens maxscale.log ``` -There are two ways for rotating the log - *flush log maxscale* and *flush logs* -- and the result is identical. The two alternatives are due to historical +There are two ways for rotating the log - *flush log maxscale* and *flush logs*; +the result is identical. The two alternatives are due to historical reasons; earlier MariaDB MaxScale had several different log files. ``` MaxScale> flush log maxscale -MaxScale> -The flush logs command may be used to rotate all logs with a single command. MaxScale> flush logs MaxScale> ``` @@ -1206,7 +1306,9 @@ of the values to 0, disables the throttling. ## Reloading The Configuration A command, _reload config_, is available that will cause MariaDB MaxScale to -reload the maxscale.cnf configuration file. Refer to the [Configuration Guide](../Getting-Started/Configuration-Guide.md) +reload the maxscale.cnf configuration file. Note that not all configuration +changes are taken into effect when the configuration is reloaded. Refer to +the [Configuration Guide](../Getting-Started/Configuration-Guide.md) for a list of parameters that can be changed with it. ## Shutting Down MariaDB MaxScale @@ -1214,10 +1316,16 @@ for a list of parameters that can be changed with it. The MariaDB MaxScale server may be shutdown using the _shutdown maxscale_ command. +``` +MaxScale> shutdown maxscale +MaxScale> +``` + # Runtime Configuration Changes Starting with the 2.1 version of MaxScale, you can modify the runtime -configuration. +configuration. This means that new objects (servers, listeners, monitors) +can be created, altered and removed at runtime. ## Servers @@ -1584,31 +1692,35 @@ increasing the number of non-blocking polls should help the situation. ``` MaxScale> show epoll -Number of epoll cycles: 534 -Number of epoll cycles with wait: 10447 -Number of read events: 35 -Number of write events: 1988 -Number of error events: 0 -Number of hangup events: 1 -Number of accept events: 3 -Number of times no threads polling: 5 -Current event queue length: 1 -Maximum event queue length: 2 -Number of DCBs with pending events: 0 -Number of wakeups with pending queue: 0 + +Poll Statistics. + +No. of epoll cycles: 343 +No. of epoll cycles with wait: 66 +No. of epoll calls returning events: 19 +No. of non-blocking calls returning events: 10 +No. of read events: 2 +No. of write events: 15 +No. of error events: 0 +No. of hangup events: 0 +No. of accept events: 4 +No. of times no threads polling: 4 +Total event queue length: 1 +Average event queue length: 1 +Maximum event queue length: 1 No of poll completions with descriptors - No. of descriptors No. of poll completions. - 1 534 - 2 0 - 3 0 - 4 0 - 5 0 - 6 0 - 7 0 - 8 0 - 9 0 - >= 10 0 -MaxScale> + No. of descriptors No. of poll completions. + 1 19 + 2 0 + 3 0 + 4 0 + 5 0 + 6 0 + 7 0 + 8 0 + 9 0 + >= 10 0 +MaxScale> ``` If the "Number of DCBs with pending events" grows rapidly it is an indication @@ -1627,46 +1739,49 @@ events took to execute once they have been allocated a thread to run on. ``` MaxScale> show eventstats + Event statistics. -Maximum queue time: 2600ms -Maximum execution time: 1600ms -Maximum event queue length: 3 -Current event queue length: 3 +Maximum queue time: 000ms +Maximum execution time: 000ms +Maximum event queue length: 1 +Total event queue length: 4 +Average event queue length: 1 + | Number of events Duration | Queued | Executed ---------------+------------+----------- - < 100ms | 107 | 461 - 100 - 200ms | 958 | 22830 - 200 - 300ms | 20716 | 2545 - 300 - 400ms | 3284 | 253 - 400 - 500ms | 505 | 45 - 500 - 600ms | 66 | 73 - 600 - 700ms | 116 | 169 - 700 - 800ms | 319 | 185 - 800 - 900ms | 382 | 42 - 900 - 1000ms | 95 | 31 - 1000 - 1100ms | 63 | 7 - 1100 - 1200ms | 18 | 4 - 1200 - 1300ms | 8 | 2 - 1300 - 1400ms | 6 | 0 - 1400 - 1500ms | 1 | 1 - 1500 - 1600ms | 3 | 1 - 1600 - 1700ms | 2 | 1 - 1700 - 1800ms | 2 | 0 - 1800 - 1900ms | 0 | 0 - 1900 - 2000ms | 1 | 0 - 2000 - 2100ms | 0 | 0 - 2100 - 2200ms | 0 | 0 - 2200 - 2300ms | 0 | 0 - 2300 - 2400ms | 0 | 0 - 2400 - 2500ms | 0 | 0 - 2500 - 2600ms | 0 | 0 - 2600 - 2700ms | 1 | 0 - 2700 - 2800ms | 0 | 0 - 2800 - 2900ms | 0 | 0 - 2900 - 3000ms | 0 | 0 - > 3000ms | 0 | 0 -MaxScale> + < 100ms | 27 | 26 + 100 - 200ms | 0 | 0 + 200 - 300ms | 0 | 0 + 300 - 400ms | 0 | 0 + 400 - 500ms | 0 | 0 + 500 - 600ms | 0 | 0 + 600 - 700ms | 0 | 0 + 700 - 800ms | 0 | 0 + 800 - 900ms | 0 | 0 + 900 - 1000ms | 0 | 0 + 1000 - 1100ms | 0 | 0 + 1100 - 1200ms | 0 | 0 + 1200 - 1300ms | 0 | 0 + 1300 - 1400ms | 0 | 0 + 1400 - 1500ms | 0 | 0 + 1500 - 1600ms | 0 | 0 + 1600 - 1700ms | 0 | 0 + 1700 - 1800ms | 0 | 0 + 1800 - 1900ms | 0 | 0 + 1900 - 2000ms | 0 | 0 + 2000 - 2100ms | 0 | 0 + 2100 - 2200ms | 0 | 0 + 2200 - 2300ms | 0 | 0 + 2300 - 2400ms | 0 | 0 + 2400 - 2500ms | 0 | 0 + 2500 - 2600ms | 0 | 0 + 2600 - 2700ms | 0 | 0 + 2700 - 2800ms | 0 | 0 + 2800 - 2900ms | 0 | 0 + 2900 - 3000ms | 0 | 0 + > 3000ms | 0 | 0 +MaxScale> ``` The statics are defined in 100ms buckets, with the count of the events that fell From 7d7ad5448286119051af92738648907427fefa28 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Markus=20M=C3=A4kel=C3=A4?= Date: Thu, 20 Apr 2017 10:21:02 +0300 Subject: [PATCH 14/29] Update Upgrading-To-MaxScale-2.1.md Added information about IPv6 changes and persisted configurations. --- Documentation/Upgrading/Upgrading-To-MaxScale-2.1.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/Documentation/Upgrading/Upgrading-To-MaxScale-2.1.md b/Documentation/Upgrading/Upgrading-To-MaxScale-2.1.md index 100c389cd..929aba427 100644 --- a/Documentation/Upgrading/Upgrading-To-MaxScale-2.1.md +++ b/Documentation/Upgrading/Upgrading-To-MaxScale-2.1.md @@ -14,6 +14,18 @@ For a complete list of changes in MaxScale 2.1.0, refer to the Before starting the upgrade, we **strongly** recommend you back up your current configuration file. +## IPv6 Support + +MaxScale 2.1.2 added support for IPv6 addresses. The default interface that listeners bind to +was changed from the IPv4 address `0.0.0.0` to the IPv6 address `::`. To bind to the old IPv4 address, +add `address=0.0.0.0` to the listener definition. + +## Persisted Configuration Files + +Starting with MaxScale 2.1, any changes made with the newly added +[runtime configuration change](../Reference/MaxAdmin.md#runtime-configuration-changes) +will be persisted in a configuration file. These files are located in `/var/lib/maxscale/maxscale.cnf.d/`. + ## MaxScale Log Files The name of the log file was changed from _maxscaleN.log_ to _maxscale.log_. The From 33b809eec11e6a50db6dc476b8756d8c3a3373ec Mon Sep 17 00:00:00 2001 From: Johan Wikman Date: Thu, 20 Apr 2017 13:12:46 +0300 Subject: [PATCH 15/29] Do not build storage_rocksdb by default --- Documentation/Filters/Cache.md | 3 +++ server/modules/filter/cache/storage/CMakeLists.txt | 3 ++- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/Documentation/Filters/Cache.md b/Documentation/Filters/Cache.md index 14b254481..16527659f 100644 --- a/Documentation/Filters/Cache.md +++ b/Documentation/Filters/Cache.md @@ -622,6 +622,9 @@ storage=storage_inmemory ## `storage_rocksdb` +This storage module is not built by default and is not included in the +MariaDB MaxScale packages. + This storage module uses RocksDB database for storing the cached data. The directory where the RocksDB database will be created is by default created into the _MaxScale cache_ directory, which usually is not on a RAM disk. For diff --git a/server/modules/filter/cache/storage/CMakeLists.txt b/server/modules/filter/cache/storage/CMakeLists.txt index 52287a9f9..ff3bc6a2b 100644 --- a/server/modules/filter/cache/storage/CMakeLists.txt +++ b/server/modules/filter/cache/storage/CMakeLists.txt @@ -1,2 +1,3 @@ -add_subdirectory(storage_rocksdb) +#Storage RocksDB not built by default. +#add_subdirectory(storage_rocksdb) add_subdirectory(storage_inmemory) From 695ba1996502e85fa0d0a9c96eefde72cce762b4 Mon Sep 17 00:00:00 2001 From: MassimilianoPinto Date: Thu, 20 Apr 2017 13:36:13 +0200 Subject: [PATCH 16/29] Massimiliano pinto doc update 2.1 (#125) * Update Nagios-Plugins.md * Update MM-Monitor.md * Update Nagios-Plugins.md * Update Nagios-Plugins.md * Update Galera-Cluster-Connection-Routing-Tutorial.md * Update Galera-Cluster-Connection-Routing-Tutorial.md * Update RabbitMQ-Setup-And-MaxScale-Integration.md * Update MaxScale-Tutorial.md * Update Cache.md * Update Transaction-Performance-Monitoring-Filter.md * Update RabbitMQ-Consumer-Client.md * Update Building-MaxScale-from-Source-Code.md * Update MariaDB-MaxScale-Installation-Guide.md * Update Install-MariaDB-MaxScale-Using-a-Tarball.md * Update RabbitMQ-Setup-And-MaxScale-Integration.md * Update RabbitMQ-Consumer-Client.md --- Documentation/Filters/Cache.md | 3 +- .../Filters/RabbitMQ-Consumer-Client.md | 17 ++- ...ansaction-Performance-Monitoring-Filter.md | 44 ++++-- .../Building-MaxScale-from-Source-Code.md | 3 +- ...nstall-MariaDB-MaxScale-Using-a-Tarball.md | 50 ++++-- .../MariaDB-MaxScale-Installation-Guide.md | 142 +++++++++++++++--- Documentation/Monitors/MM-Monitor.md | 18 ++- ...era-Cluster-Connection-Routing-Tutorial.md | 116 +++++++++++--- Documentation/Tutorials/MaxScale-Tutorial.md | 81 ++++++++-- Documentation/Tutorials/Nagios-Plugins.md | 85 ++++++----- ...RabbitMQ-Setup-And-MaxScale-Integration.md | 54 +++++-- 11 files changed, 459 insertions(+), 154 deletions(-) diff --git a/Documentation/Filters/Cache.md b/Documentation/Filters/Cache.md index 16527659f..46534ee2d 100644 --- a/Documentation/Filters/Cache.md +++ b/Documentation/Filters/Cache.md @@ -654,7 +654,8 @@ created, under which the actual instance specific cache directories are created. Specifies whether RocksDB should collect statistics that later can be queried using `maxadmin`. It should be noted, though, that collecting RocksDB statistics -is not without a cost. From the [RocksDB Documentation](https://github.com/facebook/rocksdb/wiki/Statistics) +is not without a cost. +From the [RocksDB Documentation](https://github.com/facebook/rocksdb/wiki/Statistics) _The overhead of statistics is usually small but non-negligible. We usually observe an overhead of 5%-10%._ diff --git a/Documentation/Filters/RabbitMQ-Consumer-Client.md b/Documentation/Filters/RabbitMQ-Consumer-Client.md index 76c9c4e03..63dc4ccaf 100644 --- a/Documentation/Filters/RabbitMQ-Consumer-Client.md +++ b/Documentation/Filters/RabbitMQ-Consumer-Client.md @@ -1,8 +1,10 @@ -#RabbitMQ Consumer Client +# RabbitMQ Consumer Client ## Overview -This utility tool is used to read messages from a RabbitMQ broker sent by the [RabbitMQ Filter](RabbitMQ-Filter.md) and forward these messages into an SQL database as queries. +This utility tool is used to read messages from a RabbitMQ broker sent by the +[RabbitMQ Filter](RabbitMQ-Filter.md) and forward these messages into an +SQL database as queries. ## Command Line Arguments @@ -14,7 +16,9 @@ The **RabbitMQ Consumer Client** only has one command line argument. ## Installation -To install the RabbitMQ Consumer Client you ca either use the provided packages or you can compile it from source code. The source code is included as a part of the MariaDB MaxScale source code and can be found in the `rabbitmq_consumer` folder. +To install the RabbitMQ Consumer Client you can either use the provided packages +or you can compile it from source code. The source code is included as a part of the +MariaDB MaxScale source code and can be found in the `rabbitmq_consumer` folder. ## Building from source @@ -48,9 +52,12 @@ include and library directories 'in buildvars.inc' ## Configuration -The consumer client requires that the `consumer.cnf` configuration file is either be present in the `etc` folder of the installation directory or in the folder specified by the `-c` argument. +The consumer client requires that the `consumer.cnf` configuration file is either +be present in the `etc` folder of the installation directory or in the folder +specified by the `-c` argument. -The source broker, the destination database and the message log file can be configured into the separate `consumer.cnf` file. +The source broker, the destination database and the message log file can be +configured into the separate `consumer.cnf` file. | Option | Description | |-----------|---------------------------------------------| diff --git a/Documentation/Filters/Transaction-Performance-Monitoring-Filter.md b/Documentation/Filters/Transaction-Performance-Monitoring-Filter.md index a09bb4181..21070c40d 100644 --- a/Documentation/Filters/Transaction-Performance-Monitoring-Filter.md +++ b/Documentation/Filters/Transaction-Performance-Monitoring-Filter.md @@ -2,11 +2,17 @@ ## Overview -The Transaction Performance Monitoring (TPM) filter is a filter module for MaxScale that monitors every SQL statement that passes through the filter. The filter groups a series of SQL statements into a transaction by detecting 'commit' or 'rollback' statements. It logs all committed transactions with necessary information, such as timestamp, client, SQL statements, latency, etc., which can be used later for transaction performance analysis. +The Transaction Performance Monitoring (TPM) filter is a filter module for MaxScale +that monitors every SQL statement that passes through the filter. +The filter groups a series of SQL statements into a transaction by detecting +'commit' or 'rollback' statements. It logs all committed transactions with necessary +information, such as timestamp, client, SQL statements, latency, etc., which +can be used later for transaction performance analysis. ## Configuration -The configuration block for the TPM filter requires the minimal filter options in it's section within the maxscale.cnf file, stored in /etc/maxscale.cnf. +The configuration block for the TPM filter requires the minimal filter +options in it's section within the maxscale.cnf file, stored in /etc/maxscale.cnf. ``` [MyLogFilter] @@ -32,7 +38,8 @@ The TPM filter accepts a number of optional parameters. ### Filename -The name of the output file created for performance logging. The default filename is **tpm.log**. +The name of the output file created for performance logging. +The default filename is **tpm.log**. ``` filename=/tmp/SqlQueryLog @@ -40,7 +47,10 @@ filename=/tmp/SqlQueryLog ### Source -The optional `source` parameter defines an address that is used to match against the address from which the client connection to MaxScale originates. Only sessions that originate from this address will be logged. +The optional `source` parameter defines an address that is used +to match against the address from which the client connection +to MaxScale originates. Only sessions that originate from this +address will be logged. ``` source=127.0.0.1 @@ -48,7 +58,10 @@ source=127.0.0.1 ### User -The optional `user` parameter defines a user name that is used to match against the user from which the client connection to MaxScale originates. Only sessions that are connected using this username are logged. +The optional `user` parameter defines a user name that is used +to match against the user from which the client connection to +MaxScale originates. Only sessions that are connected using +this username are logged. ``` user=john @@ -56,7 +69,8 @@ user=john ### Delimiter -The optional `delimiter` parameter defines a delimiter that is used to distinguish columns in the log. The default delimiter is **`:::`**. +The optional `delimiter` parameter defines a delimiter that is used to +distinguish columns in the log. The default delimiter is **`:::`**. ``` delimiter=::: @@ -64,7 +78,9 @@ delimiter=::: ### Query_delimiter -The optional `query_delimiter` defines a delimiter that is used to distinguish different SQL statements in a transaction. The default query delimiter is **`@@@`**. +The optional `query_delimiter` defines a delimiter that is used to +distinguish different SQL statements in a transaction. +The default query delimiter is **`@@@`**. ``` query_delimiter=@@@ @@ -72,7 +88,11 @@ query_delimiter=@@@ ### Named_pipe -**`named_pipe`** is the path to a named pipe, which TPM filter uses to communicate with 3rd-party applications (e.g., [DBSeer](http://dbseer.org)). Logging is enabled when the router receives the character '1' and logging is disabled when the router receives the character '0' from this named pipe. The default named pipe is **`/tmp/tpmfilter`** and logging is **disabled** by default. +**`named_pipe`** is the path to a named pipe, which TPM filter uses to +communicate with 3rd-party applications (e.g., [DBSeer](http://dbseer.org)). +Logging is enabled when the router receives the character '1' and logging is +disabled when the router receives the character '0' from this named pipe. +The default named pipe is **`/tmp/tpmfilter`** and logging is **disabled** by default. named_pipe=/tmp/tpmfilter @@ -89,7 +109,8 @@ Similarly, the following command disables the logging: ### Example 1 - Log Transactions for Performance Analysis -You want to log every transaction with its SQL statements and latency for future transaction performance analysis. +You want to log every transaction with its SQL statements and latency +for future transaction performance analysis. Add a filter with the following definition: @@ -111,7 +132,8 @@ passwd=mypasswd filters=PerformanceLogger ``` -After the filter reads the character '1' from its named pipe, the following is an example log that is generated from the above TPM filter with the above configuration: +After the filter reads the character '1' from its named pipe, the following +is an example log that is generated from the above TPM filter with the above configuration: ``` @@ -120,4 +142,4 @@ After the filter reads the character '1' from its named pipe, the following is a ... ``` -Note that 3 and 5 are latencies of each transaction in milliseconds. \ No newline at end of file +Note that 3 and 5 are latencies of each transaction in milliseconds. diff --git a/Documentation/Getting-Started/Building-MaxScale-from-Source-Code.md b/Documentation/Getting-Started/Building-MaxScale-from-Source-Code.md index 09cb312ed..787c6b69e 100644 --- a/Documentation/Getting-Started/Building-MaxScale-from-Source-Code.md +++ b/Documentation/Getting-Started/Building-MaxScale-from-Source-Code.md @@ -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 diff --git a/Documentation/Getting-Started/Install-MariaDB-MaxScale-Using-a-Tarball.md b/Documentation/Getting-Started/Install-MariaDB-MaxScale-Using-a-Tarball.md index d8eeb4b3f..b86303acc 100644 --- a/Documentation/Getting-Started/Install-MariaDB-MaxScale-Using-a-Tarball.md +++ b/Documentation/Getting-Started/Install-MariaDB-MaxScale-Using-a-Tarball.md @@ -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 diff --git a/Documentation/Getting-Started/MariaDB-MaxScale-Installation-Guide.md b/Documentation/Getting-Started/MariaDB-MaxScale-Installation-Guide.md index 9106066a2..2c8c29ff0 100644 --- a/Documentation/Getting-Started/MariaDB-MaxScale-Installation-Guide.md +++ b/Documentation/Getting-Started/MariaDB-MaxScale-Installation-Guide.md @@ -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. diff --git a/Documentation/Monitors/MM-Monitor.md b/Documentation/Monitors/MM-Monitor.md index 039840122..86e31d5bc 100644 --- a/Documentation/Monitors/MM-Monitor.md +++ b/Documentation/Monitors/MM-Monitor.md @@ -2,11 +2,15 @@ ## Overview -The Multi-Master Monitor is a monitoring module for MaxScale that monitors Master-Master replication. It assigns master and slave roles inside MaxScale based on whether the read_only parameter on a server is set to off or on. +The Multi-Master Monitor is a monitoring module for MaxScale that monitors Master-Master replication. +It assigns master and slave roles inside MaxScale based on whether the read_only parameter on a server +is set to off or on. ## Configuration -A minimal configuration for a monitor requires a set of servers for monitoring and a username and a password to connect to these servers. The user requires the REPLICATION CLIENT privilege to successfully monitor the state of the servers. +A minimal configuration for a monitor requires a set of servers for monitoring and an username +and a password to connect to these servers. The user requires the REPLICATION CLIENT privilege +to successfully monitor the state of the servers. ``` [Multi-Master Monitor] @@ -20,7 +24,8 @@ passwd=mypwd ## Common Monitor Parameters -For a list of optional parameters that all monitors support, read the [Monitor Common](Monitor-Common.md) document. +For a list of optional parameters that all monitors support, read +the [Monitor Common](Monitor-Common.md) document. ## Multi-Master Monitor optional parameters @@ -28,9 +33,12 @@ These are optional parameters specific to the Multi-Master Monitor. ### `detect_stale_master` -Allow previous master to be available even in case of stopped or misconfigured replication. This allows services that depend on master and slave roles to continue functioning as long as the master server is available. +Allow previous master to be available even in case of stopped or misconfigured replication. +This allows services that depend on master and slave roles to continue functioning as long as +the master server is available. -This is a situation which can happen if all slave servers are unreachable or the replication breaks for some reason. +This is a situation which can happen if all slave servers are unreachable or the +replication breaks for some reason. ``` detect_stale_master=true diff --git a/Documentation/Tutorials/Galera-Cluster-Connection-Routing-Tutorial.md b/Documentation/Tutorials/Galera-Cluster-Connection-Routing-Tutorial.md index 06a15d2e7..2594eb8e4 100644 --- a/Documentation/Tutorials/Galera-Cluster-Connection-Routing-Tutorial.md +++ b/Documentation/Tutorials/Galera-Cluster-Connection-Routing-Tutorial.md @@ -2,33 +2,53 @@ # Environment & Solution Space -The object of this tutorial is to have a system that has two ports available, one for write connections to the database cluster and the other for read connections to the database. +The object of this tutorial is to have a system that has two ports available, one for +write connections to the database cluster and the other for read connections to the database. ## Setting up MariaDB MaxScale -The first part of this tutorial is covered in [MariaDB MaxScale Tutorial](MaxScale-Tutorial.md). Please read it and follow the instructions for setting up MariaDB MaxScale with the type of cluster you want to use. +The first part of this tutorial is covered in [MariaDB MaxScale Tutorial](MaxScale-Tutorial.md). +Please read it and follow the instructions for setting up MariaDB MaxScale with the +type of cluster you want to use. -Once you have MariaDB MaxScale installed and the database users created, we can create the configuration file for MariaDB MaxScale. +Once you have MariaDB MaxScale installed and the database users created, we can create +the configuration file for MariaDB MaxScale. ## Creating Your MariaDB MaxScale Configuration -MariaDB MaxScale configuration is held in an ini file that is located in the file maxscale.cnf in the directory /etc, if you have installed in the default location then this file is available in /etc/maxscale.cnf. This is not created as part of the installation process and must be manually created. A template file does exist within the /usr/share/maxscale directory that may be use as a basis for your configuration. +MariaDB MaxScale configuration is held in an ini file that is located in the file maxscale.cnf +in the directory /etc, if you have installed in the default location then this file +is available in /etc/maxscale.cnf. This is not created as part of the installation process +and must be manually created. A template file does exist within the /usr/share/maxscale directory +that may be use as a basis for your configuration. -A global, maxscale, section is included within every MariaDB MaxScale configuration file; this is used to set the values of various MariaDB MaxScale wide parameters, perhaps the most important of these is the number of threads that MariaDB MaxScale will use to execute the code that forwards requests and handles responses for clients. +A global, maxscale, section is included within every MariaDB MaxScale configuration file; +this is used to set the values of various MariaDB MaxScale wide parameters, perhaps +the most important of these is the number of threads that MariaDB MaxScale will use +to execute the code that forwards requests and handles responses for clients. ``` [maxscale] threads=4 ``` -Since we are using Galera Cluster and connection routing we want a single to which the client application can connect; MariaDB MaxScale will then route connections to this port onwards to the various nodes within the Galera Cluster. To achieve this within MariaDB MaxScale we need to define a service in the ini file. Create a section for each in your MariaDB MaxScale configuration file and set the type to service, the section name is the names of the service and should be meaningful to the administrator. Names may contain whitespace. +Since we are using Galera Cluster and connection routing we want a single to which +the client application can connect; MariaDB MaxScale will then route connections to +this port onwards to the various nodes within the Galera Cluster. To achieve this +within MariaDB MaxScale we need to define a service in the ini file. Create a section +for each in your MariaDB MaxScale configuration file and set the type to service, +the section name is the names of the service and should be meaningful to +the administrator. Names may contain whitespace. ``` [Galera Service] type=service ``` -The router for this section the readconnroute module, also the service should be provided with the list of servers that will be part of the cluster. The server names given here are actually the names of server sections in the configuration file and not the physical hostnames or addresses of the servers. +The router for this section the readconnroute module, also the service should be +provided with the list of servers that will be part of the cluster. The server names +given here are actually the names of server sections in the configuration file and not +the physical hostnames or addresses of the servers. ``` [Galera Service] @@ -37,7 +57,12 @@ router=readconnroute servers=dbserv1, dbserv2, dbserv3 ``` -In order to instruct the router to which servers it should route we must add router options to the service. The router options are compared to the status that the monitor collects from the servers and used to restrict the eligible set of servers to which that service may route. In our case we use the option that restricts us to servers that are fully functional members of the Galera cluster which are able to support SQL operations on the cluster. To achieve this we use the router option synced. +In order to instruct the router to which servers it should route we must add router +options to the service. The router options are compared to the status that the monitor +collects from the servers and used to restrict the eligible set of servers to which that +service may route. In our case we use the option that restricts us to servers that are +fully functional members of the Galera cluster which are able to support SQL operations +on the cluster. To achieve this we use the router option synced. ``` [Galera Service] @@ -47,14 +72,20 @@ router_options=synced servers=dbserv1, dbserv2, dbserv3 ``` -The final step in the service section is to add the username and password that will be used to populate the user data from the database cluster. There are two options for representing the password, either plain text or encrypted passwords may be used. In order to use encrypted passwords a set of keys must be generated that will be used by the encryption and decryption process. To generate the keys use the maxkeys command and pass the name of the secrets file in which the keys are stored. +The final step in the service section is to add the username and password that will be +used to populate the user data from the database cluster. There are two options for +representing the password, either plain text or encrypted passwords may be used. +In order to use encrypted passwords a set of keys must be generated that will be used +by the encryption and decryption process. To generate the keys use the maxkeys command +and pass the name of the secrets file in which the keys are stored. ``` % maxkeys /var/lib/maxscale/.secrets % ``` -Once the keys have been created the maxpasswd command can be used to generate the encrypted password. +Once the keys have been created the maxpasswd command can be used to generate +the encrypted password. ``` % maxpasswd plainpassword @@ -62,7 +93,8 @@ Once the keys have been created the maxpasswd command can be used to generate th % ``` -The username and password, either encrypted or plain text, are stored in the service section using the user and passwd parameters. +The username and password, either encrypted or plain text, are stored in the service +section using the user and passwd parameters. ``` [Galera Service] @@ -74,7 +106,12 @@ user=maxscale passwd=96F99AA1315BDC3604B006F427DD9484 ``` -This completes the definitions required by the service, however listening ports must be associated with a service in order to allow network connections. This is done by creating a series of listener sections. These sections again are named for the convenience of the administrator and should be of type listener with an entry labeled service which contains the name of the service to associate the listener with. Each service may have multiple listeners. +This completes the definitions required by the service, however listening ports must +be associated with a service in order to allow network connections. This is done by +creating a series of listener sections. These sections again are named for the convenience +of the administrator and should be of type listener with an entry labeled service which +contains the name of the service to associate the listener with. +Each service may have multiple listeners. ``` [Galera Listener] @@ -82,7 +119,10 @@ type=listener service=Galera Service ``` -A listener must also define the protocol module it will use for the incoming network protocol, currently this should be the MySQLClient protocol for all database listeners. The listener may then supply a network port to listen on and/or a socket within the file system. +A listener must also define the protocol module it will use for the incoming +network protocol, currently this should be the MySQLClient protocol for all +database listeners. The listener may then supply a network port to listen on +and/or a socket within the file system. ``` [Galera Listener] @@ -93,9 +133,15 @@ port=4306 socket=/tmp/DB.Cluster ``` -An address parameter may be given if the listener is required to bind to a particular network address when using hosts with multiple network addresses. The default behavior is to listen on all network interfaces. +An address parameter may be given if the listener is required to bind to a particular +network address when using hosts with multiple network addresses. +The default behavior is to listen on all network interfaces. -The next stage is the configuration is to define the server information. This defines how to connect to each of the servers within the cluster, again a section is created for each server, with the type set to server, the network address and port to connect to and the protocol to use to connect to the server. Currently the protocol for all database connections in MySQLBackend. +The next stage is the configuration is to define the server information. +This defines how to connect to each of the servers within the cluster, again a section +is created for each server, with the type set to server, the network address and port to +connect to and the protocol to use to connect to the server. Currently the protocol for +all database connections in MySQLBackend. ``` [dbserv1] @@ -117,7 +163,12 @@ port=3306 protocol=MySQLBackend ``` -In order for MariaDB MaxScale to monitor the servers using the correct monitoring mechanisms a section should be provided that defines the monitor to use and the servers to monitor. Once again a section is created with a symbolic name for the monitor, with the type set to monitor. Parameters are added for the module to use, the list of servers to monitor and the username and password to use when connecting to the the servers with the monitor. +In order for MariaDB MaxScale to monitor the servers using the correct monitoring +mechanisms a section should be provided that defines the monitor to use and +the servers to monitor. Once again a section is created with a symbolic name for +the monitor, with the type set to monitor. Parameters are added for the module to use, +the list of servers to monitor and the username and password to use when connecting to +the servers with the monitor. ``` [Galera Monitor] @@ -128,9 +179,12 @@ user=maxscale passwd=96F99AA1315BDC3604B006F427DD9484 ``` -As with the password definition in the server either plain text or encrypted passwords may be used. +As with the password definition in the server either plain text or encrypted +passwords may be used. -The final stage in the configuration is to add the option service which is used by the maxadmin command to connect to MariaDB MaxScale for monitoring and administration purposes. This creates a service section and a listener section. +The final stage in the configuration is to add the option service which is used by +the maxadmin command to connect to MariaDB MaxScale for monitoring and +administration purposes. This creates a service section and a listener section. ``` [CLI] @@ -145,7 +199,9 @@ socket=default ## Starting MariaDB MaxScale -Upon completion of the configuration process MariaDB MaxScale is ready to be started for the first time. This may either be done manually by running the maxscale command or via the service interface. +Upon completion of the configuration process MariaDB MaxScale is ready to be +started for the first time. This may either be done manually by running the +maxscale command or via the service interface. ``` % maxscale @@ -157,7 +213,10 @@ or % service maxscale start ``` -Check the error log in /var/log/maxscale to see if any errors are detected in the configuration file and to confirm MariaDB MaxScale has been started. Also the maxadmin command may be used to confirm that MariaDB MaxScale is running and the services, listeners etc have been correctly configured. +Check the error log in /var/log/maxscale to see if any errors are detected in +the configuration file and to confirm MariaDB MaxScale has been started. +Also the maxadmin command may be used to confirm that MariaDB MaxScale is running +and the services, listeners etc have been correctly configured. ``` % maxadmin list services @@ -180,9 +239,14 @@ dbserv3 | 192.168.2.3 | 3306 | 0 | Running, Synced, Sl -------------------+-----------------+-------+-------------+-------------------- ``` -A Galera Cluster is a multi-master clustering technology, however the monitor is able to impose false notions of master and slave roles within a Galera Cluster in order to facilitate the use of Galera as if it were a standard MySQL Replication setup. This is merely an internal MariaDB MaxScale convenience and has no impact on the behavior of the cluster. +A Galera Cluster is a multi-master clustering technology, however the monitor is able +to impose false notions of master and slave roles within a Galera Cluster in order to +facilitate the use of Galera as if it were a standard MySQL Replication setup. +This is merely an internal MariaDB MaxScale convenience and has no impact on the behavior of the cluster. -You can control which Galera node is the master server by using the _priority_ mechanism of the Galera Monitor module. For more details, read the [Galera Monitor](../Monitors/Galera-Monitor.md) documentation. +You can control which Galera node is the master server by using the _priority_ +mechanism of the Galera Monitor module. For more details, +read the [Galera Monitor](../Monitors/Galera-Monitor.md) documentation. ``` % maxadmin list listeners @@ -197,4 +261,10 @@ CLI | maxscaled | localhost | 6603 | Running % ``` -MariaDB MaxScale is now ready to start accepting client connections and routing them to the master or slaves within your cluster. Other configuration options are available that can alter the criteria used for routing, such as using weights to obtain unequal balancing operations. These options may be found in the MariaDB MaxScale Configuration Guide. More detail on the use of maxadmin can be found in the document ["MaxAdmin - The MariaDB MaxScale Administration & Monitoring Client Application"](../Reference/MaxAdmin.md). +MariaDB MaxScale is now ready to start accepting client connections and routing +them to the master or slaves within your cluster. Other configuration options are +available that can alter the criteria used for routing, such as using weights to +obtain unequal balancing operations. +These options may be found in the MariaDB MaxScale Configuration Guide. +More detail on the use of maxadmin can be found in the document +["MaxAdmin - The MariaDB MaxScale Administration & Monitoring Client Application"](../Reference/MaxAdmin.md). diff --git a/Documentation/Tutorials/MaxScale-Tutorial.md b/Documentation/Tutorials/MaxScale-Tutorial.md index 443893ef2..86c28c13d 100644 --- a/Documentation/Tutorials/MaxScale-Tutorial.md +++ b/Documentation/Tutorials/MaxScale-Tutorial.md @@ -1,10 +1,21 @@ # Setting up MariaDB MaxScale -This document is designed as a quick introduction to setting up MariaDB MaxScale in an environment in which you have either a MySQL Master-Slave replication cluster with one master and multiple slave servers or a multi-node Galera cluster. The process of setting and configuring MariaDB MaxScale will be covered within this document. +This document is designed as a quick introduction to setting up MariaDB MaxScale +in an environment in which you have either a MySQL Master-Slave replication cluster +with one master and multiple slave servers or a multi-node Galera cluster. +The process of setting and configuring MariaDB MaxScale will be covered within this document. -The installation and configuration of the MySQL Replication or the Galera cluster will not be covered nor will any discussion of installation management tools to handle automated or semi-automated failover of the replication cluster. The [Setting Up Replication](https://mariadb.com/kb/en/mariadb/setting-up-replication/) article on the MariaDB knowledgebase can help you get started with replication clusters and the [Getting Started With Mariadb Galera Cluster](https://mariadb.com/kb/en/mariadb/getting-started-with-mariadb-galera-cluster/) article will help you set up a Galera cluster. +The installation and configuration of the MySQL Replication or the Galera cluster +will not be covered nor will any discussion of installation management tools +to handle automated or semi-automated failover of the replication cluster. +The [Setting Up Replication](https://mariadb.com/kb/en/mariadb/setting-up-replication/) +article on the MariaDB knowledgebase can help you get started with replication clusters +and the [Getting Started With Mariadb Galera Cluster](https://mariadb.com/kb/en/mariadb/getting-started-with-mariadb-galera-cluster/) article will help you set up a Galera cluster. -This tutorial will assume the user is running from one of the binary distributions available and has installed this in the default location. Building from source code in GitHub is covered in the [Building from Source](../Getting-Started/Building-MaxScale-from-Source-Code.md) document. +This tutorial will assume the user is running from one of the binary distributions +available and has installed this in the default location. +Building from source code in GitHub is covered in the +[Building from Source](../Getting-Started/Building-MaxScale-from-Source-Code.md) document. ## Process @@ -18,19 +29,33 @@ The steps involved in setting up MariaDB MaxScale are: ## Installation -The precise installation process will vary from one distribution to another details of what to do with the RPM and DEB packages can be found on the download site when you select the distribution you are downloading from. The process involves setting up your package manager to include the MariaDB repositories and then running the package manager for your distribution (usually yum or apt-get). +The precise installation process will vary from one distribution to another +details of what to do with the RPM and DEB packages can be found on the download +site when you select the distribution you are downloading from. +The process involves setting up your package manager to include the MariaDB repositories +and then running the package manager for your distribution (usually yum or apt-get). -Upon successful completion of the installation command you will have MariaDB MaxScale installed and ready to be run but without a configuration. You must create a configuration file before you first run MariaDB MaxScale which is covered in a later section. +Upon successful completion of the installation command you will have MariaDB MaxScale +installed and ready to be run but without a configuration. +You must create a configuration file before you first run MariaDB MaxScale +which is covered in a later section. ## Creating Database Users -MariaDB MaxScale needs to connect to the backend databases and run queries for two reasons; one to determine the current state of the database and the other to retrieve the user information for the database cluster. The first pair of credentials will be used by the monitor modules and the second is used by MariaDB MaxScale itself. This may be done either using two separate usernames or with a single user. +MariaDB MaxScale needs to connect to the backend databases and run queries for +two reasons; one to determine the current state of the database and the other to +retrieve the user information for the database cluster. The first pair of +credentials will be used by the monitor modules and the second is used by +MariaDB MaxScale itself. This may be done either using two separate usernames +or with a single user. -The first user required must be able to select data from the table mysql.user, to create this user follow the steps below. +The first user required must be able to select data from the table mysql.user, +to create this user follow the steps below. 1. Connect to the current master server in your replication tree as the root user -2. Create the user, substituting the username, password and host on which maxscale runs within your environment +2. Create the user, substituting the username, password and host on which maxscale +runs within your environment ``` MariaDB [(none)]> create user '*username*'@'*maxscalehost*' identified by '*password*'; @@ -42,7 +67,9 @@ MariaDB [(none)]> grant SELECT on mysql.user to '*username*'@'*maxscalehost*'; **Query OK, 0 rows affected (0.03 sec)** ``` -Additionally, `SELECT` privileges on the `mysql.db` and `mysql.tables_priv` tables and `SHOW DATABASES` privileges are required in order to load databases name and grants suitable for database name authorization. +Additionally, `SELECT` privileges on the `mysql.db` and `mysql.tables_priv` tables +and `SHOW DATABASES` privileges are required in order to load databases name +and grants suitable for database name authorization. ``` MariaDB [(none)]> GRANT SELECT ON mysql.db TO 'username'@'maxscalehost'; @@ -56,7 +83,11 @@ MariaDB [(none)]> GRANT SHOW DATABASES ON *.* TO 'username'@'maxscalehost'; **Query OK, 0 rows affected (0.00 sec)** ``` -The second user is used to monitored the state of the cluster. This user, which may be the same username as the first, requires permissions to access the various sources of monitoring data. In order to monitor a replication cluster this user must be granted the role REPLICATION CLIENT. This is only required by the MySQL monitor and Multi-Master monitor modules. +The second user is used to monitored the state of the cluster. This user, which may be +the same username as the first, requires permissions to access the various sources +of monitoring data. In order to monitor a replication cluster this user must be granted +the role REPLICATION CLIENT. This is only required by the MySQL monitor +and Multi-Master monitor modules. ``` MariaDB [(none)]> grant REPLICATION CLIENT on *.* to '*username*'@'*maxscalehost*'; @@ -64,17 +95,32 @@ MariaDB [(none)]> grant REPLICATION CLIENT on *.* to '*username*'@'*maxscalehost **Query OK, 0 rows affected (0.00 sec)** ``` -If you wish to use two different usernames for the two different roles of monitoring and collecting user information then create a different username using the first two steps from above. +If you wish to use two different usernames for the two different roles of monitoring +and collecting user information then create a different username using the first +two steps from above. ## Creating additional grants for users -Because MariaDB MaxScale sits between the clients and the backend databases, the backend databases will see all clients as if they were connecting from MariaDB MaxScale's address. This usually requires users to create additional grants for MariaDB MaxScale's hostname. The best way to describe this process is with an example. +Because MariaDB MaxScale sits between the clients and the backend databases, +the backend databases will see all clients as if they were connecting from +MariaDB MaxScale's address. +This usually requires users to create additional grants for MariaDB MaxScale's hostname. +The best way to describe this process is with an example. -User `'jdoe'@'192.168.0.200` has the following grant on the cluster: `GRANT SELECT, INSERT, UPDATE, DELETE ON *.* TO 'jdoe'@'192.168.0.200'`. When the user connects directly to the server it will see it as `'jdoe'@'192.168.0.200` connecting to the server and it will match the grant for `'jdoe'@'192.168.0.200`. +User `'jdoe'@'192.168.0.200` has the following grant on the cluster: +`GRANT SELECT, INSERT, UPDATE, DELETE ON *.* TO 'jdoe'@'192.168.0.200'`. +When the user connects directly to the server it will see it as +`'jdoe'@'192.168.0.200` connecting to the server and it will match +the grant for `'jdoe'@'192.168.0.200`. -If MariaDB MaxScale is at the address `192.168.0.101` and the user `jdoe` connects to this MariaDB MaxScale, the backend server will see the connection as `'jdoe'@'192.168.0.101'`. Since the backend server has no grants for `'jdoe'@'192.168.0.101'`, the connection from MariaDB MaxScale to the server will be refused. +If MariaDB MaxScale is at the address `192.168.0.101` and the user `jdoe` +connects to this MariaDB MaxScale, the backend server will see the connection as +`'jdoe'@'192.168.0.101'`. Since the backend server has no grants for +`'jdoe'@'192.168.0.101'`, the connection from MariaDB MaxScale to the server +will be refused. -We can fix this by either creating a matching grant for user `jdoe` from the MariaDB MaxScale address or by using a wildcard to cover both addresses. +We can fix this by either creating a matching grant for user `jdoe` from +the MariaDB MaxScale address or by using a wildcard to cover both addresses. The quickest way to do this is by doing a SHOW GRANTS query: ``` @@ -95,7 +141,10 @@ MariaDB [(none)]> GRANT SELECT, INSERT, UPDATE, DELETE ON *.* TO 'jdoe'@'192.168 Query OK, 0 rows affected (0.00 sec) ``` -The other option is to use a wildcard grant like `GRANT SELECT, INSERT, UPDATE, DELETE ON *.* TO 'jdoe'@'%'`. This is more convenient but also less secure than having specific grants for both the client's address and MariaDB MaxScale's address. +The other option is to use a wildcard grant like +`GRANT SELECT, INSERT, UPDATE, DELETE ON *.* TO 'jdoe'@'%'`. +This is more convenient but also less secure than having specific grants +for both the client's address and MariaDB MaxScale's address. ## Creating the configuration file diff --git a/Documentation/Tutorials/Nagios-Plugins.md b/Documentation/Tutorials/Nagios-Plugins.md index ebf896af3..02304c02c 100644 --- a/Documentation/Tutorials/Nagios-Plugins.md +++ b/Documentation/Tutorials/Nagios-Plugins.md @@ -1,49 +1,40 @@ # MariaDB MaxScale Nagios plugins, for Nagios 3.5.1 -Massimiliano Pinto - -Last Updated: 12th March 2015 - -## Document History - - - - - - - - - - - - - - - - - -
DateChangeWho
10th March 2015Initial versionMassimiliano Pinto
20th May 2016MaxAdmin uses UNIX socket onlyMassimiliano Pinto
- # Introduction -Nagios® Core™ is an Open Source system and network monitoring application. It watches hosts and services that you specify, alerting you when things go bad and when they get better. -Nagios plugins are compiled executables or scripts (Perl scripts, shell scripts, etc.) that can be run from a command line to check the status or a host or service. Nagios uses the results from plugins to determine the current status of hosts and services on your network. -Nagios core executes a plugin whenever there is a need to check the status of a service or host. +Nagios® Core™ is an Open Source system and network monitoring application. +It watches hosts and services that you specify, alerting you when things go bad +and when they get better. +Nagios plugins are compiled executables or scripts (Perl scripts, shell scripts, etc.) +that can be run from a command line to check the status or a host or service. +Nagios uses the results from plugins to determine the current status of hosts and +services on your network. +Nagios core executes a plugin whenever there is a need to check the status +of a service or host. -While MariaDB MaxScale resources and status can be monitored via CLI using maxadmin commands, Nagios Plugin provides an automated way for system administration and database administrators to monitor MariaDB MaxScale. The diagram below provides view of how Nagios and MariaDB MaxScale interact. +While MariaDB MaxScale resources and status can be monitored via CLI using +maxadmin commands, Nagios Plugin provides an automated way for system administration +and database administrators to monitor MariaDB MaxScale. +The diagram below provides view of how Nagios and MariaDB MaxScale interact. ![Nagios and MariaDB MaxScale interaction](images/HowMaxScaleWorksWithNagios.png) There are three Nagios plugin scripts that MariaDB MaxScale provides. -1. check_maxscale_threads.pl: This command provides you the status of current running threads and events in the queue on MariaDB MaxScale Server. The Performance data associated with this command current and historic wait time for threads and events +1. check_maxscale_threads.pl: This command provides you the status of current running +threads and events in the queue on MariaDB MaxScale Server. +The Performance data associated with this command current and historic wait time for threads and events -2. check_maxscale_resources.pl: This command provides you status of various resources on MariaDB MaxScale server. The Performance data associated provides details on respective resources. +2. check_maxscale_resources.pl: This command provides you status of various resources +on MariaDB MaxScale server. The Performance data associated provides +details on respective resources. Current resources are: modules, services, listeners, servers, sessions, filters. -3. check_maxscale_monitor.pl: This command provides you status of the configured monitor modules on MariaDB MaxScale server. +3. check_maxscale_monitor.pl: This command provides you status of the configured +monitor modules on MariaDB MaxScale server. -In order to use these scripts on your Nagios Server, you need to copy them from the MariaDB MaxScale binary package or download them from source tree on GitHub. +In order to use these scripts on your Nagios Server, you need to copy them +from the MariaDB MaxScale binary package or download them from source tree on GitHub. # MariaDB MaxScale Nagios Plugin Requirements @@ -65,10 +56,13 @@ socket=default ## Prepare Nagios configuration files. -Assuming Nagios installed on a separated server and the plugins are in /usr/lib64/nagios/plugins and configuration files are in /etc/nagios: +Assuming Nagios installed on a separated server and the plugins are +in /usr/lib64/nagios/plugins and configuration files are in /etc/nagios: -* Copy MariaDB MaxScale plugin scripts (./nagios/plugins/check_maxscale_*.pl) to /usr/lib64/nagios/plugins on Nagios Server -* Copy New commands and server1 definition (./nagios/plugins/maxscale_commands.cfg, server1.cfg) to /etc/nagios/objects/ on Nagios Server +* Copy MariaDB MaxScale plugin scripts (./nagios/plugins/check_maxscale_*.pl) +to /usr/lib64/nagios/plugins on Nagios Server +* Copy New commands and server1 definition (./nagios/plugins/maxscale_commands.cfg, server1.cfg) +to /etc/nagios/objects/ on Nagios Server * Edit /etc/nagios/nagios.cfg on Nagios Server and add (just after localhost.cfg or commands.cfg) @@ -87,14 +81,18 @@ cfg_file=/etc/nagios/objects/server1.cfg - The default maxadmin executable path is /usr/bin/maxadmin can be changed by -m option - default maxadmin socket (/tmp/maxadmin.sock) can be changed with -S option - maxadmin executable is no longer required to be copied in Nagios server. -- the UNIX user in ssh connection should be also admin user for MariaDB MaxScale admin. First time access or no configured users means the "root" user is the only one that can access MariaDB MaxScale admin interface via UNIX socket. +- the UNIX user in ssh connection should be also admin user for MariaDB MaxScale admin. +First time access or no configured users means the "root" user is the only one that can access +MariaDB MaxScale admin interface via UNIX socket. Test maxadmin with proper user in maxscale server and later via SSH. Those checks are strongly recommended before using Nagios scripts. -For additional information about Maxadmin and MariaDB MaxScale administrative interface please refer to [MaxAdmin Utility](../Reference/MaxAdmin.md) +For additional information about Maxadmin and MariaDB MaxScale administrative interface +please refer to [MaxAdmin Utility](../Reference/MaxAdmin.md) -This example shows configuration that needs to be done on Nagios server in order to communicate to MariaDB MaxScale server that is running on host server1. +This example shows configuration that needs to be done on Nagios server in order to +communicate to MariaDB MaxScale server that is running on host server1. In this example we are using the check_maxscale_resource as the check command ``` @@ -109,7 +107,8 @@ In this example we are using the check_maxscale_resource as the check command ``` ### Check new running monitors -* Restart Nagios and check new monitors are running in HTTP Interface "Current Status -> Services" on Nagios Server +* Restart Nagios and check new monitors are running in HTTP Interface +"Current Status -> Services" on Nagios Server * Look for any errors in /var/log/nagios/nagios.log or nagios.debug on Nagios Server # Nagios Plugin command line usage @@ -127,7 +126,8 @@ In this example we are using the check_maxscale_resource as the check command -u = username to connect to maxscale host via SSH (same user is used for maxadmin authentication) -i = identity file to use for at -m = /path/to/maxadmin - -S = UNIX socket path between maxadmin and maxscale (default is /tmp/maxadmin.sock) + -S = UNIX socket path between maxadmin and maxscale (default + is /tmp/maxadmin.sock) (2) ./check_maxscale_resources.pl -h @@ -166,7 +166,10 @@ Example for 'services' ``` #./check_maxscale_resources.pl -r resources -OK: 7 services found | services1=RW_Router;readwritesplit;1;1 services2=RW_Split;readwritesplit;1;1 services3=Test Service;readconnroute;1;1 services4=Master Service;readconnroute;2;2 services5=Debug Service;debugcli;1;1 services6=CLI;cli;2;145 services7=MaxInfo;maxinfo;2;2 +OK: 7 services found | services1=RW_Router;readwritesplit;1;1 services2=RW_Split; +readwritesplit;1;1 services3=Test Service;readconnroute;1;1 services4=Master Service; +readconnroute;2;2 services5=Debug Service;debugcli;1;1 services6=CLI;cli;2;145 +services7=MaxInfo;maxinfo;2;2 ``` Returns OK and the number of services diff --git a/Documentation/Tutorials/RabbitMQ-Setup-And-MaxScale-Integration.md b/Documentation/Tutorials/RabbitMQ-Setup-And-MaxScale-Integration.md index ffd85a4c7..0cf502fbc 100644 --- a/Documentation/Tutorials/RabbitMQ-Setup-And-MaxScale-Integration.md +++ b/Documentation/Tutorials/RabbitMQ-Setup-And-MaxScale-Integration.md @@ -1,34 +1,42 @@ # Rabbit MQ setup and MariaDB MaxScale Integration ## Introduction -A step by step guide helps installing a RabbitMQ server and testing it before MariaDB MaxScale integration. +A step by step guide helps installing a RabbitMQ server and testing it before +MariaDB MaxScale integration. -New plugin filter and a message consumer application need to be compiled and linked with an external C library, RabbitMQ-c, that provides AMQP protocol integration. +New plugin filter and a message consumer application need to be compiled and +linked with an external C library, RabbitMQ-c, that provides AMQP protocol integration. Custom configuration, with TCP/IP and Queue parameters, is also detailed here. The software install setup provides RPM and DEB packaging and traditional compilation steps. ## Step 1 - Get the RabbitMQ binaries -On Centos 6.5 using fedora / RHEL rpm get the rpm from [http://www.rabbitmq.com/](http://www.rabbitmq.com/ "RabbitMQ") +On Centos 6.5 using fedora / RHEL rpm get the rpm from +[http://www.rabbitmq.com/](http://www.rabbitmq.com/ "RabbitMQ") rabbitmq-server-3.3.4-1.noarch.rpm Please note, before installing RabbitMQ, you must install Erlang. Example: - +``` yum install erlang Package erlang-R14B-04.3.el6.x86_64 already installed and latest version +``` ## Step 2 - Install and Start the Server Install the packages using your distribution's package manager and start the server: +``` yum install rabbitmq-server-3.3.4-1.noarch.rpm systemctl start rabbitmq-server.service -To configure your RabbitMQ server, please refer to the RabbitMQ website: [http://www.rabbitmq.com/](http://www.rabbitmq.com/ RabbitMQ website). +``` +To configure your RabbitMQ server, please refer to the RabbitMQ website: +[http://www.rabbitmq.com/](http://www.rabbitmq.com/ RabbitMQ website). -rabbitmqctl is a command line tool for managing a RabbitMQ broker. It performs all actions by connecting to one of the broker's nodes. +rabbitmqctl is a command line tool for managing a RabbitMQ broker. +It performs all actions by connecting to one of the broker's nodes. ``` rabbitmqctl list_queues @@ -87,12 +95,14 @@ make make install ``` -Please note, this will install the packages to /usr. If you do not wish to install them to this location, provide a different value for the CMAKE_INSTALL_PREFIX variable. +Please note, this will install the packages to /usr. If you do not wish to install +them to this location, provide a different value for the CMAKE_INSTALL_PREFIX variable. ### Setup using the EPEL repository -Check how to configure your distribution for the EPEL repository: [https://fedoraproject.org/wiki/EPEL](https://fedoraproject.org/wiki/EPEL EPEL) +Check how to configure your distribution for the EPEL repository: +[https://fedoraproject.org/wiki/EPEL](https://fedoraproject.org/wiki/EPEL EPEL) Configure your repositories and install the software: @@ -114,7 +124,9 @@ yum install rabbitmq-server ### Basic tests with library -The required library librabbitmq-c is now installed and we continue with basic operations with amqp_* tools, located in the examples/ folder of the build directory, testing client server interaction. +The required library librabbitmq-c is now installed and we continue with basic +operations with amqp_* tools, located in the examples/ folder of the build directory, +testing client server interaction. Please note, those example applications may not be included in the RPM library packages. @@ -185,7 +197,8 @@ port=5672 logging_trigger=all ``` -Logging triggers define whether to log all or a subset of the incoming queries using these options: +Logging triggers define whether to log all or a subset of the incoming queries +using these options: ``` # log only some elements or all @@ -230,9 +243,13 @@ anything targeting my1 table is logged SELECT NOW(), SELECT MD5(“xyz)” are not logged ``` -Please note that if we want to log only the user ‘maxtest’ accessing the schema ‘test’ with target ‘my1’ the option logging_strict must be set to TRUE and if we want to include those selects without schema name the option logging_log_all must be set to TRUE. +Please note that if we want to log only the user ‘maxtest’ accessing the +schema ‘test’ with target ‘my1’ the option logging_strict must be set +to TRUE and if we want to include those selects without schema name the +option logging_log_all must be set to TRUE. -The mqfilter logs into the MariaDB MaxScale TRACE log information about the matched logging triggers and the message delivering: +The mqfilter logs into the MariaDB MaxScale TRACE log information about +the matched logging triggers and the message delivering: ``` 2014 09/03 06:22:04 Trigger is TRG_SOURCE: user: testuser = testuser @@ -288,7 +305,9 @@ and finally we can launch it: # ./consumer ``` -If the consumer.cnf file is not in the same directory as the binary file is, you can provide the location of the folder that it is in by passing it the -c flag followed by the path: +If the consumer.cnf file is not in the same directory as the binary file is, +you can provide the location of the folder that it is in by passing +it the -c flag followed by the path: ``` # ./consumer -c path/to/file @@ -298,7 +317,8 @@ and start MariaDB MaxScale as well ## Step 5 - Test the filter and check collected data -Assuming that MariaDB MaxScale and the message consumer are successfully running let’s connect to the service with an active mqfilter: +Assuming that MariaDB MaxScale and the message consumer are successfully +running let’s connect to the service with an active mqfilter: ``` [root@maxscale-02 MaxScale]# mysql -h 127.0.0.1 -P 4506 -uxxx -pyyy @@ -347,8 +367,10 @@ MariaDB [mqpairs]> select * from pairs; 7 rows in set (0.01 sec) ``` -The filter send queries to the RabbitMQ server in the canonical format, i.e select RAND(?), RAND(?). -The queries Message Queue Consumer application gets from the server are stored with a counter that quickly shows how many times that normalized query was received: +The filter send queries to the RabbitMQ server in the canonical format, +i.e select RAND(?), RAND(?). +The queries Message Queue Consumer application gets from the server +are stored with a counter that quickly shows how many times that normalized query was received: ``` | 01050106010701080109010a010b010c10d | select RAND(?), RAND(?) | Columns: 2 | 2014-09-02 11:24:37 | 2014-09-02 11:29:15 | 3 | From 09086994bf0c38a2bc647012abf751f4c0be09aa Mon Sep 17 00:00:00 2001 From: Johan Wikman Date: Thu, 20 Apr 2017 14:59:52 +0300 Subject: [PATCH 17/29] 2.1 doc johan (#126) * Update Documentation-Contents.md * Update SchemaRouter-technical.md * Update Plugin-development-guide.md * Update Replication-Proxy-Binlog-Router-Tutorial.md * Update MaxScale-HA-with-lsyncd.md * Update MaxScale-Information-Schema.md * Update Galera-Cluster-Read-Write-Splitting-Tutorial.md * Update GSSAPI-Authenticator.md --- .../Authenticators/GSSAPI-Authenticator.md | 2 +- .../Plugin-development-guide.md | 24 ++++----- .../SchemaRouter-technical.md | 2 +- Documentation/Documentation-Contents.md | 51 ++++++++++--------- ...a-Cluster-Read-Write-Splitting-Tutorial.md | 12 ++--- .../Tutorials/MaxScale-HA-with-lsyncd.md | 2 +- .../Tutorials/MaxScale-Information-Schema.md | 20 ++++---- ...eplication-Proxy-Binlog-Router-Tutorial.md | 6 +-- 8 files changed, 62 insertions(+), 57 deletions(-) diff --git a/Documentation/Authenticators/GSSAPI-Authenticator.md b/Documentation/Authenticators/GSSAPI-Authenticator.md index ead0bfa93..ce434d5b7 100644 --- a/Documentation/Authenticators/GSSAPI-Authenticator.md +++ b/Documentation/Authenticators/GSSAPI-Authenticator.md @@ -19,7 +19,7 @@ the _kadmin_ or _kadmin.local_ tools. kadmin.local -q "addprinc -nokey mariadb/example.com@EXAMPLE.COM" ``` -The _-nokey_ option will make the principal a passwordless one. This allows the +The `-nokey` option will make the principal a passwordless one. This allows the _maxscale_ user to acquire a ticket for it without a password being prompted. The next step is to export this principal into the Kerberos keytab file. diff --git a/Documentation/Design-Documents/Plugin-development-guide.md b/Documentation/Design-Documents/Plugin-development-guide.md index 3677ca3a9..1b4d74fe3 100644 --- a/Documentation/Design-Documents/Plugin-development-guide.md +++ b/Documentation/Design-Documents/Plugin-development-guide.md @@ -8,19 +8,19 @@ on, so the APIs of these two are discussed in detail. ## Table of Contents -1. [Introduction](#introduction) -* [Module categories](#module-categories) -* [Common definitions and headers](#common-definitions-and-headers) - 1. [Module information container](#module-information-container) -* [Module API](#module-api) - 1. [Overview](#overview) - * [General module management](#general-module-management) - * [Protocol](#protocol) - * [Authenticator](#authenticator) - * [Filter and Router](#filter-and-router) - * [Monitor](#monitor) +* [Introduction](#introduction) + * [Module categories](#module-categories) + * [Common definitions and headers](#common-definitions-and-headers) +* [Module information container](#module-information-container) + * [Module API](#module-api) +* [Overview](#overview) + * [General module management](#general-module-management) + * [Protocol](#protocol) + * [Authenticator](#authenticator) + * [Filter and Router](#filter-and-router) + * [Monitor](#monitor) * [Compiling, installing and running](#compiling-installing-and-running) - 1. [Hands-on example: RoundRobinRouter](#hands-on-example-roundrobinrouter) +* [Hands-on example: RoundRobinRouter](#hands-on-example-roundrobinrouter) * [Summary and conclusion](#summary-and-conclusion) ## Introduction diff --git a/Documentation/Design-Documents/SchemaRouter-technical.md b/Documentation/Design-Documents/SchemaRouter-technical.md index 6c42e9563..e9543c339 100644 --- a/Documentation/Design-Documents/SchemaRouter-technical.md +++ b/Documentation/Design-Documents/SchemaRouter-technical.md @@ -1,4 +1,4 @@ -#SchemaRouter Router - Technical Overview +# SchemaRouter Router - Technical Overview This document is designed with a developer's point-of-view in mind. It explains the lifecycle of the module and details about its internal workings. It refers to the source code which can be found at [GitHub](https://github.com/mariadb-corporation/MaxScale). diff --git a/Documentation/Documentation-Contents.md b/Documentation/Documentation-Contents.md index 9a2a8e26d..ae0abca87 100644 --- a/Documentation/Documentation-Contents.md +++ b/Documentation/Documentation-Contents.md @@ -1,12 +1,10 @@ -[Search page for MariaDB MaxScale Documentation](http://mariadb-corporation.github.io/MaxScale/Search/) - # Contents ## About MariaDB MaxScale - [About MariaDB MaxScale](About/About-MaxScale.md) - - [Release Notes](Release-Notes/MaxScale-2.1.1-Release-Notes.md) + - [Release Notes](Release-Notes/MaxScale-2.1.3-Release-Notes.md) - [Changelog](Changelog.md) - [Limitations](About/Limitations.md) @@ -23,8 +21,6 @@ ## Reference - [MaxAdmin - Admin Interface](Reference/MaxAdmin.md) - - [How Errors are Handled in MariaDB MaxScale](Reference/How-errors-are-handled-in-MaxScale.md) - - [Debug and Diagnostic Support](Reference/Debug-And-Diagnostic-Support.md) - [Routing Hints](Reference/Hint-Syntax.md) - [MaxBinlogCheck](Reference/MaxBinlogCheck.md) - [MaxScale REST API](REST-API/API.md) @@ -39,51 +35,61 @@ The main tutorial for MariaDB MaxScale consist of setting up MariaDB MaxScale fo These tutorials are for specific use cases and module combinations. - [Administration Tutorial](Tutorials/Administration-Tutorial.md) + - [Avro Router Tutorial](Tutorials/Avrorouter-Tutorial.md) - [Filter Tutorial](Tutorials/Filter-Tutorial.md) - - [MariaDB MaxScale Information Schema Tutorial](Tutorials/MaxScale-Information-Schema.md) + - [Galera Cluster Connection Routing Tutorial](Tutorials/Galera-Cluster-Connection-Routing-Tutorial.md) + - [Galera Gluster Read Write Splitting Tutorial](Tutorials/Galera-Cluster-Read-Write-Splitting-Tutorial.md) - [MySQL Cluster Setup](Tutorials/MySQL-Cluster-Setup.md) - - [Replication Proxy with the Binlog Router Tutorial](Tutorials/Replication-Proxy-Binlog-Router-Tutorial.md) - - [RabbitMQ Setup and MariaDB MaxScale Integration Tutorial](Tutorials/RabbitMQ-Setup-And-MaxScale-Integration.md) + - [MySQL Replication Connection Routing Tutorial](Tutorials/MySQL-Replication-Connection-Routing-Tutorial.md) + - [MySQL Replication Read Write Splitting Tutorial](Tutorials/MySQL-Replication-Read-Write-Splitting-Tutorial.md) + - [MariaDB MaxScale Information Schema Tutorial](Tutorials/MaxScale-Information-Schema.md) + - [Notification Service](Tutorials/Notification-Service.md) - [RabbitMQ and Tee Filter Data Archiving Tutorial](Tutorials/RabbitMQ-And-Tee-Archiving.md) + - [RabbitMQ Setup and MariaDB MaxScale Integration Tutorial](Tutorials/RabbitMQ-Setup-And-MaxScale-Integration.md) + - [Replication Proxy with the Binlog Router Tutorial](Tutorials/Replication-Proxy-Binlog-Router-Tutorial.md) - [Simple Schema Sharding Tutorial](Tutorials/Simple-Sharding-Tutorial.md) Here are tutorials on monitoring and managing MariaDB MaxScale in cluster environments. - - [Nagios Plugins for MariaDB MaxScale Tutorial](Tutorials/Nagios-Plugins.md) - [MariaDB MaxScale HA with Corosync-Pacemaker](Tutorials/MaxScale-HA-with-Corosync-Pacemaker.md) - [MariaDB MaxScale HA with Lsyncd](Tutorials/MaxScale-HA-with-lsyncd.md) - + - [Nagios Plugins for MariaDB MaxScale Tutorial](Tutorials/Nagios-Plugins.md) + ## Routers The routing module is the core of a MariaDB MaxScale service. The router documentation contains all module specific configuration options and detailed explanations of their use. - - [Read Write Split](Routers/ReadWriteSplit.md) - - [Read Connection Router](Routers/ReadConnRoute.md) - - [Schemarouter](Routers/SchemaRouter.md) - - [Binlogrouter](Routers/Binlogrouter.md) - [Avrorouter](Routers/Avrorouter.md) + - [Binlogrouter](Routers/Binlogrouter.md) + - [Read Connection Router](Routers/ReadConnRoute.md) + - [Read Write Split](Routers/ReadWriteSplit.md) + - [Schemarouter](Routers/SchemaRouter.md) There are also two diagnostic routing modules. The CLI is for MaxAdmin and the Debug CLI client for Telnet. - [CLI](Routers/CLI.md) - - [Debug CLI](Routers/Debug-CLI.md) ## Filters Here are detailed documents about the filters MariaDB MaxScale offers. They contain configuration guides and example use cases. Before reading these, you should have read the filter tutorial so that you know how they work and how to configure them. + - [Cache](Filters/Cache.md) + - [Consistent Critical Read Filter](Filters/CCRFilter.md) + - [Database Firewall Filter](Filters/Database-Firewall-Filter.md) + - [Insert Stream Filter](Filters/Insert-Stream-Filter.md) + - [Luafilter](Filters/Luafilter.md) + - [Masking Filter](Filters/Masking.md) + - [Maxrows Filter](Filters/Maxrows.md) + - [Named Server Filter](Filters/Named-Server-Filter.md) - [Query Log All](Filters/Query-Log-All-Filter.md) + - [RabbitMQ Filter](Filters/RabbitMQ-Filter.md) - [Regex Filter](Filters/Regex-Filter.md) - [Tee Filter](Filters/Tee-Filter.md) - [Top N Filter](Filters/Top-N-Filter.md) - - [Database Firewall Filter](Filters/Database-Firewall-Filter.md) - - [RabbitMQ Filter](Filters/RabbitMQ-Filter.md) - - [Named Server Filter](Filters/Named-Server-Filter.md) - - [Luafilter](Filters/Luafilter.md) - - [Insert Stream Filter](Filters/Insert-Stream-Filter.md) + - [Transaction Performance Monitoring Filter](Filters/Transaction-Performance-Monitoring-Filter.md) ## Monitors @@ -93,9 +99,10 @@ Common options for all monitor modules. Module specific documentation. - - [MySQL Monitor](Monitors/MySQL-Monitor.md) + - [Aurora Monitor](Monitors/Aurora-Monitor.md) - [Galera Monitor](Monitors/Galera-Monitor.md) - [Multi-Master Monitor](Monitors/MM-Monitor.md) + - [MySQL Monitor](Monitors/MySQL-Monitor.md) - [MySQL Cluster Monitor](Monitors/NDB-Cluster-Monitor.md) ## Protocols @@ -120,8 +127,6 @@ document. ## Design Documents - - [Core Objects Design (in development)](http://mariadb-corporation.github.io/MaxScale/Design-Documents/core-objects-html-docs) - - [Binlog Router Design (in development)](http://mariadb-corporation.github.io/MaxScale/Design-Documents/binlog-router-html-docs) - [DCB States (to be replaced in StarUML)](Design-Documents/DCB-States.pdf) - [Schema Sharding Router Technical Documentation](Design-Documents/SchemaRouter-technical.md) - [Plugin development guide](Design-Documents/Plugin-development-guide.md) diff --git a/Documentation/Tutorials/Galera-Cluster-Read-Write-Splitting-Tutorial.md b/Documentation/Tutorials/Galera-Cluster-Read-Write-Splitting-Tutorial.md index 383496b80..c4c23ffa5 100644 --- a/Documentation/Tutorials/Galera-Cluster-Read-Write-Splitting-Tutorial.md +++ b/Documentation/Tutorials/Galera-Cluster-Read-Write-Splitting-Tutorial.md @@ -12,7 +12,7 @@ Once you have MariaDB MaxScale installed and the database users created, we can ## Creating Your MariaDB MaxScale Configuration -MariaDB MaxScale configuration is held in an ini file that is located in the file maxscale.cnf in the directory /etc, if you have installed in the default location then this file is available in /etc/maxscale.cnf. This is not created as part of the installation process and must be manually created. A template file does exist within the /usr/share/maxscale directory that may be use as a basis for your configuration. +MariaDB MaxScale configuration is held in an ini file that is located in the file `maxscale.cnf` in the directory `/etc`, if you have installed in the default location then this file is available in `/etc/maxscale.cnf`. This is not created as part of the installation process and must be manually created. A template file does exist within the `/usr/share/maxscale` directory that may be use as a basis for your configuration. A global, maxscale, section is included within every MariaDB MaxScale configuration file; this is used to set the values of various MariaDB MaxScale wide parameters, perhaps the most important of these is the number of threads that MariaDB MaxScale will use to execute the code that forwards requests and handles responses for clients. @@ -71,7 +71,7 @@ type=listener service=Splitter Service ``` -A listener must also define the protocol module it will use for the incoming network protocol, currently this should be the MySQLClient protocol for all database listeners. The listener may then supply a network port to listen on and/or a socket within the file system. +A listener must also define the protocol module it will use for the incoming network protocol, currently this should be the `MySQLClient` protocol for all database listeners. The listener may then supply a network port to listen on and/or a socket within the file system. ``` [Splitter Listener] @@ -84,7 +84,7 @@ socket=/tmp/ClusterMaster An address parameter may be given if the listener is required to bind to a particular network address when using hosts with multiple network addresses. The default behavior is to listen on all network interfaces. -The next stage is the configuration is to define the server information. This defines how to connect to each of the servers within the cluster, again a section is created for each server, with the type set to server, the network address and port to connect to and the protocol to use to connect to the server. Currently the protocol module for all database connections in MySQLBackend. +The next stage is the configuration is to define the server information. This defines how to connect to each of the servers within the cluster, again a section is created for each server, with the type set to server, the network address and port to connect to and the protocol to use to connect to the server. Currently the protocol module for all database connections in `MySQLBackend`. ``` [dbserv1] @@ -119,7 +119,7 @@ passwd=96F99AA1315BDC3604B006F427DD9484 As with the password definition in the server either plain text or encrypted passwords may be used. -This monitor module will assign one node within the Galera Cluster as the current master and other nodes as slave. Only those nodes that are active members of the cluster are considered when making the choice of master node. Normally the master node will be the node with the lowest value of the status variable, WSREP_LOCAL_INDEX. When cluster membership changes a new master may be elected. In order to prevent changes of the node that is currently master, a parameter can be added to the monitor that will result in the current master remaining as master even if a node with a lower value of WSREP_LOCAL_INDEX joins the cluster. This parameter is called disable_master_failback. +This monitor module will assign one node within the Galera Cluster as the current master and other nodes as slave. Only those nodes that are active members of the cluster are considered when making the choice of master node. Normally the master node will be the node with the lowest value of the status variable, `WSREP_LOCAL_INDEX`. When cluster membership changes a new master may be elected. In order to prevent changes of the node that is currently master, a parameter can be added to the monitor that will result in the current master remaining as master even if a node with a lower value of `WSREP_LOCAL_INDEX` joins the cluster. This parameter is called `disable_master_failback`. ``` [Galera Monitor] @@ -159,7 +159,7 @@ or % service maxscale start ``` -Check the error log in /var/log/maxscale to see if any errors are detected in the configuration file and to confirm MariaDB MaxScale has been started. Also the maxadmin command may be used to confirm that MariaDB MaxScale is running and the services, listeners etc have been correctly configured. +Check the error log in `/var/log/maxscale` to see if any errors are detected in the configuration file and to confirm MariaDB MaxScale has been started. Also the maxadmin command may be used to confirm that MariaDB MaxScale is running and the services, listeners etc have been correctly configured. ``` % maxadmin list services @@ -199,4 +199,4 @@ CLI | maxscaled | localhost | 6603 | Running ---------------------+--------------------+-----------------+-------+-------- ``` -MariaDB MaxScale is now ready to start accepting client connections and routing them to the master or slaves within your cluster. Other configuration options are available that can alter the criteria used for routing, these include monitoring the replication lag within the cluster and routing only to slaves that are within a predetermined delay from the current master or using weights to obtain unequal balancing operations. These options may be found in the MariaDB MaxScale Configuration Guide. More detail on the use of maxadmin can be found in the document "MaxAdmin - The MariaDB MaxScale Administration & Monitoring Client Application". +MariaDB MaxScale is now ready to start accepting client connections and routing them to the master or slaves within your cluster. Other configuration options are available that can alter the criteria used for routing, these include monitoring the replication lag within the cluster and routing only to slaves that are within a predetermined delay from the current master or using weights to obtain unequal balancing operations. These options may be found in the MariaDB MaxScale Configuration Guide. More details on the use of maxadmin can be found in the document _MaxAdmin - The MariaDB MaxScale Administration & Monitoring Client Application_. diff --git a/Documentation/Tutorials/MaxScale-HA-with-lsyncd.md b/Documentation/Tutorials/MaxScale-HA-with-lsyncd.md index ac3f0aacf..ef78112d4 100644 --- a/Documentation/Tutorials/MaxScale-HA-with-lsyncd.md +++ b/Documentation/Tutorials/MaxScale-HA-with-lsyncd.md @@ -2,7 +2,7 @@ ***This guide was written for lsyncd 2.1.5.*** -This document guides you in setting up multiple MariaDB MaxScale instances and synchronizing the configuration files with lsyncd. Lsyncd is a rsync wrapper which can synchronize files across the network. The lsyncd daemon uses a configuration file to control the files to synchronize and the remote targets where these files are synchronized to. +This document guides you in setting up multiple MariaDB MaxScale instances and synchronizing the configuration files with _lsyncd_. Lsyncd is a _rsync_ wrapper which can synchronize files across the network. The lsyncd daemon uses a configuration file to control the files to synchronize and the remote targets where these files are synchronized to. Copying the configuration file and running the lsyncd daemon on all the hosts keeps all the configuration files in sync. Modifications in the configuration file on one of the hosts will be copied on the other hosts. This allows administrators to easily provide a highly available, disaster resistant MariaDB MaxScale installation with up-to-date configuration files on all the hosts. diff --git a/Documentation/Tutorials/MaxScale-Information-Schema.md b/Documentation/Tutorials/MaxScale-Information-Schema.md index fa1f1f13c..66d6af869 100644 --- a/Documentation/Tutorials/MaxScale-Information-Schema.md +++ b/Documentation/Tutorials/MaxScale-Information-Schema.md @@ -5,9 +5,9 @@ The plugin is capable of returning data in one of two ways, either as MySQL resu # Configuration -The plugin is configured in the maxscale.cnf plugin in much the same way as any other router service is configured, there needs to be a service section in the configuration file and also listeners defined for that service. The service does not however require any backend servers to be associated with it, or any monitors. +The plugin is configured in the `maxscale.cnf` configuration file in much the same way as any other router service is configured; there must be a service section in the configuration file and also listeners defined for that service. The service does not however require any backend servers to be associated with it, or any monitors. -The service entry needs to define the service name, the type as service and the router module to load. +The service entry should define the service name, the type as service and the router module to load. The specified user, with the password (plain or encrypted via maxpassword utility) is allowed to connect via MySQL protocol. Currently the user can connect to maxinfo from any remote IP and to localhost as well. @@ -196,7 +196,7 @@ mysql> The show services command does not accept a like clause and will ignore any like clause that is given. -## Show listeners +## Show listeners The show listeners command will return a set of status information for every listener defined within the MariaDB MaxScale configuration file. @@ -248,7 +248,7 @@ mysql> show sessions; mysql> ``` -## Show clients +## Show clients The show clients command reports a row for every client application connected to MariaDB MaxScale. Like clauses are not available of the show clients command. @@ -284,7 +284,7 @@ mysql> show servers; mysql> ``` -## Show modules +## Show modules The show modules command reports the information on the modules currently loaded into MariaDB MaxScale. This includes the name type and version of each module. It also includes the API version the module has been written against and the current release status of the module. @@ -309,7 +309,7 @@ mysql> show modules; mysql> ``` -## Show monitors +## Show monitors The show monitors command reports each monitor configured within the system and the state of that monitor. @@ -376,7 +376,7 @@ Each row represents a time interval, in 100ms increments, with the counts repres The simplified JSON interface takes the URL of the request made to maxinfo and maps that to a show command in the above section. -## Variables +## Variables The /variables URL will return the MariaDB MaxScale variables, these variables can not be filtered via this interface. @@ -460,7 +460,7 @@ $ curl http://maxscale.mariadb.com:8003/listeners $ ``` -## Modules +## Modules The /modules URI returns data for each plugin that has been loaded into MariaDB MaxScale. The plugin name, type and version are returned as is the version of the plugin API that the plugin was built against and the release status of the plugin. @@ -479,7 +479,7 @@ $ curl http://maxscale.mariadb.com:8003/modules $ ``` -## Sessions +## Sessions The /sessions URI returns a JSON array with an object for each active session within MariaDB MaxScale. @@ -511,7 +511,7 @@ $ curl http://maxscale.mariadb.com:8003/clients $ ``` -## Servers +## Servers The /servers URI is used to retrieve information for each of the servers defined within the MariaDB MaxScale configuration. This information includes the connection count and the current status as monitored by MariaDB MaxScale. The connection count is only those connections made by MariaDB MaxScale to those servers. diff --git a/Documentation/Tutorials/Replication-Proxy-Binlog-Router-Tutorial.md b/Documentation/Tutorials/Replication-Proxy-Binlog-Router-Tutorial.md index 381b69a57..2d68f96ff 100644 --- a/Documentation/Tutorials/Replication-Proxy-Binlog-Router-Tutorial.md +++ b/Documentation/Tutorials/Replication-Proxy-Binlog-Router-Tutorial.md @@ -1,9 +1,9 @@ # MariaDB MaxScale as a Binlog Server -MariaDB MaxScale is a dynamic data routing platform that sits between a database layer and the clients of that database, the binlog router described here is somewhat different to that original concept, moving MariaDB MaxScale down to play a role within the database layer itself. +MariaDB MaxScale is a dynamic data routing platform that sits between a database layer and the clients of that database. However, the binlog router described here is somewhat different to that original concept, moving MariaDB MaxScale down to play a role within the database layer itself. -In a traditional MySQL replication setup a single master server is created and a set of slaves MySQL instances are configured to pull the binlog files from that master to the slaves. There are some problems, however, in this setup; when the number of slaves grows an increasing load is placed on the master, to serve the binlogs to each slave. When the master server fails, some action must be performed on every slave server before a new server can become the master server. +In a traditional MySQL replication setup a single master server is created and a set of slaves MySQL instances are configured to pull the binlog files from that master to the slaves. There are some problems, however, in this setup; when the number of slaves grows, an increasing load caused by the serving of binlogs to each slave, is placed on the master. When the master server fails, some action must be performed on every slave server before a new server can become the master server. -Introducing a proxy layer between the master server and the slave servers can improve the situation, by reducing the load on the master to simply serving the proxy layer rather than all of the slaves. The slaves only need to be aware of the proxy layer and not of the real master server. Removing need for the slaves to have knowledge of the master, greatly simplifies the process of replacing a failed master within a replication environment. +Introducing a proxy layer between the master server and the slave servers can improve the situation, by reducing the load on the master to simply serving the proxy layer rather than all of the slaves. The slaves only need to be aware of the proxy layer and not of the real master server. Removing the need for the slaves to have knowledge of the actual master, greatly simplifies the process of replacing a failed master within a replication environment. ## MariaDB/MySQL as a Binlog Server The most obvious solution to the requirement for a proxy layer within a replication environment is to use a MariaDB or MySQL database instance. The database server is designed to allow this, since a slave server is able to be configured such that it will produce binary logs for updates it has itself received via replication from the master server. This is done with the *log_slave_updates* configuration option of the server. In this case the server is known as an intermediate master, it is simultaneously a slave to the real master and a master to the other slaves in the configuration. From 0f7b29f8bf73aed78b9a0e05b6bfdb95f92c9768 Mon Sep 17 00:00:00 2001 From: Johan Wikman Date: Thu, 20 Apr 2017 14:58:52 +0300 Subject: [PATCH 18/29] Add 2.1.3 release notes --- .../MaxScale-2.1.3-Release-Notes.md | 62 +++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 Documentation/Release-Notes/MaxScale-2.1.3-Release-Notes.md diff --git a/Documentation/Release-Notes/MaxScale-2.1.3-Release-Notes.md b/Documentation/Release-Notes/MaxScale-2.1.3-Release-Notes.md new file mode 100644 index 000000000..89b2af04c --- /dev/null +++ b/Documentation/Release-Notes/MaxScale-2.1.3-Release-Notes.md @@ -0,0 +1,62 @@ +# MariaDB MaxScale 2.1.3 Release Notes + +Release 2.1.3 is a GA release. + +This document describes the changes in release 2.1.3, when compared to +release [2.1.2](MaxScale-2.1.2-Release-Notes.md). + +If you are upgrading from release 2.0, please also read the following +release notes: +[2.1.2](./MaxScale-2.1.2-Release-Notes.md) +[2.1.1](./MaxScale-2.1.1-Release-Notes.md) +[2.1.0](./MaxScale-2.1.0-Release-Notes.md) + +For any problems you encounter, please consider submitting a bug +report at [Jira](https://jira.mariadb.org). + +## Changed Features + +### Cache + +* The storage `storage_rocksdb` is no longer built by default and is + not included in the MariaDB MaxScale package. + +### Maxrows + +* It can now be specified whether the _maxrows_ filter should return an + empty resultset, an error packet or an ok packet, when the limit has + been reached. + + Please refer to the + [maxrows documentation](../Filters/Maxrows.md) + for details. + +## Bug fixes + +[Here is a list of bugs fixed since the release of MaxScale 2.1.2.](https://jira.mariadb.org/browse/MXS-1212?jql=project%20%3D%20MXS%20AND%20issuetype%20%3D%20Bug%20AND%20resolution%20in%20(Fixed%2C%20Done)%20AND%20fixVersion%20%3D%202.1.3) + +* [MXS-1227](https://jira.mariadb.org/browse/MXS-1227) Nagios Plugins broken by change in output of "show monitors" in 2.1 +* [MXS-1221](https://jira.mariadb.org/browse/MXS-1221) Nagios plugin scripts does not process -S option properly +* [MXS-1212](https://jira.mariadb.org/browse/MXS-1212) Excessive execution time when maxrows limit has been reached +* [MXS-1202](https://jira.mariadb.org/browse/MXS-1202) maxadmin "show service" counters overflow +* [MXS-1200](https://jira.mariadb.org/browse/MXS-1200) config file lines limited to ~1024 chars + +## Known Issues and Limitations + +There are some limitations and known issues within this version of MaxScale. +For more information, please refer to the [Limitations](../About/Limitations.md) document. + +## Packaging + +RPM and Debian packages are provided for the Linux distributions supported +by MariaDB Enterprise. + +Packages can be downloaded [here](https://mariadb.com/resources/downloads). + +## Source Code + +The source code of MaxScale is tagged at GitHub with a tag, which is identical +with the version of MaxScale. For instance, the tag of version X.Y.Z of MaxScale +is X.Y.Z. Further, *master* always refers to the latest released non-beta version. + +The source code is available [here](https://github.com/mariadb-corporation/MaxScale). From 008d86f99aabe4448050a7d857c261338526003d Mon Sep 17 00:00:00 2001 From: Johan Wikman Date: Thu, 20 Apr 2017 15:02:12 +0300 Subject: [PATCH 19/29] Update 2.1 Change Log --- Documentation/Changelog.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/Changelog.md b/Documentation/Changelog.md index 941c717c1..5aeeb1639 100644 --- a/Documentation/Changelog.md +++ b/Documentation/Changelog.md @@ -1,4 +1,4 @@ -#Changelog +# Changelog ## MariaDB MaxScale 2.1 * MariaDB MaxScale is licensed under MariaDB BSL 1.1. @@ -21,6 +21,7 @@ * MaxScale now supports IPv6 For more details, please refer to: +* [MariaDB MaxScale 2.1.3 Release Notes](Release-Notes/MaxScale-2.1.3-Release-Notes.md) * [MariaDB MaxScale 2.1.2 Release Notes](Release-Notes/MaxScale-2.1.2-Release-Notes.md) * [MariaDB MaxScale 2.1.1 Release Notes](Release-Notes/MaxScale-2.1.1-Release-Notes.md) * [MariaDB MaxScale 2.1.0 Release Notes](Release-Notes/MaxScale-2.1.0-Release-Notes.md) From 73c38230fee5ea64f233238cb08fa17acdff46e8 Mon Sep 17 00:00:00 2001 From: Johan Wikman Date: Thu, 20 Apr 2017 15:53:29 +0300 Subject: [PATCH 20/29] Update README.md --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 65a6eb736..07520f6c7 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,7 @@ For information about installing and using MaxScale, please refer to the documentation. The official documentation can be found on the [MariaDB Knowledge Base](https://mariadb.com/kb/en/mariadb-enterprise/maxscale/). +- [MariaDB MaxScale 2.1 Documentation](https://mariadb.com/kb/en/mariadb-enterprise/6308/) - [MariaDB MaxScale 2.0 Documentation](https://mariadb.com/kb/en/mariadb-enterprise/mariadb-maxscale-20-contents/) - [MariaDB MaxScale 1.4 Documentation](https://mariadb.com/kb/en/mariadb-enterprise/mariadb-maxscale-14/maxscale-maxscale-contents/) From e8dfccb4c8484b3182a78187dabef4c9dbddede1 Mon Sep 17 00:00:00 2001 From: Esa Korhonen Date: Fri, 21 Apr 2017 10:49:20 +0300 Subject: [PATCH 21/29] 2.1 doc esak (#127) * Update MySQL-Replication-Read-Write-Splitting-Tutorial.md * Update MySQL-Replication-Read-Write-Splitting-Tutorial.md * Update MySQL-Replication-Read-Write-Splitting-Tutorial.md * Update MySQL-Cluster-Setup.md * Update Administration-Tutorial.md * Update Administration-Tutorial.md * Update Galera-Cluster-Connection-Routing-Tutorial.md * Update CLI.md * Update ReadWriteSplit.md * Update Tee-Filter.md * Update CCRFilter.md * Update RabbitMQ-Filter.md * Update Debug-And-Diagnostic-Support.md * Update MaxBinlogCheck.md * Update Configuration-Guide.md * Update Module-Commands.md --- Documentation/Filters/CCRFilter.md | 2 +- Documentation/Filters/RabbitMQ-Filter.md | 5 +- Documentation/Filters/Tee-Filter.md | 10 +- .../Getting-Started/Configuration-Guide.md | 41 ++++---- .../Reference/Debug-And-Diagnostic-Support.md | 8 +- Documentation/Reference/MaxBinlogCheck.md | 35 +++---- Documentation/Reference/Module-Commands.md | 5 +- Documentation/Routers/CLI.md | 7 +- Documentation/Routers/ReadWriteSplit.md | 26 +++--- .../Tutorials/Administration-Tutorial.md | 64 +++++++------ .../Tutorials/MySQL-Cluster-Setup.md | 93 ++++++++++--------- ...plication-Read-Write-Splitting-Tutorial.md | 35 +++---- 12 files changed, 166 insertions(+), 165 deletions(-) diff --git a/Documentation/Filters/CCRFilter.md b/Documentation/Filters/CCRFilter.md index baad24144..b900ec2f7 100644 --- a/Documentation/Filters/CCRFilter.md +++ b/Documentation/Filters/CCRFilter.md @@ -10,7 +10,7 @@ done through MaxScale while still allowing scaleout of non-critical reads. When the filter detects a statement that would modify the database, it attaches a routing hint to all following statements. This routing hint guides the routing module to route the statement to the master server where data is guaranteed to be -in a up-to-date state. +in an up-to-date state. ## Filter Options diff --git a/Documentation/Filters/RabbitMQ-Filter.md b/Documentation/Filters/RabbitMQ-Filter.md index 35fb285d6..83f5da6a7 100644 --- a/Documentation/Filters/RabbitMQ-Filter.md +++ b/Documentation/Filters/RabbitMQ-Filter.md @@ -1,7 +1,8 @@ -#RabbitMQ Filter +# RabbitMQ Filter ## Overview -This filter is designed to extract queries and transform them into a canonical form e.g. `INSERT INTO database.table VALUES ("John Doe", "Downtown",100,50.0);` turns into `INSERT INTO database.table VALUES ("?", "?",?,?);`. The filter pushes these canonicalized queries and their replies in to a RabbitMQ broker where they can later be retrieved. The retrieval can be done with your own application or the [RabbitMQ Consumer Client](RabbitMQ-Consumer-Client.md) utility tool, which reads the messages from the broker and sends the contents of those messages as SQL queries to a database. + +This filter is designed to extract queries and transform them into a canonical form e.g. `INSERT INTO database.table VALUES ("John Doe", "Downtown",100,50.0);` turns into `INSERT INTO database.table VALUES ("?", "?",?,?);`. The filter pushes these canonized queries and their replies into a RabbitMQ broker where they can later be retrieved from. The retrieval can be done with a custom application or the [RabbitMQ Consumer Client](RabbitMQ-Consumer-Client.md) utility tool, which reads the messages from the broker and sends the contents of those messages as SQL queries to a database. ## Configuration diff --git a/Documentation/Filters/Tee-Filter.md b/Documentation/Filters/Tee-Filter.md index 29f35c2b6..c0a1e3d47 100644 --- a/Documentation/Filters/Tee-Filter.md +++ b/Documentation/Filters/Tee-Filter.md @@ -2,7 +2,7 @@ ## Overview -The tee filter is a filter module for MariaDB MaxScale is a "plumbing" fitting in the MariaDB MaxScale filter toolkit. It can be used in a filter pipeline of a service to make a copy of requests from the client and dispatch a copy of the request to another service within MariaDB MaxScale. +The tee filter is a "plumbing" fitting in the MariaDB MaxScale filter toolkit. It can be used in a filter pipeline of a service to make copies of requests from the client and send the copies to another service within MariaDB MaxScale. ## Configuration @@ -45,7 +45,7 @@ The tee filter requires a mandatory parameter to define the service to replicate ### Match -An optional parameter that can be used to limit the queries that will be replicated by the tee filter. The parameter value is a regular expression that is used to match against the SQL text. Only SQL statements that matches the text passed as the value of this parameter will be sent to the service defined in the filter section. +An optional parameter used to limit the queries that will be replicated by the tee filter. The parameter value is a regular expression that is used to match against the SQL text. Only SQL statements that matches the text passed as the value of this parameter will be sent to the service defined in the filter section. ``` match=insert.*into.*order* @@ -55,7 +55,7 @@ All regular expressions are evaluated with the option to ignore the case of the ### Exclude -An optional parameter that can be used to limit the queries that will be replicated by the tee filter. The parameter value is a regular expression that is used to match against the SQL text. SQL statements that match the text passed as the value of this parameter will be excluded from the replication stream. +An optional parameter used to limit the queries that will be replicated by the tee filter. The parameter value is a regular expression that is used to match against the SQL text. SQL statements that match the text passed as the value of this parameter will be excluded from the replication stream. ``` exclude=select @@ -83,9 +83,9 @@ user=john ### Example 1 - Replicate all inserts into the orders table -Assume an order processing system that has a table called orders. You also have another database server, the datamart server, that requires all inserts into orders to be replicated to it. Deletes and updates are not however required. +Assume an order processing system that has a table called orders. You also have another database server, the datamart server, that requires all inserts into orders to be replicated to it. Deletes and updates are not, however, required. -Set up a service in MariaDB MaxScale, called Orders, to communicate with the order processing system with the tee filter applied to it. Also set up a service to talk the datamart server, using the DataMart service. The tee filter would have as it’s service entry the DataMart service, by adding a match parameter of "insert into orders" would then result in all requests being sent to the order processing system, and insert statements that include the orders table being additionally sent to the datamart server. +Set up a service in MariaDB MaxScale, called Orders, to communicate with the order processing system with the tee filter applied to it. Also set up a service to talk to the datamart server, using the DataMart service. The tee filter would have as it’s service entry the DataMart service, by adding a match parameter of "insert into orders" would then result in all requests being sent to the order processing system, and insert statements that include the orders table being additionally sent to the datamart server. ``` [Orders] diff --git a/Documentation/Getting-Started/Configuration-Guide.md b/Documentation/Getting-Started/Configuration-Guide.md index 2f8613dbe..ec3eefd51 100644 --- a/Documentation/Getting-Started/Configuration-Guide.md +++ b/Documentation/Getting-Started/Configuration-Guide.md @@ -2,11 +2,11 @@ ## 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 +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 MariaDB MaxScale itself. +the behavior of the program. # Table of Contents @@ -25,23 +25,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 @@ -134,7 +133,7 @@ used for systems dedicated for running MariaDB MaxScale. threads=1 ``` -It should be noted that additional threads will be created to execute other +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. @@ -346,7 +345,7 @@ 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 +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 diff --git a/Documentation/Reference/Debug-And-Diagnostic-Support.md b/Documentation/Reference/Debug-And-Diagnostic-Support.md index cec11bd33..a9e1557f4 100644 --- a/Documentation/Reference/Debug-And-Diagnostic-Support.md +++ b/Documentation/Reference/Debug-And-Diagnostic-Support.md @@ -1,10 +1,4 @@ -MariaDB MaxScale - -Debug & Diagnostic Support - -Mark Riddoch - -Last Updated: 24th November 2014 +# MariaDB MaxScale Debug & Diagnostic Support [[TOC]] diff --git a/Documentation/Reference/MaxBinlogCheck.md b/Documentation/Reference/MaxBinlogCheck.md index 9210f379a..3041cd79a 100644 --- a/Documentation/Reference/MaxBinlogCheck.md +++ b/Documentation/Reference/MaxBinlogCheck.md @@ -1,24 +1,16 @@ -# Maxbinlogcheck - -# The MySQL/MariaDB binlog check utility - -Massimiliano Pinto - -Last Updated: 07th December 2016 +# Maxbinlogcheck, the MySQL/MariaDB binlog check utility # Overview -Maxbinlogcheck is a command line utility for checking binlogfiles downloaded by MariaDB MaxScale binlog router or the MySQL/MariaDB binlog files stored in a database server acting as a master in a replication environment. -It checks the binlog file against any corruption and incomplete transaction stored and reports a transaction summary after reading all the events. -It may optionally truncate binlog file. +Maxbinlogcheck is a command line utility for checking binlogfiles. The files may have been downloaded by the MariaDB MaxScale binlog router or they may be MySQL/MariaDB binlog files stored in a database server acting as a master in a replication environment. Maxbinlogcheck checks the binlog files against any corruption and stored incomplete transactions and reports a transaction summary after reading all the events. It may optionally truncate the binlog file. -Maxbinlogcheck supports +Maxbinlogcheck supports: * MariaDB 5.5 and MySQL 5.6 - * MariaDB 10.0 and 10.1 with a command line option # Running maxbinlogcheck + ``` # /usr/local/bin/maxbinlogcheck /path_to_file/bin.000002 ``` @@ -36,27 +28,27 @@ The maxbinlogcheck command accepts a number of switches -f --fix - If the option is set the binlog file will be truncated at last safe transaction pos in case of any error + If set the binlog file will be truncated at last safe transaction pos in case of any error -M --mariadb10 - Check the current binlog against MariaDB 10.0.x events + Checks the current binlog against MariaDB 10.0.x events -d --debug - Set the debug mode. If set the FD Events, Rotate events and opening/closing transactions are displayed. + Sets the debug mode. If set the FD Events, Rotate events and opening/closing transactions are displayed. -? --help - Print usage information regarding maxbinlogcheck + Prints usage information regarding maxbinlogcheck -V --version - Print the maxbinlogcheck version information + Prints the maxbinlogcheck version information -K @@ -71,7 +63,7 @@ The maxbinlogcheck command accepts a number of switches -H --header - Print the binlog event header + Prints the binlog event header @@ -183,7 +175,7 @@ This file is corrupted, as reported by the utility: 2015-09-08 10:03:16 Check retcode: 1, Binlog Pos = 245 ``` -The suggested safe pos is 245 +The suggested safe pos is 245. Use -f option for fix with debug: @@ -281,8 +273,9 @@ And finally big transaction is now done. 2015-09-08 10:17:16 Check retcode: 0, Binlog Pos = 590760698 ``` -**Note** -with current maxbinlogcheck it's not possible to fix a binlog with incomplete transaction and no other errors +**Note** + +With current maxbinlogcheck it's not possible to fix a binlog with incomplete transaction and no other errors If that is really desired it will be possible with UNIX command line: diff --git a/Documentation/Reference/Module-Commands.md b/Documentation/Reference/Module-Commands.md index 624ad0af8..2fffa4b33 100644 --- a/Documentation/Reference/Module-Commands.md +++ b/Documentation/Reference/Module-Commands.md @@ -53,9 +53,8 @@ int main(int argc, char **argv) } ``` -The array of _modulecmd_arg_type_t_ type is used to tell what kinds of arguments -the command expects. The first argument is a SERVER which will be replaced with a -pointer to a server. The second argument is an optional string argument. +The array _my_args_ of type _modulecmd_arg_type_t_ is used to tell what kinds of arguments +the command expects. The first argument is a boolean and the second argument is an optional string. Arguments are passed to the parsing function as an array of void pointers. They are interpreted as the types the command expects. diff --git a/Documentation/Routers/CLI.md b/Documentation/Routers/CLI.md index 5d088e1fd..706e2b4b7 100644 --- a/Documentation/Routers/CLI.md +++ b/Documentation/Routers/CLI.md @@ -5,7 +5,7 @@ of the `maxscaled` protocol. ## Configuration -Two components are required in order to run the command line interface for use with +Two components are required to run the command line interface for _maxadmin_; a service and a listener. The listener may either use a Unix domain socket or an internet socket. @@ -31,6 +31,7 @@ protocol=maxscaled address=localhost port=6603 ``` + In the example above, two listeners have been specified; one that listens on the default Unix domain socket and one that listens on the default port. In the latter case, if the `address=` entry is removed, connections are allowed from any machine @@ -38,9 +39,9 @@ on your network. In the former case, if the value of `socket` is changed and in the latter case, if the value of `port` is changed, _maxadmin_ must be invoked with the `-S` and -`-P` options respectively. +`-P` options, respectively. -Note that if Unix domain sockets are used, the connection is secure, but _maxadmin_ +If Unix domain sockets are used, the connection is secure, but _maxadmin_ can only be used on the same host where MariaDB MaxScale runs. If internet sockets are used, the connection is _inherently insecure_ but _maxadmin_ can be used from another host than the one where MariaDB MaxScale runs. diff --git a/Documentation/Routers/ReadWriteSplit.md b/Documentation/Routers/ReadWriteSplit.md index 49608eee2..4fe082241 100644 --- a/Documentation/Routers/ReadWriteSplit.md +++ b/Documentation/Routers/ReadWriteSplit.md @@ -1,6 +1,6 @@ # Readwritesplit -This document provides a short overview of the **readwritesplit** router module and its intended use case scenarios. It also displays all router configuration parameters with their descriptions. A list of current limitations of the module is included and examples of the router's use are provided. +This document provides a short overview of the **readwritesplit** router module and its intended use case scenarios. It also displays all router configuration parameters with their descriptions. A list of current limitations of the module is included and use examples are provided. ## Overview @@ -10,7 +10,7 @@ The router is designed to be used with a traditional Master-Slave replication cl ## Configuration -Readwritesplit router-specific settings are specified in the configuration file of MariaDB MaxScale in its specific section. The section can be freely named but the name is used later as a reference from listener section. +Readwritesplit router-specific settings are specified in the configuration file of MariaDB MaxScale in its specific section. The section can be freely named but the name is used later as a reference in a listener section. For more details about the standard service parameters, refer to the [Configuration Guide](../Getting-Started/Configuration-Guide.md). @@ -23,18 +23,16 @@ For more details about the standard service parameters, refer to the [Configurat max_slave_connections= ### `max_slave_replication_lag` -**`max_slave_replication_lag`** specifies how many seconds a slave is allowed to be behind the master. If the lag is bigger than configured value a slave can't be used for routing. + +**`max_slave_replication_lag`** specifies how many seconds a slave is allowed to be behind the master. If the lag is bigger than the configured value a slave can't be used for routing. This feature is disabled by default. max_slave_replication_lag= -This applies to Master/Slave replication with MySQL monitor and `detect_replication_lag=1` options set. -Please note max_slave_replication_lag must be greater than monitor interval. - -This option only affects Master-Slave clusters. Galera clusters do not have a -concept of slave lag even if the application of write sets might have lag. +This applies to Master/Slave replication with MySQL monitor and `detect_replication_lag=1` options set. max_slave_replication_lag must be greater than the monitor interval. +This option only affects Master-Slave clusters. Galera clusters do not have a concept of slave lag even if the application of write sets might have lag. ### `use_sql_variables_in` @@ -44,11 +42,11 @@ concept of slave lag even if the application of write sets might have lag. The default is to use SQL variables in all servers. -When value all is used, queries reading session variables can be routed to any available slave (depending on selection criteria). Note, that queries modifying session variables are routed to all backend servers by default, excluding write queries with embedded session variable modifications, such as: +When value `all` is used, queries reading session variables can be routed to any available slave (depending on selection criteria). Queries modifying session variables are routed to all backend servers by default, excluding write queries with embedded session variable modifications, such as: INSERT INTO test.t1 VALUES (@myid:=@myid+1) -In above-mentioned case the user-defined variable would only be updated in the master where query would be routed due to `INSERT` statement. +In above-mentioned case the user-defined variable would only be updated in the master where the query would be routed to due to the `INSERT` statement. **Note:** As of version 2.1 of MaxScale, all of the router options can also be defined as parameters. The values defined in _router_options_ will have priority @@ -74,7 +72,9 @@ Multiple options can be defined as a comma-separated list of parameter-value pai ``` router_options=