diff --git a/Documentation/Reference/Hint-Syntax.md b/Documentation/Reference/Hint-Syntax.md index fbebd2263..046c822f1 100644 --- a/Documentation/Reference/Hint-Syntax.md +++ b/Documentation/Reference/Hint-Syntax.md @@ -24,11 +24,11 @@ module=hintfilter ## Comments and comment types -The client connection will need to have comments enabled. For example the `mysql` command line client has comments disabled by default. +The client connection will need to have comments enabled. For example the `mysql` command line client has comments disabled by default and they need to be enabled by passing the `-c` option. -For comment types, use either `-- ` (notice the whitespace) or `#` after the semicolon or `/* .. */` before the semicolon. All comment types work with routing hints. +For comment types, use either `-- ` (notice the whitespace after the double hyphen) or `#` after the semicolon or `/* .. */` before the semicolon. -The MySQL manual doesn`t specify if comment blocks, i.e. `/* .. */`, should contain a w +The MySQL manual doesn't specify if comment blocks, i.e. `/* .. */`, should contain a whitespace character before or after the tags, so adding whitespace at both the start and the end is advised. ## Hint body @@ -39,10 +39,10 @@ All hints must start with the `maxscale` tag. -- maxscale ``` -The hints have two types, ones that route to a server and others that contain +The hints have two types, ones that define a server type and others that contain name-value pairs. -###Routing destination hints +### Routing destination hints These hints will instruct the router to route a query to a certain type of a server. ``` diff --git a/Documentation/Reference/How-errors-are-handled-in-MaxScale.md b/Documentation/Reference/How-errors-are-handled-in-MaxScale.md deleted file mode 100644 index 4e212b187..000000000 --- a/Documentation/Reference/How-errors-are-handled-in-MaxScale.md +++ /dev/null @@ -1,56 +0,0 @@ -# How errors are handled in MariaDB MaxScale - -This document describes how errors are handled in MariaDB MaxScale, its protocol modules and routers. - -Assume a client, maxscale, and master/slave replication cluster. - -An "error" can be due to failed authentication, routing error (unsupported query type etc.), or backend failure. - -## Authentication error - -Authentication is relatively complex phase in the beginning of session creation. Roughly speaking, client protocol has loaded user information from backend so that it can authenticate client without consulting backend. When client sends authentication data to MariaDB MaxScale data is compared against backend’s user data in the client protocol module. If authentication fails client protocol module refreshes backend data just in case it had became obsolete after last refresh. If authentication still fails after refresh, authentication error occurs. - -Close sequence starts from mysql_client.c:gw_read_client_event where - -1. session state is set to SESSION_STATE_STOPPING - -2. dcb_close is called for client DCB - - 1. client DCB is removed from epoll set and state is set to DCB_STATE_NOPOLLING - - 2. client protocol’s close is called (gw_client_close) - - * protocol struct is done’d - - * router’s closeSession is called (includes calling dcb_close for backends) - - 3. dcb_call_callback is called for client DCB with DCB_REASON_CLOSE - - 4. client DCB is set to zombies list - -Each call for dcb_close in closeSession repeat steps 2a-d. - -## Routing errors - -### Invalid capabilities returned by router - -When client protocol module receives query from client the protocol state is (typically) MYSQL_IDLE. The protocol state is checked in mysql_client.c:gw_read_client_event. First place where a hard error may occur is when router capabilities are read. If router response is invalid (other than RCAP_TYPE_PACKET_INPUT and RCAP_TYPE_STMT_INPUT). In case of invalid return value from the router, error is logged, followed by session closing. - -### Backend failure - -When mysql_client.c:gw_read_client_event calls either route_by_statement or directly MXS_SESSION_ROUTE_QUERY script, which calls the routeQuery function of the head session’s router. routeQuery returns 1 if succeed, or 0 in case of error. Success here means that query was routed and reply will be sent to the client while error means that routing failed because of backend (server/servers/service) failure or because of side effect of backend failure. - -In case of backend failure, error is replied to client and handleError is called to resolve backend problem. handleError is called with action ERRACT_NEW_CONNECTION which tells to error handler that it should try to find a replacement for failed backend. Handler will return true if there are enough backend servers for session’s needs. If handler returns false it means that session can’t continue processing further queries and will be closed. Client will be sent an error message and dcb_close is called for client DCB. - -Close sequence is similar to that described above from phase #2 onward. - -Reasons for "backend failure" in rwsplit: - -* router has rses_closed == true because other thread has detected failure and started to close session - -* master has disappeared; demoted to slave, for example - -### Router error - -In cases where MXS_SESSION_ROUTE_QUERY has returned successfully (=1) query may not be successfully processed in backend or even sent to it. It is possible that router fails in routing the particular query but there is no such error which would prevent session from continuing. In this case router handles error silently by creating and adding MySQL error to first available backend’s (incoming) eventqueue where it is found and sent to client (clientReply). - diff --git a/Documentation/Reference/MaxAdmin.md b/Documentation/Reference/MaxAdmin.md index d65ebe41f..593e40ef1 100644 --- a/Documentation/Reference/MaxAdmin.md +++ b/Documentation/Reference/MaxAdmin.md @@ -331,34 +331,128 @@ that file. A help system is available that describes the commands available via the administration interface. To obtain a list of all commands available simply type -the command help. +the command `help`. ``` -MaxScale> help Available commands: - add [user|server] - remove [user|server] - create [server|listener|monitor] - destroy [server|listener|monitor] - alter [server|monitor] - set [server|pollsleep|nbpolls|log_throttling] - clear server - disable [heartbeat|log|log-priority|sessionlog|sessionlog-priority|root|feedback|syslog|maxlog|account] - enable [heartbeat|log|log-priority|sessionlog|sessionlog-priority|root|feedback|syslog|maxlog|account] - flush [log|logs] - list [clients|dcbs|filters|listeners|modules|monitors|services|servers|sessions|threads|commands] - reload [config|dbusers] - restart [monitor|service|listener] - shutdown [maxscale|monitor|service|listener] - show [dcblist|dcbs|dcb|dbusers|epoll|eventq|eventstats|feedbackreport|filter|filters|log_throttling|modules|monitor|monitors|persistent|server|servers|serversjson|services|service|session|sessionlist|sessions|tasks|threads|users] - sync logs - call command +add: + add user - Add insecure account for using maxadmin over the network + add server - Add a new server to a service -Type help command to see details of each command. Where commands require names -as arguments and these names contain whitespace either the \ character may be -used to escape the whitespace or the name may be enclosed in double quotes ". +remove: + remove user - Remove account for using maxadmin over the network + remove server - Remove a server from a service or a monitor -MaxScale> +create: + create server - Create a new server + create listener - Create a new listener for a service + create monitor - Create a new monitor + +destroy: + destroy server - Destroy a server + destroy listener - Destroy a listener + destroy monitor - Destroy a monitor + +alter: + alter server - Alter server parameters + alter monitor - Alter monitor parameters + +set: + set server - Set the status of a server + set pollsleep - Set poll sleep period + set nbpolls - Set non-blocking polls + set log_throttling - Set the log throttling configuration + +clear: + clear server - Clear server status + +disable: + disable log-priority - Disable a logging priority + disable sessionlog-priority - [Deprecated] Disable a logging priority for a particular session + disable root - Disable root access + disable feedback - Disable MaxScale feedback to notification service + disable syslog - Disable syslog logging + disable maxlog - Disable MaxScale logging + disable account - Disable Linux user + +enable: + enable log-priority - Enable a logging priority + enable sessionlog-priority - [Deprecated] Enable a logging priority for a session + enable root - Enable root user access to a service + enable feedback - Enable MaxScale feedback to notification service + enable syslog - Enable syslog logging + enable maxlog - Enable MaxScale logging + enable account - Activate a Linux user account for MaxAdmin use + +flush: + flush log - Flush the content of a log file and reopen it + flush logs - Flush the content of a log file and reopen it + +list: + list clients - List all the client connections to MaxScale + list dcbs - List all active connections within MaxScale + list filters - List all filters + list listeners - List all listeners + list modules - List all currently loaded modules + list monitors - List all monitors + list services - List all services + list servers - List all servers + list sessions - List all the active sessions within MaxScale + list threads - List the status of the polling threads in MaxScale + list commands - List registered commands + +reload: + reload config - Reload the configuration + reload dbusers - Reload the database users for a service + +restart: + restart monitor - Restart a monitor + restart service - Restart a service + restart listener - Restart a listener + +shutdown: + shutdown maxscale - Initiate a controlled shutdown of MaxScale + shutdown monitor - Stop a monitor + shutdown service - Stop a service + shutdown listener - Stop a listener + +show: + show dcbs - Show all DCBs + show dbusers - [deprecated] Show user statistics + show authenticators - Show authenticator diagnostics for a service + show epoll - Show the polling system statistics + show eventstats - Show event queue statistics + show feedbackreport - Show the report of MaxScale loaded modules, suitable for Notification Service + show filter - Show filter details + show filters - Show all filters + show log_throttling - Show the current log throttling setting (count, window (ms), suppression (ms)) + show modules - Show all currently loaded modules + show monitor - Show monitor details + show monitors - Show all monitors + show persistent - Show the persistent connection pool of a server + show server - Show server details + show servers - Show all servers + show serversjson - Show all servers in JSON + show services - Show all configured services in MaxScale + show service - Show a single service in MaxScale + show session - Show session details + show sessions - Show all active sessions in MaxScale + show tasks - Show all active housekeeper tasks in MaxScale + show threads - Show the status of the worker threads in MaxScale + show users - Show enabled Linux accounts + show version - Show the MaxScale version number + +sync: + sync logs - Flush log files to disk + +call: + call command - Call module command + + +Type `help COMMAND` to see details of each command. +Where commands require names as arguments and these names contain +whitespace either the \ character may be used to escape the whitespace +or the name may be enclosed in double quotes ". ``` To see more details on a particular command, and a list of the sub commands of @@ -366,54 +460,78 @@ the command, type help followed by the command name. ``` MaxScale> help list -Available options to the list command: -'clients' - List all clients +Available options to the `list` command: -List all the client connections to MaxScale +list clients - List all the client connections to MaxScale -'dcbs' - List all DCBs +Usage: list clients -List all the DCBs active within MaxScale +---------------------------------------------------------------------------- -'filters' - List all filters +list dcbs - List all active connections within MaxScale -List all the filters defined within MaxScale +Usage: list dcbs -'listeners' - List all listeners +---------------------------------------------------------------------------- -List all the listeners defined within MaxScale +list filters - List all filters -'modules' - List all currently loaded modules +Usage: list filters -List all currently loaded modules +---------------------------------------------------------------------------- -'monitors' - List all monitors +list listeners - List all listeners -List all monitors +Usage: list listeners -'services' - List all the services +---------------------------------------------------------------------------- -List all the services defined within MaxScale +list modules - List all currently loaded modules -'servers' - List all servers +Usage: list modules -List all the servers defined within MaxScale +---------------------------------------------------------------------------- -'sessions' - List all sessions +list monitors - List all monitors -List all the active sessions within MaxScale +Usage: list monitors -'threads' - List polling threads +---------------------------------------------------------------------------- -List the status of the polling threads in MaxScale +list services - List all services -'commands' - List registered commands +Usage: list services + +---------------------------------------------------------------------------- + +list servers - List all servers + +Usage: list servers + +---------------------------------------------------------------------------- + +list sessions - List all the active sessions within MaxScale + +Usage: list sessions + +---------------------------------------------------------------------------- + +list threads - List the status of the polling threads in MaxScale + +Usage: list threads + +---------------------------------------------------------------------------- + +list commands - List registered commands + +Usage: list commands [MODULE] [COMMAND] -Usage list commands [MODULE] [COMMAND] Parameters: MODULE Regular expressions for filtering module names COMMAND Regular expressions for filtering module command names +Example: list commands my-module my-command + MaxScale> ``` @@ -432,16 +550,15 @@ available within your MariaDB MaxScale configuration. ``` MaxScale> list services Services. ---------------------------+----------------------+--------+--------------- -Service Name | Router Module | #Users | Total Sessions ---------------------------+----------------------+--------+--------------- -Test Service | readconnroute | 1 | 1 -Split Service | readwritesplit | 1 | 1 -Filter Service | readconnroute | 1 | 1 -QLA Service | readconnroute | 1 | 1 -Debug Service | debugcli | 1 | 1 -CLI | cli | 2 | 24 ---------------------------+----------------------+--------+--------------- +--------------------------+-------------------+--------+----------------+------------------- +Service Name | Router Module | #Users | Total Sessions | Backend databases +--------------------------+-------------------+--------+----------------+------------------- +RWSplit | readwritesplit | 1 | 1 | server1, server2, server3, server4 +SchemaRouter | schemarouter | 1 | 1 | server1, server2, server3, server4 +RWSplit-Hint | readwritesplit | 1 | 1 | server1, server2, server3, server4 +ReadConn | readconnroute | 1 | 1 | server1 +CLI | cli | 2 | 2 | +--------------------------+-------------------+--------+----------------+------------------- MaxScale> ``` @@ -451,16 +568,15 @@ command can be used. ``` MaxScale> list listeners Listeners. ----------------------+--------------------+-----------------+-------+-------- -Service Name | Protocol Module | Address | Port | State ----------------------+--------------------+-----------------+-------+-------- -Test Service | MySQLClient | * | 4006 | Running -Split Service | MySQLClient | * | 4007 | Running -Filter Service | MySQLClient | * | 4008 | Running -QLA Service | MySQLClient | * | 4009 | Running -Debug Service | telnetd | localhost | 4242 | Running -CLI | maxscaled | localhost | 6603 | Running ----------------------+--------------------+-----------------+-------+-------- +----------------------+---------------------+--------------------+-----------------+-------+-------- +Name | Service Name | Protocol Module | Address | Port | State +----------------------+---------------------+--------------------+-----------------+-------+-------- +RWSplit-Listener | RWSplit | MySQLClient | * | 4006 | Running +SchemaRouter-Listener | SchemaRouter | MySQLClient | * | 4010 | Running +RWSplit-Hint-Listener | RWSplit-Hint | MySQLClient | * | 4009 | Running +ReadConn-Listener | ReadConn | MySQLClient | * | 4008 | Running +CLI-Listener | CLI | maxscaled | default | 0 | Running +----------------------+---------------------+--------------------+-----------------+-------+-------- MaxScale> ``` @@ -472,23 +588,37 @@ to examine as an argument. Where a service name contains spaces characters there should either be escaped or the name placed in quotes. ``` -MaxScale> show service "QLA Service" -Service 0x70c6a0 - Service: QLA Service - Router: readconnroute (0x7ffff0f7ae60) - Number of router sessions: 0 - Current no. of router sessions: 0 - Number of queries forwarded: 0 - Started: Wed Jun 25 10:08:23 2014 - Backend databases - 127.0.0.1:3309 Protocol: MySQLBackend - 127.0.0.1:3308 Protocol: MySQLBackend - 127.0.0.1:3307 Protocol: MySQLBackend - 127.0.0.1:3306 Protocol: MySQLBackend - Users data: 0x724340 - Total connections: 1 - Currently connected: 1 -MaxScale> +MaxScale> show service RWSplit + Service: RWSplit + Router: readwritesplit + State: Started + + use_sql_variables_in: all + slave_selection_criteria: LEAST_CURRENT_OPERATIONS + master_failure_mode: fail_instantly + max_slave_replication_lag: -1 + retry_failed_reads: true + strict_multi_stmt: true + disable_sescmd_history: true + max_sescmd_history: 0 + master_accept_reads: false + + Number of router sessions: 0 + Current no. of router sessions: 1 + Number of queries forwarded: 0 + Number of queries forwarded to master: 0 (0.00%) + Number of queries forwarded to slave: 0 (0.00%) + Number of queries forwarded to all: 0 (0.00%) + Started: Thu Apr 20 09:45:13 2017 + Root user access: Disabled + Backend databases: + [127.0.0.1]:3000 Protocol: MySQLBackend Name: server1 + [127.0.0.1]:3001 Protocol: MySQLBackend Name: server2 + [127.0.0.1]:3002 Protocol: MySQLBackend Name: server3 + [127.0.0.1]:3003 Protocol: MySQLBackend Name: server4 + Total connections: 1 + Currently connected: 1 +MaxScale> ``` This allows the set of backend servers defined by the service to be seen along @@ -503,9 +633,10 @@ from one of the backend databases defined for the service. The _show dbusers_ command can be used to examine the user data held by MariaDB MaxScale. ``` -MaxScale> show dbusers "Filter Service" -User names: pappo@%, rana@%, new_control@%, new_nuovo@%, uno@192.168.56.1, nuovo@192.168.56.1, pesce@%, tryme@192.168.1.199, repluser@%, seven@%, due@%, pippo@%, mmm@%, daka@127.0.0.1, timour@%, ivan@%, prova@%, changeme@127.0.0.1, uno@%, massimiliano@127.0.0.1, massim@127.0.0.1, massi@127.0.0.1, masssi@127.0.0.1, pappo@127.0.0.1, rana@127.0.0.1, newadded@127.0.0.1, newaded@127.0.0.1, pesce@127.0.0.1, repluser@127.0.0.1, seven@127.0.0.1, pippo@127.0.0.1, due@127.0.0.1, nopwd@127.0.0.1, timour@127.0.0.1, controlla@192.168.56.1, ivan@127.0.0.1, ppp@127.0.0.1, daka@%, nuovo@127.0.0.1, uno@127.0.0.1, repluser@192.168.56.1, havoc@%, tekka@192.168.1.19, due@192.168.56.1, qwerty@127.0.0.1, massimiliano@%, massi@%, massim@% -MaxScale> +MaxScale> show dbusers RWSplit +User names: @localhost @localhost.localdomain 14567USER@localhost monuser@localhost monuser@% 14609USER@localhost maxuser@localhost maxuser@% 14651USER@localhost maxtest@localhost maxtest@% 14693USER@localhost skysql@localhost skysql@% 14735USER@localhost cliuser@localhost cliuser@% repuser@localhost repuser@% +MaxScale> + ``` ## Reloading Service User Data @@ -518,8 +649,8 @@ the MariaDB MaxScale internal table. The reload dbusers command can be used to force the reloading of the user table within MariaDB MaxScale. ``` -MaxScale> reload dbusers "Split Service" -Loaded 34 database users for service Split Service. +MaxScale> reload dbusers RWSplit +Reloaded database users for service RWSplit. MaxScale> ``` @@ -531,8 +662,8 @@ already in place for a service, but will stop any new connections from being accepted. ``` -MaxScale> shutdown service "Split Service" -MaxScale> +MaxScale> shutdown service RWSplit +MaxScale> ``` ## Restart A Stopped Service @@ -540,7 +671,7 @@ MaxScale> A stopped service may be restarted by using the _restart service_ command. ``` -MaxScale> restart service "Split Service" +MaxScale> restart service RWSplit MaxScale> ``` @@ -557,15 +688,15 @@ configured within MariaDB MaxScale. ``` MaxScale> list servers Servers. --------------------+-----------------+-------+----------------------+------------ -Server | Address | Port | Status | Connections --------------------+-----------------+-------+----------------------+------------ -server1 | 127.0.0.1 | 3306 | Running | 0 -server2 | 127.0.0.1 | 3307 | Master, Running | 0 -server3 | 127.0.0.1 | 3308 | Running | 0 -server4 | 127.0.0.1 | 3309 | Slave, Running | 0 --------------------+-----------------+-------+----------------------+------------ -MaxScale> +-------------------+-----------------+-------+-------------+-------------------- +Server | Address | Port | Connections | Status +-------------------+-----------------+-------+-------------+-------------------- +server1 | 127.0.0.1 | 3000 | 0 | Master, Running +server2 | 127.0.0.1 | 3001 | 0 | Slave, Running +server3 | 127.0.0.1 | 3002 | 0 | Slave, Running +server4 | 127.0.0.1 | 3003 | 0 | Slave, Running +-------------------+-----------------+-------+-------------+-------------------- +MaxScale> ``` ## Server Details @@ -575,17 +706,20 @@ server_ command. ``` MaxScale> show server server2 -Server 0x70d460 (server2) - Server: 127.0.0.1 - Status: Master, Running - Protocol: MySQLBackend - Port: 3307 - Server Version: 5.5.25-MariaDB-log - Node Id: 124 - Number of connections: 0 - Current no. of conns: 0 - Current no. of operations: 0 -MaxScale> +Server 0x6501d0 (server2) + Server: 127.0.0.1 + Status: Slave, Running + Protocol: MySQLBackend + Port: 3001 + Server Version: 10.1.22-MariaDB + Node Id: 3001 + Master Id: 3000 + Slave Ids: + Repl Depth: 1 + Number of connections: 0 + Current no. of conns: 0 + Current no. of operations: 0 +MaxScale> ``` If the server has a non-zero value set for the server configuration item @@ -637,6 +771,7 @@ format described below in the DCB section) with a command like: ``` MaxScale> show persistent server1 +Number of persistent DCBs: 0 ``` # Working With Sessions @@ -654,38 +789,17 @@ comprehensive being the _list sessions_ command. ``` MaxScale> list sessions -Sessions. -----------------+-----------------+----------------+-------------------------- Session | Client | Service | State -----------------+-----------------+----------------+-------------------------- -0x7267a0 | 127.0.0.1 | CLI | Session ready for routing -0x726340 | | CLI | Listener Session -0x725720 | | Debug Service | Listener Session -0x724720 | | QLA Service | Listener Session -0x72a750 | | Filter Service | Listener Session -0x709500 | | Split Service | Listener Session -0x7092d0 | | Test Service | Listener Session +10 | localhost | CLI | Session ready for routing +11 | ::ffff:127.0.0.1 | RWSplit | Session ready for routing -----------------+-----------------+----------------+-------------------------- -MaxScale> + +MaxScale> ``` -This lists all the sessions for both user connections and for the service -listeners. - -The _list clients_ command will give just the subset of sessions that originate -from a client connection. - -``` -MaxScale> list clients -Client Connections ------------------+------------+----------------------+------------ - Client | DCB | Service | Session ------------------+------------+----------------------+------------ - 127.0.0.1 | 0x7274b0 | CLI | 0x727700 - 127.0.0.1 | 0x727900 | QLA Service | 0x727da0 ------------------+------------+----------------------+------------ -MaxScale> -``` +This will give a list of client connections. ## Display Session Details @@ -694,14 +808,15 @@ possible to determine more detail regarding a session by using the _show session_ command. ``` -MaxScale> show session 0x727da0 -Session 0x727da0 - State: Session ready for routing - Service: QLA Service (0x70d6a0) - Client DCB: 0x727900 - Client Address: 127.0.0.1 - Connected: Wed Jun 25 15:27:21 2014 -MaxScale> +MaxScale> show session 11 +Session 11 + State: Session ready for routing + Service: RWSplit + Client Address: maxuser@::ffff:127.0.0.1 + Connected: Thu Apr 20 09:51:31 2017 + + Idle: 82 seconds +MaxScale> ``` # Descriptor Control Blocks @@ -723,20 +838,23 @@ MaxScale server, the most straightforward being the _list dcbs_ command. ``` MaxScale> list dcbs Descriptor Control Blocks -------------+----------------------------+----------------------+---------- - DCB | State | Service | Remote -------------+----------------------------+----------------------+---------- - 0x667170 | DCB for listening socket | Test Service | - 0x71a350 | DCB for listening socket | Split Service | - 0x724b40 | DCB for listening socket | Filter Service | - 0x7250d0 | DCB for listening socket | QLA Service | - 0x725740 | DCB for listening socket | Debug Service | - 0x726740 | DCB for listening socket | CLI | - 0x7274b0 | DCB in the polling loop | CLI | 127.0.0.1 - 0x727900 | DCB in the polling loop | QLA Service | 127.0.0.1 - 0x72e880 | DCB in the polling loop | QLA Service | -------------+----------------------------+----------------------+---------- -MaxScale> +------------------+----------------------------+--------------------+---------- + DCB | State | Service | Remote +------------------+----------------------------+--------------------+---------- + 0x68c0a0 | DCB for listening socket | RWSplit | + 0x6e23f0 | DCB for listening socket | CLI | + 0x691710 | DCB for listening socket | SchemaRouter | + 0x7fffe40130f0 | DCB in the polling loop | CLI | localhost + 0x6b7540 | DCB for listening socket | RWSplit-Hint | + 0x6cd020 | DCB for listening socket | ReadConn | + 0x7fffd80130f0 | DCB in the polling loop | RWSplit | ::ffff:127.0.0.1 + 0x7fffdc014590 | DCB in the polling loop | RWSplit | + 0x7fffdc0148d0 | DCB in the polling loop | RWSplit | + 0x7fffdc014c60 | DCB in the polling loop | RWSplit | + 0x7fffdc014ff0 | DCB in the polling loop | RWSplit | +------------------+----------------------------+--------------------+---------- + +MaxScale> ``` A MariaDB MaxScale server that has activity on it will however have many more @@ -753,28 +871,49 @@ address to determine the one of interest. ## DCB Details -The details of an individual DCB can be obtained by use of the _show dcb_ +The details of DCBs can be obtained by use of the _show dcbs_ command ``` -MaxScale> show dcb 0x727900 -DCB: 0x727900 - DCB state: DCB in the polling loop - Username: somename - Protocol: MySQLBackend - Server Status: Master, running - Role: Request Handler - Connected to: 127.0.0.1 - Owning Session: 0x727da0 - Statistics: - No. of Reads: 4 - No. of Writes: 3 - No. of Buffered Writes: 0 - No. of Accepts: 0 - No. of High Water Events: 0 - No. of Low Water Events: 0 - Added to persistent pool: Jun 24 09:09:56 -MaxScale> +DCB: 0x68c0a0 + DCB state: DCB for listening socket + Service: RWSplit + Role: Service Listener + Statistics: + No. of Reads: 0 + No. of Writes: 0 + No. of Buffered Writes: 0 + No. of Accepts: 1 + No. of High Water Events: 0 + No. of Low Water Events: 0 +DCB: 0x7fffd80130f0 + DCB state: DCB in the polling loop + Service: RWSplit + Connected to: ::ffff:127.0.0.1 + Username: maxuser + Role: Client Request Handler + Statistics: + No. of Reads: 5 + No. of Writes: 0 + No. of Buffered Writes: 6 + No. of Accepts: 0 + No. of High Water Events: 0 + No. of Low Water Events: 0 +DCB: 0x7fffdc014590 + DCB state: DCB in the polling loop + Service: RWSplit + Server name/IP: 127.0.0.1 + Port number: 3000 + Protocol: MySQLBackend + Server status: Master, Running + Role: Backend Request Handler + Statistics: + No. of Reads: 4 + No. of Writes: 0 + No. of Buffered Writes: 3 + No. of Accepts: 0 + No. of High Water Events: 0 + No. of Low Water Events: 0 ``` The information Username, Protocol, Server Status are not always relevant, and @@ -832,58 +971,38 @@ within a session. First use _list sessions_ or _list clients_ to find the session of interest and then run the _show session_ command ``` -MaxScale> list clients -Client Connections ------------------+------------+----------------------+------------ - Client | DCB | Service | Session ------------------+------------+----------------------+------------ - 127.0.0.1 | 0x7361a0 | Split Service | 0x736680 - 127.0.0.1 | 0x737ec0 | Plumbing | 0x7382b0 - 127.0.0.1 | 0x73ab20 | DigitalOcean | 0x73ad90 - 127.0.0.1 | 0x7219e0 | CLI | 0x721bd0 ------------------+------------+----------------------+------------ -MaxScale> show session 0x736680 -Session 0x736680 - State: Session ready for routing - Service: Split Service (0x719f60) - Client DCB: 0x7361a0 - Client Address: 127.0.0.1 - Connected: Thu Jun 26 10:10:44 2014 - Filter: top10 - Report size 10 - Logging to file /tmp/Query.top10.1. - Current Top 10: - 1 place: - Execution time: 23.826 seconds - SQL: select sum(salary), year(from_date) from salaries s, (select distinct year(from_date) as y1 from salaries) y where (makedate(y.y1, 1) between s.from_date and s.to_date) group by y.y1 ("1988-08-01? - 2 place: - Execution time: 5.251 seconds - SQL: select d.dept_name as "Department", y.y1 as "Year", count(*) as "Count" from departments d, dept_emp de, (select distinct year(from_date) as y1 from dept_emp order by 1) y where d.dept_no = de.dept_no and (makedate(y.y1, 1) between de.from_date and de.to_date) group by y.y1, d.dept_name order by 1, 2 - 3 place: - Execution time: 2.903 seconds - SQL: select year(now()) - year(birth_date) as age, gender, avg(salary) as "Average Salary" from employees e, salaries s where e.emp_no = s.emp_no and ("1988-08-01" between from_date AND to_date) group by year(now()) - year(birth_date), gender order by 1,2 - 4 place: - Execution time: 2.138 seconds - SQL: select dept_name as "Department", sum(salary) / 12 as "Salary Bill" from employees e, departments d, dept_emp de, salaries s where e.emp_no = de.emp_no and de.dept_no = d.dept_no and ("1988-08-01" between de.from_date AND de.to_date) and ("1988-08-01" between s.from_date AND s.to_date) and s.emp_no = e.emp_no group by dept_name order by 1 - 5 place: - Execution time: 0.839 seconds - SQL: select dept_name as "Department", avg(year(now()) - year(birth_date)) as "Average Age", gender from employees e, departments d, dept_emp de where e.emp_no = de.emp_no and de.dept_no = d.dept_no and ("1988-08-01" between from_date AND to_date) group by dept_name, gender - 6 place: - Execution time: 0.662 seconds - SQL: select year(hire_date) as "Hired", d.dept_name, count(*) as "Count" from employees e, departments d, dept_emp de where de.emp_no = e.emp_no and de.dept_no = d.dept_no group by d.dept_name, year(hire_date) - 7 place: - Execution time: 0.286 seconds - SQL: select moves.n_depts As "No. of Departments", count(moves.emp_no) as "No. of Employees" from (select de1.emp_no as emp_no, count(de1.emp_no) as n_depts from dept_emp de1 group by de1.emp_no) as moves group by moves.n_depts order by 1 - 8 place: - Execution time: 0.248 seconds - SQL: select year(now()) - year(birth_date) as age, gender, count(*) as "Count" from employees group by year(now()) - year(birth_date), gender order by 1,2@ - 9 place: - Execution time: 0.182 seconds - SQL: select year(hire_date) as "Hired", count(*) as "Count" from employees group by year(hire_date) - 10 place: - Execution time: 0.169 seconds - SQL: select year(hire_date) - year(birth_date) as "Age", count(*) as Count from employees group by year(hire_date) - year(birth_date) order by 1 -MaxScale> +MaxScale> list sessions +-----------------+-----------------+----------------+-------------------------- +Session | Client | Service | State +-----------------+-----------------+----------------+-------------------------- +6 | ::ffff:127.0.0.1 | RWSplit-Top | Session ready for routing +7 | localhost | CLI | Session ready for routing +-----------------+-----------------+----------------+-------------------------- + +MaxScale> show session 6 +Session 6 + State: Session ready for routing + Service: RWSplit-Top + Client Address: maxuser@::ffff:127.0.0.1 + Connected: Thu Apr 20 09:58:38 2017 + + Idle: 9 seconds + Filter: Top + Report size 10 + Logging to file /tmp/top.1. + Current Top 10: + 1 place: + Execution time: 0.000 seconds + SQL: show tables from information_schema + 2 place: + Execution time: 0.000 seconds + SQL: show databases + 3 place: + Execution time: 0.000 seconds + SQL: show tables + 4 place: + Execution time: 0.000 seconds + SQL: select @@version_comment limit 1 ``` The data displayed varies from filter to filter, the example above is the top @@ -903,12 +1022,12 @@ command. ``` MaxScale> list monitors -+----------------------+--------------------- -| Monitor | Status -+----------------------+--------------------- -| MySQL Monitor | Running -+----------------------+--------------------- -MaxScale> +---------------------+--------------------- +Monitor | Status +---------------------+--------------------- +MySQL-Monitor | Running +---------------------+--------------------- +MaxScale> ``` ## Details Of A Particular Monitor @@ -916,62 +1035,62 @@ MaxScale> To see the details of a particular monitor use the _show monitor_ command. ``` -MaxScale> show monitor "MySQL Monitor" -Monitor: 0x71c370 - Name: MySQL Monitor - Monitor running - Sampling interval: 10000 milliseconds - MaxScale MonitorId: 24209641 - Replication lag: disabled - Monitored servers: 127.0.0.1:3306, 127.0.0.1:3307, 127.0.0.1:3308, 127.0.0.1:3309 -MaxScale> -``` +MaxScale> show monitor MySQL-Monitor +Monitor: 0x6577e0 +Name: MySQL-Monitor +State: Running +Sampling interval: 10000 milliseconds +Connect Timeout: 3 seconds +Read Timeout: 1 seconds +Write Timeout: 2 seconds +Monitored servers: [127.0.0.1]:3000, [127.0.0.1]:3001, [127.0.0.1]:3002, [127.0.0.1]:3003 +MaxScale MonitorId: 0 +Replication lag: disabled +Detect Stale Master: enabled +Server information -## Controlling Replication Heartbeat +Server: server1 +Server ID: 3000 +Read only: OFF +Slave configured: NO +Slave IO running: NO +Slave SQL running: NO +Master ID: -1 +Master binlog file: +Master binlog position: 0 -Some monitors provide a replication heartbeat mechanism that monitors the delay -for data that is replicated from a master to slaves in a tree structured -replication environment. This can be enabled or disabled using the commands -_enable heartbeat_ and _disable heartbeat_. +Server: server2 +Server ID: 3001 +Read only: OFF +Slave configured: YES +Slave IO running: YES +Slave SQL running: YES +Master ID: 3000 +Master binlog file: binlog.000001 +Master binlog position: 435 -``` -MaxScale> disable heartbeat "MySQL Monitor" -MaxScale> enable heartbeat "MySQL Monitor" -MaxScale> -``` +Server: server3 +Server ID: 3002 +Read only: OFF +Slave configured: YES +Slave IO running: YES +Slave SQL running: YES +Master ID: 3000 +Master binlog file: binlog.000001 +Master binlog position: 435 -Please note that changes made via this interface will not persist across -restarts of MariaDB MaxScale. To make a permanent change edit the maxscale.cnf -file. +Server: server4 +Server ID: 3003 +Read only: OFF +Slave configured: YES +Slave IO running: YES +Slave SQL running: YES +Master ID: 3000 +Master binlog file: binlog.000001 +Master binlog position: 435 -Enabling the replication heartbeat mechanism will add the display of heartbeat -information in the show server output -``` -MaxScale> show server server4 -Server 0x719800 (server4) - Server: 127.0.0.1 - Status: Slave, Running - Protocol: MySQLBackend - Port: 3309 - Server Version: 5.5.25-MariaDB-log - Node Id: 4 - Number of connections: 0 - Current no. of conns: 0 -MaxScale> enable heartbeat "MySQL Monitor" -MaxScale> show server server4 -Server 0x719800 (server4) - Server: 127.0.0.1 - Status: Slave, Running - Protocol: MySQLBackend - Port: 3309 - Server Version: 5.5.25-MariaDB-log - Node Id: 4 - Slave delay: 0 - Last Repl Heartbeat: Thu Jun 26 17:04:58 2014 - Number of connections: 0 - Current no. of conns: 0 -MaxScale> +MaxScale> ``` ## Shutting Down A Monitor @@ -981,14 +1100,14 @@ manual control of the status of servers using the _set server_ and _clear server_ commands. ``` -MaxScale> shutdown monitor "MySQL Monitor" +MaxScale> shutdown monitor MySQL-Monitor MaxScale> list monitors -+----------------------+--------------------- -| Monitor | Status -+----------------------+--------------------- -| MySQL Monitor | Stopped -+----------------------+--------------------- -MaxScale> +---------------------+--------------------- +Monitor | Status +---------------------+--------------------- +MySQL-Monitor | Stopped +---------------------+--------------------- +MaxScale> ``` ## Restarting A Monitor @@ -997,16 +1116,14 @@ A monitor that has been shutdown may be restarted using the _restart monitor_ command. ``` -MaxScale> restart monitor "MySQL Monitor" -MaxScale> show monitor "MySQL Monitor" -Monitor: 0x71a310 - Name: MySQL Monitor - Monitor running - Sampling interval: 10000 milliseconds - MaxScale MonitorId: 24201552 - Replication lag: enabled - Monitored servers: 127.0.0.1:3306, 127.0.0.1:3307, 127.0.0.1:3308, 127.0.0.1:3309 -MaxScale> +MaxScale> restart monitor MySQL-Monitor +MaxScale> list monitors +---------------------+--------------------- +Monitor | Status +---------------------+--------------------- +MySQL-Monitor | Running +---------------------+--------------------- +MaxScale> ``` # MaxScale Status Commands @@ -1025,17 +1142,21 @@ determine what each thread is currently being used for. ``` MaxScale> show threads Polling Threads. -Historic Thread Load Average: 1.00. -Current Thread Load Average: 1.00. -15 Minute Average: 0.48, 5 Minute Average: 1.00, 1 Minute Average: 1.00 + +Historic Thread Load Average: 1.06. +Current Thread Load Average: 0.00. +15 Minute Average: 0.10, 5 Minute Average: 0.30, 1 Minute Average: 0.67 + Pending event queue length averages: -15 Minute Average: 0.90, 5 Minute Average: 1.83, 1 Minute Average: 2.00 +15 Minute Average: 0.00, 5 Minute Average: 0.00, 1 Minute Average: 0.00 + ID | State | # fds | Descriptor | Running | Event ----+------------+--------+------------------+----------+--------------- - 0 | Processing | 1 | 0xf55a70 | < 100ms | IN|OUT - 1 | Processing | 1 | 0xf49ba0 | < 100ms | IN|OUT - 2 | Processing | 1 | 0x7f54c0030d00 | < 100ms | IN|OUT -MaxScale> + 0 | Polling | | | | + 1 | Polling | | | | + 2 | Processing | 1 | 0x6e0dd0 | <202400ms | IN|OUT + 3 | Polling | | | | +MaxScale> ``` The resultant output returns data as to the average thread utilization for the @@ -1044,27 +1165,6 @@ thread that shows what DCB that thread is currently processing events for, the events it is processing and how long, to the nearest 100ms has been send processing these events. -## The Event Queue - -At the core of MariaDB MaxScale is an event driven engine that is processing -network events for the network connections between MariaDB MaxScale and client -applications and MariaDB MaxScale and the backend servers. It is possible to see -the event queue using the _show eventq_ command. This will show the events -currently being executed and those that are queued for execution. - -``` -MaxScale> show eventq -Event Queue. -DCB | Status | Processing Events | Pending Events ------------------+------------+--------------------+------------------- -0x1e22f10 | Processing | IN|OUT | -MaxScale> -``` - -The output of this command gives the DCB’s that are currently in the event -queue, the events queued for that DCB, and events that are being processed for -that DCB. - ## The Housekeeper Tasks Internally MariaDB MaxScale has a housekeeper thread that is used to perform @@ -1075,8 +1175,8 @@ are outstanding within the housekeeper. MaxScale> show tasks Name | Type | Frequency | Next Due --------------------------+----------+-----------+------------------------- -Load Average | Repeated | 10 | Wed Nov 19 15:10:51 2014 -MaxScale> +Load Average | Repeated | 10 | Thu Apr 20 10:02:26 2017 +MaxScale> ``` # Administration Commands @@ -1089,23 +1189,25 @@ those modules the _list modules_ command can be used. ``` MaxScale> list modules Modules. -----------------+-------------+---------+-------+------------------------- -Module Name | Module Type | Version | API | Status -----------------+-------------+---------+-------+------------------------- -tee | Filter | V1.0.0 | 1.1.0 | Alpha -qlafilter | Filter | V1.1.1 | 1.1.0 | Alpha -topfilter | Filter | V1.0.1 | 1.1.0 | Alpha -MySQLBackend | Protocol | V2.0.0 | 1.0.0 | Alpha -maxscaled | Protocol | V1.0.0 | 1.0.0 | Alpha -telnetd | Protocol | V1.0.1 | 1.0.0 | Alpha -MySQLClient | Protocol | V1.0.0 | 1.0.0 | Alpha -mysqlmon | Monitor | V1.2.0 | 1.0.0 | Alpha -readconnroute | Router | V1.0.2 | 1.0.0 | Alpha -readwritesplit | Router | V1.0.2 | 1.0.0 | Alpha -debugcli | Router | V1.1.1 | 1.0.0 | Alpha -cli | Router | V1.0.0 | 1.0.0 | Alpha -----------------+-------------+---------+-------+------------------------- -MaxScale> +----------------+-----------------+---------+-------+------------------------- +Module Name | Module Type | Version | API | Status +----------------+-----------------+---------+-------+------------------------- +qc_sqlite | QueryClassifier | V1.0.0 | 1.1.0 | Beta +MySQLAuth | Authenticator | V1.1.0 | 1.1.0 | GA +MySQLClient | Protocol | V1.1.0 | 1.1.0 | GA +MaxAdminAuth | Authenticator | V2.1.0 | 1.1.0 | GA +maxscaled | Protocol | V2.0.0 | 1.1.0 | GA +MySQLBackendAuth | Authenticator | V1.0.0 | 1.1.0 | GA +MySQLBackend | Protocol | V2.0.0 | 1.1.0 | GA +mysqlmon | Monitor | V1.5.0 | 3.0.0 | GA +schemarouter | Router | V1.0.0 | 2.0.0 | Beta +readwritesplit | Router | V1.1.0 | 2.0.0 | GA +topfilter | Filter | V1.0.1 | 2.2.0 | GA +readconnroute | Router | V1.1.0 | 2.0.0 | GA +cli | Router | V1.0.0 | 2.0.0 | GA +----------------+-----------------+---------+-------+------------------------- + +MaxScale> ``` This command provides important version information for the module. Each module @@ -1143,14 +1245,12 @@ $ kill -SIGUSR1 $ # MaxScale closes the file (i.e. maxscale1.log) and reopens maxscale.log ``` -There are two ways for rotating the log - *flush log maxscale* and *flush logs* -- and the result is identical. The two alternatives are due to historical +There are two ways for rotating the log - *flush log maxscale* and *flush logs*; +the result is identical. The two alternatives are due to historical reasons; earlier MariaDB MaxScale had several different log files. ``` MaxScale> flush log maxscale -MaxScale> -The flush logs command may be used to rotate all logs with a single command. MaxScale> flush logs MaxScale> ``` @@ -1206,7 +1306,9 @@ of the values to 0, disables the throttling. ## Reloading The Configuration A command, _reload config_, is available that will cause MariaDB MaxScale to -reload the maxscale.cnf configuration file. Refer to the [Configuration Guide](../Getting-Started/Configuration-Guide.md) +reload the maxscale.cnf configuration file. Note that not all configuration +changes are taken into effect when the configuration is reloaded. Refer to +the [Configuration Guide](../Getting-Started/Configuration-Guide.md) for a list of parameters that can be changed with it. ## Shutting Down MariaDB MaxScale @@ -1214,10 +1316,16 @@ for a list of parameters that can be changed with it. The MariaDB MaxScale server may be shutdown using the _shutdown maxscale_ command. +``` +MaxScale> shutdown maxscale +MaxScale> +``` + # Runtime Configuration Changes Starting with the 2.1 version of MaxScale, you can modify the runtime -configuration. +configuration. This means that new objects (servers, listeners, monitors) +can be created, altered and removed at runtime. ## Servers @@ -1229,20 +1337,21 @@ to servers are persisted meaning that they will still be in effect even after a restart. ``` -'server' - Create a new server +create server - Create a new server Usage: create server NAME HOST [PORT] [PROTOCOL] [AUTHENTICATOR] [OPTIONS] -Create a new server from the following parameters. - +Parameters: NAME Server name HOST Server host address PORT Server port (default 3306) PROTOCOL Server protocol (default MySQLBackend) AUTHENTICATOR Authenticator module name (default MySQLAuth) -OPTIONS Options for the authenticator module +OPTIONS Comma separated list of options for the authenticator -The first three parameters are required, the others are optional. +The first two parameters are required, the others are optional. + +Example: create server my-db-1 192.168.0.102 3306 ``` ### Adding Servers to Services and Monitors @@ -1256,14 +1365,17 @@ sessions will only use the servers that were a part of the service when they were created. ``` -'server' - Add a new server to a service +add server - Add a new server to a service Usage: add server SERVER TARGET... -The TARGET must be a list of service and monitor names -e.g. add server my-db my-service 'Cluster Monitor' +Parameters: +SERVER The server that is added to TARGET +TARGET List of service and/or monitor names separated by spaces A server can be assigned to a maximum of 11 objects in one command + +Example: add server my-db my-service "Cluster Monitor" ``` ### Removing Servers from Services and Monitors @@ -1274,14 +1386,17 @@ server` also apply to `remove server`. The servers will only be removed from new sessions created after the command is executed. ``` -'server' - Remove a server from a service or a monitor +remove server - Remove a server from a service or a monitor Usage: remove server SERVER TARGET... -The TARGET must be a list of service and monitor names -e.g. remove server my-db my-service 'Cluster Monitor' +Parameters: +SERVER The server that is removed from TARGET +TARGET List of service and/or monitor names separated by spaces A server can be removed from a maximum of 11 objects in one command + +Example: remove server my-db my-service "Cluster Monitor" ``` ### Altering Servers @@ -1295,8 +1410,14 @@ required SSL parameters (`ssl`, `ssl_key`, `ssl_cert` and `ssl_ca_cert`) must be given in the same command. ``` +alter server - Alter server parameters + Usage: alter server NAME KEY=VALUE ... +Parameters: +NAME Server name +KEY=VALUE List of `key=value` pairs separated by spaces + This will alter an existing parameter of a server. The accepted values for KEY are: address Server address @@ -1310,9 +1431,10 @@ ssl_ca_cert Path to SSL CA certificate ssl_version SSL version ssl_cert_verify_depth Certificate verification depth -A maximum of 11 parameters can be changed at one time. To configure SSL for a newly created server, the 'ssl', 'ssl_cert', 'ssl_key' and 'ssl_ca_cert' parameters must be given at the same time. + +Example: alter server my-db-1 address=192.168.0.202 port=3307 ``` ### Destroying Servers @@ -1322,9 +1444,14 @@ created with the `create server` command should be destroyed. A server can only be destroyed once it has been removed from all services and monitors. ``` -'server' - Destroy a server +destroy server - Destroy a server Usage: destroy server NAME + +Parameters: +NAME Server to destroy + +Example: destroy server my-db-1 ``` ## Listeners @@ -1342,16 +1469,15 @@ order for SSL to be enabled. The _default_ parameter can be used to signal that MaxScale should use a default value for the parameter in question. ``` -'listener' - Create a new listener for a service +create listener - Create a new listener for a service Usage: create listener SERVICE NAME [HOST] [PORT] [PROTOCOL] [AUTHENTICATOR] [OPTIONS] [SSL_KEY] [SSL_CERT] [SSL_CA] [SSL_VERSION] [SSL_VERIFY_DEPTH] -Create a new server from the following parameters. - +Parameters SERVICE Service where this listener is added NAME Listener name -HOST Listener host address (default 0.0.0.0) +HOST Listener host address (default [::]) PORT Listener port (default 3306) PROTOCOL Listener protocol (default MySQLClient) AUTHENTICATOR Authenticator module name (default MySQLAuth) @@ -1365,6 +1491,8 @@ SSL_VERIFY_DEPTH Certificate verification depth The first two parameters are required, the others are optional. Any of the optional parameters can also have the value 'default' which will be replaced with the default value. + +Example: create listener my-service my-new-listener 192.168.0.101 4006 ``` ### Destroying Listeners @@ -1375,9 +1503,16 @@ startup. The listener is stopped but it will remain a part of the runtime configuration until the next restart. ``` -'listener' - Destroy a listener +destroy listener - Destroy a listener Usage: destroy listener SERVICE NAME + +Parameters: +NAME Listener to destroy + +The listener is stopped and it will be removed on the next restart of MaxScale + +Example: destroy listener my-listener ``` ## Monitors @@ -1390,11 +1525,15 @@ it with the `restart monitor` command. The _user_ and _password_ parameters of the monitor must be defined before the monitor is started. ``` -'monitor' - Create a new monitor +create monitor - Create a new monitor Usage: create monitor NAME MODULE + +Parameters: NAME Monitor name MODULE Monitor module + +Example: create monitor my-monitor mysqlmon ``` ### Altering Monitors @@ -1403,13 +1542,26 @@ To alter a monitor, use the `alter monitor` command. Module specific parameters can also be altered. ``` -'monitor' - Alter monitor parameters +alter monitor - Alter monitor parameters Usage: alter monitor NAME KEY=VALUE ... +Parameters: +NAME Monitor name +KEY=VALUE List of `key=value` pairs separated by spaces + +All monitors support the following values for KEY: +user Username used when connecting to servers +password Password used when connecting to servers +monitor_interval Monitoring interval in milliseconds +backend_connect_timeout Server coneection timeout in seconds +backend_write_timeout Server write timeout in seconds +backend_read_timeout Server read timeout in seconds + This will alter an existing parameter of a monitor. To remove parameters, pass an empty value for a key e.g. 'maxadmin alter monitor my-monitor my-key=' -A maximum of 11 key-value pairs can be changed at one time + +Example: alter monitor my-monitor user=maxuser password=maxpwd ``` ### Destroying Monitors @@ -1420,9 +1572,16 @@ should be destroyed and they will remain a part of the runtime configuration until the next restart. ``` -'monitor' - Destroy a monitor +destroy monitor - Destroy a monitor Usage: destroy monitor NAME + +Parameters: +NAME Monitor to destroy + +The monitor is stopped and it will be removed on the next restart of MaxScale + +Example: destroy monitor my-monitor ``` ## Other Modules @@ -1434,6 +1593,18 @@ To list all module commands, execute `list commands` in maxadmin. This shows all commands that the modules have exposed. It also explains what they do and what sort of arguments they take. +``` +list commands - List registered commands + +Usage: list commands [MODULE] [COMMAND] + +Parameters: +MODULE Regular expressions for filtering module names +COMMAND Regular expressions for filtering module command names + +Example: list commands my-module my-command +``` + If no module commands are registered, no output will be generated. Refer to the module specific documentation for more details about module commands. @@ -1442,6 +1613,21 @@ maxadmin. The __ is the name of the module and __ is the command that should be called. The commands take a variable amount of arguments which are explained in the output of `list commands`. +``` +call command - Call module command + +Usage: call command MODULE COMMAND ARGS... + +Parameters: +MODULE The module name +COMMAND The command to call +ARGS... Arguments for the command + +To list all registered commands, run 'list commands'. + +Example: call command my-module my-command hello world! +``` + An example of this is the `dbfwfilter` module that implements a rule reloading mechanism as a module command. This command takes a filter name as a parameter. @@ -1506,31 +1692,35 @@ increasing the number of non-blocking polls should help the situation. ``` MaxScale> show epoll -Number of epoll cycles: 534 -Number of epoll cycles with wait: 10447 -Number of read events: 35 -Number of write events: 1988 -Number of error events: 0 -Number of hangup events: 1 -Number of accept events: 3 -Number of times no threads polling: 5 -Current event queue length: 1 -Maximum event queue length: 2 -Number of DCBs with pending events: 0 -Number of wakeups with pending queue: 0 + +Poll Statistics. + +No. of epoll cycles: 343 +No. of epoll cycles with wait: 66 +No. of epoll calls returning events: 19 +No. of non-blocking calls returning events: 10 +No. of read events: 2 +No. of write events: 15 +No. of error events: 0 +No. of hangup events: 0 +No. of accept events: 4 +No. of times no threads polling: 4 +Total event queue length: 1 +Average event queue length: 1 +Maximum event queue length: 1 No of poll completions with descriptors - No. of descriptors No. of poll completions. - 1 534 - 2 0 - 3 0 - 4 0 - 5 0 - 6 0 - 7 0 - 8 0 - 9 0 - >= 10 0 -MaxScale> + No. of descriptors No. of poll completions. + 1 19 + 2 0 + 3 0 + 4 0 + 5 0 + 6 0 + 7 0 + 8 0 + 9 0 + >= 10 0 +MaxScale> ``` If the "Number of DCBs with pending events" grows rapidly it is an indication @@ -1549,46 +1739,49 @@ events took to execute once they have been allocated a thread to run on. ``` MaxScale> show eventstats + Event statistics. -Maximum queue time: 2600ms -Maximum execution time: 1600ms -Maximum event queue length: 3 -Current event queue length: 3 +Maximum queue time: 000ms +Maximum execution time: 000ms +Maximum event queue length: 1 +Total event queue length: 4 +Average event queue length: 1 + | Number of events Duration | Queued | Executed ---------------+------------+----------- - < 100ms | 107 | 461 - 100 - 200ms | 958 | 22830 - 200 - 300ms | 20716 | 2545 - 300 - 400ms | 3284 | 253 - 400 - 500ms | 505 | 45 - 500 - 600ms | 66 | 73 - 600 - 700ms | 116 | 169 - 700 - 800ms | 319 | 185 - 800 - 900ms | 382 | 42 - 900 - 1000ms | 95 | 31 - 1000 - 1100ms | 63 | 7 - 1100 - 1200ms | 18 | 4 - 1200 - 1300ms | 8 | 2 - 1300 - 1400ms | 6 | 0 - 1400 - 1500ms | 1 | 1 - 1500 - 1600ms | 3 | 1 - 1600 - 1700ms | 2 | 1 - 1700 - 1800ms | 2 | 0 - 1800 - 1900ms | 0 | 0 - 1900 - 2000ms | 1 | 0 - 2000 - 2100ms | 0 | 0 - 2100 - 2200ms | 0 | 0 - 2200 - 2300ms | 0 | 0 - 2300 - 2400ms | 0 | 0 - 2400 - 2500ms | 0 | 0 - 2500 - 2600ms | 0 | 0 - 2600 - 2700ms | 1 | 0 - 2700 - 2800ms | 0 | 0 - 2800 - 2900ms | 0 | 0 - 2900 - 3000ms | 0 | 0 - > 3000ms | 0 | 0 -MaxScale> + < 100ms | 27 | 26 + 100 - 200ms | 0 | 0 + 200 - 300ms | 0 | 0 + 300 - 400ms | 0 | 0 + 400 - 500ms | 0 | 0 + 500 - 600ms | 0 | 0 + 600 - 700ms | 0 | 0 + 700 - 800ms | 0 | 0 + 800 - 900ms | 0 | 0 + 900 - 1000ms | 0 | 0 + 1000 - 1100ms | 0 | 0 + 1100 - 1200ms | 0 | 0 + 1200 - 1300ms | 0 | 0 + 1300 - 1400ms | 0 | 0 + 1400 - 1500ms | 0 | 0 + 1500 - 1600ms | 0 | 0 + 1600 - 1700ms | 0 | 0 + 1700 - 1800ms | 0 | 0 + 1800 - 1900ms | 0 | 0 + 1900 - 2000ms | 0 | 0 + 2000 - 2100ms | 0 | 0 + 2100 - 2200ms | 0 | 0 + 2200 - 2300ms | 0 | 0 + 2300 - 2400ms | 0 | 0 + 2400 - 2500ms | 0 | 0 + 2500 - 2600ms | 0 | 0 + 2600 - 2700ms | 0 | 0 + 2700 - 2800ms | 0 | 0 + 2800 - 2900ms | 0 | 0 + 2900 - 3000ms | 0 | 0 + > 3000ms | 0 | 0 +MaxScale> ``` The statics are defined in 100ms buckets, with the count of the events that fell diff --git a/Documentation/Routers/Avrorouter.md b/Documentation/Routers/Avrorouter.md index dcd86c648..8676955a3 100644 --- a/Documentation/Routers/Avrorouter.md +++ b/Documentation/Routers/Avrorouter.md @@ -262,8 +262,7 @@ For more information on how to use these scripts, see the output of `cdc.py -h` To build the avrorouter from source, you will need the [Avro C](https://avro.apache.org/docs/current/api/c/) library, liblzma, [the Jansson library](http://www.digip.org/jansson/) and sqlite3 development headers. When -configuring MaxScale with CMake, you will need to add `-DBUILD_CDC=Y --DBUILD_CDC=Y` to build the avrorouter and the CDC protocol module. +configuring MaxScale with CMake, you will need to add `-DBUILD_CDC=Y` to build the CDC module set. For more details about building MaxScale from source, please refer to the [Building MaxScale from Source Code](../Getting-Started/Building-MaxScale-from-Source-Code.md) document. diff --git a/Documentation/Routers/Binlogrouter.md b/Documentation/Routers/Binlogrouter.md index fe12fd470..a0d4bc43e 100644 --- a/Documentation/Routers/Binlogrouter.md +++ b/Documentation/Routers/Binlogrouter.md @@ -13,7 +13,7 @@ replication setup where replication is high-priority. ## Mandatory Router Parameters -The binlogrouter requires the `server`, `user` and `passwd` parameters. These +The binlogrouter requires the `server`, `user` and `password` parameters. These should be configured according to the [Configuration Guide](../Getting-Started/Configuration-Guide.md#service). @@ -32,18 +32,20 @@ following options should be given as a value to the `router_options` parameter. ### `binlogdir` -This parameter allows the location that MariaDB MaxScale uses to store binlog -files to be set. If this parameter is not set to a directory name then MariaDB +This parameter controls the location where MariaDB MaxScale stores the binary log +files. If this parameter is not set to a directory name then MariaDB MaxScale will store the binlog files in the directory -/var/cache/maxscale/. In the binlog dir there is also the 'cache' -directory that contains data retrieved from the master during registration phase -and the master.ini file which contains the configuration of current configured -master. +`/var/cache/maxscale/` where `` is the name of the +service in the configuration file. The _binlogdir_ also contains the +_cache_ subdirectory which stores data retrieved from the master during the slave +registration phase. The master.ini file also resides in the _binlogdir_. This +file keeps track of the current master configuration and it is updated when a +`CHANGE MASTER TO` query is executed. From 2.1 onwards, the 'cache' directory is stored in the same location as other user credential caches. This means that with the default options, the user credential cache is stored in -/var/cache/maxscale///cache/. +`/var/cache/maxscale///cache/`. Read the [MySQL Authenticator](../Authenticators/MySQL-Authenticator.md) documentation for instructions on how to define a custom location for the user @@ -51,45 +53,45 @@ cache. ### `uuid` -This is used to set the unique uuid that the binlog router uses when it connects -to the master server. If no explicit value is given for the uuid in the -configuration file then a uuid will be generated. +This is used to set the unique UUID that the binlog router uses when it connects +to the master server. If no explicit value is given for the UUID in the +configuration file then a UUID will be generated. ### `server_id` -As with uuid, MariaDB MaxScale must have a unique _server id_ for the connection -it makes to the master. This parameter provides the value of the server id that +As with UUID, MariaDB MaxScale must have a unique _server_id_. This parameter +configures the value of the _server_id_ that MariaDB MaxScale will use when connecting to the master. -The id can also be specified using `server-id` but that is deprecated -and will be removed in a future release of MariaDB MaxScale. +Older versions of MaxScale allowed the ID to be specified using `server-id`. +This has been deprecated and will be removed in a future release of MariaDB MaxScale. ### `master_id` -The _server id_ value that MariaDB MaxScale should use to report to the slaves +The _server_id_ value that MariaDB MaxScale should use to report to the slaves that connect to MariaDB MaxScale. This may either be the same as the server id of the real master or can be chosen to be different if the slaves need to be -aware of the proxy layer. The real master server id will be used if the option +aware of the proxy layer. The real master server ID will be used if the option is not set. -The id can also be specified using `master-id` but that is deprecated -and will be removed in a future release of MariaDB MaxScale. +Older versions of MaxScale allowed the ID to be specified using `master-id`. +This has been deprecated and will be removed in a future release of MariaDB MaxScale. ### `master_uuid` -It is a requirement of replication that each slave have a unique UUID value. The -MariaDB MaxScale router will identify itself to the slaves using the uuid of the +It is a requirement of replication that each slave has a unique UUID value. The +MariaDB MaxScale router will identify itself to the slaves using the UUID of the real master if this option is not set. ### `master_version` -The MariaDB MaxScale router will identify itself to the slaves using the server -version of the real master if this option is not set. +By default, the router will identify itself to the slaves using the server +version of the real master. This option allows the router to use a custom version string. ### `master_hostname` -The MariaDB MaxScale router will identify itself to the slaves using the server -hostname of the real master if this option is not set. +By default, the router will identify itself to the slaves using the +hostname of the real master. This option allows the router to use a custom hostname. ### `user` @@ -113,13 +115,13 @@ the router options or using the username and password defined of the service must be granted replication privileges on the database server. ``` - MariaDB> CREATE USER 'repl'@'maxscalehost' IDENTIFIED by 'password'; - MariaDB> GRANT REPLICATION SLAVE ON *.* TO 'repl'@'maxscalehost'; +CREATE USER 'repl'@'maxscalehost' IDENTIFIED by 'password'; +GRANT REPLICATION SLAVE ON *.* TO 'repl'@'maxscalehost'; ``` ### `password` -The password of the above user. If the password is not explicitly given then the +The password for the user. If the password is not explicitly given then the password in the service entry will be used. For compatibility with other username and password definitions within the MariaDB MaxScale configuration file it is also possible to use the parameter passwd=. @@ -167,9 +169,9 @@ incomplete transactions detection. ### `send_slave_heartbeat` -This defines whether (on | off) MariaDB MaxScale sends to the slave the -heartbeat packet when there are no real binlog events to send. The default value -if 'off', no heartbeat event is sent to slave server. If value is 'on' the +This defines whether MariaDB MaxScale sends the heartbeat packet to the slave +when there are no real binlog events to send. The default value +is 'off' and no heartbeat events are sent to slave servers. If value is 'on' the interval value (requested by the slave during registration) is reported in the diagnostic output and the packet is send after the time interval without any event to send. @@ -205,6 +207,7 @@ master.ini or later via CHANGE MASTER TO. This parameter cannot be modified at runtime, default is 9. ### `encrypt_binlog` + Whether to encrypt binlog files: the default is Off. When set to On the binlog files will be encrypted using specified AES algorithm @@ -226,11 +229,11 @@ the binlog events positions in binlog file are the same as in the master binlog file and there is no position mismatch. ### `encryption_algorithm` -'aes_ctr' or 'aes_cbc' -The default is 'aes_cbc' +The encryption algorithm, either 'aes_ctr' or 'aes_cbc'. The default is 'aes_cbc' ### `encryption_key_file` + The specified key file must contains lines with following format: `id;HEX(KEY)` @@ -277,10 +280,8 @@ values may be used for all other options. ## Examples -The [Replication -Proxy](../Tutorials/Replication-Proxy-Binlog-Router-Tutorial.md) tutorial will +The [Replication Proxy](../Tutorials/Replication-Proxy-Binlog-Router-Tutorial.md) tutorial will show you how to configure and administrate a binlogrouter installation. - Tutorial also includes SSL communication setup to the master server and SSL client connections setup to MaxScale Binlog Server. diff --git a/Documentation/Routers/Debug-CLI.md b/Documentation/Routers/Debug-CLI.md index 25a0dc472..2d7251509 100644 --- a/Documentation/Routers/Debug-CLI.md +++ b/Documentation/Routers/Debug-CLI.md @@ -18,38 +18,4 @@ protocol=telnetd port=4442 ``` -Connections using the telnet protocol to port 4442 of the MariaDB MaxScale host will result in a new debug CLI session. A default username and password are used for this module, new users may be created using the add user command. As soon as any users are explicitly created the default username will no longer continue to work. The default username is admin with a password of mariadb. - -The debugcli supports two modes of operation, `developer` and `user`. The mode is set via the `router_options` parameter. The user mode is more suited to end-users and administrators, whilst the develop mode is explicitly targeted to software developing adding or maintaining the MariaDB MaxScale code base. Details of the differences between the modes can be found in the debugging guide for MariaDB MaxScale. The default is `user` mode. The following service definition would enable a developer version of the debugcli. - -``` -[Debug Service] -type=service -router=debugcli -router_options=developer -``` - -It should be noted that both `user` and `developer` instances of debugcli may be defined within the same instance of MariaDB MaxScale, however they must be defined as two distinct services, each with a distinct listener. - -``` -[Debug Service] -type=service -router=debugcli -router_options=developer - -[Debug Listener] -type=listener -service=Debug Service -protocol=telnetd -port=4442 - -[Admin Service] -type=service -router=debugcli - -[Admin Listener] -type=listener -service=Debug Service -protocol=telnetd -port=4242 -``` +Connections using the telnet protocol to port 4442 of the MariaDB MaxScale host will result in a new debug CLI session. A default username and password are used for this module, new users may be created using the administrative interface. As soon as any users are explicitly created the default username will no longer continue to work. The default username is `admin` with a password of `mariadb`. diff --git a/Documentation/Routers/ReadConnRoute.md b/Documentation/Routers/ReadConnRoute.md index b34442526..f6c20b249 100644 --- a/Documentation/Routers/ReadConnRoute.md +++ b/Documentation/Routers/ReadConnRoute.md @@ -8,11 +8,9 @@ The readconnroute router provides simple and lightweight load balancing across a ## Configuration -Readconnroute router-specific settings are specified in the configuration file of MariaDB MaxScale in its specific section. The section can be freely named but the name is used later as a reference from listener section. - For more details about the standard service parameters, refer to the [Configuration Guide](../Getting-Started/Configuration-Guide.md). -## Router Options +### Router Options **`router_options`** can contain a list of valid server roles. These roles are used as the valid types of servers the router will form connections to when new sessions are created. ``` diff --git a/Documentation/Routers/SchemaRouter.md b/Documentation/Routers/SchemaRouter.md index b9956d978..36bef935b 100644 --- a/Documentation/Routers/SchemaRouter.md +++ b/Documentation/Routers/SchemaRouter.md @@ -1,4 +1,4 @@ -#SchemaRouter Router +# SchemaRouter Router The SchemaRouter router provides an easy and manageable sharding solution by building a single logical database server from multiple separate ones. Each database is shown to the client and queries targeting unique databases are routed to their respective servers. In addition to providing simple database-based sharding, the schemarouter router also enables cross-node session variable usage by routing all queries that modify the session to all nodes. @@ -29,7 +29,7 @@ The list of databases is built by sending a SHOW DATABASES query to all the serv If you are connecting directly to a database or have different users on some of the servers, you need to get the authentication data from all the servers. You can control this with the `auth_all_servers` parameter. With this parameter, MariaDB MaxScale forms a union of all the users and their grants from all the servers. By default, the schemarouter will fetch the authentication data from all servers. -For example, if two servers have the database 'shard' and the following rights are granted only on one server, all queries targeting the database 'shard' would be routed to the server where the grants were given. +For example, if two servers have the database `shard` and the following rights are granted only on one server, all queries targeting the database `shard` would be routed to the server where the grants were given. ``` # Execute this on both servers @@ -68,6 +68,8 @@ refresh_interval=60 ## Router Options +**Note:** Router options for the Schemarouter were deprecated in MaxScale 2.1. + The following options are options for the `router_options` parameter of the service. Multiple router options are given as a comma separated list of key value pairs. @@ -87,7 +89,7 @@ will not be consistent anymore. ### `refresh_databases` Enable database map refreshing mid-session. These are triggered by a failure to -change the database i.e. `USE ...``queries. +change the database i.e. `USE ...` queries. ### `refresh_interval` diff --git a/Documentation/Tutorials/MaxScale-HA-with-Corosync-Pacemaker.md b/Documentation/Tutorials/MaxScale-HA-with-Corosync-Pacemaker.md index ee7d2ab5c..e41fcf559 100644 --- a/Documentation/Tutorials/MaxScale-HA-with-Corosync-Pacemaker.md +++ b/Documentation/Tutorials/MaxScale-HA-with-Corosync-Pacemaker.md @@ -12,15 +12,15 @@ Please note the solution is a quick setup example that may not be suited for all ## Clustering Software installation -On each node in the cluster do the following steps: +On each node in the cluster do the following steps. -(1) Add clustering repos to yum +### Add clustering repos to yum ``` # vi /etc/yum.repos.d/ha-clustering.repo ``` -Add the following to the file +Add the following to the file. ``` [haclustering] @@ -30,7 +30,7 @@ enabled=1 gpgcheck=0 ``` -(2) Install the software +### Install the software ``` # yum install pacemaker corosync crmsh @@ -44,7 +44,7 @@ Package corosync-1.4.5-2.4.x86_64 Package crmsh-2.0+git46-1.1.x86_64 ``` -(3) Assign hostname on each node +### Assign hostname on each node In this example the three names used for the nodes are: node1,node,node3 @@ -56,7 +56,7 @@ In this example the three names used for the nodes are: node1,node,node3 [root@server3 ~]# hostname node3 ``` -(4) For each node add server names in /etc/hosts +For each node, add all the server names into `/etc/hosts`. ``` [root@node3 ~]# vi /etc/hosts @@ -70,9 +70,9 @@ In this example the three names used for the nodes are: node1,node,node3 10.35.15.26 node3 ``` -**Please note**: add **current-node** as an alias for the current node in each of the /etc/hosts files. +**Note**: add _current-node_ as an alias for the current node in each of the /etc/hosts files. -(5) Prepare authkey for optional cryptographic use +### Prepare authkey for optional cryptographic use On one of the nodes, say node2 run the corosync-keygen utility and follow @@ -84,7 +84,7 @@ Corosync Cluster Engine Authentication key generator. Gathering 1024 bits After completion the key will be found in /etc/corosync/authkey. ``` -(6) Prepare the corosync configuration file +### Prepare the corosync configuration file Using node2 as an example: @@ -141,7 +141,7 @@ name: pacemaker } ``` -**Please note** in this example: +**Note**: in this example: - unicast UDP is used @@ -149,7 +149,7 @@ name: pacemaker - Pacemaker processes are started by the corosync daemon, so there is no need to launch it via /etc/init.d/pacemaker start -(7) copy configuration files and auth key on each of the other nodes +### Copy configuration files and auth key on each of the other nodes ``` [root@node2 ~]# scp /etc/corosync/* root@node1:/etc/corosync/ @@ -157,11 +157,7 @@ name: pacemaker [root@node2 ~]# scp /etc/corosync/* root@nodeN:/etc/corosync/ ``` -(8) Corosync needs port *5*405 to be opened: - -- configure any firewall or iptables accordingly - -For a quick start just disable iptables on each nodes: +Corosync needs port 5405 to be opened. Configure any firewall or iptables accordingly. For a quick start just disable iptables on each nodes: ``` [root@node2 ~]# service iptables stop @@ -169,7 +165,7 @@ For a quick start just disable iptables on each nodes: [root@nodeN ~]# service iptables stop ``` -(9) Start Corosyn on each node: +### Start Corosyn on each node ``` [root@node2 ~] #/etc/init.d/corosync start @@ -177,14 +173,14 @@ For a quick start just disable iptables on each nodes: [root@nodeN ~] #/etc/init.d/corosync start ``` -and check the corosync daemon is successfully bound to port 5405: +Check that the corosync daemon is successfully bound to port 5405. ``` [root@node2 ~] #netstat -na | grep 5405 udp 0 0 10.228.103.72:5405 0.0.0.0:* ``` -Check if other nodes are reachable with nc utility and option UDP (-u): +Check if other nodes are reachable with nc utility and option UDP (-u). ``` [root@node2 ~] #echo "check ..." | nc -u node1 5405 @@ -194,19 +190,21 @@ Check if other nodes are reachable with nc utility and option UDP (-u): [root@node1 ~] #echo "check ..." | nc -u node3 5405 ``` -If the following message is displayed +If the following message is displayed, there is an issue with communication between the nodes. -**nc: Write error: Connection refused** +``` +nc: Write error: Connection refused +``` -There is an issue with communication between the nodes, this is most likely to be an issue with the firewall configuration on your nodes. Check and resolve issues with your firewall configuration. +This is most likely to be an issue with the firewall configuration on your nodes. Check and resolve any issues with your firewall configuration. -(10) Check the cluster status, from any node +### Check the cluster status from any node ``` [root@node3 ~]# crm status ``` -After a while this will be the output: +The command should produce the following. ``` [root@node3 ~]# crm status @@ -239,9 +237,9 @@ For additional information see: [http://clusterlabs.org/doc/](http://clusterlabs.org/doc/) -The configuration is automatically updated on every node: +The configuration is automatically updated on every node. -Check it from another node, say node1 +Check it from another node, say node1: ``` [root@node1 ~]# crm configure show @@ -260,9 +258,9 @@ property cib-bootstrap-options: \ The Corosync / Pacemaker cluster is ready to be configured to manage resources. -## MariaDB MaxScale init script /etc/init.d/maxscale +## MariaDB MaxScale init script -The MariaDB MaxScale /etc/init.d./maxscale script allows to start/stop/restart and monitor MariaDB MaxScale process running in the system. +The MariaDB MaxScale init script in `/etc/init.d./maxscale` allows to start, stop, restart and monitor the MariaDB MaxScale process running on the system. ``` [root@node1 ~]# /etc/init.d/maxscale @@ -315,14 +313,11 @@ Checking MaxScale status: MaxScale (pid 25953) is running.[ OK ] The script exit code for "status" is 0 - -Note: the MariaDB MaxScale script is LSB compatible and returns the proper exit code for each action: - -For additional information; +Read the following for additional information about LSB init scripts: [http://www.linux-ha.org/wiki/LSB_Resource_Agents](http://www.linux-ha.org/wiki/LSB_Resource_Agents) -After checking MariaDB MaxScale is well managed by the /etc/init.d/script is possible to configure the MariaDB MaxScale HA via Pacemaker. +After checking that the init scripts for MariaDB MaxScale work, it is possible to configure MariaDB MaxScale for HA via Pacemaker. # Configure MariaDB MaxScale for HA with Pacemaker @@ -333,7 +328,7 @@ op start interval="0” timeout=”15s” \ op stop interval="0” timeout=”30s” ``` -MaxScale resource will be started: +MaxScale resource will be started. ``` [root@node2 ~]# crm status @@ -351,11 +346,11 @@ Online: [ node1 node2 node3 ] MaxScale (lsb:maxscale): Started node1 ``` -##Basic use cases: +## Basic use cases -### 1. Resource restarted after a failure: +### Resource restarted after a failure -In the example MariaDB MaxScale PID is 26114, kill the process immediately: +In the example MariaDB MaxScale PID is 26114, kill the process immediately. ``` [root@node2 ~]# kill -9 26114 @@ -377,9 +372,9 @@ Failed actions: MaxScale_monitor_15000 on node1 'not running' (7): call=19, status=complete, last-rc-change='Mon Jun 30 13:16:14 2014', queued=0ms, exec=0ms ``` -**Note** the **MaxScale_monitor** failed action +**Note**: the _MaxScale_monitor_ failed action -After a few seconds it will be started again: +After a few seconds it will be started again. ``` [root@node2 ~]# crm status @@ -397,9 +392,9 @@ Online: [ node1 node2 node3 ] MaxScale (lsb:maxscale): Started node1 ``` -### 2. The resource cannot be migrated to node1 for a failure: +### The resource cannot be migrated to node1 for a failure -First, migrate the the resource to another node, say node3 +First, migrate the the resource to another node, say node3. ``` [root@node1 ~]# crm resource migrate MaxScale node3 @@ -412,7 +407,7 @@ Failed actions: MaxScale_start_0 on node1 'not running' (7): call=76, status=complete, last-rc-change='Mon Jun 30 13:31:17 2014', queued=2015ms, exec=0ms ``` -Note the **MaxScale_start** failed action on node1, and after a few seconds +**Note**: the _MaxScale_start_ failed action on node1, and after a few seconds. ``` [root@node3 ~]# crm status @@ -434,7 +429,7 @@ Failed actions: MaxScale_start_0 on node1 'not running' (7): call=76, status=complete, last-rc-change='Mon Jun 30 13:31:17 2014', queued=2015ms, exec=0ms ``` -Successfully, MaxScale has been started on a new node: node2. +Successfully, MaxScale has been started on a new node (node2). **Note**: Failed actions remain in the output of crm status. @@ -447,7 +442,7 @@ Cleaning up MaxScale on node2 Cleaning up MaxScale on node3 ``` -The cleaned status is visible from other nodes as well: +The cleaned status is visible from other nodes as well. ``` [root@node2 ~]# crm status @@ -467,25 +462,21 @@ Online: [ node1 node2 node3 ] ## Add a Virtual IP (VIP) to the cluster -It’s possible to add a virtual IP to the cluster: +It’s possible to add a virtual IP to the cluster. MariaDB MaxScale process will be only contacted via this IP. The virtual IP can move across nodes in case one of them fails. -MariaDB MaxScale process will be only contacted with this IP, that mat move across nodes with maxscale process as well. - -Setup is very easy: - -assuming an addition IP address is available and can be added to one of the nodes, this i the new configuration to add: +The Setup is very easy. Assuming an addition IP address is available and can be added to one of the nodes, this is the new configuration to add. ``` [root@node2 ~]# crm configure primitive maxscale_vip ocf:heartbeat:IPaddr2 params ip=192.168.122.125 op monitor interval=10s ``` -MariaDB MaxScale process and the VIP must be run in the same node, so it’s mandatory to add to the configuration the group ‘maxscale_service’. +MariaDB MaxScale process and the VIP must be run in the same node, so it is mandatory to add to the configuration to the group ‘maxscale_service’. ``` [root@node2 ~]# crm configure group maxscale_service maxscale_vip MaxScale ``` -The final configuration is, from another node: +The following is the final configuration. ``` [root@node3 ~]# crm configure show @@ -511,7 +502,7 @@ property cib-bootstrap-options: \ last-lrm-refresh=1404125486 ``` -Check the resource status: +Check the resource status. ``` [root@node1 ~]# crm status @@ -533,5 +524,5 @@ Online: [ node1 node2 node3 ] MaxScale (lsb:maxscale): Started node2 ``` -With both resources on node2, now MariaDB MaxScale service will be reachable via the configured VIP address 192.168.122.125 +With both resources on node2, now MariaDB MaxScale service will be reachable via the configured VIP address 192.168.122.125. diff --git a/Documentation/Tutorials/MySQL-Replication-Connection-Routing-Tutorial.md b/Documentation/Tutorials/MySQL-Replication-Connection-Routing-Tutorial.md index 597fdf717..c14ff8a5d 100644 --- a/Documentation/Tutorials/MySQL-Replication-Connection-Routing-Tutorial.md +++ b/Documentation/Tutorials/MySQL-Replication-Connection-Routing-Tutorial.md @@ -12,34 +12,34 @@ Once you have MariaDB MaxScale installed and the database users created, we can ## Creating Your MariaDB MaxScale Configuration -MariaDB MaxScale reads its configuration from `/etc/maxscale.cnf`. This is not created as part of the installation process and must be manually created. A template file does exist in the `/usr/share/maxscale` folder that can be use as a basis for your configuration. +MariaDB MaxScale reads its configuration from `/etc/maxscale.cnf`. A template configuration is provided with the MaxScale installation. -A global, maxscale, section is included within every MariaDB MaxScale configuration file; this is used to set the values of various MariaDB MaxScale wide parameters, perhaps the most important of these is the number of threads that MariaDB MaxScale will use to execute the code that forwards requests and handles responses for clients. +A global, `[maxscale]`, section is included within every MariaDB MaxScale configuration file; this is used to set the values of various MariaDB MaxScale wide parameters, perhaps the most important of these is the number of threads that MariaDB MaxScale will use to handle client requests. ``` [maxscale] threads=4 ``` -Since we are using MySQL Replication and connection routing we want two different ports to which the client application can connect; one that will be directed to the current master within the replication cluster and another that will load balance between the slaves. To achieve this within MariaDB MaxScale we need to define two services in the ini file; one for the read/write operations that should be executed on the master server and another for connections to one of the slaves. Create a section for each in your MariaDB MaxScale configuration file and set the type to service, the section names are the names of the services themselves and should be meaningful to the administrator. Names may contain whitespace. +Since we are using MySQL Replication and connection routing we want two different ports to which the client application can connect; one that will be directed to the current master within the replication cluster and another that will load balance between the slaves. To achieve this within MariaDB MaxScale we need to define two services in the ini file; one for the read/write operations that should be executed on the master server and another for connections to one of the slaves. Create a section for each in your MariaDB MaxScale configuration file and set the type to service, the section names are the names of the services themselves and should be meaningful to the administrator. Avoid using whitespace in the section names. ``` -[Write Service] +[Write-Service] type=service -[Read Service] +[Read-Service] type=service ``` The router for these two sections is identical, the readconnroute module, also the services should be provided with the list of servers that will be part of the cluster. The server names given here are actually the names of server sections in the configuration file and not the physical hostnames or addresses of the servers. ``` -[Write Service] +[Write-Service] type=service router=readconnroute servers=dbserv1, dbserv2, dbserv3 -[Read Service] +[Read-Service] type=service router=readconnroute servers=dbserv1, dbserv2, dbserv3 @@ -48,13 +48,13 @@ servers=dbserv1, dbserv2, dbserv3 In order to instruct the router to which servers it should route we must add router options to the service. The router options are compared to the status that the monitor collects from the servers and used to restrict the eligible set of servers to which that service may route. In our case we use the two options master and slave for our two services. ``` -[Write Service] +[Write-Service] type=service router=readconnroute router_options=master servers=dbserv1, dbserv2, dbserv3 -[Read Service] +[Read-Service] type=service router=readconnroute router_options=slave @@ -77,7 +77,7 @@ maxpasswd plainpassword The username and password, either encrypted or plain text, are stored in the service section using the user and passwd parameters. ``` -[Write Service] +[Write-Service] type=service router=readconnroute router_options=master @@ -85,7 +85,7 @@ servers=dbserv1, dbserv2, dbserv3 user=maxscale passwd=96F99AA1315BDC3604B006F427DD9484 -[Read Service] +[Read-Service] type=service router=readconnroute router_options=slave @@ -97,28 +97,28 @@ passwd=96F99AA1315BDC3604B006F427DD9484 This completes the definitions required by the services, however listening ports must be associated with the services in order to allow network connections. This is done by creating a series of listener sections. These sections again are named for the convenience of the administrator and should be of type listener with an entry labeled service which contains the name of the service to associate the listener with. Each service may have multiple listeners. ``` -[Write Listener] +[Write-Listener] type=listener -service=Write Service +service=Write-Service -[Read Listener] +[Read-Listener] type=listener -service=Read Service +service=Read-Service ``` A listener must also define the protocol module it will use for the incoming network protocol, currently this should be the MySQLClient protocol for all database listeners. The listener may then supply a network port to listen on and/or a socket within the file system. ``` -[Write Listener] +[Write-Listener] type=listener -service=Write Service +service=Write-Service protocol=MySQLClient port=4306 socket=/tmp/ClusterMaster -[Read Listener] +[Read-Listener] type=listener -service=Read Service +service=Read-Service protocol=MySQLClient port=4307 ``` @@ -150,7 +150,7 @@ protocol=MySQLBackend In order for MariaDB MaxScale to monitor the servers using the correct monitoring mechanisms a section should be provided that defines the monitor to use and the servers to monitor. Once again a section is created with a symbolic name for the monitor, with the type set to monitor. Parameters are added for the module to use, the list of servers to monitor and the username and password to use when connecting to the the servers with the monitor. ``` -[Replication Monitor] +[Replication-Monitor] type=monitor module=mysqlmon servers=dbserv1, dbserv2, dbserv3 @@ -168,7 +168,7 @@ The final stage in the configuration is to add the option service which is used type=service router=cli -[CLI Listener] +[CLI-Listener] type=listener service=CLI protocol=maxscaled @@ -195,59 +195,38 @@ Check the error log in /var/log/maxscale/ to see if any errors are detected in t % maxadmin list services Services. - --------------------------+----------------------+--------+--------------- - Service Name | Router Module | #Users | Total Sessions - --------------------------+----------------------+--------+--------------- - Read Service | readconnroute | 1 | 1 - Write Service | readconnroute | 1 | 1 - CLI | cli | 2 | 2 - --------------------------+----------------------+--------+--------------- % maxadmin list servers Servers. - -------------------+-----------------+-------+-------------+-------------------- - Server | Address | Port | Connections | Status - -------------------+-----------------+-------+-------------+-------------------- - dbserv1 | 192.168.2.1 | 3306 | 0 | Running, Slave - dbserv2 | 192.168.2.2 | 3306 | 0 | Running, Master - dbserv3 | 192.168.2.3 | 3306 | 0 | Running, Slave - -------------------+-----------------+-------+-------------+-------------------- % maxadmin list listeners Listeners. - ---------------------+--------------------+-----------------+-------+-------- - Service Name | Protocol Module | Address | Port | State - ---------------------+--------------------+-----------------+-------+-------- - Read Service | MySQLClient | * | 4307 | Running - Write Service | MySQLClient | * | 4306 | Running - CLI | maxscaled | localhost | 6603 | Running - ---------------------+--------------------+-----------------+-------+-------- - -% ``` -MariaDB MaxScale is now ready to start accepting client connections and routing them to the master or slaves within your cluster. Other configuration options are available that can alter the criteria used for routing, these include monitoring the replication lag within the cluster and routing only to slaves that are within a predetermined delay from the current master or using weights to obtain unequal balancing operations. These options may be found in the MariaDB MaxScale Configuration Guide. More detail on the use of maxadmin can be found in the document [MaxAdmin - The MariaDB MaxScale Administration & Monitoring Client Application](Administration-Tutorial.md). +MariaDB MaxScale is now ready to start accepting client connections and routing them to the master or slaves within your cluster. Other configuration options are available that can alter the criteria used for routing, these include monitoring the replication lag within the cluster and routing only to slaves that are within a predetermined delay from the current master or using weights to obtain unequal balancing operations. These options may be found in the MariaDB MaxScale Configuration Guide. + +More detail on the use of maxadmin can be found in the document [MaxAdmin - The MariaDB MaxScale Administration & Monitoring Client Application](Administration-Tutorial.md). diff --git a/Documentation/Tutorials/Notification-Service.md b/Documentation/Tutorials/Notification-Service.md index 450082cc4..92f733d54 100644 --- a/Documentation/Tutorials/Notification-Service.md +++ b/Documentation/Tutorials/Notification-Service.md @@ -1,27 +1,5 @@ # MariaDB MaxScale Notification Service and Feedback Support -Massimiliano Pinto - -Last Updated: 10th March 2015 - -## Contents - -## Document History - - - - - - - - - - - - -
DateChangeWho
10th March 2015Initial versionMassimiliano Pinto
- - ## Overview The purpose of Notification Service in MariaDB MaxScale is for a customer registered for the service to receive update notices, security bulletins, fixes and workarounds that are tailored to the database server configuration. @@ -30,9 +8,9 @@ The purpose of Notification Service in MariaDB MaxScale is for a customer regist MariaDB MaxScale may collect the installed plugins and send the information's nightly, between 2:00 AM and 4:59 AM. -It tries to send data and if there is any failure (timeout, server is down, etc), the next retry is in 1800 seconds (30 minutes) +It tries to send data and if there is any failure (timeout, server is down, etc), the next retry is in 1800 seconds (30 minutes). -This feature is not enabled by default: MariaDB MaxScale must be configured in [feedback] section: +This feature is not enabled by default: MariaDB MaxScale must be configured in `[feedback]` section: ``` [feedback] @@ -41,15 +19,16 @@ feedback_url=https://enterprise.mariadb.com/feedback/post feedback_user_info=x-y-z-w ``` -The activation code that will be provided by MariaDB corp upon request by the customer and it should be put in feedback_user_info. +The activation code that will be provided by MariaDB Corporation Ab upon request by the customer and it should be put in feedback_user_info. Example: +``` feedback_user_info=0467009f-b04d-45b1-a77b-b6b2ec9c6cf4 - +``` MariaDB MaxScale generates the feedback report containing following information: - -The activation code used to enable feedback + - The activation code used to enable feedback - MariaDB MaxScale Version - An identifier of the MariaDB MaxScale installation, i.e. the HEX encoding of SHA1 digest of the first network interface MAC address - Operating System (i.e Linux) @@ -57,12 +36,12 @@ MariaDB MaxScale generates the feedback report containing following information: - All the modules in use in MariaDB MaxScale and their API and version - MariaDB MaxScale server UNIX_TIME at generation time -MariaDB MaxScale shall send the generated feedback report to a feedback server specified in feedback_url +MariaDB MaxScale shall send the generated feedback report to a feedback server specified in _feedback_url_. ## Manual Operation -If it’s not possible to send data due to firewall or security settings the report could be generated manually (feedback_user_info is required) via MaxAdmin +If it’s not possible to send data due to firewall or security settings the report could be generated manually (feedback_user_info is required) via MaxAdmin. ``` MaxScale>show feedbackreport diff --git a/Documentation/Tutorials/Simple-Sharding-Tutorial.md b/Documentation/Tutorials/Simple-Sharding-Tutorial.md index 62ff35323..7268ef64f 100644 --- a/Documentation/Tutorials/Simple-Sharding-Tutorial.md +++ b/Documentation/Tutorials/Simple-Sharding-Tutorial.md @@ -1,4 +1,4 @@ -#Simple Sharding with Two Servers +# Simple Sharding with Two Servers ![Schema Based Sharding](images/Simple-Sharding.png) @@ -10,25 +10,13 @@ MariaDB MaxScale will appear to the client as a database server with the combina This document is designed as a simple tutorial on schema-based sharding using MariaDB MaxScale in an environment in which you have two servers. The object of this tutorial is to have a system that, to the client side, acts like a single MySQL database but actually is sharded between the two servers. -The process of setting and configuring MariaDB MaxScale will be covered within this document. The installation and configuration of the MySQL servers will not be covered in-depth. The users should be configured according to the configuration guide. +The database users should be configured according to [the configuration guide](../Getting-Started/Configuration-Guide.md). The [MaxScale Tutorial](MaxScale-Tutorial.md) contains easy to follow instructions on how to set up MaxScale. + +This tutorial will assume the user is using of the binary distributions available and has installed this in the default location. The process of configuring MariaDB MaxScale will be covered within this document. The installation and configuration of the MySQL servers will not be covered in-depth. -This tutorial will assume the user is running from one of the binary distributions available and has installed this in the default location. Building from source code in GitHub is covered in guides elsewhere as is installing to non-default locations. +## Preparing MaxScale -## Process - -The steps involved in creating a system from the binary distribution of MariaDB MaxScale are: - -* Install the package relevant to your distribution - -* Create the required users on your MariaDB or MySQL server - -* Create a MariaDB MaxScale configuration file - -### Installation - -The precise installation process will vary from one distribution to another details of what to do with the RPM and DEB packages can be found on the download site when you select the distribution you are downloading from. The process involves setting up your package manager to include the MariaDB repositories and then running the package manager for your distribution, RPM or apt-get. - -Upon successful completion of the installation command you will have MariaDB MaxScale installed and ready to be run but without a configuration. You must create a configuration file before you first run MariaDB MaxScale. +Follow the [MaxScale Tutorial](MaxScale-Tutorial.md) to install and prepare the required database users for MaxScale. You don't need to create the configuration file for MaxScale as it will be covered in the next section. ### Creating Your MariaDB MaxScale Configuration @@ -92,7 +80,8 @@ After this we have a fully working configuration and we can move on to starting Upon completion of the configuration process MariaDB MaxScale is ready to be started . This may either be done manually by running the maxscale command or via the service interface. The service scripts are located in the `/etc/init.d/` folder and are accessible through both the `service` and `systemctl` commands. -After starting MariaDB MaxScale check the error log in /var/log/maxscale to see if any errors are detected in the configuration file. Also the maxadmin command may be used to confirm that MariaDB MaxScale is running and the services, listeners etc have been correctly configured. - MariaDB MaxScale is now ready to start accepting client connections and routing them. Queries are routed to the right servers based on the database they target and switching between the shards is seamless since MariaDB MaxScale keeps the session state intact between servers. +If MariaDB MaxScale fails to start, check the error log in `/var/log/maxscale` to see what sort of errors were detected. + +**Note:** As the sharding solution in MaxScale is relatively simple, cross-database queries between two or more shards are not supported. diff --git a/Documentation/Upgrading/Upgrading-To-MaxScale-2.1.md b/Documentation/Upgrading/Upgrading-To-MaxScale-2.1.md index 100c389cd..929aba427 100644 --- a/Documentation/Upgrading/Upgrading-To-MaxScale-2.1.md +++ b/Documentation/Upgrading/Upgrading-To-MaxScale-2.1.md @@ -14,6 +14,18 @@ For a complete list of changes in MaxScale 2.1.0, refer to the Before starting the upgrade, we **strongly** recommend you back up your current configuration file. +## IPv6 Support + +MaxScale 2.1.2 added support for IPv6 addresses. The default interface that listeners bind to +was changed from the IPv4 address `0.0.0.0` to the IPv6 address `::`. To bind to the old IPv4 address, +add `address=0.0.0.0` to the listener definition. + +## Persisted Configuration Files + +Starting with MaxScale 2.1, any changes made with the newly added +[runtime configuration change](../Reference/MaxAdmin.md#runtime-configuration-changes) +will be persisted in a configuration file. These files are located in `/var/lib/maxscale/maxscale.cnf.d/`. + ## MaxScale Log Files The name of the log file was changed from _maxscaleN.log_ to _maxscale.log_. The