diff --git a/About/Limitations.md b/About/Limitations.md new file mode 100644 index 000000000..db6c92f09 --- /dev/null +++ b/About/Limitations.md @@ -0,0 +1,104 @@ +# Limitations and Known Issues within MaxScale + +The purpose of this documentation is to provide a central location that will document known issues and limitations within the MaxScale product and the plugins that form part of that product. Since limitations may related to specific plugins or to MaxScale as a whole this document is divided into a number of sections, the purpose of which are to isolate the limitations to the components which illustrate them. + +## Limitations in the MaxScale core + +This section describes the limitations that are common to all configuration of plugins with MaxScale. + +## Limitations with MySQL Protocol support + +* Compression + +* SSL + +Both capabilities are not included in MySQL server handshake + +* LOAD DATA LOCAL INFILE currently not supported + +## Limitations with MySQL Master/Slave Replication monitoring + +## Limitations with Galera Cluster Monitoring + +Master selection is based only on MIN(wsrep_local_index), no other server parameter. + +## Limitations in the connection router + + If Master changes (ie. new Master promotion) during current connection the router cannot check the change + +## Limitations in the Read/Write Splitter + +### Scale-out limitations + +In master-slave replication cluster also read-only queries are routed to master too in the following situations: + +* if they are executed inside an open transaction + +* in case of prepared statement execution + +* statement includes a stored procedure, or an UDF call + +### Limitations in client session handling + +Some of the queries that client sends are routed to all backends instead of sending them just to one of server. These queries include "USE " and “SET autocommit=0” among many others. Read/Write Splitter sends a copy of these queries to each backend server and forwards the first reply it receives to the client. Below is a list of MySQL commands which we call session commands : + +COM_INIT_DB (USE creates this) + +COM_CHANGE_USER + +COM_STMT_CLOSE + +COM_STMT_SEND_LONG_DATA + +COM_STMT_RESET + +COM_STMT_PREPARE + +Also these are session commands: + +COM_QUIT (no response) + +COM_REFRESH + +COM_DEBUG + +COM_PING + +In addition there are query types which belong to the same group: + +SQLCOM_CHANGE_DB + +SQLCOM_DEALLOCATE_PREPARE + +SQLCOM_PREPARE + +SQLCOM_SET_OPTION + +SELECT ..INTO variable|OUTFILE|DUMPFILE + +Then there are queries which modify session characteristics, listed as derived, internal RWSplit types: + + QUERY_TYPE_ENABLE_AUTOCOMMIT + + QUERY_TYPE_DISABLE_AUTOCOMMIT + +There is a possibility for misbehavior; if "USE mytable" was executed in one of the slaves and it failed, it may be due to replication lag rather than the fact it didn’t exist. Thus the same command may end up with different result among backend servers. This disparity is missed. + +The above-mentioned behavior can be partially controller with RWSplit configuration parameter called + +use_sql_variables_in=[master|all] (master) + +Server-side session variables are called as SQL variables. If "master" or no value is set, SQL variables are read and written in master only. Autocommit values and prepared statements are routed to all nodes always. + +NOTE: If variable is written as a part of write query, it is treated like write query and not routed to all servers. For example, INSERT INTO test.t1 VALUES (@myvar:= 7) . + +Examples: + +If new database "db" was created and client executes “USE db” and it is routed to slave before the CREATE DATABASE clause is replicated to all slaves there is a risk of executing query in wrong database. Similarly, if any response that RWSplit sends back to the client differ from that of the master, there is a risk for misbehavior. + +Most imaginable reasons are related to replication lag but it could be possible that a slave fails to execute something because of some non-fatal, temporary failure while execution of same command succeeds in other backends. + +## Authentication Related Limitations + +MySQL old passwords are not supported + diff --git a/About/MaxScale-1.0.4-Release-Notes.md b/About/MaxScale-1.0.4-Release-Notes.md new file mode 100644 index 000000000..bb473ea1c --- /dev/null +++ b/About/MaxScale-1.0.4-Release-Notes.md @@ -0,0 +1,140 @@ +MaxScale Release Notes + +1.0.4 GA + +This document details the changes in version 1.0.4 since the release of the 1.0.2 Release Candidate of the MaxScale product. + +# New Features + +No new features have been introduced since the released candidate was released. + +# Bug Fixes + +A number of bug fixes have been applied between the 0.6 alpha and this alpha release. The table below lists the bugs that have been resolved. The details for each of these may be found in bugs.mariadb.com. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IDSummary
644Buffered that were cloned using the gwbuf_clone routine failed to initialise the buffer lock structure correctly.
643Recursive filter definitions in the configuration file could cause MaxScale to loop
665An access to memory that had already been freed could be made within the MaxScale core
664MySQL Authentication code could access memory that had already been freed.
673MaxScale could crash if it had an empty user table and the MaxAdmin show dbusers command was run
670The tee filter could lose statement on the branch service if the branch service was significantly slower at executing statements compared with the main service.
653Memory corruption could occur with extremely long hostnames in the mysql.user table.
657If the branch service of a tee filter shutdown unexpectedly then MaxScale could fail
654Missing quotes in MaxAdmin show dbusers command could cause MaxAdmin to crash
677A race condition existed in the tee filter client reply handling
658The readconnroute router did not correctly close sessions when a backend database failed
662MaxScale startup hangs if no backend servers respond
676MaxScale writes a log entry, "Write to backend failed. Session closed." when changing default database via readwritesplit with max_slave_connections != 100%
650Tee filter does not correctly detect missing branch service
645Tee filter can hang MaxScale if the read/write splitter is used
678Tee filter does not always send full query to branch service
679A shared pointer in the service was leading to misleading service states
680The Read/Write Splitter can not load users if there are no databases available at startup
681The Read/Write Splitter could crash is the value of max_slave_connections was set to a low percentage and only a small number of backend servers are available
+ + +# Known Issues + +There are a number bugs and known limitations within this version of MaxScale, the most serious of this are listed below. + +* The SQL construct "LOAD DATA LOCAL INFILE" is not fully supported. + +* The Read/Write Splitter is a little too strict when it receives errors from slave servers during execution of session commands. This can result in sessions being terminated in situation in which MaxScale could recover without terminating the sessions. + +* MaxScale can not manage authentication that uses wildcard matching in hostnames in the mysql.user table of the backend database. The only wildcards that can be used are in IP address entries. + +* When users have different passwords based on the host from which they connect MaxScale is unable to determine which password it should use to connect to the backend database. This results in failed connections and unusable usernames in MaxScale. + +# Packaging + +Both RPM and Debian packages are available for MaxScale in addition to the tar based releases previously distributed we now provide + +* CentOS/RedHat 5 + +* CentOS/RedHat 6 + +* CentOS/RedHat 7 + +* Debian 6 + +* Debian 7 + +* Ubuntu 12.04 LTS + +* Ubuntu 13.10 + +* Ubuntu 14.04 LTS + +* Fedora 19 + +* Fedora 20 + +* OpenSuSE 13 + +# MaxScale Home Default Value + +The installation assumes that the default value for the environment variable MAXSCALE_HOME is set to /usr/local/skysql/maxscale. This is hard coded in the service startup file that is placed in /etc/init.d/maxscale by the installation process. + diff --git a/Documentation-Contents.md b/Documentation-Contents.md index 72d598914..34fb6a1af 100644 --- a/Documentation-Contents.md +++ b/Documentation-Contents.md @@ -1,8 +1,30 @@ # Contents +## About MaxScale + + - [Release Notes 1.0.4](About/MaxScale-1.0.4-Release-Notes.md) + - [Limitations](About/Limitations.md) + ## Getting Started - [Getting Started with MaxScale](Getting-Started/Getting-Started-With-MaxScale.md) + - [Configuration Guide](Getting-Started/Configuration-Guide.md) + +## Reference + + - [MaxAdmin](Reference/MaxAdmin.md) + - [MaxScale HA with Corosync-Pacemaker](Reference/MaxScale-HA-with-Corosync-Pacemaker.md) + - [How Errors are Handled in MaxScale](Reference/How-errors-are-handled-in-MaxScale.md) + - [Debug and Diagnostic Support](Reference/Debug-And-Diagnostic-Support.md) + +## Tutorials + + - [Administration Tutorial](Tutorials/Administration-Tutorial.md) + - [Filter Tutorial](Tutorials/Filter-Tutorial.md) + - [Galera Cluster Connection Routing Tutorial](Tutorials/Galera-Cluster-Connection-Routing-Tutorial.md) + - [Galera Cluster Read-Write Splitting Tutorial](Tutorials/Galera-Cluster-Read-Write-Splitting-Tutorial.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) ## Filters diff --git a/Getting-Started/Configuration-Guide.md b/Getting-Started/Configuration-Guide.md new file mode 100644 index 000000000..5a7c94890 --- /dev/null +++ b/Getting-Started/Configuration-Guide.md @@ -0,0 +1,1575 @@ +MaxScale + +Configuration & Usage Scenarios + +Mark Riddoch + +Last Updated: 29th November 2014 + +# Contents + +[[TOC]] + +# Document History + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
DateChangeWho
21st July 2013Initial versionMark Riddoch
23rd July 2013Addition of default user and password for a monitor and discussion of monitor user requirements +New monitor documented for Galera clusters +Addition of example Galera cluster configurationMark Riddoch
13th November 2013state for Galera Monitor is "synced"Massimiliano Pinto
2nd December 2013Updated the description of the command line arguments to match the code updates. +Improved descriptions and general documentation. +Enhanced example configurationsMark Riddoch
6th February 2014Added “enable_root_user” as a service parameterMassimiliano Pinto
7th February 2014Addition of bind address information +Clarification of user configuration required for monitoring users and the user needed to fetch the user dataMark Riddoch
3rd March 2014MySQL authentication with hostnamesMassimiliano Pinto
3rd March 2014Addition of section that describes authentication requirements and the rules for creating user credentialsMark Riddoch
28th March 2014Unix socket supportMassimiliano Pinto
8th May 2014Added “version_string” parameter in serviceMassimiliano Pinto
29th May 2014Added troubleshooting sectionMassimiliano Pinto
2nd June 2014Correction of some typos, clarification of the meaning of session modification statements and the default user for the CLI. +Addition of debugcli configuration option for developer and user modes.Mark Riddoch
4th June 2014Addition of “monitor_interval” for monitorsMassimiliano Pinto
6th June 2014Addition of filters sectionsMark Riddoch
27th June 2014Addition of server weighting, the configuration for the maxadmin clientMark Riddoch
2nd July 2014Addition of new readwritesplit router options with description and examples.Vilho Raatikka
28th August 2014Addition of “detect_stale_master” option for MySQL monitorMassimiliano Pinto
26th September 2014Addition of ‘localhost_match_wildcard_host’ service optionMassimiliano Pinto
24th October 2014Addition of “disable_master_failback” option for Galera monitorMassimiliano Pinto
4th November 2014Addition of timeouts for all monitorsMassimiliano Pinto
11th November 2014Addition of missing top filterMark Riddoch
+ + +# Introduction + +The purpose of this document is to describe how to configure MaxScale and to discuss some possible usage scenarios for MaxScale. MaxScale is designed with flexibility in mind, and consists of an event processing core with various support functions and plugin modules that tailor the behaviour of the MaxScale itself. + +## Terms + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TermDescription
serviceA service represents a set of databases with a specific access mechanism that is offered to clients of MaxScale. The access mechanism defines the algorithm that MaxScale will use to direct particular requests to the individual databases.
serverA server represents an individual database server to which a client can be connected via MaxScale.
routerA router is a module within MaxScale that will route client requests to the various database servers which MaxScale provides a service interface to.
connection routingConnection routing is a method of handling requests in which 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 routingStatement 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.
protocolA protocol is a module of software that is used to communicate with another software entity within the system. MaxScale supports the dynamic loading of protocol modules to allow for increased flexibility.
moduleA module is a separate code entity that may be loaded dynamically into MaxScale to increase the available functionality. Modules are implemented as run-time loadable shared objects.
monitorA monitor is a module that can be executed within MaxScale to monitor the state of a set of database. The use of an internal monitor is optional, monitoring may be performed externally to MaxScale.
listenerA listener is the network endpoint that is used to listen for connections to MaxScale from the client applications. A listener is associated to a single service, however a service may have many listeners.
connection failoverWhen a connection currently being used between MaxScale and the database server fails a replacement will be automatically created to another server by MaxScale without client intervention
backend databaseA term used to refer to a database that sits behind MaxScale and is accessed by applications via MaxScale.
filterA module that can be placed between the client and the 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 + +The MaxScale configuration is read from a file which can be located in a number of placing, MaxScale will search for the configuration file in a number of locations. + +1. If the environment variable MAXSCALE_HOME is set then MaxScale will look for a configuration file called MaxScale.cnf in the directory $MAXSCALE_HOME/etc + +2. If MAXSCALE_HOME is not set or the configuration file is not in the location above MaxScale will look for a file in /etc/MaxScale.cnf + +Alternatively MaxScale can be started with the -c flag and the path of the MaxScale home directory tree. + +An explicit path to a configuration file can be passed by using the -f option to MaxScale. + +The configuration file itself is based on the "ini" file format and consists of various sections that are used to build the configuration, these sections define services, servers, listeners, monitors and global settings. + +## Global Settings + +The global settings, in a section named [MaxScale], allow various parameters that affect MaxScale as a whole to be tuned. Currently the only setting that is supported is the number of threads to use to handle the network traffic. MaxScale will also accept the section name of [gateway] for global settings. This is for backward compatibility with versions prior to the naming of MaxScale. + +### Threads + +To control the number of threads that poll for network traffic set the parameter threads to a number. It is recommended that you start with a single thread and add more as you find the performance is not satisfactory. MaxScale is implemented to be very thread efficient, so a small number of threads is usually adequate to support reasonably heavy workloads. Adding more threads may not improve performance and can consume resources needlessly. + +# Valid options are: + +# threads= + +[MaxScale] + +threads=1 + +It should be noted that additional threads will be created to execute other internal services within MaxScale, this setting is merely used to configure the number of threads that will be used to manage the user connections. + +## Service + +A service represents the database service that MaxScale offers to the clients. In general a service consists of a set of backend database servers and a routing algorithm that determines how MaxScale decides to send statements or route connections to those backend servers. + +A service may be considered as a virtual database server that MaxScale makes available to its clients. + +Several different services may be defined using the same set of backend servers. For example a connection based routing service might be used by clients that already performed internal read/write splitting, whilst a different statement based router may be used by clients that are not written with this functionality in place. Both sets of applications could access the same data in the same databases. + +A service is identified by a service name, which is the name of the configuration file section and a type parameter of service + +[Test Service] + +type=service + +In order for MaxScale to forward any requests it must have at least one service defined within the configuration file. The definition of a service alone is not enough to allow MaxScale to forward requests however, the service is merely present to link together the other configuration elements. + +### Router + +The router parameter of a service defines the name of the router module that will be used to implement the routing algorithm between the client of MaxScale and the backend databases. Additionally routers may also be passed a comma separated list of options that are used to control the behaviour of the routing algorithm. The two parameters that control the routing choice are router and router_options. The router options are specific to a particular router and are used to modify the behaviour of the router. The read connection router can be passed options of master, slave or synced, an example of configuring a service to use this router and limiting the choice of servers to those in slave state would be as follows. + +router=readconnroute + +router_options=slave + +To change the router to connect on to servers in the master state as well as slave servers, the router options can be modified to include the master state. + +router=readconnroute + +router_options=master,slave + +A more complete description of router options and what is available for a given router is included with the documentation of the router itself. + +### Filters + +The filters option allow a set of filters to be defined for a service; requests from the client are passed through these filters before being sent to the router for dispatch to the backend server. The filters parameter takes one or more filter names, as defined within the filter definition section of the configuration file. Multiple filters are separated using the | character. + +filters=counter | QLA + +The requests pass through the filters from left to right in the order defined in the configuration parameter. + +### Servers + +The servers parameter in a service definition provides a comma separated list of the backend servers that comprise the service. The server names are those used in the name section of a block with a type parameter of server (see below). + +servers=server1,server2,server3 + +### User + +The user parameter, along with the passwd parameter are used to define the credentials used to connect to the backend servers to extract the list of database users from the backend database that is used for the client authentication. + +user=maxscale + +passwd=Mhu87p2D + +Authentication of incoming connections is performed by MaxScale itself rather than by the database server to which the client is connected. The client will authenticate itself with MaxScale, using the username, hostname and password information that MaxScale has extracted from the backend database servers. For a detailed discussion of how this impacts the authentication process please see the "Authentication" section below. + +The host matching criteria is restricted to IPv4, IPv6 will be added in a future release. + +Existing user configuration in the backend databases must be checked and may be updated before successful MaxScale authentication: + +In order for MaxScale to obtain all the data it must be given a username it can use to connect to the database and retrieve that data. This is the parameter that gives MaxScale the username to use for this purpose. + +The account used must be able to select from the mysql.user table, the following is an example showing how to create this user. + +MariaDB [mysql]> create user 'maxscale'@'maxscalehost' identified by 'Mhu87p2D'; + +Query OK, 0 rows affected (0.01 sec) + +MariaDB [mysql]> grant SELECT on mysql.user to 'maxscale'@'maxscalehost'; + +Query OK, 0 rows affected (0.00 sec) + +Additionally, GRANT SELECT on the mysql.db table 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'; + +Query OK, 0 rows affected (0.00 sec) + +MariaDB [(none)]> GRANT SHOW DATABASES ON *.* TO 'username'@'maxscalehost'; + +Query OK, 0 rows affected (0.00 sec) + +### Passwd + +The passwd parameter provides the password information for the above user and may be either a plain text password or it may be an encrypted password. See the section on encrypting passwords for use in the MaxScale.cnf file. This user must be capable of connecting to the backend database and executing the SQL statement "SELECT user, host, password,Select_priv FROM mysql.user" + +and additionally these SQL statements loading database names and database grants. + +* "SELECT user, host, db FROM mysql.db" + +* "SELECT * FROM INFORMATION_SCHEMA.SCHEMATA" + +* "SELECT GRANTEE,PRIVILEGE_TYPE FROM INFORMATION_SCHEMA.USER_PRIVILEGES" + +**enable_root_user** + +This parameter controls the ability of the root user to connect to MaxScale and hence onwards to the backend servers via MaxScale. + +The default value is 0, disabling the ability of the root user to connect to MaxScale. + +Example for enabling root user: + +enable_root_user=1 + +Values of "on" or “true” may also be given to enable the root user and “off” or “false” may be given to disable the use of the root user. + +enable_root_user=true + +**localhost_match_wildcard_host** + +This parameter enables matching of ‘127.0.0.1’ (localhost) against ‘%’ wildcard host for MySQL protocol authentication. The default value is 0, therefore in order to authenticate a connection from the same machine as the one which MaxScale is running on an explicit user@lcoalhost entry will be required in the MySQL user table. + +**version_string** + +This parameter sets a custom version string that is sent in the MySQL Handshake from MaxScale to clients. + +Example: + +version_string=5.5.37-MariaDB-RWsplit + +If not set, the default value is the server version of the embedded MySQL/MariaDB library. Example: 5.5.35-MariaDB + +### weightby + +The weightby parameter is used in conjunction with server parameters in order to control the load balancing applied in the router in use by the service. This allows varying weights to be applied to each server to create a non-uniform distribution of the load amongst the servers. + +An example of this might be to define a parameter for each server that represents the amount of resource available on the server, we could call this serversize. Every server should then have a serversize parameter set for the server. + +serversize=10 + +The service would then have the parameter weightby set. If there are 4 servers defined in the service, serverA, serverB, serverC and serverD, with the serversize set as shown in the table below, the connections would balanced using the percentages in this table. + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Serverserversize% connections
serverA1018%
serverB1527%
serverC1018%
serverD2036%
+ + +## Server + +Server sections are used to define the backend database servers that can be formed into a service. A server may be a member of one or more services within MaxScale. Servers are identified by a server name which is the section name in the configuration file. Servers have a type parameter of server, plus address port and protocol parameters. + +[server1] + +type=server + +address=127.0.0.1 + +port=3000 + +protocol=MySQLBackend + +### Address + +The IP address or hostname of the machine running the database server that is being defined. MaxScale will use this address to connect to the backend database server. + +### Port + +The port on which the database listens for incoming connections. MaxScale will use this port to connect to the database server. + +### Protocol + +The name for the protocol module to use to connect MaxScale to the database. Currently only one backend protocol is supported, the MySQLBackend module. + +### Monitoruser + +The monitor has a username and password that is used to connect to all servers for monitoring purposes, this may be overridden by supplying a monitoruser statement for each individual server + +monitoruser=mymonitoruser + +### MonitorPw + +The monitor has a username and password that is used to connect to all servers for monitoring purposes, this may be overridden by supplying a monpasswd statement for the individual servers + +monitorpw=mymonitorpasswd + +The monpasswd parameter may be either a plain text password or it may be an encrypted password. See the section on encrypting passwords for use in the MaxScale.cnf file. + +## Listener + +The listener defines a port and protocol pair that is used to listen for connections to a service. A service may have multiple listeners associated with it, either to support multiple protocols or multiple ports. As with other elements of the configuration the section name is the listener name and it can be selected freely. A type parameter is used to identify the section as a listener definition. Address is optional and it allows the user to limit connections to certain interface only. Socket is also optional and used for Unix socket connections. + +[] + +type=listener + +service=] + +protocol=[MySQLClient|HTTPD] + +address=[IP|hostname] + +port= + +socket= + +### Service + +The service to which the listener is associated. This is the name of a service that is defined elsewhere in the configuration file. + +### Protocol + +The name of the protocol module that is used for the communication between the client and MaxScale itself. + +### Address + +The address option sets the address that will be used to bind the listening socket. The address may be specified as an IP address in ‘dot notation’ or as a hostname. If the address option is not included in the listener definition the listener will bind to all network interfaces. + +### Port + +The port to use to listen for incoming connections to MaxScale from the clients. If the port is omitted from the configuration a default port for the protocol will be used. + +**Socket** + +The socket option may be included in a listener definition, this configures the listener to use Unix domain sockets to listen for incoming connections. The parameter value given is the name of the socket to use. + +If a socket option and an address option is given then the listener will listen on both the specific IP address and the Unix socket. + +## Filter + +Filters provide a means to manipulate or process requests as they pass through MaxScale between the client side protocol and the query router. A filter should be defined in a section with a type of filter. + +[QLA] + +type=filter + +module=qlafilter + +options=/tmp/QueryLog + +The section name may then be used in one or more services by using the filters= parameter in the service section. In order to use the above filter for a service called "QLA Service", an entry of the following form would exist for that service. + +[QLA Service] + +type=service + +router=readconnroute + +router_options=slave + +servers=server1,server2,server3,server4 + +user=massi + +passwd=6628C50E07CCE1F0392EDEEB9D1203F3 + +filters=QLA + +![image alt text](images/image_10.png) + +See the Services section for more details on how to configure the various options of a service. Note that some filters require parsing of the statement which makes them compatible with statement-based routers only, such as Read/Write Split router. + +### Module + +The module parameter defines the name of the loadable module that implements the filter. + +### Options + +The options parameter is used to pass options to the filter to control the actions the filter will perform. The values that can be passed differ between filter implementation, the inclusion of an options parameter is optional. + +### Other Parameters + +Any other parameters present in the filters section will be passed to the filter to be interpreted by the filter. An example of this is the regexfilter that requires the two parameters match and replace + +[regex] + +type=filter + +module=regexfilter + +match=form + +replace=from + +## Monitor + +In order for the various router modules to function correctly they require information about the state of the servers that are part of the service they provide. MaxScale has the ability to internally monitor the state of the back-end database servers or that state may be feed into MaxScale from external monitoring systems. If automated monitoring and failover of services is required this is achieved by running a monitor module that is designed for the particular database architecture that is in use. + +Monitors are defined in much the same way as other elements in the configuration file, with the section name being the name of the monitor instance and the type being set to monitor. + +[MySQL Monitor] + +type=monitor + +module=mysqlmon + +servers=server1,server2,server3 + +user=dbmonitoruser + +passwd=dbmonitorpwd + +monitor_interval=8000 + +backend_connect_timeout=3 + +backend_read_timeout=1 + +backend_write_timeout=2 + +# mysqlmon specific options + +detect_replication_lag=0 + +detect_stale_master=0 + +[Galera Monitor] + +type=monitor + +module=galeramon + +servers=server1,server2,server3 + +user=dbmonitoruser + +passwd=dbmonitorpwd + +monitor_interval=8000 + +backend_connect_timeout=3 + +backend_read_timeout=1 + +backend_write_timeout=2 + +# galeramon specific options + +disable_master_failback=0 + +### Module + +The module parameter defines the name of the loadable module that implements the monitor. This module is loaded and executed on a separate thread within MaxScale. + +### Servers + +The servers parameter is a comma separated list of server names to monitor, these are the names defined elsewhere in the configuration file. The set of servers monitored by a single monitor need not be the same as the set of servers used within any particular server, a single monitor instance may monitor servers in multiple servers. + +### User + +The user parameter defines the username that the monitor will use to connect to the monitored databases. Depending on the monitoring module used this user will require specific privileges in order to determine the state of the nodes, details of those privileges can be found in the sections on each of the monitor modules. + +Individual servers may define override values for the user and password the monitor uses by setting the monuser and monpasswd parameters in the server section. + +### Passwd + +The password parameter may be either a plain text password or it may be an encrypted password. See the section on encrypting passwords for use in the MaxScale.cnf file. + +**Monitor_interval** + +The monitor_interval parameter sets the sampling interval in milliseconds for each monitor, the default value is 10000 milliseconds. + +**Detect_replication_lag** + +This options if set to 1 will allow MySQL monitor to collect the replication lag among all configured slaves by checking the content of maxscale_schema.replication_heartbeat table. The master server writes in and slaves fetch a UNIX timestamp from that there. + +This timestamp is updated in each node server struct and it’s used to calculate the replication lag. + +That value is also used by the Read / Write split module via max_slave_replication_lag and LEAST_BEHIND_MASTER options. + +Replication lag is measured by writing to a table, replication_heartbeat in the maxscale_schema, updates to this table will be observed on the slave in order to determine the lag between the slave and the master on which it was written. If the slave is many minutes behind the master and MaxScale is then started the information in the slave table is not available and that slave may be excluded from the routing decision. + +A specific grant for the monitor user might be required in order to create schema/table and for read/write operations. + +This monitor option is not enabled by default. + +**Detect_stale_master** + +This options if set to 1 will allow MySQL monitor to select the previous selected Master for next operations even if no slaves at all are found by the monitor polling. + +This is such a case when the replication on all slave has been stopped via STOP SLAVE or the current configuration was removed by RESET SLAVE ALL. + +As there are no slaves the replication topology cannot be computed and MaxScale can only check if the current monitored server was the master before: if that’s the case + +MySQL monitor adds to the server status field the SERVER_STALE_STATUS bit and a log entry appears in the Message Log file. + +If MaxScale or monitor is restarted and the Replication is still not configured or started there will not be any master server available even with this option enabled. + +This option is not enabled by default and should be used at the administrator risk. + +**Disable_master_failback** + +This option if set to 1 will allow Galera monitor to keep the existing selected master even if another node,after joining back the cluster may be selected as candidate master. + +The master role assignment currently follows one rule: take the server with lowest wsrep_local_index value. + +By default, if a node takes a lower index than the current master one the monitor will set the master role to that node: this monitor option, if set, prevents the master change. + +The server status field may have the SERVER_MASTER_STICKINESS bit, meaning the current master selection is not based on the available rules but it’s the one previously selected and then kept, accordingly to option value equal 1. + + + +Anyway, a new master will be selected in case of current master failure, regardless the option value. + +**Backend_connect_timeout** + +This option, with default value of 3 sets the monitor connect timeout to backends. + +**Backend_read_timeout** + +Default value is 1. Read Timeout is the timeout in seconds for each attempt to read from the server. There are retries if necessary, so the total effective timeout value is three times the option value. That’s for mysql_real_connect C API. + +**Backend_write_timeout** + +Default value is 2. Write Timeout is the timeout in seconds for each attempt to write to the server. There is a retry if necessary, so the total effective timeout value is two times the option value. That’s for mysql_real_connect C API. + +# Protocol Modules + +The protocols supported by MaxScale are implemented as external modules that are loaded dynamically into the MaxScale core. These modules reside in the directory $MAXSCALE_HOME/modules, if the environment variable $MAXSCALE_HOME is not set it defaults to /usr/local/skysql/MaxScale. It may also be set by passing the -c option on the MaxScale command line. + +## MySQLClient + +This is the implementation of the MySQL protocol that is used by clients of MaxScale to connect to MaxScale. + +## MySQLBackend + +The MySQLBackend protocol module is the implementation of the protocol that MaxScale uses to connect to the backend MySQL, MariaDB and Percona Server databases. This implementation is tailored for the MaxScale to MySQL Database traffic and is not a general purpose implementation of the MySQL protocol. + +## Telnetd + +The telnetd protocol module is used for connections to MaxScale itself for the purposes of creating interactive user sessions with the MaxScale instance itself. Currently this is used in conjunction with a special router implementation, the debugcli. + +## maxscaled + +The protocol used used by the maxadmin client application in order to connect to MaxScale and access the command line interface. + +## HTTPD + +This protocol module is currently still under development, it provides a means to create HTTP connections to MaxScale for use by web browsers or RESTful API clients. + +# Router Modules + +The main task of MaxScale is to accept database connections from client applications and route the connections or the statements sent over those connections to the various services supported by MaxScale. + +There are two flavours of routing that MaxScale can perform, connection based routing and statement based routine. These each have their own characteristics and costs associated with them. + +## Connection Based Routing + +Connection based routing is a mechanism by which MaxScale will, for each incoming connection decide on an appropriate outbound server and will forward all statements to that server without examining the internals of the statement. Once an inbound connection is associated to a particular backend database it will remain connected to that server until the connection is closed or the server fails. The Read Connection Router is an example of connection-based routing. + +## Statement Based Routing + +Statement based routing is somewhat different, the routing modules examine every statement the client sends and determines, on a per statement basis, which of the set of backend servers in the service is best to execute the statement. This gives better dynamic balancing of the load within the cluster but comes at a cost. The query router must understand the statement that is being routing and may have to parse the statement in order to achieve this. + +Parsing within the router adds overhead to the cost of routing and makes this type of router best suitable for loads in which the gains outweigh this added cost. The added cost from statement parsing also gives the possibility to create and use new type of filters which are based on statement processing. In contrast to the added processing cost, statement-based routing may increase the performance of the cluster by offloading statements away from the master when possible. + +## Available Routing Modules + +Currently a small number of query routers are available, these are in different stages of completion and offer different facilities. + +### Readconnroute + +This is a connection based query router that was originally targeted at environments in which the clients already performed splitting of read and write queries into separate connections. + +Whenever a new connection is received the router will examine the state of all the servers that form part of the service and route the connection to the server with least connections currently that matches the filter constraints given in the router options. This results in a balancing of the active connections, however different connections may have different lifetimes and the connections may become unbalanced when later viewed. + +The read connection router can be configured to balance the connections from the clients across all the backend servers that are running, just those backend servers that are currently replication slaves or those that are replication masters when routing to a master slave replication environment. When a Galera cluster environment is in use the servers can be filtered to just the set that are part of the cluster and in the ‘synced’ state. These options are configurable via the router_options that can be set within a service. The router_option strings supported are "master", “slave” and “synced”. + +#### Master/Slave Replication Setup + +To setup MaxScale to route connections evenly between all the current slave servers in a replication cluster, a service entry of the form shown below is required. + +[Read Service] + +type=service + +router=readconnroute + +router_options=slave + +servers=server1,server2,server3,server4 + +user=maxscale + +passwd=thepasswd + +With the addition of a listener for this service, which defines the port and protocol that MaxScale uses + +[Read Listener] + +type=listener + +service=Read Service + +protocol=MySQLClient + +port=4006 + +the client can now connect to port 4006 on the host which is running MaxScale. Statements sent using this connection will then be routed to one of the slaves in the server set defined in the Read Service. Exactly which is selected will be determined by balancing the number of connections to each of those whose current state is "slave". + +Altering the router options to be slave, master would result in the connections being balanced between all the servers within the cluster. + +It is assumed that the client will have a separate connection to the master server, however this can be routed via MaxScale, allowing MaxScale to manage the determination of which server is master. To do this you would add a second service and listener definition for the master server. + +[Write Service] + +type=service + +router=readconnroute + +router_options=master + +servers=server1,server2,server3,server4 + +user=maxscale + +passwd=thepasswd + +[Write Listener] + +type=listener + +service=Write Service + +protocol=MySQLClient + +port=4007 + +This allows the clients to direct write requests to port 4007 and read requests to port 4006 of the MaxScale host without the clients needing to understand the configuration of the Master/Slave replication cluster. + +Connections to port 4007 would automatically be directed to the server that is the master for replication at the time connection is opened. Whilst this is a simple mapping to a single server it does give the advantage that the clients have no requirement to track which server is currently the master, devolving responsibility for managing the failover to MaxScale. + +In order for MaxScale to be able to determine the state of these servers the mysqlmon monitor module should be run against the set of servers that comprise the service. + +#### Galera Cluster Configuration for Read Connection router + +Although not primarily designed for a multi-master replication setup, it is possible to use the readconnroute in this situation. The readconnroute connection router can be used to balance the connections across a Galera cluster. A special monitor is available that detects if nodes are joined to a Galera Cluster, with the addition of a router option to only route connections to nodes marked as synced. MaxScale can ensure that users are never connected to a node that is not a full cluster member. + +[Galera Service] + +type=service + +router=readconnroute + +router_options=synced + +servers=server1,server2,server3,server4 + +user=maxscale + +passwd=thepasswd + +[Galera Listener] + +type=listener + +service=Galera Service + +protocol=MySQLClient + +port=3336 + +[Galera Monitor] + +type=monitor + +module=galeramon + +servers=server1,server2,server3,server4 + +user=galeramon + +passwd=galeramon + +The specialized Galera monitor can also select one of the node in the cluster as master, the others will be marked as slave. These roles are only assigned to synced nodes. + +It then possible to have services/listeners with router_options=master or slave accessing a subset of all galera nodes. The "synced" simply means: access all nodes. Examples of different readconn router configurations for Galera: + +[Galera Master Service] + +type=service + +router=readconnroute + +router_options=master + +[Galera Slave Service] + +type=service + +router=readconnroute + +router_options=slave + +### Read/Write Split router + +The Read/Write Split router is implemented in readwritesplit module. It is a statement-based router that has been designed for use within Master/Slave replication environments. It examines and optionally parses every statement to find out whether the statement can be routed to slave instead of master. + +#### Starting a readwritesplit router session + +When client connects to readwritesplit service for the first time, client is authenticated against user data loaded from backend database. After successful authentication connection for client queries is created and followed by that, a readwritesplit router session is initialized. + +Router session processes its specific configuration parameters and establishes connections to master and slaves. The number of slaves in each session depends on the value of max_slave_connections parameter (default is 1) and the availability of slaves. Most suitable number of slaves varies as it depends on the number of clients, and the backend servers and the type of load. In Figure below Server 1 is the master and Servers 2-7 are the available slaves. In this example max_slave_connections=3. + +![image alt text](images/image_11.png) + +#### Routing to master + +Routing to master is important for data consistency and because majority of writes are written to binlog and thus become replicated to slaves. + +The following operations are routed to master: + +* write statements, + +* all statements within an open transaction, + +* stored procedure calls, and + +* user-defined function calls. + +* DDL statements (DROP|CREATE|ALTER TABLE … etc.) + +* EXECUTE (prepared) statements + +* all statements using temporary tables + +In addition to these, if readwritesplit service is configured with max_slave_replication_lag parameter, and if all slaves suffer from too long replication lag, then statements will be routed to master. (There might be other similar configuration parameters in the future which limit the number of statements that will be routed to slaves.) + +#### Routing to slaves + +Ability to route some statements to slaves is important because it also decreases the load targeted to master. Moreover, it is possible to have multiple slaves to share the load in contrast to single master. + +Queries which can be routed to slaves must be auto committed and belong to one of the following group: + +* read-only database queries, + +* read-only queries to system, or user-defined variables, + +* SHOW statements, and + +* system function calls. + +#### Routing to every session backend + +Third class of statements includes those, which modify session data, such as session system variables, user-defined variables, the database being used etc. We call them session commands, and they must be replicated as they affect the future results of read and write operations, so they must be executed on all servers that could execute statements on behalf of this client. + +Session commands include for example: + +* SET statements + +* USE + +* embedded system/user-defined variable assignments (SELECT (@myvar := 5)) in read-only statements + +* PREPARE statements + +* QUIT, PING, STMT RESET, CHANGE USER, etc. commands + +Note: if variable assignment is embedded in write statement it is routed to master only. For example, INSERT INTO t1 values(@myvar:=5, 7) would be routed to master only. + +#### Configuring Read/Write Split router + +Read/Write Split router-specific settings are specified in the configuration file of MaxScale in its specific section. The section can be freely named but the name is used latter as a reference from listener section. + +The configuration consists of mandatory and optional parameters. + +##### Mandatory parameters + +**type** specifies the type of service. For readwritesplit module the type is: + +type=router + +**service **specifies the router module to be used. For readwritesplit the value is: + + service=readwritesplit + +**servers **provide a list of servers, which must include one master and available slaves. Syntax for servers is: + + servers= + +*Note that each server on the list must have its own section in the configuration file where it is defined.* + +**user **is assigned with the username which router session uses for accessing backends for loading the content of mysql.user table (and mysql.db and database names as well) and optionally for creating, and using maxscale_schema.replication_heartbeat table. + +**passwd **specifies corresponding password for the user. Syntax for user and passwd is: + +user= + +passwd= + +##### Optional parameters + +**max_slave_connections **sets the maximum number of slaves a router session uses at any moment. Default value is 1. Syntax for max_slave_connections is: + + max_slave_connections= + +**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. Syntax for max_slave_replication_lag is: + + max_slave_replication_lag= + +This applies to Master/Slave replication with MySQL monitor and detect_replication_lag=1 options set + +**router_options **may include multiple readwritesplit-specific options. Values are either singular or parameter-value pairs. Currently available is a single option which specifies the criteria used in slave selection both in initialization of router session and per each query. *Note, that due to the current monitor implementations, the value specified here should be twice the monitor interval + 1**.* + + options=slave_selection_criteria= + +where is one of the following: + + /** slave with least connections in total */ + + LEAST_GLOBAL_CONNECTIONS + + /** slave with least connections from this router */ + + LEAST_ROUTER_CONNECTIONS + + /** slave with smallest replication lag */ + + LEAST_BEHIND_MASTER + + /** slave with least active operations */ + + LEAST_CURRENT_OPERATIONS** **(default) + +**use_sql_variables_in** specifies where should queries, which read session variable, be routed. The syntax for use_sql_variable_in is: + + use_sql_variables_in=[master|all] + +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: + + 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. + +An example of Read/Write Split router configuration : + +[RWSplit Service] + +type=service + +router=readwritesplit + +router_options=slave_selection_criteria=LEAST_BEHIND_MASTER + +max_slave_connections=50% + +max_slave_replication_lag=61 + +servers=server1,server2,server3,server4 + +user=myuser + +passwd=mypass + +filters=qla|fetch|from + +In addition to this, readwritesplit needs configuration for a listener, for all servers listed, and for each filter. Listener, server - and filter configurations are described in their own sections in this document. + +Below is a listener example for the "RWSplit Service" defined above: + +[RWSplit Listener] + +type=listener + +service=RWSplit Service + +protocol=MySQLClient + +port=4044 + +The client would merely connect to port 4044 on the MaxScale host and statements would be directed to the master, slave or all backends as appropriate. Determination of the master or slave status may be done via a monitor module within MaxScale or externally. In this latter case the server flags would need to be set via the MaxScale debug interface, in future versions an API will be available for this purpose. + +Galera Cluster Configuration for Read/Write Split router + + + +Galera monitor assigns Master and Slave roles to appropriate sync’ed Galera nodes. Using readwritesplit with Galera is seamless; only change needed to the configuration above is replacing the list of MySQL replication servers with list of Galera nodes. With the same example as above: + +Simply configure a Split Service with galera nodes: + +[RWSplit Service] + +type=service + +router=readwritesplit + +max_slave_connections=50% + +servers=galera_node1,galera_node2,galera_node3 + +user=myuser + +passwd=mypass + +filters=qla|fetch|from + +### Debugcli + +The debugcli is a special case of a statement based router. Rather than direct the statements at an external data source they are handled internally. These statements are simple text commands and the results are the output of debug commands within MaxScale. The service and listener definitions for a debug cli service only differ from other services in that they require no backend server definitions. + +#### Debug CLI Configuration + +The definition of the debug cli service is illustrated below + +[Debug Service] + +type=service + +router=debugcli + +[Debug Listener] + +type=listener + +service=Debug Service + +protocol=telnetd + +port=4442 + +Connections using the telnet protocol to port 4442 of the 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 skysql. + +The debugcli supports two modes of operation, developer mode and user mode. The mode is set via the router_options parameter of the debugcli. 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 MaxScale code base. Details of the differences between the modes can be found in the debugging guide for MaxScale. The default mode for the debugcli 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 a user and a developer version of the debugcli may be defined within the same instance of 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 + +### CLI + +The command line interface as used by maxadmin. This is a variant of the debugcli that is built slightly differently so that it may be accessed by the client application maxadmin. The CLI requires the use of the maxscaled protocol. + +#### CLI Configuration + +There are two components to the definition required in order to run the command line interface to use with MaxAdmin; a service and a listener. + +The default entries required are shown below. + +[CLI] + +type=service + +router=cli + +[CLI Listener] + +type=listener + +service=CLI + +protocol=maxscaled + +address=localhost + +port=6603 + +Note that this uses the default port of 6603 and confines the connections to localhost connections only. Remove the address= entry to allow connections from any machine on your network. Changing the port from 6603 will mean that you must allows pass a -p option to the MaxAdmin command. + +# Monitor Modules + +Monitor modules are used by MaxScale to internally monitor the state of the backend databases in order to set the server flags for each of those servers. The router modules then use these flags to determine if the particular server is a suitable destination for routing connections for particular query classifications. The monitors are run within separate threads of MaxScale and do not affect the MaxScale performance. + +The use of monitors is optional, it is possible to run MaxScale with external monitoring, in which case arrangements must be made for an external entity to set the status of each of the servers that MaxScale can route to. + +# Parameters that apply to all monitors are: + +* monitor_interval + +* backend_connect_timeout + +* backend_read_timeout + +* backend_write_timeout + +Other parameters are monitor specific. + +## Mysqlmon + +The MySQLMon monitor is a simple monitor designed for use with MySQL Master/Slave replication cluster. To execute the mysqlmon monitor an entry as shown below should be added to the MaxScale configuration file. + +[MySQL Monitor] + +type=monitor + +module=mysqlmon + +servers=server1,server2,server3,server4 + +This will monitor the 4 servers; server1, server2, server3 and server4. It will set the status of running or failed and master or slave for each of the servers. + +The monitor uses the username given in the monitor section or the server specific user that is given in the server section to connect to the server. This user must have sufficient permissions on the database to determine the state of replication. The roles that must be granted to this user are REPLICATION SLAVE and REPLICATION CLIENT. + +To create a user that can be used to monitor the state of the cluster, the following commands could be used, assuming that MaxScale is running on the host ‘maxscalehost’ + +MariaDB [mysql]> create user 'maxscalemon'@'maxscalehost' identified by 'Ha79hjds'; + +Query OK, 0 rows affected (0.01 sec) + +MariaDB [mysql]> grant REPLICATION SLAVE on *.* to 'maxscalemon'@'maxscalehost'; + +Query OK, 0 rows affected (0.00 sec) + +MariaDB [mysql]> grant REPLICATION CLIENT on *.* to 'maxscalemon'@'maxscalehost'; + +Query OK, 0 rows affected (0.00 sec) + +MariaDB [mysql]> + +MySQL monitor fetches the @@server_id variable and other informations from SHOW SLAVE STATUS in order to compute the replication topology tree that may include intermediate master servers, called relay servers. + +The Master server used by router modules is the so called "root master": a server that has the SERVER_MASTER status bit set and it’s at the lowest level of the replication depth. + +MySQL monitor may optionally (detect_replication_lag=1) detect the replication lag among servers by using the maxscale_schema.replication_heartbeat table: the monitor user must have rights to create it and write into. + +Another option (detect_stale_master=1) may also allow to set a Stale Master when the replication has been stopped or the configuration doesn’t allow to have both IO and SQL replication threads running on all slaves: the previous detected working Master will be selected for read and write operations. + +Please note, those two options are not enabled by default. + +## Galeramon + +The Galeramon monitor is a simple router designed for use with MySQL Galera cluster. To execute the galeramon monitor an entry as shown below should be added to the MaxScale configuration file. + +[Galera Monitor] + +type=monitor + +module=galeramon + +servers=galera_node1,galera_node2,galera_node3 + +This will monitor the 4 servers; server1, server2, server3 and server4. It will set the status of running or failed and joined for those servers that reported the Galera JOINED status. + +The user that is configured for use with the Galera monitor must have sufficient privileges to select from the information_schema database and GLOBAL_STATUS table within that database. + +To create a user that can be used to monitor the state of the cluster, the following commands could be used, assuming that MaxScale is running on the host maxscalehost. + +MariaDB [mysql]> create user 'maxscalemon'@'maxscalehost' identified by 'Ha79hjds'; + +Query OK, 0 rows affected (0.01 sec) + +MariaDB [mysql]> + +The Galera monitor can also assign Master and Slave roles to the configured nodes: + +among the set of synced servers, the one with the lowest value of ‘wsrep_local_index’ is selected as the current master while the others are slaves: that’s the only available master selection rule right now. + +This way is possible to configure the node access based not only on ‘synced’ state but even on Master and Slave role enabling the use of Read Write split operation on a Galera cluster and avoiding any possible write conflict. + +It may happen that after a node failure or reboot or node joining back the cluster, the + +‘wsrep_local_index’ in the cluster nodes changes. + +This might result in monitor assigning the Master role to another server. + +In order to avoid such situation the disable_master_failback=1 configuration option helps keeping the current master regardless ‘wsrep_local_index’ value. + +The option it’s not enabled by default. + +Example status for a Galera server node is: + +Server 0x261fe50 (server2) + + Server: 192.168.1.101 + + Status: Master, Synced, Running + +Protocol: MySQLBackend + +Port: 3306 + + Server Version: 5.5.40-MariaDB-wsrep-log + + Node Id: 0 + +Server 0x2d1b3c0 (server4) + + Server: 192.168.122.144 + + Status: Slave, Synced, Running + + Protocol: MySQLBackend + + Port: 3306 + + Server Version: 5.5.40-MariaDB-wsrep-log + + Node Id: 1 + +# Filter Modules + +Currently four example filters are included in the MaxScale distribution + + + + + + + + + + + + + + + + + + + + + + + + + + +
ModuleDescription
testfilterStatement counting Filter - a simple filter that counts the number of SQL statements executed within a session. Results may be viewed via the debug interface.
qlafilterQuery Logging Filter - a simple query logging filter that write all statements for a session into a log file for that session.
regexfilterQuery Rewrite Filter - an example of how filters can alter the query contents. This filter allows a regular expression to be defined, along with replacement text that should be substituted for every match of that regular expression.
teeA filter that duplicates SQL requests and sends the duplicates to another service within MaxScale.
topfilterA filter that records the top running queries in terms of execution time. The number of queries to maintain is configurable, upon completion of a session a log file is written with the details of those top queries.
+ + +These filters are merely examples of what may be achieved with the filter API and are not sophisticated or consider as suitable for production use, they merely illustrate the functionality possible. + +## Statement Counting Filter + +The statement counting filter is implemented in the module names testfilter and merely keeps a count of the number of SQL statements executed. The filter requires no options to be passed and takes no parameters. The statement count can be viewed via the diagnostic and debug interface of MaxScale. + +In order to add this filter to an existing service create a filter section to name the filter as follows + +[counter] + +type=filter + +module=testfilter + +Then add the filter to your service by including the filters= parameter in the service section. + +filters=counter + +## Query Log All Filter + +The QLA filter simply writes all SQL statements to a log file along with a timestamp for the statement. An example of the file produced by the QLA filter is shown below + +00:36:04.922 5/06/2014, select @@version_comment limit 1 + +00:36:12.663 5/06/2014, SELECT DATABASE() + +00:36:12.664 5/06/2014, show databases + +00:36:12.665 5/06/2014, show tables + +A new file is created for each client connection, the name of the logfile can be controlled by the use of the router options. No parameters are used by the QLA filter. The filter is implemented by the loadable module qlafilter. + +To add the QLA filter to a service you must create a filter section to name the filter, associated the loadable module and define the filename option. + +[QLA] + +type=filter + +module=qlafilter + +options=/tmp/QueryLog + +Then add the filters= parameter into the service that you wish to log by adding this parameter to the service section + +filters=QLA + +A log file will be created for each client connection, the name of that log file will be /tmp/QueryLog. + +## Regular Expression Filter + +The regular expression filter is a simple text based query rewriting filter. It allows a regular expression to be used to match text in a SQL query and then a string replacement to be made against that match. The filter is implemented by the regexfilter loadable module and is passed two parameters, a match string and a replacement string. + +To add the filter to your service you must first create a filter section to name the filter and give the match and replacement strings. Here we define a filter that will convert to MariaDB 10 command show all slaves status to the older form of show slave status for MariaDB 5.5. + +[slavestatus] + +type=filter + +module=regexfilter + +match=show *all *slaves + +replace=show slave + +You must then add this filter to your service by adding the filters= option + +filters=slavestatus + +Another example would be a filter to convert from the MySQL 5.1 create table syntax that used the TYPE keyword to the newer ENGINE keyword. + +[EnginerFilter] + +type=filter + +module=regexfilter + +match=TYPE + +replace=ENGINE + +This would then change the SQL sent by a client application written to work with MySQL 5.1 into SQL that was compliant with MySQL 5.5. The statement + +create table supplier(id integer, name varchar(80)) type=innodb + +would be replaced with + +create table supplier(id integer, name varchar(80)) ENGINE=innodb + +before being sent to the server. Note that the text in the match string is case independent. + +## Tee Filter + +The tee filter is a filter module for MaxScale is a "plumbing" fitting in the 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 MaxScale. + +The configuration block for the TEE filter requires the minimal filter parameters in it’s section within the MaxScale.cnf file that defines the filter to load and the service to send the duplicates to. + +[ArchiveFilter] + +type=filter + +module=tee + +service=Archive + +In addition parameters may be added to define patterns to match against to either include or exclude particular SQL statements to be duplicated. You may also define that the filter is only active for connections from a particular source or when a particular user is connected. + +## Top Filter + +The top filter is a filter module for MaxScale that monitors every SQL statement that passes through the filter. It measures the duration of that statement, the time between the statement being sent and the first result being returned. The top N times are kept, along with the SQL text itself and a list sorted on the execution times of the query is written to a file upon closure of the client session. + +The configuration block for the TOP filter requires the minimal filter options in it’s section within the MaxScale.cnf file, stored in $MAXSCALE_HOME/etc/MaxScale.cnf. + +[MyLogFilter] + +type=filter + +module=topfilter + +filebase=/var/log/Top10Queries + +count=10 + +In addition parameters may be added to define patterns to match against to either include or exclude particular SQL statements to be duplicated. You may also define that the filter is only active for connections from a particular source or when a particular user is connected. + +# 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 MaxScale. Encryption keys may be created manually by executing the maxkeys utility with the argument of the filename to store the key. + +maxkeys $MAXSCALE_HOME/etc/.secrets + +Changing the encryption key for 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 password you require to encrypt as an argument. The environment variable MAXSCALE_HOME must be set, or MaxScale must be installed in the default location before maxpasswd can be executed. + +maxpasswd 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. MaxScale will determine this as an encrypted password and automatically decrypt it before sending it the database server. + +[Split Service] + +type=service + +router=readwritesplit + +servers=server1,server2,server3,server4 + +user=maxscale + +password=61DD955512C39A4A8BC4BB1E5F116705 + +# Configuration Updates + +The current MaxScale configuration may be updating by editing the configuration file and then forcing MaxScale to reread the configuration file. To force MaxScale to reread the configuration file a SIGTERM signal is sent to the MaxScale process. + +Some changes in configuration can not be dynamically applied and require a complete restart of MaxScale, whilst others will take some time to be applied. + +## Limitations + +Services that are removed via the configuration update mechanism can not be physically removed from MaxScale until there are no longer any connections using the service. + +When the number of threads is decreased the threads will not actually be terminated until such time as they complete the current operation of that thread. + +Monitors can not be completely removed from the running MaxScale. + +# Authentication + +MySQL uses username, passwords and the client host in order to authenticate a user, so a typical user would be defined as user X at host Y and would be given a password to connect. MaxScale uses exactly the same rules as MySQL when users connect to the MaxScale instance, i.e. it will check the address from which the client is connecting and treat this in exactly the same way that MySQL would. MaxScale will pull the authentication data from one of the backend servers and use this to match the incoming connections, the assumption being that all the backend servers for a particular service will share the same set of user credentials. + +It is important to understand, however, that when MaxScale itself makes connections to the backend servers the backend server will see all connections as originating from the host that runs MaxScale and not the original host from which the client connected to MaxScale. Therefore the backend servers should be configured to allow connections from the MaxScale host for every user that can connect from any host. Since there is only a single password within the database server for a given host, this limits the configuration such that a given user name must have the same password for every host from which they can connect. + +To clarify, if a user X is defined as using password *pass1* from host a and *pass2* from host b then there must be an entry in the user table for user X form the MaxScale host, say *pass1*. + +This would result in rows in the user table as follows + + + + + + + + + + + + + + + + + + + + + + +
UsernamePasswordClient Host
Xpass1a
Xpass2b
Xpass1MaxScale
+ + +In this case the user X would be able to connect to MaxScale from host a giving the password of *pass1*. In addition MaxScale would be able to create connections for this user to the backend servers using the username X and password *pass1*, since the MaxScale host is also defined to have password *pass1*. User X would not however be able to connect from host b since they would need to provide the password *pass2* in order to connect to MaxScale, but then MaxScale would not be able to connect to the backends as it would also use the password *pass2* for these connections. + +## Wildcard Hosts + +Hostname mapping in MaxScale works in exactly the same way as for MySQL, if the wildcard is used for the host then any host other than the localhost (127.0.0.1) will match. It is important to consider that the localhost check will be performed at the MaxScale level and at the MySQL server level. + +If MaxScale and the databases are on separate hosts there are two important changes in behaviour to consider: + +1. Clients running on the same machine as the backend database now may access the database using the wildcard entry. The localhost check between the client and MaxScale will allow the use of the wildcard, since the client is not running on the MaxScale host. Also the wildcard entry can be used on the database host as MaxScale is making that connection and it is not running on the same host as the database. + +2. Clients running on the same host as MaxScale can not access the database via MaxScale using the wildcard entry since the connection to MaxScale will be from the localhost. These clients are able to access the database directly, as they will use the wildcard entry. + +If MaxScale is running on the same host as one or more of the database nodes to which it is acting as a proxy then the wildcard host entries can be used to connect to MaxScale but not to connect onwards to the database running on the same node. + +In all these cases the issue may be solved by adding an explicit entry for the localhost address that has the same password as the wildcard entry. This may be done using a statement as below for each of the databases that are required: + +MariaDB [mysql]> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP ON employee.* 'user1'@'localhost' IDENTIFIED BY ‘xxx’; + +Query OK, 0 rows affected (0.00 sec) + +## Limitations + +At the time of writing the authentication mechanism within MaxScale does not support IPV6 address matching in connections rules. This is also in line with the current protocol modules that do not support IPV6. + +Wildcard address supported in the current version of MaxScale are: + +192.168.3.% + +192.168.%.% + +192.%.%.% + +and short notations + +192.% + +192.%.% + +192.168.% + +# Error Reporting + +MaxScale is designed to be executed as a service, therefore all error reports, including configuration errors, are written to the MaxScale error log file. MaxScale will log to a set of files in the directory $MAXSCALE_HOME/log, the only exception to this is if the log directory is not writable, in which case a message is sent to the standard error descriptor. + +Troubleshooting + +MaxScale binds on TCP ports and UNIX sockets as well. + +If there is a local firewall in the server where MaxScale is installed, the IP and port must be configured in order to receive connections from outside. + +If the firewall is a network facility among all the involved servers, a configuration update is required as well. + +Example: + +[Galera Listener] + +type=listener + + address=192.1681.3.33 + + port=4408 + + socket=/servers/maxscale/galera.sock + + + +TCP/IP Traffic must be permitted to 192.1681.3.33 port 4408 + +For Unix socket, the socket file path (example: /servers/maxscale/galera.sock) must be writable by the Unix user MaxScale runs as. + diff --git a/Getting-Started/images/image_10.png b/Getting-Started/images/image_10.png new file mode 100644 index 000000000..e61bf5d3d Binary files /dev/null and b/Getting-Started/images/image_10.png differ diff --git a/Getting-Started/images/image_11.png b/Getting-Started/images/image_11.png new file mode 100644 index 000000000..35bf8d0e7 Binary files /dev/null and b/Getting-Started/images/image_11.png differ diff --git a/Reference/Debug-And-Diagnostic-Support.md b/Reference/Debug-And-Diagnostic-Support.md new file mode 100644 index 000000000..19f07f68a --- /dev/null +++ b/Reference/Debug-And-Diagnostic-Support.md @@ -0,0 +1,1946 @@ +MaxScale + +Debug & Diagnostic Support + +Mark Riddoch + +Last Updated: 24th November 2014 + +[[TOC]] + +# Change History + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
DateComment
20th June 2013Initial Version
22nd July 2013Updated with new naming MaxScale +Addition of description of login process for the debug CLI +Updates debug CLI output examples +Addition of show users, shutdown maxscale, shutdown service, restart service, set server, clear server, reload users, reload config and add user commands.
23rd July 2013Rename of show users command to show dbusers and addition of the show users command to show the admin users. +Addition of example configuration data.
14th November 2013Added enable/disable log commands details +Added Galera Monitor as an example in show monitors
3rd March 2014Added show users details for MySQL users
27th May 2014Document the new debugcli mode switch and command changes in the two modes. +Added the new show server command.
29th May 2014Addition of new list command that gives concise tabular output
4th June 2014Added new ‘show monitors’ and ‘show servers’ details
29th August 2014Added new ‘show monitors’ details for MySQL/Galera monitors
+ + +# Introduction + +MaxScale is a complex application and as such is bound to have bugs and support issues that occur from time to time. There are a number of things we need to consider for the development stages and long term supportability of MaxScale + +* Flexible logging of MaxScale activity + +* Support for connecting a debugger to MaxScale + +* A diagnostic interface to MaxScale + +The topic of logging has already been discussed in another document in this series of documents about MaxScale and will not be covered further here. + +# Debugger Support + +Beyond the language support for debugging using tools such as gdb, MaxScale will also offer convenience functions for the debugger to call and a command line argument that is useful to run MaxScale under the debugger. + +## Command Line Option + +Normally when MaxScale starts it will place itself in the background and setup the signal masks so that it is immune to the normal set of signals that will cause the process to exit, SIGINT and SIGQUIT. This behaviour is normally what is required, however if you wish to run MaxScale under the control of a debugger it is useful to suppress this behaviour. A command line option, -d is provided to turn off this behaviour. + +% gdb maxscale + +(gdb) run -d + +## Convenience Functions + +A set of convenience functions is provided that may be used within the debugger session to extract information from MaxScale. + +### Printing Services + +A service within MaxScale provides the encapsulation of the port MaxScale listen on, the protocol it uses, the set of servers it may route to and the routing method to use. Two functions exists that allow you to display the details of the services and may be executed from within a debugger session. + +The printAllServices() function will print all the defined services within MaxScale and is invoked using the call syntax of the debugger. + +(gdb) call printAllServices() + +Service 0x60da20 + + Service: Debug Service + + Router: debugcli (0x7ffff5a7c2a0) + + Started: Thu Jun 20 15:13:32 2013 + + Backend databases + + Total connections: 1 + + Currently connected: 1 + +Service 0x60d010 + + Service: Test Service + + Router: readconnroute (0x7ffff5c7e260) + + Started: Thu Jun 20 15:13:32 2013 + + Backend databases + + 127.0.0.1:3308 Protocol: MySQLBackend + + 127.0.0.1:3307 Protocol: MySQLBackend + + 127.0.0.1:3306 Protocol: MySQLBackend + + Total connections: 1 + + Currently connected: 1 + +(gdb) + +It is possible to print an individual service if you know the memory address of the service. + +(gdb) call printService(0x60da20) + +Service 0x60da20 + + Service: Debug Service + + Router: debugcli (0x7ffff5a7c2a0) + + Started: Thu Jun 20 15:13:32 2013 + + Backend databases + + Total connections: 1 + + Currently connected: 1 + +(gdb) + +### Printing Sessions + +Sessions represent the data for a client that is connecting through MaxScale, there will be a session for each client and one for each listener for a specific port/protocol combination. Similarly there are two calls to print all or a particular session. + +(gdb) call printAllSessions() + +Session 0x60fdf0 + + Service: Debug Service (0x60da20) + + Client DCB: 0x60f6c0 + + Connected: Thu Jun 20 15:13:32 2013 + +Session 0x60f620 + + Service: Test Service (0x60d010) + + Client DCB: 0x60ead0 + + Connected: Thu Jun 20 15:13:32 2013 + +(gdb) call printSession(0x60fdf0) + +Session 0x60fdf0 + + Service: Debug Service (0x60da20) + + Client DCB: 0x60f6c0 + + Connected: Thu Jun 20 15:13:32 2013 + +(gdb) + +### Printing Servers + +Servers are a representation of the backend database to which MaxScale may route SQL statements. Similarly two calls exist to print server details. + +(gdb) call printAllServers() + +Server 0x60d9a0 + + Server: 127.0.0.1 + + Protocol: MySQLBackend + + Port: 3308 + +Server 0x60d920 + + Server: 127.0.0.1 + + Protocol: MySQLBackend + + Port: 3307 + +Server 0x60d8a0 + + Server: 127.0.0.1 + + Protocol: MySQLBackend + + Port: 3306 + +(gdb) call printServer(0x60d920) + +Server 0x60d920 + + Server: 127.0.0.1 + + Protocol: MySQLBackend + + Port: 3307 + +(gdb) + +### Modules + +MaxScale makes significant use of moules, shared objects, that are loaded on demand based on the configuration. A routine exists that will print the currently loaded modules. + +(gdb) call printModules() + +Module Name | Module Type | Version + +----------------------------------------------------- + +telnetd | Protocol | V1.0.0 + +MySQLClient | Protocol | V1.0.0 + +testroute | Router | V1.0.0 + +debugcli | Router | V1.0.0 + +readconnroute | Router | V1.0.0 + +(gdb) + +### Descriptor Control Blocks + +The Descriptor Control Block (DCB) is an important concept within MaxScale since it is this block that is passed to the polling system, when an event occurs it is that structure that is available and from this structure it must be possible to navigate to all other structures that contain state regarding the session and protocol in use. + +![image alt text](images/image_0.png) + +Similar print routines exist for the DCB + +(gdb) call printAllDCBs() + +DCB: 0x60ead0 + + DCB state: DCB for listening socket + + Queued write data: 0 + + Statistics: + + No. of Reads: 0 + + No. of Writes: 0 + + No. of Buffered Writes: 0 + + No. of Accepts: 0 + +DCB: 0x60f6c0 + + DCB state: DCB for listening socket + + Queued write data: 0 + + Statistics: + + No. of Reads: 0 + + No. of Writes: 0 + + No. of Buffered Writes: 0 + + No. of Accepts: 0 + +(gdb) call printDCB(0x60ead0) + +DCB: 0x60ead0 + + DCB state: DCB for listening socket + + Queued write data: 0 + + Statistics: + + No. of Reads: 0 + + No. of Writes: 0 + + No. of Buffered Writes: 0 + + No. of Accepts: 0 + +(gdb) + +# Diagnostic Interface + +It is possible to configure a service to run within MaxScale that will allow a user to telnet to a port on the machine and be connected to MaxScale. This is configured by creating a service that uses the debugcli routing module and the telnetd protocol with an associated listener. The service does not require any backend databases to be configured since the router never forwards any data, it merely accepts commands and executes them, returning data to the user. + +The example below shows the configuration that is required to set-up a debug interface that listens for incoming telnet connections on port 4442. + +[Debug Service] + +type=service + +router=debugcli + +[Debug Listener] + +type=listener + +service=Debug Service + +protocol=telnetd + +port=4442 + +The Debug Service section sets up a service with no backend database servers, but with a debugcli module as the router. This module will implement the commands and send the data back to the client. + +The debugcli accepts router options of either developer or user, these are used to control the mode of the user interface. If no router options are given then the CLI is in user mode by default. + +The Debug Listener section setups the protocol and port combination and links that to the service. + +Assuming a configuration that includes the debug service, with the listening port set to 4442, to connect from the machine that runs MaxScale you must first install telnet and then simply call telnet to connect. + +-bash-4.1$ telnet localhost 4442 + +Trying 127.0.0.1... + +Connected to localhost. + +Escape character is '^]'. + +Welcome the SkySQL MaxScale Debug Interface (V1.1.0). + +Type help for a list of available commands. + +MaxScale login: admin + +Password: + +MaxScale> + +As delivered MaxScale uses a default login name of admin with the password of skysql for connections to the debug interface. Users may be added to the CLI by use of the add user command. + +This places you in the debug command line interface of MaxScale, there is a help system that will display the commands available to you + +**MaxScale> **help + +Available commands: + + add user + + clear server + + disable log + + enable log + + list [listeners|modules|services|servers|sessions] + + reload [config|dbusers] + + remove user + + restart [monitor|service] + + set server + + show [dcbs|dcb|dbusers|epoll|modules|monitors|server|servers|services|service|session|sessions|users] + + shutdown [maxscale|monitor|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 ". + +**MaxScale> ** + +Different command help is shown in user mode and developer mode, in user mode the help for the show command is; + +**MaxScale>** help show + +Available options to the show command: + + dcbs Show all descriptor control blocks (network connections) + + dcb Show a single descriptor control block e.g. show dcb 0x493340 + + dbusers Show statistics and user names for a service's user table. + + Example : show dbusers + + epoll Show the poll statistics + + modules Show all currently loaded modules + + monitors Show the monitors that are configured + + server Show details for a named server, e.g. show server dbnode1 + + servers Show all configured servers + + services Show all configured services in MaxScale + + service Show a single service in MaxScale, may be passed a service name + + session Show a single session in MaxScale, e.g. show session 0x284830 + + sessions Show all active sessions in MaxScale + + users Show statistics and user names for the debug interface + +**MaxScale>** + +However in developer mode the help is; + +**MaxScale>** help show + +Available options to the show command: + + dcbs Show all descriptor control blocks (network connections) + + dcb Show a single descriptor control block e.g. show dcb 0x493340 + + dbusers Show statistics and user names for a service's user table + + epoll Show the poll statistics + + modules Show all currently loaded modules + + monitors Show the monitors that are configured + + server Show details for a server, e.g. show server 0x485390 + + servers Show all configured servers + + services Show all configured services in MaxScale + + session Show a single session in MaxScale, e.g. show session 0x284830 + + sessions Show all active sessions in MaxScale + + users Show statistics and user names for the debug interface + +**MaxScale>** + +The commands available are very similar to those described above to print things from the debugger, the advantage being that you do not need a debug version or a debugger to use them. + +## Listing Services + +The list services command is designed to give a concise tabular view of the currently configured services within MaxScale along with key data that summarises the use beign made of the service. + +**MaxScale>** list services + +Service Name | Router Module | #Users | Total Sessions + +-------------------------------------------------------------------------- + +Test Service | readconnroute | 1 | 1 + +Split Service | readwritesplit | 1 | 1 + +Debug Service | debugcli | 2 | 2 + +**MaxScale>** + +This provides a useful mechanism to see what is configured and provide the service names that can be passed to a show service command. + +## Listing Listeners + +The list listeners command outputs a table that provides the current set of listeners within the MaxScale instance and shows the status of each listener. + +**MaxScale>** list listeners + +Service Name | Protocol Module | Address | Port | State + +--------------------------------------------------------------------------- + +Test Service | MySQLClient | (null) | 4006 | Running + +Split Service | MySQLClient | (null) | 4007 | Running + +Debug Service | telnetd | localhost | 4242 | Running + +**MaxScale>** + +## Listing Servers + +The list servers command will display a table that contains a row for every server defined in the configuration file. The row contains the server name that can be passed to the show server command, the address and port of the server, its current status and the number of connections to that server from MaxScale. + +**MaxScale>** list servers + +Server | Address | Port | Status | Connections + +------------------------------------------------------------------------------- + +server1 | 127.0.0.1 | 3306 | Running | 0 + +server2 | 127.0.0.1 | 3307 | Slave, Running | 0 + +server3 | 127.0.0.1 | 3308 | Master, Running | 0 + +server4 | 127.0.0.1 | 3309 | Slave, Running | 0 + +**MaxScale>** + +## Listing Modules + +The list modules command displays a table of all the modules loaded within MaxScale. + +**MaxScale> **list modules + +Module Name | Module Type | Version + +----------------------------------------------------- + +telnetd | Protocol | V1.0.1 + +MySQLClient | Protocol | V1.0.0 + +mysqlmon | Monitor | V1.1.0 + +readconnroute | Router | V1.0.2 + +readwritesplit | Router | V1.0.2 + +debugcli | Router | V1.1.1 + +**MaxScale>**** ** + +## Showing Services + +The show services command will show all the services configured currently + +**MaxScale>** show services + +Service 0xf44c10 + + Service: Test Service + + Router: readconnroute (0x7f7fd8afba40) + + Number of router sessions: 0 + + Current no. of router sessions: 0 + + Number of queries forwarded: 0 + + Started: Mon Jul 22 11:24:09 2013 + + 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: 0xf454b0 + + Total connections: 1 + + Currently connected: 1 + +Service 0xf43910 + + Service: Split Service + + Router: readwritesplit (0x7f7fd8f05460) + + Number of router sessions: 0 + + Current no. of router sessions: 0 + + Number of queries forwarded: 0 + + Number of queries forwarded to master: 0 + + Number of queries forwarded to slave: 0 + + Number of queries forwarded to all: 0 + + Started: Mon Jul 22 11:24:09 2013 + + Backend databases + + 127.0.0.1:3308 Protocol: MySQLBackend + + 127.0.0.1:3307 Protocol: MySQLBackend + + 127.0.0.1:3306 Protocol: MySQLBackend + + Users data: 0xf449b0 + + Total connections: 1 + + Currently connected: 1 + +Service 0xea0190 + + Service: Debug Service + + Router: debugcli (0x7f7fd910d620) + + Started: Mon Jul 22 11:24:09 2013 + + Backend databases + + Users data: 0xea2d80 + + Total connections: 2 + + Currently connected: 2 + +**MaxScale>** + +## Showing Sessions + +There are two options to show sessions, either an individual session or all sessions + +**MaxScale>** show sessions + +Session 0x6f8f20 + + State: Session Ready + + Service: Debug Service (0x649190) + + Client DCB: 0x6f8e20 + + Client Address: 0.0.0.0 + + Connected: Mon Jul 22 11:31:56 2013 + +Session 0x6f83b0 + + State: Session Allocated + + Service: Split Service (0x6ec910) + + Client DCB: 0x64b430 + + Client Address: 127.0.0.1 + + Connected: Mon Jul 22 11:31:28 2013 + +Session 0x6efba0 + + State: Listener Session + + Service: Debug Service (0x649190) + + Client DCB: 0x64b180 + + Connected: Mon Jul 22 11:31:21 2013 + +Session 0x64b530 + + State: Listener Session + + Service: Split Service (0x6ec910) + + Client DCB: 0x6ef8e0 + + Connected: Mon Jul 22 11:31:21 2013 + +Session 0x618840 + + State: Listener Session + + Service: Test Service (0x6edc10) + + Client DCB: 0x6ef320 + + Connected: Mon Jul 22 11:31:21 2013 + +**MaxScale>** show session 0x6f83b0 + +Session 0x6f83b0 + + State: Session Allocated + + Service: Split Service (0x6ec910) + + Client DCB: 0x64b430 + + Client Address: 127.0.0.1 + + Connected: Mon Jul 22 11:31:28 2013 + +**MaxScale> ** + +## Show Servers + +The configured backend databases can be displayed using the show servers command. + +**MaxScale>** show servers + +Server 0x6ec840 (server1) + + Server: 127.0.0.1 + + Status: Running + + Protocol: MySQLBackend + + Port: 3306 + + Number of connections: 0 + + Current no. of connections:0 + +Server 0x6ec770 (server2) + + Server: 127.0.0.1 + + Status: Master, Running + + Protocol: MySQLBackend + + Port: 3307 + + Server Version: 5.5.35-MariaDB-log + + Node Id: 1 + + Master Id: -1 + + Slave Ids: 2,3 + + Repl Depth: 0 + + Last Repl Heartbeat: 1417080906 + + Number of connections: 1 + + Current no. of connections:1 + +Server 0x6ec6a0 (server3) + + Server: 127.0.0.1 + + Status: Slave, Running + + Protocol: MySQLBackend + + Port: 3308 + + Server Version: 5.5.35-MariaDB-log + +Node Id: 2 + + Master Id: 1 + + Slave Ids: + + Repl Depth: 1 + + Slave delay: 8 + + Last Repl Heartbeat: 1417080898 + + Number of connections: 1 + + Current no. of connections:1 + +Server 0x6ec5d0 (server4) + + Server: 127.0.0.1 + + Status: Down + + Protocol: MySQLBackend + + Port: 3309 + + Server Version: 5.5.35-MariaDB-log + + Node Id: 3 + + Master Id: 1 + + Slave Ids: + + Repl Depth: 1 + + Number of connections: 0 + + Current no. of connections:0 + +**MaxScale>** + +* Version string is available in the output only if the node is running. + +* Node Id possible values: + +* the value of server-id from MySQL or MariaDB servers in Master/Slave replication setup. + +* the value of ‘wsrep_local_index’ for Galera cluster nodes + +* the -1 value for a failure getting one of these informations + +* Repl Depth is the replication depth level found by MaxScale MySQL Monitor + +* Master Id is the master node, if available, for current server + +* Slave Ids is the slave list for the current node, if availbable + +Note, the Master Root Server used for routing decision is the server with master role and with lowest replication depth level. All slaves servers even if they are intermediate master are suitable for read statement routing decisions. + +* Slave Delay is the found time difference used for Replication Lag support in routing decision, between the value read by the Slave (it was inserted into the master) and maxscale current time + + Value of 0 or less than monitor interval means there is no replication delay. + +* Last Repl Heartbeat is the maxScale timestamp read or inserted (if current server is master) + +The Replication Heartbeat table is updated by MySQL replication, starting MaxScale when there is a significant slave delay may result that Slave Delay and Last Repl Heartbeat are not available for some time in the slave server details + +## There may be other status description such us: + + Slave of External Server: the node is slave of a server not configured + + in MaxScale (by MySQL monitor) + + Master Stickiness: the Master node is kept (by Galera monitor) + + Stale Status: the master node is kept even if the replication + + is not working (by MySQL monitor) + + Auth Error: Monitor was not able to login into backend + +A few examples: + +Server 0x1a5aae0 (server3) + + Server: 127.0.0.1 + + Status: Master, Slave of External Server, Running + + Protocol: MySQLBackend + + Port: 3308 + + Server Version: 5.5.35-MariaDB-log + + Node Id: 3 + + Master Id: 1 + + Slave Ids: 2 + + Repl Depth: 1 + +Server 0x2d1b5c0 (server2) + + Server: 192.168.122.142 + + Status: Master, Synced, Master Stickiness, Running + + Protocol: MySQLBackend + + Port: 3306 + + Server Version: 5.5.40-MariaDB-wsrep-log + + Node Id: 1 + + Repl Depth: 0 + +## Show Server + +Details of an individual server can be displayed by using the show server command. In user mode the show server command is passed the name of the server to display, these names are the section names used in the configuration file. + +**MaxScale>** show server server4 + +Server 0x6ec5d0 (server4) + + Server: 127.0.0.1 + + Status: Down + + Protocol: MySQLBackend + + Port: 3309 + + Number of connections: 0 + + Current no. of connections:0 + +**MaxScale>** + +In developer mode the show server command is passed the address of a server structure. + +**MaxScale>** show server 0x6ec5d0 + +Server 0x6ec5d0 (server4) + + Server: 127.0.0.1 + + Status: Down + + Protocol: MySQLBackend + + Port: 3309 + + Number of connections: 0 + + Current no. of connections:0 + +**MaxScale>** + +## Show DCBS + +There are two forms of the show command that will give you DCB information, the first will display information for all DCBs within the system. + +**MaxScale>** show dcbs + +DCB: 0x6ef320 + + DCB state: DCB for listening socket + + Service: Test Service + + Queued write data: 0 + + Statistics: + + No. of Reads: 0 + + No. of Writes: 0 + + No. of Buffered Writes: 0 + + No. of Accepts: 0 + +DCB: 0x6ef8e0 + + DCB state: DCB for listening socket + + Service: Split Service + + Queued write data: 0 + + Statistics: + + No. of Reads: 0 + + No. of Writes: 0 + + No. of Buffered Writes: 0 + + No. of Accepts: 1 + +DCB: 0x64b180 + + DCB state: DCB for listening socket + + Service: Debug Service + + Queued write data: 0 + + Statistics: + + No. of Reads: 0 + + No. of Writes: 0 + + No. of Buffered Writes: 0 + + No. of Accepts: 1 + +DCB: 0x64b430 + + DCB state: DCB processing event + + Service: Split Service + + Connected to: 127.0.0.1 + + Queued write data: 0 + + Statistics: + + No. of Reads: 2 + + No. of Writes: 3 + + No. of Buffered Writes: 0 + + No. of Accepts: 0 + +DCB: 0x6f8400 + + DCB state: DCB in the polling loop + + Service: Split Service + + Queued write data: 0 + + Statistics: + + No. of Reads: 3 + + No. of Writes: 1 + + No. of Buffered Writes: 0 + + No. of Accepts: 0 + +DCB: 0x6f8b40 + + DCB state: DCB in the polling loop + + Service: Split Service + + Queued write data: 0 + + Statistics: + + No. of Reads: 2 + + No. of Writes: 0 + + No. of Buffered Writes: 0 + + No. of Accepts: 0 + +DCB: 0x6f8e20 + + DCB state: DCB processing event + + Service: Debug Service + + Connected to: 0.0.0.0 + + Queued write data: 0 + + Statistics: + + No. of Reads: 8 + + No. of Writes: 133 + + No. of Buffered Writes: 0 + + No. of Accepts: 0 + +**MaxScale>** + + + +An individual DCB can be displayed by passing the DCB address to the show dcb command + +**MaxScale>** show dcb 0x64b430 + +DCB: 0x64b430 + + DCB state: DCB processing event + + Connected to: 127.0.0.1 + + Owning Session: 7308208 + + Queued write data: 0 + + Statistics: + + No. of Reads: 2 + + No. of Writes: 3 + + No. of Buffered Writes: 0 + + No. of Accepts: 0 + +**MaxScale>** + +## Show Modules + +The show modules command will display the list of the currently loaded modules + +**MaxScale>** show modules + +Module Name | Module Type | Version + +----------------------------------------------------- + +MySQLBackend | Protocol | V2.0.0 + +telnetd | Protocol | V1.0.1 + +MySQLClient | Protocol | V1.0.0 + +mysqlmon | Monitor | V1.0.0 + +readconnroute | Router | V1.0.2 + +readwritesplit | Router | V1.0.2 + +debugcli | Router | V1.1.0 + +**MaxScale>** + +## Show Polling Statistics + +Display statistics related to the main polling loop. The epoll cycles is the count of the number of times epoll has returned with one or more event. The other counters are for each individual events that has been detected. + +**MaxScale>** show epoll + +Number of epoll cycles: 7928 + +Number of read events: 2000920 + +Number of write events: 2000927 + +Number of error events: 0 + +Number of hangup events: 0 + +Number of accept events: 4 + +**MaxScale>** + + + +## Show Dbusers + +The show dbuser command allows data regarding the table that holds the database users for a service to be displayed. It does not give the actual user data, but rather details of the hashtable distribution. + +The show dbuser command takes different arguments in the two modes of MaxScale, in user mode it may be passed the name of a service rather than an address, whilst in developer mode it needs the address of a user structure that has been extracted from a service. + +In developer mode the show users commands must be passed the address of the user table, this can be extracted from the output of a show services command. + +**MaxScale>** show services + +Service 0x6ec910 + + Service: Split Service + + Router: readwritesplit (0x7ffff1698460) + + Number of router sessions: 1 + + Current no. of router sessions: 0 + + Number of queries forwarded: 2 + + Number of queries forwarded to master: 0 + + Number of queries forwarded to slave: 1 + + Number of queries forwarded to all: 1 + + Started: Mon Jul 22 11:31:21 2013 + + Backend databases + + 127.0.0.1:3308 Protocol: MySQLBackend + + 127.0.0.1:3307 Protocol: MySQLBackend + + 127.0.0.1:3306 Protocol: MySQLBackend + + Users data: 0x6ed9b0 + + Total connections: 2 + + Currently connected: 1 + +… + +The following example shows the MySQL users. + +Users are loaded with the host (IPv4 data) as they are created in the backend. + +**MaxScale>** show dbusers 0x6ed9b0 + +Users table data + +Hashtable: 0x19243a0, size 52 + + No. of entries: 16 + + Average chain length: 0.3 + + Longest chain length: 4 + +User names: one@%, new@192.168.56.1, new@127.0.0.1, repluser@%, seven@127.0.0.1, four@% + +**MaxScale>** + +In user mode the command is simply passed the name of the service + +**MaxScale>** show dbusers "Split Service" + +Users table data + +Hashtable: 0x19243a0, size 52 + + No. of entries: 16 + + Average chain length: 0.3 + + Longest chain length: 4 + +User names: one@%, new@192.168.56.1, new@127.0.0.1, repluser@%, seven@127.0.0.1, four@% + +**MaxScale>** + +Please note the use of quotes in the name in order to escape the white space character. + +## Show Users + +The show users command lists the users defined for the administration interface. Note that if there are no users defined, and the default admin user is in use, then no users will be displayed. + +**MaxScale> **show users + +Administration interface users: + +Users table data + +Hashtable: 0x25ef5e0, size 52 + + No. of entries: 2 + + Average chain length: 0.0 + + Longest chain length: 1 + +User names: admin, mark + +**MaxScale>** + +## Show Monitors + +The show monitors show the status of the database monitors. The address of the monitor can be used for the shutdown monitor and restart monitor commands. + +**MaxScale>** show monitors + +Monitor: 0x80a510 + + Name: MySQL Monitor + + Monitor running + + Sampling interval: 10000 milliseconds + + Replication lag: enabled + + Detect Stale Master: disabled + + Connect Timeout: 3 seconds + + Read Timeout: 1 seconds + + Write Timeout: 2 seconds + + Monitored servers: 127.0.0.1:3306, 127.0.0.1:3307, 127.0.0.1:3308, 127.0.0.1:3309 + +Monitor: 0x73d3d0 + + Name: Galera Monitor + + Monitor running + + Sampling interval: 7000 milliseconds + +Master Failback: off + + Connect Timeout: 3 seconds + + Read Timeout: 1 seconds + + Write Timeout: 2 seconds + + Monitored servers: 127.0.0.1:3310, 127.0.0.1:3311, 127.0.0.1:3312 + +**MaxScale>** + +Monitor timeouts used in Galera and MySQL monitor follow the rules of mysql_real_connect C API: + +* Connect Timeout is the connect timeout in seconds. + +* Read Timeout is the timeout in seconds for each attempt to read from the server. There are retries if necessary, so the total effective timeout value is three times the option value. + +* Write Timeout is the timeout in seconds for each attempt to write to the server. There is a retry if necessary, so the total effective timeout value is two times the option value. + +## Shutdown maxscale + +The CLI can be used to shutdown the MaxScale server by use of the shutdown command, it may be called with the argument either maxscale or gateway. + +**MaxScale>** shutdown maxscale + +## Shutdown monitor + +The shutdown monitor command stops the thread that is used to run the monitor and will stop any update of the server status flags. This is useful prior to manual setting of the states of the server using the set server and clear server commands. + +**MaxScale>** show monitors + +Monitor: 0x80a510 + + Name: MySQL Monitor + + Monitor running + +Sampling interval: 10000 milliseconds + + Monitored servers: 127.0.0.1:3306, 127.0.0.1:3307, 127.0.0.1:3308, 127.0.0.1:3309 + +**MaxScale>** shutdown monitor 0x80a510 + +**MaxScale>** show monitors + +Monitor: 0x80a510 + + Name: MySQL Monitor + + Monitor stopped + + Sampling interval: 10000 milliseconds + + Monitored servers: 127.0.0.1:3306, 127.0.0.1:3307, 127.0.0.1:3308, 127.0.0.1:3309 + +**MaxScale>** + +It may take some time before a monitor actually stops following the issuing of a shutdown monitor command. Stopped monitors can be restarted by issuing a restart monitor command. + +## Shutdown service + +The shutdown service command can be used to stop the listener for a particular service. This will prevent any new clients from using the service but will not terminate any clients already connected to the service. + +The shutdown service command needs the address of a service to be passed as an argument, this can be obtained by running show services. + +**MaxScale>** show services + +Service 0x6edc10 + + Service: Test Service + + Router: readconnroute (0x7ffff128ea40) + + Number of router sessions: 257 + + Current no. of router sessions: 0 + + Number of queries forwarded: 1000193 + + Started: Mon Jul 22 11:31:21 2013 + + 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: 0x6ee4b0 + + Total connections: 258 + + Currently connected: 1 + +Service 0x6ec910 + + Service: Split Service + + Router: readwritesplit (0x7ffff1698460) + + Number of router sessions: 1 + + Current no. of router sessions: 0 + + Number of queries forwarded: 2 + + Number of queries forwarded to master: 0 + + Number of queries forwarded to slave: 1 + + Number of queries forwarded to all: 1 + + Started: Mon Jul 22 11:31:21 2013 + + Backend databases + + 127.0.0.1:3308 Protocol: MySQLBackend + + 127.0.0.1:3307 Protocol: MySQLBackend + + 127.0.0.1:3306 Protocol: MySQLBackend + + Users data: 0x6ed9b0 + + Total connections: 2 + + Currently connected: 1 + +Service 0x649190 + + Service: Debug Service + + Router: debugcli (0x7ffff18a0620) + + Started: Mon Jul 22 11:31:21 2013 + + Backend databases + + Users data: 0x64bd80 + + Total connections: 2 + + Currently connected: 2 + +**MaxScale>** shutdown service 0x6edc10 + +In user mode the shutdown service command may be passed the name of the service as defined in configuration file. + +**MaxScale>** shutdown service Split\ Service + +## Restart service + +The restart service command can be used to restart a previously stopped listener for a service. In developer mode the address of the service must be passed. + +**MaxScale>** restart service 0x6edc10 + +**MaxScale>** + +In user mode the name of the service may be passed. + +**MaxScale>** restart service Test\ Service + +**MaxScale>** + +As with shutdown service the address of the service should be passed as an argument. + +## Restart Monitor + +The restart monitor command will restart a previously stopped monitor. + +**MaxScale> **show monitors + +Monitor: 0x80a510 + + Name: MySQL Monitor + + Monitor stopped + + Monitored servers: 127.0.0.1:3306, 127.0.0.1:3307, 127.0.0.1:3308, 127.0.0.1:3309 + +**MaxScale>** restart monitor 0x80a510 + +**MaxScale>** + +## Set server + +The set server command can be used to set the status flags of a server directly from the user interface. The command should be passed a server address that has been obtained from the output of a show servers command. + +**MaxScale>** show servers + +Server 0x6ec840 (server1) + + Server: 127.0.0.1 + + Status: Running + + Protocol: MySQLBackend + + Port: 3306 + + Server Version: 10.0.11-MariaDB-log + + Node Id: 29 + + Number of connections: 0 + + Current n. of conns: 0 + +Server 0x6ec770 (server2) + + Server: 127.0.0.1 + + Status: Master, Running + + Protocol: MySQLBackend + + Port: 3307 + + Server Version: 5.5.35-MariaDB-log + + Node Id: 1 + + Number of connections: 1 + + Current n. of conns: 0 + +Server 0x6ec6a0 (server3) + + Server: 127.0.0.1 + + Status: Slave, Running + + Protocol: MySQLBackend + + Port: 3308 + + Server Version: 5.5.35-MariaDB-log + + Node Id: 2 + + Number of connections: 258 + + Current n. of conns: 0 + +Server 0x6ec5d0 (server4) + + Server: 127.0.0.1 + + Status: Down + + Protocol: MySQLBackend + + Port: 3309 + + Node Id: -1 + + Number of connections: 0 + + Current n. of conns: 0 + +**MaxScale>** set server 0x6ec840 slave + +Valid options that are recognised by the set server command are running, master and slave. Please note that if the monitor is running it will reset the flags to match reality, this interface is really for use when the monitor is disabled. + +In user mode there is no need to find the address of the server structure, the name of the server from the section header in the configuration file make be given. + +**MaxScale>** set server server1 slave + + + +## Clear server + +The clear server command is the complement to the set server command, it allows status bits related to a server to be cleared. + +**MaxScale>** clear server 0x6ec840 slave + +Likewise in user mode the server name may be given. + +**MaxScale>** clear server server1 slave + +## Reload users + +The reload users command is used to force a service to go back and reload the table of database users from the backend database. This is the data used in the transparent authentication mechanism in the MySQL protocol. The command should be passed the address of the service as shown in the output of the show services command. + +**MaxScale>** show services + +Service 0x6edc10 + + Service: Test Service + + Router: readconnroute (0x7ffff128ea40) + + Number of router sessions: 257 + + Current no. of router sessions: 0 + + Number of queries forwarded: 1000193 + + Started: Mon Jul 22 11:31:21 2013 + + 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: 0x6ee4b0 + + Total connections: 258 + + Currently connected: 1 + +Service 0x6ec910 + + Service: Split Service + + Router: readwritesplit (0x7ffff1698460) + + Number of router sessions: 1 + + Current no. of router sessions: 0 + + Number of queries forwarded: 2 + + Number of queries forwarded to master: 0 + + Number of queries forwarded to slave: 1 + + Number of queries forwarded to all: 1 + + Started: Mon Jul 22 11:31:21 2013 + + Backend databases + + 127.0.0.1:3308 Protocol: MySQLBackend + + 127.0.0.1:3307 Protocol: MySQLBackend + + 127.0.0.1:3306 Protocol: MySQLBackend + + Users data: 0x6ed9b0 + + Total connections: 2 + + Currently connected: 1 + +Service 0x649190 + + Service: Debug Service + + Router: debugcli (0x7ffff18a0620) + + Started: Mon Jul 22 11:31:21 2013 + + Backend databases + + Users data: 0x64bd80 + + Total connections: 2 + + Currently connected: 2 + +**MaxScale>** reload users 0x6edc10 + +Loaded 34 users. + +**MaxScale>** + +If user mode is in use then the service name may be given. + +**MaxScale>** reload users "Test Service" + +Loaded 34 users. + + **MaxScale>** + +## Reload config + +The reload config command can be used to force MaxScale to re-read the MaxScale.cnf and update itself to the latest configuration defined in that configuration file. It is also possible to force the reading of the configuration file by sending a HangUp signal (SIGHUP) to the maxscale process. + +**MaxScale>** reload config + +Reloading configuration from file. + +**MaxScale>** + +Note, not all configuration elements can be changed dynamically currently. This mechanism can be used to add new services, servers to services, listeners to services and to update passwords. It can not be used to remove services, servers or listeners currently. + +## Add user + +The add user command is used to add new users to the debug CLI of MaxScale. The default behaviour of the CLI for MaxScale is to have a login name of admin and a fixed password of skysql. Adding new users will disable this default behaviour and limit the login access to the users that are added. + +**MaxScale>** add user admin july2013 + +User admin has been successfully added. + +**MaxScale>** add user mark hambleden + +User mark has been successfully added. + +**MaxScale>** + +User names must be unique within the debug CLI, this excludes the admin default user, which may be redefined. + +**MaxScale>** add user mark 22july + +User admin already exists. + +**MaxScale>**** ** + +If you should forget or lose the the account details you may simply remove the passwd file in $MAXSCALE_HOME/etc and the system will revert to the default behaviour with admin/skysql as the account. + +## Enable/disable log + +The enable/disable log command is used to enable/disable the log facility of MaxScale. The default behaviour for MaxScale is to have all logs enabled in DEBUG version, and only error log in production release. + +Examples: + +**MaxScale>** help enable log + +Available options to the enable command: + + log Enable Log options for MaxScale, options trace | error | message E.g. enable log message. + +**MaxScale>** help disable log + +Available options to the disable command: + + log Disable Log for MaxScale, Options: debug | trace | error | message E.g. disable log debug + +**MaxScale>** disable log trace + +**MaxScale>** + +No output for these commands in the debug interface, but in the affected logs there is a message: + +2013 11/14 16:08:33 --- Logging is disabled -- + +# Logging facility + +MaxScale generates output of its behavior to four distinct logs, error, messages, trace and debug log. Error and message logs are enabled by default but all logs can be dynamically enabled and disabled by using maxadm utility, debug client interface (telnet) or optionally by using your own application through the client API. + +## Log contents + +By default all log files are located in : $MAXSCALE_HOME/log and named as : + +skygw_errW.log, skygw_msgX.log, skygw_traceY.log and skygw_debugZ.log + +where W, X, Y, and Z are sequence numbers for files within the same directory, + +### Error log + +Error log includes errors and warnings; things that occur during runtime and of which the user should at least be aware of. An entry in error log doesn’t necessarily mean a problem - it may be a notification of failed backend server, for example. + +Example: + +MariaDB Corporation MaxScale /home/jdoe/bin/develop/log/skygw_err1.log Mon Dec 8 13:28:15 2014 + +----------------------------------------------------------------------- + +--- Logging is enabled. + +2014-12-08 13:28:15 Error : Unable to find filter 'testfi' for service 'RW Split Router' + +2014-12-08 13:28:26 MaxScale received signal SIGINT. Shutting down. + +2014-12-08 13:28:27 MaxScale is shut down. + +----------------------------------------------------------------------- + +### Message log + +The content of message log consists of information about loaded modules, opened listen ports and other information about file locations etc. The amount of data written in message log is typically very small. + +Example: + +MariaDB Corporation MaxScale /home/jdoe/bin/develop/log/skygw_msg1.log Tue Dec 9 14:47:05 2014 + +----------------------------------------------------------------------- + +--- Logging is enabled. + +2014-12-09 14:47:05 Home directory : /home/jdoe/bin/develop + +2014-12-09 14:47:05 Data directory : /home/jdoe/bin/develop/data/data5398 + +2014-12-09 14:47:05 Log directory : /home/jdoe/bin/develop/log + +2014-12-09 14:47:05 Configuration file : /home/jdoe/bin/develop/etc/MaxScale.cnf + +2014-12-09 14:47:05 Initialise CLI router module V1.0.0. + +2014-12-09 14:47:05 Loaded module cli: V1.0.0 from /home/jdoe/bin/develop/modules/libcli.so + +2014-12-09 14:47:05 Initialise debug CLI router module V1.1.1. + +2014-12-09 14:47:05 Loaded module debugcli: V1.1.1 from /home/jdoe/bin/develop/modules/libdebugcli.so + +2014-12-09 14:47:05 Loaded module testroute: V1.0.0 from /home/jdoe/bin/develop/modules/libtestroute.so + +2014-12-09 14:47:05 Initialise readconnroute router module V1.1.0. + +2014-12-09 14:47:05 Loaded module readconnroute: V1.1.0 from /home/jdoe/bin/develop/modules/libreadconnroute.so + +2014-12-09 14:47:05 Initializing statemend-based read/write split router module. + +2014-12-09 14:47:05 Loaded module readwritesplit: V1.0.2 from /home/jdoe/bin/develop/modules/libreadwritesplit.so + +2014-12-09 14:47:05 Initialise the MySQL Monitor module V1.4.0. + +2014-12-09 14:47:05 Loaded module mysqlmon: V1.4.0 from /home/jdoe/bin/develop/modules/libmysqlmon.so + +2014-12-09 14:47:05 MariaDB Corporation MaxScale 1.0.1-beta (C) MariaDB Corporation Ab 2013-2014 + +2014-12-09 14:47:05 MaxScale is running in process 5398 + +2014-12-09 14:47:05 Encrypted password file /home/jdoe/bin/develop/etc/.secrets can't be accessed (No such file or directory). Password encryption is not used. + +2014-12-09 14:47:05 Loaded 6 MySQL Users for service [RW Split Router]. + +2014-12-09 14:47:05 Loaded module MySQLClient: V1.0.0 from /home/jdoe/bin/develop/modules/libMySQLClient.so + +2014-12-09 14:47:05 Loaded 8 MySQL Users for service [Read Connection Router]. + +2014-12-09 14:47:05 Loaded module telnetd: V1.0.1 from /home/jdoe/bin/develop/modules/libtelnetd.so + +2014-12-09 14:47:05 Loaded module maxscaled: V1.0.0 from /home/jdoe/bin/develop/modules/libmaxscaled.so + +2014-12-09 14:47:05 Info: A Master Server is now available: 127.0.0.1:3000 + +2014-12-09 14:47:10 MaxScale is shut down. + +----------------------------------------------------------------------- + +### Trace log + +Trace log includes information about available servers and their states, client sessions, queries being executed, routing decisions and other routing related data. Trace log can be found from the same directory with other logs but it is physically stored elsewhere, to OSs shared memory to reduce the latency caused by logging. The location of physical file is : /dev/shm//skygw_traceX.log where ‘X’ is the same sequence number as in the file name in the $MAXSCALE_HOME/log directory. + +Individual trace log entry looks similar to those in other logs but there is some difference too. Some log entries include a number within square brackets to specify which client session they belong to. For example: + +2014-12-09 14:52:36 [6] Session write, routing to all servers. + +Writing trace log for each client may produce so much data that it seriously affects on the performance of MaxScale. It may also be difficult to follow a specific session if the log is flooded with data from other sessions. While it is possible to dynamically enable and disable trace log as a whole, one can also choose to explicitly enable trace logging for a specific session by first enabling trace log, finding out the session id of the interesting session, disabling trace log and finally enabling trace log only for a given session: + +1. enable log trace (and examine the session id) + +2. disable log trace + +3. enable sessionlog trace + +Example of trace log: + +MariaDB Corporation MaxScale /dev/shm/5420/skygw_trace1.log Tue Dec 9 14:51:29 2014 + +----------------------------------------------------------------------- + +--- Logging is disabled. + +2014-12-09 14:51:52 --- Logging is enabled -- + +2014-12-09 14:52:03 Servers and router connection counts: + +2014-12-09 14:52:03 current operations : 0 in 127.0.0.1:3003 RUNNING SLAVE + +2014-12-09 14:52:03 current operations : 0 in 127.0.0.1:3002 RUNNING SLAVE + +2014-12-09 14:52:03 current operations : 0 in 127.0.0.1:3000 RUNNING MASTER + +2014-12-09 14:52:03 Selected RUNNING SLAVE in 127.0.0.1:3003 + +2014-12-09 14:52:03 Selected RUNNING SLAVE in 127.0.0.1:3002 + +2014-12-09 14:52:03 Selected RUNNING MASTER in 127.0.0.1:3000 + +... + +2014-12-09 14:52:28 [6] > Autocommit: [enabled], trx is [not open], cmd: COM_QUERY, type: QUERY_TYPE_READ, stmt: select count(*) from user + +2014-12-09 14:52:28 [6] Route query to slave 127.0.0.1:3003 < + +2014-12-09 14:52:36 [6] Disable autocommit : implicit START TRANSACTION before executing the next command. + +2014-12-09 14:52:36 [6] > Autocommit: [disabled], trx is [open], cmd: COM_QUERY, type: QUERY_TYPE_GSYSVAR_WRITE|QUERY_TYPE_BEGIN_TRX|QUERY_TYPE_DISABLE_AUTOCOMMIT, stmt: set autocommit=0 + +2014-12-09 14:52:36 [6] Session write, routing to all servers. + +2014-12-09 14:52:36 [6] Route query to slave 127.0.0.1:3003 + +2014-12-09 14:52:36 [6] Route query to slave 127.0.0.1:3002 + +2014-12-09 14:52:36 [6] Route query to master 127.0.0.1:3000 < + +2014-12-09 14:52:39 [6] > Autocommit: [disabled], trx is [open], cmd: COM_QUERY, type: QUERY_TYPE_BEGIN_TRX, stmt: begin + +2014-12-09 14:52:39 [6] Route query to master 127.0.0.1:3000 < + +2014-12-09 14:52:51 [6] > Autocommit: [disabled], trx is [open], cmd: COM_QUERY, type: QUERY_TYPE_READ, stmt: select count(*) from user + +2014-12-09 14:52:51 [6] Route query to master 127.0.0.1:3000 < + +2014-12-09 14:52:59 Servers and router connection counts: + +2014-12-09 14:52:59 current operations : 0 in 127.0.0.1:3003 RUNNING SLAVE + +2014-12-09 14:52:59 current operations : 0 in 127.0.0.1:3002 RUNNING SLAVE + +2014-12-09 14:52:59 current operations : 0 in 127.0.0.1:3000 RUNNING MASTER + +2014-12-09 14:52:59 Selected RUNNING SLAVE in 127.0.0.1:3003 + +2014-12-09 14:52:59 Selected RUNNING SLAVE in 127.0.0.1:3002 + +2014-12-09 14:52:59 Selected RUNNING MASTER in 127.0.0.1:3000 + +2014-12-09 14:52:59 Started RW Split Router client session [7] for 'maxuser' from 127.0.0.1 + +In the log, session’s life cycle is covered by annotating its beginning and the end. During the session, each statement is surrounded with ‘>’ and ‘<’ characters. Entries without ‘[]’ belong to other than client sessions, monitor, for example. + +## Managing logs + +The log files are located in + +$MAXSCALE_HOME/log + +by default. If, however, trace and debug logs are enabled, only a soft link is created there. MaxScale process creates a directory under + +/dev/shm/ + +where it stores the physical trace and debug log files. Link and physical files share the same name. These logs consume the main memory of the host they run on so it is important to archive or remove them periodically to avoid unnecessary main-memory consumption. + +## Rotating logs + +Log files may grow very large over time and that is why users may want to split log files into several smaller ones. That is called log rotation. User can rotate all logs by executing + +flush logs + +Specific log file can be rotated by executing + +flush log [error|message|trace|debug] + +The commands above can be executed either by using maxadmin utility or via debug client API with telnet. The sequence number included in the log filename is used to separate files from each other. The logic behind sequence numbering is such that if the log directory is empty when MaxScale is started, new log files will be created with sequence number 1 in their names, skygw_err1.log, for example. If files of the same type already exist, the new MaxScale process opens the file with largest sequence number and applies into it. If existing log file isn’t writable for the user that MaxScale runs on, new log file will be created with bigger sequence number. + +More information about log files and administering them can be found from **MaxScale Administration Tutorial**. + diff --git a/Reference/How-errors-are-handled-in-MaxScale.md b/Reference/How-errors-are-handled-in-MaxScale.md new file mode 100644 index 000000000..28ac113ce --- /dev/null +++ b/Reference/How-errors-are-handled-in-MaxScale.md @@ -0,0 +1,56 @@ +# How errors are handled in MaxScale + +This document describes how errors are handled in 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 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 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 SESSION_ROUTE_QUERY has returned successfully (=1) query may not be successfully processed in backend or even sent to it. It is posible 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). + diff --git a/Reference/MaxAdmin.md b/Reference/MaxAdmin.md new file mode 100644 index 000000000..7834efc22 --- /dev/null +++ b/Reference/MaxAdmin.md @@ -0,0 +1,1355 @@ +MaxAdmin + +The MaxScale Administrative + +& Monitoring Client Application + +Mark Riddoch + +Last Updated: 19th November 2014 + +# Contents + +[[TOC]] + +# Overview + +MaxAdmin is a simple client interface that can be used to interact with the MaxScale server, it allows the display of internal MaxScale statistics, status and control of MaxScale operations. + +MaxAdmin supports + +* Interactive user sessions + +* Execution of one-off commands via command line arguments + +* Execution of command scripts + +# Running MaxAdmin + +The MaxAdmin client application may be run in two different modes, either as an interactive command shell for executing commands against MaxScale or by passing commands on the MaxAdmin command line itself. + +## Command Line Switches + +The MaxAdmin command accepts a number of switches + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SwitchLong OPtionDescription
-u user--user=...Sets the username that will be used for the MaxScale connection. If no -u option is passed on the MaxAdmin command line then the default username of ‘admin’ will be used.
-p password--password=...Sets the user password that will be used. If no -p option is passed on the command line then MaxAdmin will prompt for interactive entry of the password.
-h hostname--hostname=...The hostname of the MaxScale server to connect to. If no -h option is passed on the command line then MaxAdmin will attempt to connect to the host ‘localhost’.
-P port--port=...The port that MaxAdmin will use to connect to the MaxScale server. if no -P option is given then the default port of 6603 will be used.
-?--helpPrint usage information regarding MaxAdmin
-v--versionPrint the maxadmin version information and exit
+ + +When a switch takes a value, this may either be as the next argument on the command line or maybe as part of the switch itself. E.g. -u me and -ume are treated in the same way. + +## Interactive Operation + +If no arguments other than the command line switches are passed to MaxAdmin it will enter its interactive mode of operation. Users will be prompted to enter commands with a **MaxScale>** prompt. The commands themselves are documented in the sections later in this document. A help system is available that will give some minimal details of the commands available. + +Command history is available on platforms that support the libedit library. This allows the use of the up and down arrow keys to recall previous commands that have been executed by MaxAdmin. The default edit mode for the history is to emulate the vi commands, the behaviour of libedit may however be customised using the .editrc file. To obtain the history of commands that have been executed use the inbuilt history command. + +In interactive mode it is possible to execute a set of commands stored in an external file by using the source command. The command takes the argument of a filename which should contain a set of MaxScale commands, one per line. These will be executed in the order they appear in the file. + +## Command Line Operation + +MaxAdmin can also be used to execute commands that are passed on the command line, e.g. + +-bash-4.1$ maxadmin -hmaxscale list services + +Password: + +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 | 27 + +--------------------------+----------------------+--------+--------------- + +-bash-4.1$ + +The single command is executed and MaxAdmin then terminates. If the -p option is not given then MaxAdmin will prompt for a password. If a MaxScale command requires an argument which contains whitespace, for example a service name, that name should be quoted. The quotes will be preserved and used in the execution of the MaxScale command. + +-bash-4.1$ maxadmin show service "QLA Service" + +Password: + +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 + +-bash-4.1$ + +Command files may be executed by either calling MaxAdmin with the name of the file that contains the commands + +maxadmin listall.ms + +Or by using the #! mechanism to make the command file executable from the shell. To do this add a line at the start of your command file that contains the #! directive with the path of the MaxAdmin executable. Command options may also be given in this line. For example to create a script file that runs a set of list commands + +#!/usr/local/bin/maxadmin -hmaxscalehost + +list modules + +list servers + +list services + +list listeners + +list dcbs + +list sessions + +list filters + +Then simply set this file to have execute permissions and it may be run like any other command in the Linux shell. + +# Getting Help + +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. + +MaxScale> help + +Available commands: + + add user + + clear server + + disable [heartbeat|log|root] + + enable [heartbeat|log|root] + + list [clients|dcbs|filters|listeners|modules|monitors|services|servers|sessions] + + reload [config|dbusers] + + remove user + + restart [monitor|service] + + set server + + show [dcbs|dcb|dbusers|epoll|filter|filters|modules|monitor|monitors|server|servers|services|service|session|sessions|users] + + shutdown [maxscale|monitor|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 ". + +MaxScale> + +To see more detail on a particular command, and a list of the sub commands of the command, type help followed by the command name. + +MaxScale> help list + +Available options to the list command: + + clients List all the client connections to MaxScale + + dcbs List all the DCBs active within MaxScale + + filters List all the filters defined within MaxScale + + listeners List all the listeners defined within MaxScale + + modules List all currently loaded modules + + monitors List all monitors + + services List all the services defined within MaxScale + + servers List all the servers defined within MaxScale + + sessions List all the active sessions within MaxScale + +MaxScale> + +# Working With Services + +A service is a very important concept in MaxScale as it defines the mechanism by which clients interact with MaxScale and can attached to the backend databases. A number of commands exist that allow interaction with the services. + +## What Services Are Available? + +The list services command can be used to discover what services are currently available within your 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 + +--------------------------+----------------------+--------+--------------- + +MaxScale> + +In order to determine which ports services are using then the list listeners 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 + +---------------------+--------------------+-----------------+-------+-------- + +MaxScale> + +## See Service Details + +It is possible to see the details of an individual service using the show service command. This command should be passed the name of the service you wish 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> + +This allows the set of backend servers defined by the service to be seen along with the service statistics and other information. + +## Examining Service Users + +MaxScale provides an authentication model by which the client application authenticates with MaxScale using the credentials they would normally use to with the database itself. MaxScale loads the user data from one of the backend databases defined for the service. The show dbusers command can be used to examine the user data held by MaxScale. + +MaxScale> show dbusers "Filter Service" + +Users table data + +Hashtable: 0x723e50, size 52 + + No. of entries: 48 + + Average chain length: 0.9 + + Longest chain length: 5 + +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> + +## Reloading Service User Data + +MaxScale will automatically reload user data if there are failed authentication requests from client applications. This reloading is rate limited and triggered by missing entries in the MaxScale table. If a user is removed from the backend database user table it will not trigger removal from the MaxScale internal table. The reload dbusers command can be used to force the reloading of the user table within MaxScale. + +MaxScale> reload dbusers "Split Service" + +Loaded 34 database users for service Split Service. + +MaxScale> + +## Stopping A Service + +It is possible to stop a service from accepting new connections by using the shutdown service command. This will not affect the connections that are already in place for a service, but will stop any new connections from being accepted. + +MaxScale> shutdown service "Split Service" + +MaxScale> + +## Restart A Stopped Service + +A stopped service may be restarted by using the restart service command. + +MaxScale> restart service "Split Service" + +MaxScale> + +# Working With Servers + +The server represents each of the instances of MySQL or MariaDB that a service may use. + +## What Servers Are Configured? + +The command list servers can be used to display a list of all the servers configured within 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 Details + +It is possible to see more details regarding a given server using the show 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 + +MaxScale> + +## Setting The State Of A Server + +MaxScale maintains a number of status bits for each server that is configured, these status bits are normally maintained by the monitors, there are two commands in the user interface that are used to manually maintain these bits also; the set server and clear server commands. + +The status bit that can be controlled are + + + + + + + + + + + + + + + + + + + + + + + + + + +
Bit NameDescription
runningThe server is responding to requests, accepting connections and executing database commands
masterThe server is a master in a replication setup or should be considered as a destination for database updates.
slaveThe server is a replication slave or is considered as a read only database.
syncedThe server is a fully fledged member of a Galera cluster
maintenanceThe server is in maintenance mode. In this mode no new connections will be established to the server. The monitors will also not monitor servers that are in maintenance mode.
+ + +All status bits, with the exception of the maintenance bit, will be set by the monitors that are monitoring the server. If manual control is required the monitor should be stopped. + +MaxScale> set server server3 maintenance + +MaxScale> clear server server3 maintenance + +MaxScale> + +# Working With Sessions + +The MaxScale session represents the state within MaxScale. Sessions are dynamic entities and not named in the configuration file, this means that sessions can not be easily named within the user interface. The sessions are referenced using ID values, these are actually memory address, however the important thing is that no two session have the same ID. + +## What Sessions Are Active in MaxScale? + +There are a number of ways to find out what sessions are active, the most 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 + +-----------------+-----------------+----------------+-------------------------- + +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> + +## Display Session Details + +Once the session ID has been determined using one of the above method it is 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> + +# Descriptor Control Blocks + +The Descriptor Control Block or DCB is a very important entity within MaxScale, it represents the state of each connection within MaxScale. A DCB is allocated for every connection from a client, every network listener and every connection to a backend database. Statistics for each of these connections are maintained within these DCB’s. + +As with session above the DCB’s are not named and are therefore referred to by the use of a unique ID, the memory address of the DCB. + +## Finding DCB’s + +There are several ways to determine what DCB’s are active within a 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> + +A MaxScale server that has activity on it will however have many more DCB’s than in the example above, making it hard to find the DCB that you require. The DCB ID is also included in a number of other command outputs, depending on the information you have it may be easier to use other methods to locate a particular DCB. + +## DCB Of A Client Connection + +To find the DCB for a particular client connection it may be best to start with the list clients command and then look at each DCB for a particular client address to determine the one of interest. + +## DCB Details + +The details of an individual DCB can be obtained by use of the show dcb command + +MaxScale> show dcb 0x727900 + +DCB: 0x727900 + + DCB state: DCB in the polling loop + + 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 + +MaxScale> + +# Working with Filters + +Filters allow the request contents and result sets from a database to be modified for a client connection, pipelines of filters can be created between the client connection and MaxScale router modules. + +## What Filters Are Configured? + +Filters are configured in the configuration file for MaxScale, they are given names and may be included in the definition of a service. The list filters command can be used to determine which filters are defined. + +MaxScale> list filters + +Filters + +--------------------+-----------------+---------------------------------------- + +Filter | Module | Options + +--------------------+-----------------+---------------------------------------- + +counter | testfilter | + +QLA | qlafilter | /tmp/QueryLog + +Replicate | tee | + +QLA_BLR | qlafilter | /tmp/QueryLog.blr0 + +regex | regexfilter | + +MySQL5.1 | regexfilter | + +top10 | topfilter | + +--------------------+-----------------+---------------------------------------- + +MaxScale> + +## Retrieve Details Of A Filter Configuration + +The command show filter can be used to display information related to a particular filter. + +MaxScale> show filter QLA + +Filter 0x719460 (QLA) + + Module: qlafilter + + Options: /tmp/QueryLog + + Limit logging to connections from 127.0.0.1 + + Include queries that match select.*from.*user.*where + +MaxScale> + +## Filter Usage + +The show session command will include details for each of the filters in use 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> + +The data displayed varies from filter to filter, the example above is the top filter. This filter prints a report of the current top queries at the time the show session command is run. + +# Working With Monitors + +Monitors are used to monitor the state of databases within MaxScale in order to supply information to other modules, specifically the routers within MaxScale. + +## What Monitors Are Running? + +To see what monitors are running within MaxScale use the list monitors command. + +MaxScale> list monitors + ++----------------------+--------------------- + +| Monitor | Status + ++----------------------+--------------------- + +| MySQL Monitor | Running + ++----------------------+--------------------- + +MaxScale> + +## Details Of A Particular Monitor + +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> + +## Controlling Replication Heartbeat + +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. + +MaxScale> disable heartbeat "MySQL Monitor" + +MaxScale> enable heartbeat "MySQL Monitor" + +MaxScale> + +Please note that changes made via this interface will not persist across restarts of MaxScale. To make a permanent change edit the MaxScale.cnf file. + +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> + +## Shutting Down A Monitor + +A monitor may be shutdown using the shutdown monitor command. This allows for manual control of the status of servers using the set server and clear server commands. + +MaxScale> shutdown monitor "MySQL Monitor" + +MaxScale> list monitors + ++----------------------+--------------------- + +| Monitor | Status + ++----------------------+--------------------- + +| MySQL Monitor | Stopped + ++----------------------+--------------------- + +MaxScale> + +## Restarting A Monitor + +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> + +# Working With Administration Interface Users + +A default installation of MaxScale allows connection to the administration interface using the username of admin and the password skysql. This username and password stay in effect as long as no other users have been created for the administration interface. As soon as the first user is added the use of admin/skysql as login credentials will be disabled. + +## What Users Have Been Defined? + +In order to see the current users that have been defined for the administration interface use the command show users. + +MaxScale> show users + +Administration interface users: + +Users table data + +Hashtable: 0x734470, size 52 + + No. of entries: 5 + + Average chain length: 0.1 + + Longest chain length: 2 + +User names: vilho, root, dba, massi, mark + +MaxScale> + +Please note that if no users have been configured the default admin/skysql user will not be shown. + +MaxScale> show users + +Administration interface users: + +No administration users have been defined. + +MaxScale> + +## Add A New User + +To add a new administrative user to the MaxScale server use the command add user. This command is passed a user name and a password. + +MaxScale> add user maria dtbse243 + +User maria has been successfully added. + +MaxScale> + +## Delete A User + +To remove a user the command remove user is used, it must also be called with the username and password of the user. The password will be checked. + +MaxScale> remove user maria des + +Failed to remove user maria. Authentication failed + +MaxScale> remove user maria dtbse243 + +User maria has been successfully removed. + +MaxScale> + +# MaxScale Status Commands + +A number of commands exists that enable the internal MaxScale status to be revealed, these commands give an insight to how MaxScale is using resource internally and are used to allow the tuning process to take place. + +## MaxScale Thread Usage + +MaxScale uses a number of threads, as defined in the MaxScale configuration file, to execute the processing of requests received from clients and the handling of responses. The show threads command can be used to 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 + +Pending event queue length averages: + +15 Minute Average: 0.90, 5 Minute Average: 1.83, 1 Minute Average: 2.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> + +The resultant output returns data as to the average thread utilisation for the past minutes 5 minutes and 15 minutes. It also gives a table, with a row per 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 MaxScale is an event driven engine that is processing network events for the network connections between MaxScale and client applications and 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 currenting in the event queue, the events queued for that DCB, and events that are beign processed for that DCB. + +## The Housekeeper Tasks + +Internally MaxScale has a housekeeper thread that is used to perform periodic tasks, it is possible to use the command show tasks to see what tasks 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> + +# Administration Commands + +## What Modules Are In use? + +In order to determine what modules are in use, and the version and status of 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> + +This command provides important version information for the module. Each module has two versions; the version of the module itself and the version of the module API that it supports. Also included in the output is the status of the module, this may be "In Development", “Alpha”, “Beta”, “GA” or “Experimental”. + +## Rotating the log files + +MaxScale write a number of log files in the log directory within MaxScale home directory. The default option for these is that the grow continually, it is recommended that periodically the log files are rotated. This will close the current log file and open a new one with a new name. The log file names use a sequence number which is incremented each time the logs are rotated. + +It is possible to rotate just a single log file, using the flush log command and the name of the log to flush. The names that are recognised by MaxAdmin are error, message, trace or debug. + +MaxScale> flush log message + +MaxScale> + +The flush logs command may be used to rotate all logs with a single command. + +MaxScale> flush log + +MaxScale> + +## Change MaxScale Logging Options + +Two commands are provided to change the logging levels within MaxScale, disable log and enable log. Using these commands the various log levels can be turned on and off, the supported levels are trace, debug and message. The error log level can not be turned off. + +MaxScale> enable log trace + +MaxScale> disable log debug + +MaxScale> + +Please note that changes made via this interface will not persist across restarts of MaxScale. To make a permanent change edit the MaxScale.cnf file. + +## Reloading The Configuration + +A command, reload config, is available that will cause MaxScale to reload the MaxScale.cnf configuration file. + +## Shutting Down MaxScale + +The MaxScale server may be shutdown using the shutdown maxscale command. + +# Configuring MaxScale to Accept MaxAdmin Connections + +In order to allow the use of the MaxAdmin client interface the service must be added to the MaxScale.cnf file of the Maxscale server. The CLI service itself must be added and a listener for the maxscaled protocol. + +The default entries required are shown below. + +[CLI] + +type=service + +router=cli + +[CLI Listener] + +type=listener + +service=CLI + +protocol=maxscaled + +address=localhost + +port=6603 + +Note that this uses the default port of 6603 and confines the connections to localhost connections only. Remove the address= entry to allow connections from any machine on your network. Changing the port from 6603 will mean that you must allows pass a -p option to the MaxAdmin command. + +# Tuning MaxScale + +The way that MaxScale does it’s polling is that each of the polling threads, as defined by the threads parameter in the configuration file, will call epoll_wait to obtain the events that are to be processed. The events are then added to a queue for execution. Any thread can read from this queue, not just the thread that added the event. + +Once the thread has done an epoll call with no timeout it will either do an epoll_wait call with a timeout or it will take an event from the queue if there is one. These two new parameters affect this behaviour. + +The first parameter, which may be set by using the non_blocking_polls option in the configuration file, controls the number of epoll_wait calls that will be issued without a timeout before MaxScale will make a call with a timeout value. The advantage of performing a call without a timeout is that the kernel treats this case as different and will not rescheduled the process in this case. If a timeout is passed then the system call will cause the MaxScale thread to be put back in the scheduling queue and may result in lost CPU time to MaxScale. Setting the value of this parameter too high will cause MaxScale to consume a lot of CPU when there is infrequent work to be done. The default value of this parameter is 3. + +This parameter may also be set via the maxadmin client using the command set nbpolls . + +The second parameter is the maximum sleep value that MaxScale will pass to epoll_wait. What normally happens is that MaxScale will do an epoll_wait call with a sleep value that is 10% of the maximum, each time the returns and there is no more work to be done MaxScale will increase this percentage by 10%. This will continue until the maximum value is reached or until there is some work to be done. Once the thread finds some work to be done it will reset the sleep time it uses to 10% of the maximum. + +The maximum sleep time is set in milliseconds and can be placed in the [maxscale] section of the configuration file with the poll_sleep parameter. Alternatively it may be set in the maxadmin client using the command set pollsleep . The default value of this parameter is 1000. + +Setting this value too high means that if a thread collects a large number of events and adds to the event queue, the other threads might not return from the epoll_wait calls they are running for some time resulting in less overall performance. Setting the sleep time too low will cause MaxScale to wake up too often and consume CPU time when there is no work to be done. + +The show epoll command can be used to see how often we actually poll with a timeout, the first two values output are significant. Also the "Number of wake with pending events" is a good measure. This is the count of the number of times a blocking call returned to find there was some work waiting from another thread. If the value is increasing rapidly reducing the maximum sleep value and 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 + +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> + +If the "Number of DCBs with pending events" grows rapidly it is an indication that MaxScale needs more threads to be able to keep up with the load it is under. + +The show threads command can be used to see the historic average for the pending events queue, it gives 15 minute, 5 minute and 1 minute averages. The load average it displays is the event count per poll cycle data. An idea load is 1, in this case MaxScale threads and fully occupied but nothing is waiting for threads to become available for processing. + +The show eventstats command can be used to see statistics about how long events have been queued before processing takes place and also how long the 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 + + | 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> + +The statics are defined in 100ms buckets, with the count of the events that fell into that bucket being recorded. + diff --git a/Reference/MaxScale-HA-with-Corosync-Pacemaker.md b/Reference/MaxScale-HA-with-Corosync-Pacemaker.md new file mode 100644 index 000000000..a4dd35125 --- /dev/null +++ b/Reference/MaxScale-HA-with-Corosync-Pacemaker.md @@ -0,0 +1,658 @@ +How to make MaxScale High Available + +Corosync/Pacemaker setup + +& MaxScale init script + +Massimiliano Pinto + +Last Updated: 4th August 2014 + +# Contents + +[Contents](#heading=h.myvf4p2ngdc5) + +[Overview](#heading=h.92d1rpk8nyx4) + +[Clustering Software installation](#heading=h.c1l0xy6aynl7) + +[MaxScale init script](#heading=h.cfb6xvv8fu1n) + +[Configure MaxScale for HA](#heading=h.qk4cgmtiugm0) + + [Use case: failed resource is restarted](#heading=h.3fszf28iz3m5) + + [Use case: failed resource migration on a node is started in another one](#heading=h.erqw535ttk7l) + +[Add a Virtual IP (VIP) to the cluster](#heading=h.vzslsgvxjyug) + +# Overview + +The document shows an example of a Pacemaker / Corosync setup with MaxScale based on Linux Centos 6.5, using three virtual servers and unicast heartbeat mode with the following minimum requirements: + +- MaxScale process is started/stopped and monitored via /etc/init.d/maxscale script that is LSB compatible in order to be managed by Pacemaker resource manager + +- A Virtual IP is set providing the access to the MaxScale process that could be set to one of the cluster nodes + +- Pacemaker/Corosync and crmsh command line tool basic knowledge + +Please note the solution is a quick setup example that may not be suited for all production environments. + +# Clustering Software installation + +On each node in the cluster do the following steps: + +(1) Add clustering repos to yum + +# vi /etc/yum.repos.d/ha-clustering.repo + +Add the following to the file + +[haclustering] + +name=HA Clustering + +baseurl=http://download.opensuse.org/repositories/network:/ha-clustering:/Stable/CentOS_CentOS-6/ + +enabled=1 + +gpgcheck=0 + +(2) Install the software + +# yum install pacemaker corosync crmsh + +Package versions used + +Package** pacemake**r-1.1.10-14.el6_5.3.x86_64 + +Package **corosync**-1.4.5-2.4.x86_64 + +Package **crmsh**-2.0+git46-1.1.x86_64 + +(3) Assign hostname on each node + + + +In this example the three names used for the nodes are: + + **node1,node,node3** + +# hostname **node1** + +... + +# hostname nodeN + +(4) For each node add server names in /etc/hosts + +[root@node3 ~]# vi /etc/hosts + +10.74.14.39 node1 + +10.228.103.72 node2 + +10.35.15.26 node3 current-node + +[root@node1 ~]# vi /etc/hosts + +10.74.14.39 node1 current-node + +10.228.103.72 node2 + +10.35.15.26 node3 + +... + +**Please 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 + +On one of the nodes, say node2 run the corosync-keygen utility and follow + +[root@node2 ~]# corosync-keygen + +Corosync Cluster Engine Authentication key generator. Gathering 1024 bits for key from /dev/random. Press keys on your keyboard to generate entropy. + +After completion the key will be found in /etc/corosync/authkey. + +(6) Prepare the corosync configuration file + +Using node2 as an example: + +[root@node2 ~]# vi /etc/corosync/corosync.conf + +Add the following to the file: + +# Please read the corosync.conf.5 manual page + +compatibility: whitetank + +totem { + + version: 2 + + secauth: off + + interface { + + member { + + memberaddr: node1 + + } + + member { + + memberaddr: node2 + + } + + member { + + memberaddr: node3 + + } + + ringnumber: 0 + + bindnetaddr: current-node + + mcastport: 5405 + + ttl: 1 + + } + + transport: udpu + +} + +logging { + + fileline: off + + to_logfile: yes + + to_syslog: yes + + logfile: /var/log/cluster/corosync.log + + debug: off + + timestamp: on + + logger_subsys { + + subsys: AMF + + debug: off + + } + +} + +# this will start Pacemaker processes + +service { + +ver: 0 + +name: pacemaker + +} + +**Please note **in this example: + +- unicast UDP is used + +- bindnetaddr for corosync process is current-node, that has the right value on each node due to the alias added in /etc/hosts above + +- 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 + +[root@node2 ~]# scp /etc/corosync/* root@node1:/etc/corosync/ + +[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: + +[root@node2 ~]# service iptables stop + +… + +[root@nodeN ~]# service iptables stop + +(9) Start Corosyn on each node: + +[root@node2 ~] #/etc/init.d/corosync start + +… + +[root@nodeN ~] #/etc/init.d/corosync start + +and check 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): + +[root@node2 ~] #echo "check ..." | nc -u node1 5405 + +[root@node2 ~] #echo "check ..." | nc -u node3 5405 + +... + +[root@node1 ~] #echo "check ..." | nc -u node2 5405 + +[root@node1 ~] #echo "check ..." | nc -u node3 5405 + +… + +If the following message is displayed + +**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. + +(10) Check the cluster status, from any node + +[root@node3 ~]# crm status + +After a while this will be the output: + +[root@node3 ~]# crm status + +Last updated: Mon Jun 30 12:47:53 2014 + +Last change: Mon Jun 30 12:47:39 2014 via crmd on node2 + +Stack: classic openais (with plugin) + +Current DC: node2 - partition with quorum + +Version: 1.1.10-14.el6_5.3-368c726 + +3 Nodes configured, 3 expected votes + +0 Resources configured + +Online: [ node1 node2 node3 ] + +For the basic setup disable the following properties: + +- stonith + +- quorum policy + +[root@node3 ~]# crm configure property 'stonith-enabled'='false' + +[root@node3 ~]# crm configure property 'no-quorum-policy'='ignore' + +For more information see: + +[http://www.clusterlabs.org/doc/crm_fencing.html](http://www.clusterlabs.org/doc/crm_fencing.html) + +[http://clusterlabs.org/doc/](http://clusterlabs.org/doc/) + +The configuration is automatically updated on every node: + +Check it from another node, say node1 + +[root@node1 ~]# crm configure show + +node node1 + +node node2 + +node node3 + +property cib-bootstrap-options: \ + + dc-version=1.1.10-14.el6_5.3-368c726 \ + + cluster-infrastructure="classic openais (with plugin)" \ + + expected-quorum-votes=3 \ + + stonith-enabled=false \ + + no-quorum-policy=ignore \ + + placement-strategy=balanced \ + + default-resource-stickiness=infinity + +The Corosync / Pacemaker cluster is ready to be configured to manage resources. + +# MaxScale init script /etc/init.d/maxscale + +The MaxScale /etc/init.d./maxscale script allows to start/stop/restart and monitor maxScale process running in the system. + +Edit it and modify the **MAXSCALE_BASEDIR** to match the installation directory you choose when you installed MaxScale. + +**Note**: + +It could be necessary to modify other variables, such as + +MAXSCALE_BIN, MAXSCALE_HOME, MAXSCALE_PIDFILE and LD_LIBRARY_PATH for a non standard setup. + +[root@node1 ~]# /etc/init.d/maxscale + +Usage: /etc/init.d/maxscale {start|stop|status|restart|condrestart|reload} + +- Start + +[root@node1 ~]# /etc/init.d/maxscale start + +Starting MaxScale: maxscale (pid 25892) is running... [ OK ] + +- Start again + +[root@node1 ~]# /etc/init.d/maxscale start + +Starting MaxScale: found maxscale (pid 25892) is running.[ OK ] + +- Stop + +[root@node1 ~]# /etc/init.d/maxscale stop + +Stopping MaxScale: [ OK ] + +- Stop again + +[root@node1 ~]# /etc/init.d/maxscale stop + +Stopping MaxScale: [FAILED] + +- Status (MaxScale not running) + +[root@node1 ~]# /etc/init.d/maxscale status + +MaxScale is stopped [FAILED] + +The script exit code for "status" is 3 + +- Status (MaxScale is running) + +[root@node1 ~]# /etc/init.d/maxscale status + +Checking MaxScale status: MaxScale (pid 25953) is running.[ OK ] + +The script exit code for "status" is 0 + + + + + +Note: the MaxScale script is LSB compatible and returns the proper exit code for each action: + +For more informations; + + [http://www.linux-ha.org/wiki/LSB_Resource_Agents](http://www.linux-ha.org/wiki/LSB_Resource_Agents) + +After checking maxScale is well managed by the /etc/init.d/script is possible to configure the MAxScale HA via Pacemaker. + +# Configure MaxScale for HA with Pacemaker + +[root@node2 ~]# crm configure primitive MaxScale lsb:maxscale \ + +op monitor interval="10s” timeout=”15s” \ + +op start interval="0” timeout=”15s” \ + +op stop interval="0” timeout=”30s” + +MaxScale resource will be started: + +[root@node2 ~]# crm status + +Last updated: Mon Jun 30 13:15:34 2014 + +Last change: Mon Jun 30 13:15:28 2014 via cibadmin on node2 + +Stack: classic openais (with plugin) + +Current DC: node2 - partition with quorum + +Version: 1.1.10-14.el6_5.3-368c726 + +3 Nodes configured, 3 expected votes + +1 Resources configured + +Online: [ node1 node2 node3 ] + + MaxScale (lsb:maxscale): Started node1 + +Basic use cases: + +# 1. Resource restarted after a failure: + +MaxScale Pid is, $MAXSCALE_PIDFILE=$MAXSCALE_HOME/log/maxscale.pid + +In the example is 26114, kill the process immediately: + +[root@node2 ~]# kill -9 26114 + +[root@node2 ~]# crm status + +Last updated: Mon Jun 30 13:16:11 2014 + +Last change: Mon Jun 30 13:15:28 2014 via cibadmin on node2 + +Stack: classic openais (with plugin) + +Current DC: node2 - partition with quorum + +Version: 1.1.10-14.el6_5.3-368c726 + +3 Nodes configured, 3 expected votes + +1 Resources configured + +Online: [ node1 node2 node3 ] + +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 + +After a few seconds it will be started again: + +[root@node2 ~]# crm status + +Last updated: Mon Jun 30 13:21:12 2014 + +Last change: Mon Jun 30 13:15:28 2014 via cibadmin on node1 + +Stack: classic openais (with plugin) + +Current DC: node2 - partition with quorum + +Version: 1.1.10-14.el6_5.3-368c726 + +3 Nodes configured, 3 expected votes + +1 Resources configured + +Online: [ node1 node2 node3 ] + + MaxScale (lsb:maxscale): Started node1 + +# 2. The resource cannot be migrated to node1 for a failure: + +First, migrate the the resource to another node, say node3 + +[root@node1 ~]# crm resource migrate MaxScale node3 + +... + +Online: [ node1 node2 node3 ] + +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 + +[root@node3 ~]# crm status + +Last updated: Mon Jun 30 13:35:00 2014 + +Last change: Mon Jun 30 13:31:13 2014 via crm_resource on node3 + +Stack: classic openais (with plugin) + +Current DC: node2 - partition with quorum + +Version: 1.1.10-14.el6_5.3-368c726 + +3 Nodes configured, 3 expected votes + +1 Resources configured + +Online: [ node1 node2 node3 ] + + MaxScale (lsb:maxscale): Started node2 + +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. + +**Note**: Failed actions remain in the output of crm status. + + With "crm resource cleanup MaxScale" is possible to cleanup the messages: + +[root@node1 ~]# crm resource cleanup MaxScale + +Cleaning up MaxScale on node1 + +Cleaning up MaxScale on node2 + +Cleaning up MaxScale on node3 + +The cleaned status is visible from other nodes as well: + +[root@node2 ~]# crm status + +Last updated: Mon Jun 30 13:38:18 2014 + +Last change: Mon Jun 30 13:38:17 2014 via crmd on node3 + +Stack: classic openais (with plugin) + +Current DC: node2 - partition with quorum + +Version: 1.1.10-14.el6_5.3-368c726 + +3 Nodes configured, 3 expected votes + +1 Resources configured + +Online: [ node1 node2 node3 ] + + MaxScale (lsb:maxscale): Started node2 + +# Add a Virtual IP (VIP) to the cluster + +It’s possible to add a virtual IP to the cluster: + +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: + +[root@node2 ~]# crm configure primitive maxscale_vip ocf:heartbeat:IPaddr2 params ip=192.168.122.125 op monitor interval=10s + + + +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’. + +[root@node2 ~]# crm configure group maxscale_service maxscale_vip MaxScale + +The final configuration is, from another node: + +[root@node3 ~]# crm configure show + +node node1 + +node node2 + +node node3 + +primitive MaxScale lsb:maxscale \ + + op monitor interval=15s timeout=10s \ + + op start interval=0 timeout=15s \ + + op stop interval=0 timeout=30s + +primitive maxscale_vip IPaddr2 \ + + params ip=192.168.122.125 \ + + op monitor interval=10s + +group maxscale_service maxscale_vip MaxScale \ + + meta target-role=Started + +property cib-bootstrap-options: \ + + dc-version=1.1.10-14.el6_5.3-368c726 \ + + cluster-infrastructure="classic openais (with plugin)" \ + + expected-quorum-votes=3 \ + + stonith-enabled=false \ + + no-quorum-policy=ignore \ + + placement-strategy=balanced \ + + last-lrm-refresh=1404125486 + +Check the resource status: + +[root@node1 ~]# crm status + +Last updated: Mon Jun 30 13:51:29 2014 + +Last change: Mon Jun 30 13:51:27 2014 via crmd on node1 + +Stack: classic openais (with plugin) + +Current DC: node2 - partition with quorum + +Version: 1.1.10-14.el6_5.3-368c726 + +3 Nodes configured, 3 expected votes + +2 Resources configured + +Online: [ node1 node2 node3 ] + + Resource Group: maxscale_service + + maxscale_vip (ocf::heartbeat:IPaddr2): Started node2 + + MaxScale (lsb:maxscale): Started node2 + +With both resources on node2, now MaxScale service will be reachable via the configured VIP address 192.168.122.125 + diff --git a/Reference/images/image_0.png b/Reference/images/image_0.png new file mode 100644 index 000000000..95c63b353 Binary files /dev/null and b/Reference/images/image_0.png differ diff --git a/Tutorials/Administration-Tutorial.md b/Tutorials/Administration-Tutorial.md new file mode 100644 index 000000000..24f47c327 --- /dev/null +++ b/Tutorials/Administration-Tutorial.md @@ -0,0 +1,204 @@ +Getting Started With MariaDB MaxScale + +Common Administration Tasks + +The purpose of this tutorial is to introduce the MaxScale Administrator to a few of the common administration tasks that need to be performed with MaxScale. It is not intended as a reference to all the tasks that may be performed, more this is aimed as an introduction for administrators who are new to MaxScale. + +# Starting MaxScale + +There are several ways to start MaxScale, the most convenient mechanism is probably using the Linux service interface. When a MaxScale package is installed the package manager will also installed a script in /etc/init.d which may be used to start and stop MaxScale either directly or via the service interface. + +$ service maxscale start + +or + +$ /etc/init.d/maxscale start + +It is also possible to start MaxScale by executing the maxscale command itself, in this case you must ensure that the environment is correctly setup or command line options are passed. The major elements to consider are the correct setting of the MAXSCALE_HOME directory and to ensure that LD_LIBRARY_PATH. The LD_LIBRARY_PATH should include the lib directory that was installed as part of the MaxScale installation, the MAXSCALE_HOME should point to /usr/local/skysql/maxscale if a default installation has been created or to the directory this was relocated to. Running the executable $MAXSCALE_HOME/bin/maxscale will result in MaxScale running as a daemon process, unattached to the terminal in which it was started and using configuration files that it finds in the $MAXSCALE_HOME directory. + +Options may be passed to the MaxScale binary that alter this default behaviour, this options are documented in the table below. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SwitchLong OptionDescription
-d--nodaemonRun MaxScale attached to the terminal rather than as a daemon process. This is useful for debugging purposes.
-c--homedir=Ignore the environment variable MAXSCALE_HOME and use the supplied argument instead.
-f--config=Use the filename passed as an argument instead of looking in $MAXSCALE_HOME/etc/MaxScale.cnf
-l|--log=Control where logs are written for the debug and trace level log messages. the default is to write these to a shared memory device, however using the -lfile or --log=file option will forced these to be written to regular files.
-v--versionPrint version information for MaxScale
-?--helpPrint usage information for MaxScale
+ + +# Stopping MaxScale + +There are numerous ways in which MaxScale can be stopped; using the service interface, killing the process or by use of the maxadmin utility. + +Stopping MaxScale with the service interface is simply a case of using the service stop command or calling the init.d script with the stop argument. + +$ service maxscale stop + +or + +$ /etc/init.d/maxscale stop + +MaxScale will also stop gracefully if it received a hangup signal, to find the process id of the MaxScale server use the ps command or read the contents of the maxscale.pid file located in the same directory as the logs. + +$ kill -HUP `cat $MAXSCALE_HOME/log/maxscale.pid` + +In order to shutdown MaxScale using the maxadmin command you may either connect with maxadmin in interactive mode or pass the "shutdown maxscale" command you wish to execute as an argument to maxadmin. + +$ maxadmin -pskysql shutdown maxscale + +# Checking The Status Of The MaxScale Services + +It is possible to use the maxadmin command to obtain statistics regarding the services that are configured within your MaxScale configuration file. The maxadmin command "list services" will give very basic information regarding the services that are define. This command may be either run in interactive mode or passed on the maxadmin command line. + +$ maxadmin -pskysql + +MaxScale> list services + +Services. + +--------------------------+----------------------+--------+--------------- + +Service Name | Router Module | #Users | Total Sessions + +--------------------------+----------------------+--------+--------------- + +RWSplitter | readwritesplit | 2 | 4 + +Cassandra | readconncouter | 1 | 1 + +CLI | cli | 2 | 2 + +--------------------------+----------------------+--------+--------------- + +MaxScale> + +It should be noted that network listeners count as a user of the service, therefore there will always be one user per network port in which the service listens. More detail can be obtained by use of the "show service" command which is passed a service name. + +# What Clients Are Connected To MaxScale + +To determine what client are currently connected to MaxScale you can use the "list clients" command within maxadmin. This will give you IP address and the ID’s of the DCB and session for that connection. As with any maxadmin command this can be passed on the command line or typed interactively in maxadmin. + +$ maxadmin -pskysql list clients + +Client Connections + +-----------------+------------------+----------------------+------------ + + Client | DCB | Service | Session + +-----------------+------------------+----------------------+------------ + + 127.0.0.1 | 0x7fe694013410 | CLI | 0x7fe69401ac10 + +-----------------+------------------+----------------------+------------ + +$ + +# Rotating Log Files + +MaxScale write log data into four log files with varying degrees of detail. With the exception of the error log, which can not be disabled, these log files may be enabled and disabled via the maxadmin interface or in the configuration file. The default behaviour of MaxScale is to grow the log files indefinitely, the administrator must take action to prevent this. + +It is possible to rotate either a single log file or all the log files with a single command. When the logfile is rotated, the current log file is closed and a new log file, with an increased sequence number in its name, is created. Log file rotation is achieved by use of the "flush log" or “flush logs” command in maxadmin. + +$ maxadmin -pskysql flush logs + +Flushes all of the logs, whereas an individual log may be flushed with the "flush log" command. + +$ maxadmin -pskysql + +MaxScale> flush log error + +MaxScale> flush log trace + +MaxScale> + +This may be integrated into the Linux logrotate mechanism by adding a configuration file to the /etc/logrotate.d directory. If we assume we want to rotate the log files once per month and wish to keep 5 log files worth of history, the configuration file would look like the following. + + + + + +
/usr/local/skysql/maxscale/log/*.log { +monthly +rotate 5 +missingok +nocompress +sharedscripts +postrotate +# run if maxscale is running +if test -n "`ps acx|grep maxscale`"; then +/usr/local/skysql/maxscale/bin/maxadmin -pskysql flush logs +fi +endscript +}
+ + +One disadvantage with this is that the password used for the maxadmin command has to be embedded in the log rotate configuration file. MaxScale will also rotate all of its log files if it receives the USR1 signal. Using this the logrotate configuration script can be rewritten as + + + + + +
/usr/local/skysql/maxscale/log/*.log { +monthly +rotate 5 +missingok +nocompress +sharedscripts +postrotate +kill -USR1 `cat /usr/local/skysql/maxscale/log/maxscale.pid` +endscript +}
+ + +# Taking A Database Server Out Of Use + +MaxScale supports the concept of maintenance mode for servers within a cluster, this allows for planned, temporary removal of a database from the cluster within the need to change the MaxScale configuration. + +To achieve the removal of a database server you can use the set server command in the maxadmin utility to set the maintenance mode flag for the server. This may be done interactively within maxadmin or by passing the command on the command line. + +MaxScale> set server dbserver3 maintenance + +MaxScale> + +This will cause MaxScale to stop routing any new requests to the server, however if there are currently requests executing on the server these will not be interrupted. + +To bring the server back into service use the "clear server" command to clear the maintenance mode bit for that server. + +MaxScale> clear server dbserver3 maintenance + +MaxScale> + +Note that maintenance mode is not persistent, if MaxScale restarts when a node is in maintenance mode a new instance of MaxScale will not honour this mode. If multiple MaxScale instances are configured to use the node them maintenance mode must be set within each MaxScale instance. However if multiple services within one MaxScale instance are using the server then you only need set the maintenance mode once on the server for all services to take note of the mode change. + diff --git a/Tutorials/Filter-Tutorial.md b/Tutorials/Filter-Tutorial.md new file mode 100644 index 000000000..ba8acc36b --- /dev/null +++ b/Tutorials/Filter-Tutorial.md @@ -0,0 +1,232 @@ +Getting Started With MariaDB MaxScale + +Filters + +# What Are Filters? + +The filter mechanism in MaxScale is a means by which processing can be inserted into the flow of requests and responses between the client connection to MaxScale and the MaxScale connection to the backend database servers. The path from the client side of MaxScale out to the actual database servers can be considered a pipeline, filters can then be placed in that pipeline to monitor, modify, copy or block the content that flows through that pipeline. + +# Types Of Filter + +Filters can be divided into a number of categories + +* Logging filters + +Logging filters do not in any way alter the statement or results of the statements that are passed through MaxScale. They merely log some information about some or all of the statements and/or result sets. + +Two examples of logging filters are contained within the MaxScale GA, a filter that will log all statements and another that will log only a number of statements, based on the duration of the execution of the query. + +* Statement rewriting filters + +Statement rewriting filters modify the statements that are passed through the filter. This allows a filter to be used as a mechanism to alter the statements that are seen by the database, an example of the use of this might be to allow an application to remain unchanged when the underlying database changes or to compensate for the migration from one database schema to another. + +The MaxScale GA includes a filter that can modify statements by use of regular expressions to match statements and replaced that matched text. + +* Result set manipulation filters + +A result set manipulation filter is very similar to a statement rewriting but applies to the result set returned rather than the statement executed. An example of this may be obfuscating the values in a column. + +The MaxScale 1.0 GA release does not contain any result set manipulation filters. + +* Routing hint filters + +Routing hint filters are filters that embed hints in the request that can be used by the router onto which the query is passed. These hints include suggested destinations as well as metric that may be used by the routing process. + +The MaxScale 1.0 GA release does not contain any hint filters. + +* Firewall filters + +A firewall filter is a mechanism that allows queries to be blocked within MaxScale before they are sent on to the database server for execution. They allow constructs or individual queries to be intercepted and give a level of access control that is more flexible than the traditional database grant mechanism. + +The 1.0 GA release of MaxScale does not include any firewall filters. + +* Pipeline control filters + +A pipeline filter is one that has an affect on how the requests are routed within the internal MaxScale components. The most obvious version of this is the ability to add a "tee" connector in the pipeline, duplicating the request and sending it to a second MaxScale service for processing. + +The MaxScale 1.0 GA release contains an implementation of a tee filter that allows statements to be matched using a regular expression and passed to a second service within MaxScale. + +# Filter Definition + +Filters are defined in the configuration file, MaxScale.ini, using a section for each filter instance. The content of the filter sections in the configuration file various from filter to filter, however there are always to entries present for every filter, the type and module. + +[MyFilter] + +type=filter + +module=xxxfilter + +The type is used by the configuration manager within MaxScale to determine what this section is defining and the module is the name of the plugin that implements the filter. + +When a filter is used within a service in MaxScale the entry filters= is added to the service definition in the ini file section for the service. Multiple filters can be defined using a syntax akin to the Linux shell pipe syntax. + +[Split Service] + +type=service + +router=readwritesplit + +servers=dbserver1,dbserver2,dbserver3,dbserver4 + +user=massi + +passwd=6628C50E07CCE1F0392EDEEB9D1203F3 + +filters=hints | top10 + +The names used in the filters= parameter are the names of the filter definition sections in the ini file. The same filter definition can be used in multiple services and the same filter module can have multiple instances, each with its own section in the ini file. + +# Filter Examples + +The filters that are bundled with the MaxScale 1.0 GA release are documented separately, in this section a short overview of how these might be used for some simple tasks will be discussed. These are just examples of how these filters might be used, other filters may also be easily added that will enhance the MaxScale functionality still further. + +## Log The 30 Longest Running Queries + +The top filter can be used to measure the execution time of every statement within a connection and log the details of the longest running statements. + +The first thing to do is to define a filter entry in the ini file for the top filter. In this case we will call it "top30". The type is filter and the module that implements the filter is called topfilter. + +[top30] + +type=filter + +module=topfilter + +count=30 + +filebase=/var/log/DBSessions/top30 + +In the definition above we have defined two filter specific parameters, the count of the number of statement to be logged and a filebase that is used to define where to log the information. This filename is a stem to which a session id is added for each new connection that uses the filter. + +The filter keeps track of every statement that is executed, monitors the time it takes for a response to come back and uses this as the measure of execution time for the statement. If the time is longer than the other statements that have been recorded, then this is added to the ordered list within the filter. Once 30 statements have been recorded those statements that have been recorded with the least time are discarded from the list. The result is that at any time the filter has a list of the 30 longest running statements in each session. + +It is possible to see what is in the current list by using the maxadmin tool to view the state of the filter by looking at the session data. First you need to find the session id for the session of interest, this can be done using commands such as list sessions. You can then use the show session command to see the details for a particular session. + +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: top30 + + Report size 30 + + Logging to file /var/log/DBSessions/top30.1. + + Current Top 30: + + 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 + +... + +When the session ends a report will be written for the session into the logfile defined. That report will include the top 30 longest running statements, plus summary data for the session; + +* The time the connection was opened. + +* The host the connection was from. + +* The username used in the connection. + +* The duration of the connection. + +* The total number of statements executed in the connection. + +* The average execution time for a statement in this connection. + +## Duplicate Data From Your Application Into Cassandra + +The scenario we are using in this example is one in which you have an online gaming application that is designed to work with a MariaDB/MySQL database. The database schema includes a high score table which you would like to have access to in a Cassandra cluster. The application is already using MaxScale to connect to a MariaDB Galera cluster, using a service names BubbleGame. The definition of that service is as follows + +[BubbleGame] + +type=service + +router=readwritesplit + +servers=dbbubble1,dbbubble2,dbbubble3,dbbubble4,dbbubble5 + +user=maxscale + +passwd=6628C50E07CCE1F0392EDEEB9D1203F3 + +The table you wish to store in Cassandra in called HighScore and will contain the same columns in both the MariaDB table and the Cassandra table. The first step is to install a MariaDB instance with the Cassandra storage engine to act as a bridge server between the relational database and Cassandra. In this bridge server add a table definition for the HighScore table with the engine type set to cassandra. Add this server into the MaxScale configuration and create a service that will connect to this server. + +[CassandraDB] + +type=server + +address=192.168.4.28 + +port=3306 + +protocol=MySQLBackend + +[Cassandra] + +type=service + +router=readconnrouter + +router_options=running + +servers=CassandraDB + +user=maxscale + +passwd=6628C50E07CCE1F0392EDEEB9D1203F3 + +Next add a filter definition for the tee filter that will duplication insert statements that are destined for the HighScore table to this new service. + +[HighScores] + +type=filter + +module=teefilter + +match=insert.*HighScore.*values + +service=Cassandra + +The above filter definition will cause all statements that match the regular expression inset.*HighScore.*values to be duplication and sent not just to the original destination, via the router but also to the service named Cassandra. + +The final step is to add the filter to the BubbleGame service to enable the use of the filter. + +[BubbleGame] + +type=service + +router=readwritesplit + +servers=dbbubble1,dbbubble2,dbbubble3,dbbubble4,dbbubble5 + +user=maxscale + +passwd=6628C50E07CCE1F0392EDEEB9D1203F3 + +filters=HighScores + diff --git a/Tutorials/Galera-Cluster-Connection-Routing-Tutorial.md b/Tutorials/Galera-Cluster-Connection-Routing-Tutorial.md new file mode 100644 index 000000000..9ffc3740a --- /dev/null +++ b/Tutorials/Galera-Cluster-Connection-Routing-Tutorial.md @@ -0,0 +1,292 @@ +Getting Started With MariaDB MaxScale + +Connection Routing with Galera Cluster + +# Environment & Solution Space + +This document is designed as a quick introduction to setting up MaxScale in an environment in which you have a Galera Cluster within which you wish to balance connection across all the database nodes of the cluster that are active members of cluster. + +The process of setting and configuring MaxScale will be covered within this document. However the installation and configuration of the Galera Cluster will not be covered. + +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. + +# Process + +The steps involved in creating a system from the binary distribution of MaxScale are: + +* Install the package relevant to your distribution + +* Create the required users in your MariaDB or MySQL Galera cluster + +* Create a 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 MaxScale installed and ready to be run but without a configuration. You must create a configuration file before you first run MaxScale. + +## Creating Database Users + +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. 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. + +1. Connect to one of the nodes in your Galera cluster as the root user + +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*'; + +**Query OK, 0 rows affected (0.00 sec)** + +3. Grant select privileges on the mysql.user table + +MariaDB [(none)]> grant SELECT on mysql.user to '*username*'@'*maxscalehost*'; + +**Query OK, 0 rows affected (0.03 sec)** + +Additionally, GRANT SELECT on the mysql.db table 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'; + +**Query OK, 0 rows affected (0.00 sec)** + +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 within the information schema. No special permission need to be granted to the user in order to query the information schema. + +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 Your MaxScale Configuration + +MaxScale configuration is held in an ini file that is located in the file MaxScale.cnf in the directory $MAXSCALE_HOME/etc, if you have installed in the default location then this file is available in /usr/local/skysql/maxscale/etc/MaxScale.cnf. This is not created as part of the installation process and must be manually created. A template file does exist within this directory that may be use as a basis for your configuration. + +A global, maxscale, section is included within every MaxScale configuration file; this is used to set the values of various MaxScale wide parameters, perhaps the most important of these is the number of threads that 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; MaxScale will then route connections to this port onwards to the various nodes within the Galera Cluster. To achieve this within MaxScale we need to define a service in the ini file. Create a section for each in your MaxScale.ini 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. + +[Galera Service] + +type=service + +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. + +[Galera Service] + +type=service + +router=readconnroute + +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. + +% maxkeys /usr/local/skysql/maxscale/etc/.secrets + +% + +Once the keys have been created the maxpasswd command can be used to generate the encrypted password. + +% maxpasswd plainpassword + +96F99AA1315BDC3604B006F427DD9484 + +% + +The username and password, either encrypted or plain text, are stored in the service section using the user and passwd parameters. + +[Galera Service] + +type=service + +router=readconnroute + +router_options=synced + +servers=dbserv1, dbserv2, dbserv3 + +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 labelled service which contains the name of the service to associate the listener with. Each service may have multiple listeners. + +[Galera Listener] + +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. + +[Galera Listener] + +type=listener + +service=Galera Service + +protocol=MySQLClient + +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 behaviour 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. + +[dbserv1] + +type=server + +address=192.168.2.1 + +port=3306 + +protocol=MySQLBackend + +[dbserv2] + +type=server + +address=192.168.2.2 + +port=3306 + +protocol=MySQLBackend + +[dbserv3] + +type=server + +address=192.168.2.3 + +port=3306 + +protocol=MySQLBackend + +In order for 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. + +[Galera Monitor] + +type=monitor + +module=galeramon + +servers=dbserv1, dbserv2, dbserv3 + +user=maxscale + +passwd=96F99AA1315BDC3604B006F427DD9484 + +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 MaxScale for monitoring and administration purposes. This creates a service section and a listener section. + +[CLI] + +type=service + +router=cli + +[CLI Listener] + +type=listener + +service=CLI + +protocol=maxscaled + +address=localhost + +port=6603 + +In the case of the example above it should be noted that an address parameter has been given to the listener, this limits connections to maxadmin commands that are executed on the same machine that hosts MaxScale. + +# Starting MaxScale + +Upon completion of the configuration process 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 + +or + +% service maxscale start + +Check the error log in /usr/local/skysql/maxscale/log to see if any errors are detected in the configuration file and to confirm MaxScale has been started. Also the maxadmin command may be used to confirm that MaxScale is running and the services, listeners etc have been correctly configured. + +% maxadmin -pskysql list services + +Services. + +--------------------------+----------------------+--------+--------------- + +Service Name | Router Module | #Users | Total Sessions + +--------------------------+----------------------+--------+--------------- + +Galera Service | readconnroute | 1 | 1 + +CLI | cli | 2 | 2 + +--------------------------+----------------------+--------+--------------- + +% maxadmin -pskysql list servers + +Servers. + +-------------------+-----------------+-------+-------------+-------------------- + +Server | Address | Port | Connections | Status + +-------------------+-----------------+-------+-------------+-------------------- + +dbserv1 | 192.168.2.1 | 3306 | 0 | Running, Synced, Master + +dbserv2 | 192.168.2.2 | 3306 | 0 | Running, Synced, Slave + +dbserv3 | 192.168.2.3 | 3306 | 0 | Running, Synced, Slave + +-------------------+-----------------+-------+-------------+-------------------- + +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 MaxScale convenience and has no impact on the behaviour of the cluster. + +% maxadmin -pskysql list listeners + +Listeners. + +---------------------+--------------------+-----------------+-------+-------- + +Service Name | Protocol Module | Address | Port | State + +---------------------+--------------------+-----------------+-------+-------- + +Galera Service | MySQLClient | * | 4306 | Running + +CLI | maxscaled | localhost | 6603 | Running + +---------------------+--------------------+-----------------+-------+-------- + +% + +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 MaxScale Configuration Guide. More detail on the use of maxadmin can be found in the document "MaxAdmin - The MaxScale Administration & Monitoring Client Application". + diff --git a/Tutorials/Galera-Cluster-Read-Write-Splitting-Tutorial.md b/Tutorials/Galera-Cluster-Read-Write-Splitting-Tutorial.md new file mode 100644 index 000000000..47015012f --- /dev/null +++ b/Tutorials/Galera-Cluster-Read-Write-Splitting-Tutorial.md @@ -0,0 +1,298 @@ +Getting Started With MariaDB MaxScale + +Read/Write Splitting with Galera Cluster + +# Environment & Solution Space + +This document is designed as a quick introduction to setting up MaxScale in an environment in which you have a Galera Cluster which you wish to use as a single database node for update and one or more read only nodes. The object of this tutorial is to have a system that appears to the clients of MaxScale as if there is a single database behind MaxScale. MaxScale will split the statements such that write statements will be sent to only one server in the cluster and read statements will be balanced across the remainder of the servers. + +The reason for a configuration like this, with all the updates being directed to a single node within what is a multi-master cluster, is to prevent any possible conflict between updates that may run on multiple nodes. Galera is built to provide the mechanism for this situation, however issues have been known to occur when conflicting transactions are committed on multiple nodes. Some applications are unable to deal with the resulting errors that may be created in this situation. + +The process of setting and configuring MaxScale will be covered within this document. However the installation and configuration of the Galera Cluster will not be covered in this tutorial. + +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. + +# Process + +The steps involved in creating a system from the binary distribution of MaxScale are: + +* Install the package relevant to your distribution + +* Create the required users in your Galera Cluster + +* Create a 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 MaxScale installed and ready to be run but without a configuration. You must create a configuration file before you first run MaxScale. + +## Creating Database Users + +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. 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. + +1. Connect to Galera Cluster as the root user + +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*'; + +**Query OK, 0 rows affected (0.00 sec)** + +3. Grant select privileges on the mysql.user table. + +MariaDB [(none)]> grant SELECT on mysql.user to '*username*'@'*maxscalehost*'; + +**Query OK, 0 rows affected (0.03 sec)** + +Additionally, GRANT SELECT on the mysql.db table 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'; + +**Query OK, 0 rows affected (0.00 sec)** + +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 within the information schema. No special permission need to be granted to the user in order to query the information schema. + +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 Your MaxScale Configuration + +MaxScale configuration is held in an ini file that is located in the file MaxScale.cnf in the directory $MAXSCALE_HOME/etc, if you have installed in the default location then this file is available in /usr/local/skysql/maxscale/etc/MaxScale.cnf. This is not created as part of the installation process and must be manually created. A template file does exist within this directory that may be use as a basis for your configuration. + +A global, maxscale, section is included within every MaxScale configuration file; this is used to set the values of various MaxScale wide parameters, perhaps the most important of these is the number of threads that MaxScale will use to execute the code that forwards requests and handles responses for clients. + +[maxscale] + +threads=4 + +The first step is to create a service for our Read/Write Splitter. Create a section in your MaxScale.ini 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. + +[Splitter Service] + +type=service + +The router for we need to use for this configuration is the readwritesplit 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. + +[Splitter Service] + +type=service + +router=readwritesplit + +servers=dbserv1, dbserv2, dbserv3 + +The final step in the service sections is to add the username and password that will be used to populate the user data from the database cluster. There are two options for representing the password, either plain text or encrypted passwords may be used. In order to use encrypted passwords a set of keys must be generated that will be used by the encryption and decryption process. To generate the keys use the maxkeys command and pass the name of the secrets file in which the keys are stored. + +% maxkeys /usr/local/skysql/maxscale/etc/.secrets + +% + +Once the keys have been created the maxpasswd command can be used to generate the encrypted password. + +% maxpasswd plainpassword + +96F99AA1315BDC3604B006F427DD9484 + +% + +The username and password, either encrypted or plain text, are stored in the service section using the user and passwd parameters. + +[Splitter Service] + +type=service + +router=readwritesplit + +servers=dbserv1, dbserv2, dbserv3 + +user=maxscale + +passwd=96F99AA1315BDC3604B006F427DD9484 + +This completes the definitions required by the service, however listening ports must be associated with the service in order to allow network connections. This is done by creating a series of listener sections. This section again is named for the convenience of the administrator and should be of type listener with an entry labelled service which contains the name of the service to associate the listener with. A service may have multiple listeners. + +[Splitter Listener] + +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. + +[Splitter Listener] + +type=listener + +service=Splitter Service + +protocol=MySQLClient + +port=3306 + +socket=/tmp/ClusterMaster + +An address parameter may be given if the listener is required to bind to a particular network address when using hosts with multiple network addresses. The default behaviour 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. + +[dbserv1] + +type=server + +address=192.168.2.1 + +port=3306 + +protocol=MySQLBackend + +[dbserv2] + +type=server + +address=192.168.2.2 + +port=3306 + +protocol=MySQLBackend + +[dbserv3] + +type=server + +address=192.168.2.3 + +port=3306 + +protocol=MySQLBackend + +In order for 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. + +[Galera Monitor] + +type=monitor + +module=galeramon + +servers=dbserv1, dbserv2, dbserv3 + +user=maxscale + +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. + +[Galera Monitor] + +type=monitor + +module=galeramon + +diable_master_failback=1 + +servers=dbserv1, dbserv2, dbserv3 + +user=maxscale + +passwd=96F99AA1315BDC3604B006F427DD9484 + +Using this option the master node will only change if there is a problem with the current master and never because other nodes have joined the cluster. + +The final stage in the configuration is to add the option service which is used by the maxadmin command to connect to MaxScale for monitoring and administration purposes. This creates a service section and a listener section. + +[CLI] + +type=service + +router=cli + +[CLI Listener] + +type=listener + +service=CLI + +protocol=maxscaled + +address=localhost + +port=6603 + +In the case of the example above it should be noted that an address parameter has been given to the listener, this limits connections to maxadmin commands that are executed on the same machine that hosts MaxScale. + +# Starting MaxScale + +Upon completion of the configuration process 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 + +or + +% service maxscale start + +Check the error log in /usr/local/skysql/maxscale/log to see if any errors are detected in the configuration file and to confirm MaxScale has been started. Also the maxadmin command may be used to confirm that MaxScale is running and the services, listeners etc have been correctly configured. + +% maxadmin -pskysql list services + +Services. + +--------------------------+----------------------+--------+--------------- + +Service Name | Router Module | #Users | Total Sessions + +--------------------------+----------------------+--------+--------------- + +Splitter Service | readwritesplit | 1 | 1 + +CLI | cli | 2 | 2 + +--------------------------+----------------------+--------+--------------- + +% maxadmin -pskysql list servers + +Servers. + +-------------------+-----------------+-------+-------------+-------------------- + +Server | Address | Port | Connections | Status + +-------------------+-----------------+-------+-------------+-------------------- + +dbserv1 | 192.168.2.1 | 3306 | 0 | Running, Synced, Master + +dbserv2 | 192.168.2.2 | 3306 | 0 | Running, Synced, Slave + +dbserv3 | 192.168.2.3 | 3306 | 0 | Running, Synced, Slave + +-------------------+-----------------+-------+-------------+-------------------- + +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 MaxScale convenience and has no impact on the behaviour of the cluster but does allow the monitor to create these pseudo roles which are utilised by the Read/Write Splitter. + +% maxadmin -pskysql list listeners + +Listeners. + +---------------------+--------------------+-----------------+-------+-------- + +Service Name | Protocol Module | Address | Port | State + +---------------------+--------------------+-----------------+-------+-------- + +Splitter Service | MySQLClient | * | 3306 | Running + +CLI | maxscaled | localhost | 6603 | Running + +---------------------+--------------------+-----------------+-------+-------- + +% + +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 MaxScale Configuration Guide. More detail on the use of maxadmin can be found in the document "MaxAdmin - The MaxScale Administration & Monitoring Client Application". + diff --git a/Tutorials/MySQL-Replication-Connection-Routing-Tutorial.md b/Tutorials/MySQL-Replication-Connection-Routing-Tutorial.md new file mode 100644 index 000000000..b95769402 --- /dev/null +++ b/Tutorials/MySQL-Replication-Connection-Routing-Tutorial.md @@ -0,0 +1,354 @@ +Getting Started With MariaDB MaxScale + +Connection Routing with MySQL Replication + +# Environment & Solution Space + +This document is designed as a quick introduction to setting up MaxScale in an environment in which you have a MySQL Replication Cluster with one master and multiple slave servers. 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 process of setting and configuring MaxScale will be covered within this document. However the installation and configuration of the MySQL Replication subsystem will not be covered nor will any discussion of installation management tools to handle automated or semi-automated failover of the replication 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 guides elsewhere as is installing to non-default locations. + +# Process + +The steps involved in creating a system from the binary distribution of MaxScale are: + +* Install the package relevant to your distribution + +* Create the required users in your MariaDB or MySQL Replication cluster + +* Create a 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 MaxScale installed and ready to be run but without a configuration. You must create a configuration file before you first run MaxScale. + +## Creating Database Users + +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. 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. + +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 + +MariaDB [(none)]> create user '*username*'@'*maxscalehost*' identified by '*password*'; + +**Query OK, 0 rows affected (0.00 sec)** + +3. Grant select privileges on the mysql.user table + +MariaDB [(none)]> grant SELECT on mysql.user to '*username*'@'*maxscalehost*'; + +**Query OK, 0 rows affected (0.03 sec)** + +Additionally, GRANT SELECT on the mysql.db table 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'; + +**Query OK, 0 rows affected (0.00 sec)** + +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 roles REPLICATION SLAVE and REPLICATION CLIENT + +MariaDB [(none)]> grant REPLICATION SLAVE on *.* to '*username*'@'*maxscalehost*'; + +**Query OK, 0 rows affected (0.00 sec)** + +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. + +## Creating Your MaxScale Configuration + +MaxScale configuration is held in an ini file that is located in the file MaxScale.cnf in the directory $MAXSCALE_HOME/etc, if you have installed in the default location then this file is available in /usr/local/skysql/maxscle/etc/MaxScale.cnf. This is not created as part of the installation process and must be manually created. A template file does exist within this directory that may be use as a basis for your configuration. + +A global, maxscale, section is included within every MaxScale configuration file; this is used to set the values of various MaxScale wide parameters, perhaps the most important of these is the number of threads that MaxScale will use to execute the code that forwards requests and handles responses for clients. + +[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 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 MaxScale.ini 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. + +[Write Service] + +type=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] + +type=service + +router=readconnroute + +servers=dbserv1, dbserv2, dbserv3 + +[Read Service] + +type=service + +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 two options master and slave for our two services. + +[Write Service] + +type=service + +router=readconnroute + +router_options=master + +servers=dbserv1, dbserv2, dbserv3 + +[Read Service] + +type=service + +router=readconnroute + +router_options=slave + +servers=dbserv1, dbserv2, dbserv3 + +The final step in the service sections is to add the username and password that will be used to populate the user data from the database cluster. There are two options for representing the password, either plain text or encrypted passwords may be used. In order to use encrypted passwords a set of keys must be generated that will be used by the encryption and decryption process. To generate the keys use the maxkeys command and pass the name of the secrets file in which the keys are stored. + +% maxkeys /usr/local/skysql/maxscale/etc/.secrets + +% + +Once the keys have been created the maxpasswd command can be used to generate the encrypted password. + +% maxpasswd plainpassword + +96F99AA1315BDC3604B006F427DD9484 + +% + +The username and password, either encrypted or plain text, are stored in the service section using the user and passwd parameters. + +[Write Service] + +type=service + +router=readconnroute + +router_options=master + +servers=dbserv1, dbserv2, dbserv3 + +user=maxscale + +passwd=96F99AA1315BDC3604B006F427DD9484 + +[Read Service] + +type=service + +router=readconnroute + +router_options=slave + +servers=dbserv1, dbserv2, dbserv3 + +user=maxscale + +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 labelled service which contains the name of the service to associate the listener with. Each service may have multiple listeners. + +[Write Listener] + +type=listener + +service=Write Service + +[Read Listener] + +type=listener + +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] + +type=listener + +service=Write Service + +protocol=MySQLClient + +port=4306 + +socket=/tmp/ClusterMaster + +[Read Listener] + +type=listener + +service=Read Service + +protocol=MySQLClient + +port=4307 + +An address parameter may be given if the listener is required to bind to a particular network address when using hosts with multiple network addresses. The default behaviour 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. + +[dbserv1] + +type=server + +address=192.168.2.1 + +port=3306 + +protocol=MySQLBackend + +[dbserv2] + +type=server + +address=192.168.2.2 + +port=3306 + +protocol=MySQLBackend + +[dbserv3] + +type=server + +address=192.168.2.3 + +port=3306 + +protocol=MySQLBackend + +In order for 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] + +type=monitor + +module=mysqlmon + +servers=dbserv1, dbserv2, dbserv3 + +user=maxscale + +passwd=96F99AA1315BDC3604B006F427DD9484 + +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 MaxScale for monitoring and administration purposes. This creates a service section and a listener section. + +[CLI] + +type=service + +router=cli + +[CLI Listener] + +type=listener + +service=CLI + +protocol=maxscaled + +address=localhost + +port=6603 + +In the case of the example above it should be noted that an address parameter has been given to the listener, this limits connections to maxadmin commands that are executed on the same machine that hosts MaxScale. + +# Starting MaxScale + +Upon completion of the configuration process 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 + +or + +% service maxscale start + +Check the error log in /usr/local/skysql/maxscale/log to see if any errors are detected in the configuration file and to confirm MaxScale has been started. Also the maxadmin command may be used to confirm that MaxScale is running and the services, listeners etc have been correctly configured. + +% maxadmin -pskysql 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 -pskysql 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 -pskysql 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 + +---------------------+--------------------+-----------------+-------+-------- + +% + +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 MaxScale Configuration Guide. More detail on the use of maxadmin can be found in the document "MaxAdmin - The MaxScale Administration & Monitoring Client Application". + diff --git a/Tutorials/MySQL-Replication-Read-Write-Splitting-Tutorial.md b/Tutorials/MySQL-Replication-Read-Write-Splitting-Tutorial.md new file mode 100644 index 000000000..6a527d421 --- /dev/null +++ b/Tutorials/MySQL-Replication-Read-Write-Splitting-Tutorial.md @@ -0,0 +1,284 @@ +Getting Started With MariaDB MaxScale + +Read/Write Splitting with MySQL Replication + +# Environment & Solution Space + +This document is designed as a quick introduction to setting up MaxScale in an environment in which you have a MySQL Replication Cluster with one master and multiple slave servers. The object of this tutorial is to have a system that appears to the clients of MaxScale as if there is a single database behind MaxScale. MaxScale will split the statements such that write statements will be sent to the current master server in the replication cluster and read statements will be balanced across a number of the slave statements. + +The process of setting and configuring MaxScale will be covered within this document. However the installation and configuration of the MySQL Replication subsystem will not be covered nor will any discussion of installation management tools to handle automated or semi-automated failover of the replication 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 guides elsewhere as is installing to non-default locations. + +# Process + +The steps involved in creating a system from the binary distribution of MaxScale are: + +* Install the package relevant to your distribution + +* Create the required users in your MariaDB or MySQL Replication cluster + +* Create a 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 MaxScale installed and ready to be run but without a configuration. You must create a configuration file before you first run MaxScale. + +## Creating Database Users + +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. 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. + +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 + +MariaDB [(none)]> create user '*username*'@'*maxscalehost*' identified by '*password*'; + +**Query OK, 0 rows affected (0.00 sec)** + +3. Grant select privileges on the mysql.user table. + +MariaDB [(none)]> grant SELECT on mysql.user to '*username*'@'*maxscalehost*'; + +**Query OK, 0 rows affected (0.03 sec)** + +Additionally, GRANT SELECT on the mysql.db table 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'; + +**Query OK, 0 rows affected (0.00 sec)** + +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 roles REPLICATION SLAVE and REPLICATION CLIENT + +MariaDB [(none)]> grant REPLICATION SLAVE on *.* to '*username*'@'*maxscalehost*'; + +**Query OK, 0 rows affected (0.00 sec)** + +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. + +## Creating Your MaxScale Configuration + +MaxScale configuration is held in an ini file that is located in the file MaxScale.cnf in the directory $MAXSCALE_HOME/etc, if you have installed in the default location then this file is available in /usr/local/skysql/maxscale/etc/MaxScale.cnf. This is not created as part of the installation process and must be manually created. A template file does exist within this directory that may be use as a basis for your configuration. + +A global, maxscale, section is included within every MaxScale configuration file; this is used to set the values of various MaxScale wide parameters, perhaps the most important of these is the number of threads that MaxScale will use to execute the code that forwards requests and handles responses for clients. + +[maxscale] + +threads=4 + +The first step is to create a service for our Read/Write Splitter. Create a section in your MaxScale.ini 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. + +[Splitter Service] + +type=service + +The router for we need to use for this configuration is the readwritesplit 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. + +[Splitter Service] + +type=service + +router=readwritesplit + +servers=dbserv1, dbserv2, dbserv3 + +The final step in the service sections is to add the username and password that will be used to populate the user data from the database cluster. There are two options for representing the password, either plain text or encrypted passwords may be used. In order to use encrypted passwords a set of keys must be generated that will be used by the encryption and decryption process. To generate the keys use the maxkeys command and pass the name of the secrets file in which the keys are stored. + +% maxkeys /usr/local/skysql/maxscale/etc/.secrets + +% + +Once the keys have been created the maxpasswd command can be used to generate the encrypted password. + +% maxpasswd plainpassword + +96F99AA1315BDC3604B006F427DD9484 + +% + +The username and password, either encrypted or plain text, are stored in the service section using the user and passwd parameters. + +[Splitter Service] + +type=service + +router=readwritesplit + +servers=dbserv1, dbserv2, dbserv3 + +user=maxscale + +passwd=96F99AA1315BDC3604B006F427DD9484 + +This completes the definitions required by the service, however listening ports must be associated with the service in order to allow network connections. This is done by creating a series of listener sections. This section again is named for the convenience of the administrator and should be of type listener with an entry labelled service which contains the name of the service to associate the listener with. A service may have multiple listeners. + +[Splitter Listener] + +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. + +[Splitter Listener] + +type=listener + +service=Splitter Service + +protocol=MySQLClient + +port=3306 + +socket=/tmp/ClusterMaster + +An address parameter may be given if the listener is required to bind to a particular network address when using hosts with multiple network addresses. The default behaviour 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. + +[dbserv1] + +type=server + +address=192.168.2.1 + +port=3306 + +protocol=MySQLBackend + +[dbserv2] + +type=server + +address=192.168.2.2 + +port=3306 + +protocol=MySQLBackend + +[dbserv3] + +type=server + +address=192.168.2.3 + +port=3306 + +protocol=MySQLBackend + +In order for 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] + +type=monitor + +module=mysqlmon + +servers=dbserv1, dbserv2, dbserv3 + +user=maxscale + +passwd=96F99AA1315BDC3604B006F427DD9484 + +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 MaxScale for monitoring and administration purposes. This creates a service section and a listener section. + +[CLI] + +type=service + +router=cli + +[CLI Listener] + +type=listener + +service=CLI + +protocol=maxscaled + +address=localhost + +port=6603 + +In the case of the example above it should be noted that an address parameter has been given to the listener, this limits connections to maxadmin commands that are executed on the same machine that hosts MaxScale. + +# Starting MaxScale + +Upon completion of the configuration process 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 + +or + +% service maxscale start + +Check the error log in /usr/local/skysql/maxscale/log to see if any errors are detected in the configuration file and to confirm MaxScale has been started. Also the maxadmin command may be used to confirm that MaxScale is running and the services, listeners etc have been correctly configured. + +% maxadmin -pskysql list services + +Services. + +--------------------------+----------------------+--------+--------------- + +Service Name | Router Module | #Users | Total Sessions + +--------------------------+----------------------+--------+--------------- + +Splitter Service | readwritesplit | 1 | 1 + +CLI | cli | 2 | 2 + +--------------------------+----------------------+--------+--------------- + +% maxadmin -pskysql 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 -pskysql list listeners + +Listeners. + +---------------------+--------------------+-----------------+-------+-------- + +Service Name | Protocol Module | Address | Port | State + +---------------------+--------------------+-----------------+-------+-------- + +Splitter Service | MySQLClient | * | 3306 | Running + +CLI | maxscaled | localhost | 6603 | Running + +---------------------+--------------------+-----------------+-------+-------- + +% + +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 MaxScale Configuration Guide. More detail on the use of maxadmin can be found in the document "MaxAdmin - The MaxScale Administration & Monitoring Client Application". +