diff --git a/Documentation/About/Limitations.md b/Documentation/About/Limitations.md index 35aa2a1d0..286d2454b 100644 --- a/Documentation/About/Limitations.md +++ b/Documentation/About/Limitations.md @@ -10,6 +10,39 @@ In versions 2.1.2 and earlier, the configuration files are limited to 1024 characters per line. This limitation was increased to 16384 characters in MaxScale 2.1.3. +## Security limitiations + +### MariaDB 10.2 + +The parser of MaxScale correctly parses `WITH` statements, but fails to +collect columns, functions and tables used in the `SELECT` defining the +`WITH` clause. + +Consequently, the database firewall will **not** block `WITH` statements +where the `SELECT` of the `WITH` clause refers to forbidden columns. + +## Prepared Statements + +For its proper functioning, MaxScale needs in general to be aware of the +transaction state and _autocommit_ mode. In order to be that, MaxScale +parses statements going through it. + +However, if a transaction is commited or rolled back, or the autocommit +mode is changed using a prepared statement, MaxScale will miss that and its +internal state will be incorrect, until the transaction state or autocommit +mode is changed using an explicit statement. + +For instance, after the following sequence of commands, MaxScale will still +think _autocommit_ is on: +``` +set autocommit=1 +PREPARE hide_autocommit FROM "set autocommit=0" +EXECUTE hide_autocommit +``` + +To ensure that MaxScale functions properly, do not commit or rollback a +transaction or change the autocommit mode using a prepared statement. + ## Protocol limitations ### Limitations with MySQL Protocol support (MySQLClient) @@ -85,6 +118,17 @@ Read queries are routed to the master server in the following situations: * if there are multiple statements inside one query e.g. `INSERT INTO ... ; SELECT LAST_INSERT_ID();` +#### JDBC Batched Statements + +Readwritesplit does not support execution of JDBC batched statements with +non-INSERT statements mixed in it. This is caused by the fact that +readwritesplit expects that the protocol is idle before another command is sent. + +Most clients conform to this expectation but some JDBC drivers send multiple +requests without waiting for the protocol to be idle. If you are using the +MariaDB Connector/J, add `useBatchMultiSend=false` to the JDBC connection string +to disable batched statement execution. + #### Backend write timeout handling The backend connections opened by readwritesplit will not be kept alive if they diff --git a/Documentation/About/Support-for-10.2.md b/Documentation/About/Support-for-10.2.md new file mode 100644 index 000000000..d2a3fbf62 --- /dev/null +++ b/Documentation/About/Support-for-10.2.md @@ -0,0 +1,100 @@ +# Support for MariaDB 10.2 + +MariaDB 10.2 introduces a fair amount of new +[features](https://mariadb.com/kb/en/mariadb/what-is-mariadb-102/). + +In the following will be explained what impact some of those features have, +when used together with MaxScale 2.1. + +## [Window Functions](https://mariadb.com/kb/en/mariadb/window-functions/) + +The parser of MariaDB MaxScale has not been extended with the window +function syntax (the `OVER` keyword is not recognized) and hence statements +using window functions will not be completely parsed. + +Since the database firewall filter will block all statements that +cannot be completely parsed, all statements that use window functions +will be blocked, if the database firewall filter is used. + +Otherwise the statements will be routed correctly. + +## [SHOW CREATE USER](https://mariadb.com/kb/en/mariadb/show-create-user/) + +Cannot be completely parsed by the MaxScale parser and hence will be +blocked by the database firewall filter, if it is used. + +Otherwise the statements will be routed correctly. + +## [CREATE USER](https://mariadb.com/kb/en/mariadb/create-user/) + +The new options are not parsed by the MaxScale parser and hence any +statements using those will be blocked by the database firewall filter, +if it is used. + +Otherwise the statements will be routed correctly. + +## [ALTER USER](https://mariadb.com/kb/en/mariadb/alter-user/) + +The new options are not parsed by the MaxScale parser and hence any +statements using those will be blocked by the database firewall filter, +if it is used. + +Otherwise the statements will be routed correctly. + +## [WITH](https://mariadb.com/kb/en/mariadb/with/) + +The MaxScale parser correctly parses `WITH` statements such as +``` +WITH t AS (SELECT a FROM t1 WHERE b >= 'c') +SELECT * FROM t2,t WHERE t2.c=t.a; +``` +, +``` +SELECT t1.a,t1.b FROM t1,t2 + WHERE t1.a>t2.c AND + t2.c in (WITH t as (SELECT * FROM t1 WHERE t1.a<5) + SELECT t2.c FROM t2,t WHERE t2.c=t.a); +``` +and +``` +WITH engineers AS ( + SELECT * FROM employees WHERE dept IN ('Development','Support') +) +SELECT * FROM engineers E1 + WHERE NOT EXISTS (SELECT 1 + FROM engineers E2 + WHERE E2.country=E1.country + AND E2.name <> E1.name); +``` +. + +However, the MaxScale parser fails to collect columns and table names +from the `SELECT` of the `WITH` clause and consequently the database +firewall filter will **NOT** be able to block `WITH` statements where +the `SELECT` of the `WITH` clause refers to to forbidden columns. + +## [CHECK CONSTRAINT](https://mariadb.com/kb/en/mariadb/constraint/) + +The new options are not parsed by the MaxScale parser and hence any +statements using those will be blocked by the database firewall filter, +if it is used. + +Otherwise the statements will be routed correctly. + +## [DEFAULT with expressions](https://mariadb.com/kb/en/mariadb/create-table/#default) + +Parsed and handled correctly. + +## [EXECUTE IMMEDIATE](https://mariadb.com/kb/en/mariadb/execute-immediate/) + +An `EXECUTE IMMEDIATE` statement will only be partially parsed, which means +that such statements will be blocked by the database firewall filter, +if it is used. + +## [JSON functions](https://mariadb.com/kb/en/mariadb/json-functions/) + +The MaxScape parser treats them as any other function. + +However, as the parser is not aware of which JSON functions are strictly +_read-only_ any statement using a JSON function will always be routed to +_master_. diff --git a/Documentation/Authenticators/GSSAPI-Authenticator.md b/Documentation/Authenticators/GSSAPI-Authenticator.md index ead0bfa93..ce434d5b7 100644 --- a/Documentation/Authenticators/GSSAPI-Authenticator.md +++ b/Documentation/Authenticators/GSSAPI-Authenticator.md @@ -19,7 +19,7 @@ the _kadmin_ or _kadmin.local_ tools. kadmin.local -q "addprinc -nokey mariadb/example.com@EXAMPLE.COM" ``` -The _-nokey_ option will make the principal a passwordless one. This allows the +The `-nokey` option will make the principal a passwordless one. This allows the _maxscale_ user to acquire a ticket for it without a password being prompted. The next step is to export this principal into the Kerberos keytab file. diff --git a/Documentation/Changelog.md b/Documentation/Changelog.md index 941c717c1..5aeeb1639 100644 --- a/Documentation/Changelog.md +++ b/Documentation/Changelog.md @@ -1,4 +1,4 @@ -#Changelog +# Changelog ## MariaDB MaxScale 2.1 * MariaDB MaxScale is licensed under MariaDB BSL 1.1. @@ -21,6 +21,7 @@ * MaxScale now supports IPv6 For more details, please refer to: +* [MariaDB MaxScale 2.1.3 Release Notes](Release-Notes/MaxScale-2.1.3-Release-Notes.md) * [MariaDB MaxScale 2.1.2 Release Notes](Release-Notes/MaxScale-2.1.2-Release-Notes.md) * [MariaDB MaxScale 2.1.1 Release Notes](Release-Notes/MaxScale-2.1.1-Release-Notes.md) * [MariaDB MaxScale 2.1.0 Release Notes](Release-Notes/MaxScale-2.1.0-Release-Notes.md) diff --git a/Documentation/Design-Documents/Plugin-development-guide.md b/Documentation/Design-Documents/Plugin-development-guide.md index 3677ca3a9..1b4d74fe3 100644 --- a/Documentation/Design-Documents/Plugin-development-guide.md +++ b/Documentation/Design-Documents/Plugin-development-guide.md @@ -8,19 +8,19 @@ on, so the APIs of these two are discussed in detail. ## Table of Contents -1. [Introduction](#introduction) -* [Module categories](#module-categories) -* [Common definitions and headers](#common-definitions-and-headers) - 1. [Module information container](#module-information-container) -* [Module API](#module-api) - 1. [Overview](#overview) - * [General module management](#general-module-management) - * [Protocol](#protocol) - * [Authenticator](#authenticator) - * [Filter and Router](#filter-and-router) - * [Monitor](#monitor) +* [Introduction](#introduction) + * [Module categories](#module-categories) + * [Common definitions and headers](#common-definitions-and-headers) +* [Module information container](#module-information-container) + * [Module API](#module-api) +* [Overview](#overview) + * [General module management](#general-module-management) + * [Protocol](#protocol) + * [Authenticator](#authenticator) + * [Filter and Router](#filter-and-router) + * [Monitor](#monitor) * [Compiling, installing and running](#compiling-installing-and-running) - 1. [Hands-on example: RoundRobinRouter](#hands-on-example-roundrobinrouter) +* [Hands-on example: RoundRobinRouter](#hands-on-example-roundrobinrouter) * [Summary and conclusion](#summary-and-conclusion) ## Introduction diff --git a/Documentation/Design-Documents/SchemaRouter-technical.md b/Documentation/Design-Documents/SchemaRouter-technical.md index 6c42e9563..e9543c339 100644 --- a/Documentation/Design-Documents/SchemaRouter-technical.md +++ b/Documentation/Design-Documents/SchemaRouter-technical.md @@ -1,4 +1,4 @@ -#SchemaRouter Router - Technical Overview +# SchemaRouter Router - Technical Overview This document is designed with a developer's point-of-view in mind. It explains the lifecycle of the module and details about its internal workings. It refers to the source code which can be found at [GitHub](https://github.com/mariadb-corporation/MaxScale). diff --git a/Documentation/Documentation-Contents.md b/Documentation/Documentation-Contents.md index 6b8057d68..6e8a45cbf 100644 --- a/Documentation/Documentation-Contents.md +++ b/Documentation/Documentation-Contents.md @@ -1,12 +1,10 @@ -[Search page for MariaDB MaxScale Documentation](http://mariadb-corporation.github.io/MaxScale/Search/) - # Contents ## About MariaDB MaxScale - [About MariaDB MaxScale](About/About-MaxScale.md) - - [Release Notes](Release-Notes/MaxScale-2.1.1-Release-Notes.md) + - [Release Notes](Release-Notes/MaxScale-2.1.3-Release-Notes.md) - [Changelog](Changelog.md) - [Limitations](About/Limitations.md) @@ -18,13 +16,12 @@ ## Upgrading MariaDB MaxScale +- [Upgrading MariaDB MaxScale from 2.0 to 2.1](Upgrading/Upgrading-To-MaxScale-2.1.md) - [Upgrading MariaDB MaxScale from 1.4 to 2.0](Upgrading/Upgrading-To-MaxScale-2.0.md) ## Reference - [MaxAdmin - Admin Interface](Reference/MaxAdmin.md) - - [How Errors are Handled in MariaDB MaxScale](Reference/How-errors-are-handled-in-MaxScale.md) - - [Debug and Diagnostic Support](Reference/Debug-And-Diagnostic-Support.md) - [Routing Hints](Reference/Hint-Syntax.md) - [MaxBinlogCheck](Reference/MaxBinlogCheck.md) - [MaxScale REST API](REST-API/API.md) @@ -39,19 +36,25 @@ The main tutorial for MariaDB MaxScale consist of setting up MariaDB MaxScale fo These tutorials are for specific use cases and module combinations. - [Administration Tutorial](Tutorials/Administration-Tutorial.md) + - [Avro Router Tutorial](Tutorials/Avrorouter-Tutorial.md) - [Filter Tutorial](Tutorials/Filter-Tutorial.md) - - [MariaDB MaxScale Information Schema Tutorial](Tutorials/MaxScale-Information-Schema.md) + - [Galera Cluster Connection Routing Tutorial](Tutorials/Galera-Cluster-Connection-Routing-Tutorial.md) + - [Galera Gluster Read Write Splitting Tutorial](Tutorials/Galera-Cluster-Read-Write-Splitting-Tutorial.md) - [MySQL Cluster Setup](Tutorials/MySQL-Cluster-Setup.md) - - [Replication Proxy with the Binlog Router Tutorial](Tutorials/Replication-Proxy-Binlog-Router-Tutorial.md) - - [RabbitMQ Setup and MariaDB MaxScale Integration Tutorial](Tutorials/RabbitMQ-Setup-And-MaxScale-Integration.md) + - [MySQL Replication Connection Routing Tutorial](Tutorials/MySQL-Replication-Connection-Routing-Tutorial.md) + - [MySQL Replication Read Write Splitting Tutorial](Tutorials/MySQL-Replication-Read-Write-Splitting-Tutorial.md) + - [MariaDB MaxScale Information Schema Tutorial](Tutorials/MaxScale-Information-Schema.md) + - [Notification Service](Tutorials/Notification-Service.md) - [RabbitMQ and Tee Filter Data Archiving Tutorial](Tutorials/RabbitMQ-And-Tee-Archiving.md) + - [RabbitMQ Setup and MariaDB MaxScale Integration Tutorial](Tutorials/RabbitMQ-Setup-And-MaxScale-Integration.md) + - [Replication Proxy with the Binlog Router Tutorial](Tutorials/Replication-Proxy-Binlog-Router-Tutorial.md) - [Simple Schema Sharding Tutorial](Tutorials/Simple-Sharding-Tutorial.md) Here are tutorials on monitoring and managing MariaDB MaxScale in cluster environments. - - [Nagios Plugins for MariaDB MaxScale Tutorial](Tutorials/Nagios-Plugins.md) - [MariaDB MaxScale HA with Corosync-Pacemaker](Tutorials/MaxScale-HA-with-Corosync-Pacemaker.md) - [MariaDB MaxScale HA with Lsyncd](Tutorials/MaxScale-HA-with-lsyncd.md) + - [Nagios Plugins for MariaDB MaxScale Tutorial](Tutorials/Nagios-Plugins.md) ## Routers @@ -59,32 +62,36 @@ The routing module is the core of a MariaDB MaxScale service. The router documen contains all module specific configuration options and detailed explanations of their use. - - [Read Write Split](Routers/ReadWriteSplit.md) - - [Read Connection Router](Routers/ReadConnRoute.md) - - [Schemarouter](Routers/SchemaRouter.md) - - [Binlogrouter](Routers/Binlogrouter.md) - [Avrorouter](Routers/Avrorouter.md) + - [Binlogrouter](Routers/Binlogrouter.md) - [HintRouter](Routers/HintRouter.md) + - [Read Connection Router](Routers/ReadConnRoute.md) + - [Read Write Split](Routers/ReadWriteSplit.md) + - [Schemarouter](Routers/SchemaRouter.md) There are also two diagnostic routing modules. The CLI is for MaxAdmin and the Debug CLI client for Telnet. - [CLI](Routers/CLI.md) - - [Debug CLI](Routers/Debug-CLI.md) ## Filters Here are detailed documents about the filters MariaDB MaxScale offers. They contain configuration guides and example use cases. Before reading these, you should have read the filter tutorial so that you know how they work and how to configure them. + - [Cache](Filters/Cache.md) + - [Consistent Critical Read Filter](Filters/CCRFilter.md) + - [Database Firewall Filter](Filters/Database-Firewall-Filter.md) + - [Insert Stream Filter](Filters/Insert-Stream-Filter.md) + - [Luafilter](Filters/Luafilter.md) + - [Masking Filter](Filters/Masking.md) + - [Maxrows Filter](Filters/Maxrows.md) + - [Named Server Filter](Filters/Named-Server-Filter.md) - [Query Log All](Filters/Query-Log-All-Filter.md) + - [RabbitMQ Filter](Filters/RabbitMQ-Filter.md) - [Regex Filter](Filters/Regex-Filter.md) - [Tee Filter](Filters/Tee-Filter.md) - [Top N Filter](Filters/Top-N-Filter.md) - - [Database Firewall Filter](Filters/Database-Firewall-Filter.md) - - [RabbitMQ Filter](Filters/RabbitMQ-Filter.md) - - [Named Server Filter](Filters/Named-Server-Filter.md) - - [Luafilter](Filters/Luafilter.md) - - [Insert Stream Filter](Filters/Insert-Stream-Filter.md) + - [Transaction Performance Monitoring Filter](Filters/Transaction-Performance-Monitoring-Filter.md) ## Monitors @@ -94,9 +101,10 @@ Common options for all monitor modules. Module specific documentation. - - [MySQL Monitor](Monitors/MySQL-Monitor.md) + - [Aurora Monitor](Monitors/Aurora-Monitor.md) - [Galera Monitor](Monitors/Galera-Monitor.md) - [Multi-Master Monitor](Monitors/MM-Monitor.md) + - [MySQL Monitor](Monitors/MySQL-Monitor.md) - [MySQL Cluster Monitor](Monitors/NDB-Cluster-Monitor.md) ## Protocols @@ -121,8 +129,6 @@ document. ## Design Documents - - [Core Objects Design (in development)](http://mariadb-corporation.github.io/MaxScale/Design-Documents/core-objects-html-docs) - - [Binlog Router Design (in development)](http://mariadb-corporation.github.io/MaxScale/Design-Documents/binlog-router-html-docs) - [DCB States (to be replaced in StarUML)](Design-Documents/DCB-States.pdf) - [Schema Sharding Router Technical Documentation](Design-Documents/SchemaRouter-technical.md) - [Plugin development guide](Design-Documents/Plugin-development-guide.md) diff --git a/Documentation/Filters/CCRFilter.md b/Documentation/Filters/CCRFilter.md index baad24144..7cbcc5400 100644 --- a/Documentation/Filters/CCRFilter.md +++ b/Documentation/Filters/CCRFilter.md @@ -7,10 +7,10 @@ This filter was introduced in MariaDB MaxScale 2.1. The Consistent Critical Read (CCR) filter allows consistent critical reads to be done through MaxScale while still allowing scaleout of non-critical reads. -When the filter detects a statement that would modify the database, it attaches a -routing hint to all following statements. This routing hint guides the routing -module to route the statement to the master server where data is guaranteed to be -in a up-to-date state. +When the filter detects a statement that would modify the database, it attaches +a routing hint to all following statements. This routing hint guides the routing +module to route the statement to the master server where data is guaranteed to +be in an up-to-date state. ## Filter Options @@ -42,8 +42,8 @@ _time_. Once the timer has elapsed, all statements are routed normally. If a new data modifying SQL statement is processed within the time window, the timer is reset to the value of _time_. -Enabling this parameter in combination with the _count_ parameter causes both the -time window and number of queries to be inspected. If either of the two +Enabling this parameter in combination with the _count_ parameter causes both +the time window and number of queries to be inspected. If either of the two conditions are met, the query is re-routed to the master. ### `count` @@ -51,8 +51,8 @@ conditions are met, the query is re-routed to the master. The number of SQL statements to route to master after detecting a data modifying SQL statement. This feature is disabled by default. -After processing a data modifying SQL statement, a counter is set to the value of -_count_ and all statements are routed to the master. Each executed statement +After processing a data modifying SQL statement, a counter is set to the value +of _count_ and all statements are routed to the master. Each executed statement after a data modifying SQL statement cause the counter to be decremented. Once the counter reaches zero, the statements are routed normally. If a new data modifying SQL statement is processed, the counter is reset to the value of @@ -61,8 +61,8 @@ _count_. ### `match` An optional parameter that can be used to control which statements trigger the -statement re-routing. The parameter value is a regular expression that is used to -match against the SQL text. Only non-SELECT statements are inspected. +statement re-routing. The parameter value is a regular expression that is used +to match against the SQL text. Only non-SELECT statements are inspected. ``` match=.*INSERT.* diff --git a/Documentation/Filters/Cache.md b/Documentation/Filters/Cache.md index 14b254481..46534ee2d 100644 --- a/Documentation/Filters/Cache.md +++ b/Documentation/Filters/Cache.md @@ -622,6 +622,9 @@ storage=storage_inmemory ## `storage_rocksdb` +This storage module is not built by default and is not included in the +MariaDB MaxScale packages. + This storage module uses RocksDB database for storing the cached data. The directory where the RocksDB database will be created is by default created into the _MaxScale cache_ directory, which usually is not on a RAM disk. For @@ -651,7 +654,8 @@ created, under which the actual instance specific cache directories are created. Specifies whether RocksDB should collect statistics that later can be queried using `maxadmin`. It should be noted, though, that collecting RocksDB statistics -is not without a cost. From the [RocksDB Documentation](https://github.com/facebook/rocksdb/wiki/Statistics) +is not without a cost. +From the [RocksDB Documentation](https://github.com/facebook/rocksdb/wiki/Statistics) _The overhead of statistics is usually small but non-negligible. We usually observe an overhead of 5%-10%._ diff --git a/Documentation/Filters/RabbitMQ-Consumer-Client.md b/Documentation/Filters/RabbitMQ-Consumer-Client.md index 76c9c4e03..63dc4ccaf 100644 --- a/Documentation/Filters/RabbitMQ-Consumer-Client.md +++ b/Documentation/Filters/RabbitMQ-Consumer-Client.md @@ -1,8 +1,10 @@ -#RabbitMQ Consumer Client +# RabbitMQ Consumer Client ## Overview -This utility tool is used to read messages from a RabbitMQ broker sent by the [RabbitMQ Filter](RabbitMQ-Filter.md) and forward these messages into an SQL database as queries. +This utility tool is used to read messages from a RabbitMQ broker sent by the +[RabbitMQ Filter](RabbitMQ-Filter.md) and forward these messages into an +SQL database as queries. ## Command Line Arguments @@ -14,7 +16,9 @@ The **RabbitMQ Consumer Client** only has one command line argument. ## Installation -To install the RabbitMQ Consumer Client you ca either use the provided packages or you can compile it from source code. The source code is included as a part of the MariaDB MaxScale source code and can be found in the `rabbitmq_consumer` folder. +To install the RabbitMQ Consumer Client you can either use the provided packages +or you can compile it from source code. The source code is included as a part of the +MariaDB MaxScale source code and can be found in the `rabbitmq_consumer` folder. ## Building from source @@ -48,9 +52,12 @@ include and library directories 'in buildvars.inc' ## Configuration -The consumer client requires that the `consumer.cnf` configuration file is either be present in the `etc` folder of the installation directory or in the folder specified by the `-c` argument. +The consumer client requires that the `consumer.cnf` configuration file is either +be present in the `etc` folder of the installation directory or in the folder +specified by the `-c` argument. -The source broker, the destination database and the message log file can be configured into the separate `consumer.cnf` file. +The source broker, the destination database and the message log file can be +configured into the separate `consumer.cnf` file. | Option | Description | |-----------|---------------------------------------------| diff --git a/Documentation/Filters/RabbitMQ-Filter.md b/Documentation/Filters/RabbitMQ-Filter.md index 35fb285d6..3fd5e7ee9 100644 --- a/Documentation/Filters/RabbitMQ-Filter.md +++ b/Documentation/Filters/RabbitMQ-Filter.md @@ -1,13 +1,26 @@ -#RabbitMQ Filter +# RabbitMQ Filter ## Overview -This filter is designed to extract queries and transform them into a canonical form e.g. `INSERT INTO database.table VALUES ("John Doe", "Downtown",100,50.0);` turns into `INSERT INTO database.table VALUES ("?", "?",?,?);`. The filter pushes these canonicalized queries and their replies in to a RabbitMQ broker where they can later be retrieved. The retrieval can be done with your own application or the [RabbitMQ Consumer Client](RabbitMQ-Consumer-Client.md) utility tool, which reads the messages from the broker and sends the contents of those messages as SQL queries to a database. + +This filter is designed to extract queries and transform them into a canonical +form e.g. `INSERT INTO database.table VALUES ("John Doe", "Downtown",100,50.0);` +turns into `INSERT INTO database.table VALUES ("?", "?",?,?);`. The filter +pushes these canonized queries and their replies into a RabbitMQ broker where +they can later be retrieved from. The retrieval can be done with a custom +application or the [RabbitMQ Consumer Client](RabbitMQ-Consumer-Client.md) +utility tool, which reads the messages from the broker and sends the contents of +those messages as SQL queries to a database. ## Configuration -The configuration block for the **mqfilter** filter requires the minimal filter options in it’s section within the maxscale.cnf file, stored in /etc/maxscale.cnf. Although the filter will start, it will use the default values which only work with a freshly installed RabbitMQ server and use its default values. This setup is mostly intended for testing the filter. +The configuration block for the **mqfilter** requires the minimal filter options +in its section within the MaxScale configuration file. Although the filter will +start, it will use the default values which only work with a freshly installed +RabbitMQ server and use its default values. This setup is mostly intended for +testing the filter. -The following is an example of a mqfilter configuration in the maxscale.cnf file used for actual logging of queries to a RabbitMQ broker on a different host. +The following is an example of an mqfilter configuration used for actual logging +of queries to a RabbitMQ broker on a different host. ``` [RabbitMQ] @@ -41,7 +54,10 @@ The mqfilter filter does not support any filter options. ### Filter Parameters -The RabbitMQ filter has parameters to control which queries are logged based on either the attributes of the user or the query itself. These can be combined to to only log queries targeting a certain table in a certain database from a certain user from a certain network address. +The RabbitMQ filter has parameters to control which queries are logged based on +either the attributes of the user or the query itself. These can be combined to +to only log queries targeting a certain table in a certain database from a +certain user from a certain network address. Option | Description | Accepted Values | Default | diff --git a/Documentation/Filters/Tee-Filter.md b/Documentation/Filters/Tee-Filter.md index 29f35c2b6..8e1155351 100644 --- a/Documentation/Filters/Tee-Filter.md +++ b/Documentation/Filters/Tee-Filter.md @@ -2,11 +2,16 @@ ## Overview -The tee filter is a filter module for MariaDB MaxScale is a "plumbing" fitting in the MariaDB MaxScale filter toolkit. It can be used in a filter pipeline of a service to make a copy of requests from the client and dispatch a copy of the request to another service within MariaDB MaxScale. +The tee filter is a "plumbing" fitting in the MariaDB MaxScale filter toolkit. +It can be used in a filter pipeline of a service to make copies of requests from +the client and send the copies to another service within MariaDB MaxScale. ## Configuration -The configuration block for the TEE filter requires the minimal filter parameters in it’s section within the maxscale.cnf file, stored in /etc/maxscale.cnf, that defines the filter to load and the service to send the duplicates to. Currently the tee filter does not support multi-statements. +The configuration block for the TEE filter requires the minimal filter +parameters in its section within the MaxScale configuration file. The service to +send the duplicates to must be defined. Currently the tee filter does not +support multi-statements. ``` [DataMartFilter] @@ -41,31 +46,45 @@ options=case,extended ## Filter Parameters -The tee filter requires a mandatory parameter to define the service to replicate statements to and accepts a number of optional parameters. +The tee filter requires a mandatory parameter to define the service to replicate +statements to and accepts a number of optional parameters. ### Match -An optional parameter that can be used to limit the queries that will be replicated by the tee filter. The parameter value is a regular expression that is used to match against the SQL text. Only SQL statements that matches the text passed as the value of this parameter will be sent to the service defined in the filter section. +An optional parameter used to limit the queries that will be replicated by the +tee filter. The parameter value is a regular expression that is used to match +against the SQL text. Only SQL statements that matches the text passed as the +value of this parameter will be sent to the service defined in the filter +section. ``` match=insert.*into.*order* ``` -All regular expressions are evaluated with the option to ignore the case of the text, therefore a match option of select will match both insert, INSERT and any form of the word with upper or lowercase characters. +All regular expressions are evaluated with the option to ignore the case of the +text, therefore a match option of select will match both insert, INSERT and any +form of the word with upper or lowercase characters. ### Exclude -An optional parameter that can be used to limit the queries that will be replicated by the tee filter. The parameter value is a regular expression that is used to match against the SQL text. SQL statements that match the text passed as the value of this parameter will be excluded from the replication stream. +An optional parameter used to limit the queries that will be replicated by the +tee filter. The parameter value is a regular expression that is used to match +against the SQL text. SQL statements that match the text passed as the value of +this parameter will be excluded from the replication stream. ``` exclude=select ``` -All regular expressions are evaluated with the option to ignore the case of the text, therefore an exclude option of select will exclude statements that contain both select, SELECT or any form of the word with upper or lowercase characters. +All regular expressions are evaluated with the option to ignore the case of the +text, therefore an exclude option of select will exclude statements that contain +both select, SELECT or any form of the word with upper or lowercase characters. ### Source -The optional source parameter defines an address that is used to match against the address from which the client connection to MariaDB MaxScale originates. Only sessions that originate from this address will be replicated. +The optional source parameter defines an address that is used to match against +the address from which the client connection to MariaDB MaxScale originates. +Only sessions that originate from this address will be replicated. ``` source=127.0.0.1 @@ -73,7 +92,9 @@ source=127.0.0.1 ### User -The optional user parameter defines a user name that is used to match against the user from which the client connection to MariaDB MaxScale originates. Only sessions that are connected using this username are replicated. +The optional user parameter defines a user name that is used to match against +the user from which the client connection to MariaDB MaxScale originates. Only +sessions that are connected using this username are replicated. ``` user=john @@ -83,9 +104,17 @@ user=john ### Example 1 - Replicate all inserts into the orders table -Assume an order processing system that has a table called orders. You also have another database server, the datamart server, that requires all inserts into orders to be replicated to it. Deletes and updates are not however required. +Assume an order processing system that has a table called orders. You also have +another database server, the datamart server, that requires all inserts into +orders to be replicated to it. Deletes and updates are not, however, required. -Set up a service in MariaDB MaxScale, called Orders, to communicate with the order processing system with the tee filter applied to it. Also set up a service to talk the datamart server, using the DataMart service. The tee filter would have as it’s service entry the DataMart service, by adding a match parameter of "insert into orders" would then result in all requests being sent to the order processing system, and insert statements that include the orders table being additionally sent to the datamart server. +Set up a service in MariaDB MaxScale, called Orders, to communicate with the +order processing system with the tee filter applied to it. Also set up a service +to talk to the datamart server, using the DataMart service. The tee filter would +have as it’s service entry the DataMart service, by adding a match parameter of +"insert into orders" would then result in all requests being sent to the order +processing system, and insert statements that include the orders table being +additionally sent to the datamart server. ``` [Orders] diff --git a/Documentation/Filters/Transaction-Performance-Monitoring-Filter.md b/Documentation/Filters/Transaction-Performance-Monitoring-Filter.md index a09bb4181..21070c40d 100644 --- a/Documentation/Filters/Transaction-Performance-Monitoring-Filter.md +++ b/Documentation/Filters/Transaction-Performance-Monitoring-Filter.md @@ -2,11 +2,17 @@ ## Overview -The Transaction Performance Monitoring (TPM) filter is a filter module for MaxScale that monitors every SQL statement that passes through the filter. The filter groups a series of SQL statements into a transaction by detecting 'commit' or 'rollback' statements. It logs all committed transactions with necessary information, such as timestamp, client, SQL statements, latency, etc., which can be used later for transaction performance analysis. +The Transaction Performance Monitoring (TPM) filter is a filter module for MaxScale +that monitors every SQL statement that passes through the filter. +The filter groups a series of SQL statements into a transaction by detecting +'commit' or 'rollback' statements. It logs all committed transactions with necessary +information, such as timestamp, client, SQL statements, latency, etc., which +can be used later for transaction performance analysis. ## Configuration -The configuration block for the TPM filter requires the minimal filter options in it's section within the maxscale.cnf file, stored in /etc/maxscale.cnf. +The configuration block for the TPM filter requires the minimal filter +options in it's section within the maxscale.cnf file, stored in /etc/maxscale.cnf. ``` [MyLogFilter] @@ -32,7 +38,8 @@ The TPM filter accepts a number of optional parameters. ### Filename -The name of the output file created for performance logging. The default filename is **tpm.log**. +The name of the output file created for performance logging. +The default filename is **tpm.log**. ``` filename=/tmp/SqlQueryLog @@ -40,7 +47,10 @@ filename=/tmp/SqlQueryLog ### Source -The optional `source` parameter defines an address that is used to match against the address from which the client connection to MaxScale originates. Only sessions that originate from this address will be logged. +The optional `source` parameter defines an address that is used +to match against the address from which the client connection +to MaxScale originates. Only sessions that originate from this +address will be logged. ``` source=127.0.0.1 @@ -48,7 +58,10 @@ source=127.0.0.1 ### User -The optional `user` parameter defines a user name that is used to match against the user from which the client connection to MaxScale originates. Only sessions that are connected using this username are logged. +The optional `user` parameter defines a user name that is used +to match against the user from which the client connection to +MaxScale originates. Only sessions that are connected using +this username are logged. ``` user=john @@ -56,7 +69,8 @@ user=john ### Delimiter -The optional `delimiter` parameter defines a delimiter that is used to distinguish columns in the log. The default delimiter is **`:::`**. +The optional `delimiter` parameter defines a delimiter that is used to +distinguish columns in the log. The default delimiter is **`:::`**. ``` delimiter=::: @@ -64,7 +78,9 @@ delimiter=::: ### Query_delimiter -The optional `query_delimiter` defines a delimiter that is used to distinguish different SQL statements in a transaction. The default query delimiter is **`@@@`**. +The optional `query_delimiter` defines a delimiter that is used to +distinguish different SQL statements in a transaction. +The default query delimiter is **`@@@`**. ``` query_delimiter=@@@ @@ -72,7 +88,11 @@ query_delimiter=@@@ ### Named_pipe -**`named_pipe`** is the path to a named pipe, which TPM filter uses to communicate with 3rd-party applications (e.g., [DBSeer](http://dbseer.org)). Logging is enabled when the router receives the character '1' and logging is disabled when the router receives the character '0' from this named pipe. The default named pipe is **`/tmp/tpmfilter`** and logging is **disabled** by default. +**`named_pipe`** is the path to a named pipe, which TPM filter uses to +communicate with 3rd-party applications (e.g., [DBSeer](http://dbseer.org)). +Logging is enabled when the router receives the character '1' and logging is +disabled when the router receives the character '0' from this named pipe. +The default named pipe is **`/tmp/tpmfilter`** and logging is **disabled** by default. named_pipe=/tmp/tpmfilter @@ -89,7 +109,8 @@ Similarly, the following command disables the logging: ### Example 1 - Log Transactions for Performance Analysis -You want to log every transaction with its SQL statements and latency for future transaction performance analysis. +You want to log every transaction with its SQL statements and latency +for future transaction performance analysis. Add a filter with the following definition: @@ -111,7 +132,8 @@ passwd=mypasswd filters=PerformanceLogger ``` -After the filter reads the character '1' from its named pipe, the following is an example log that is generated from the above TPM filter with the above configuration: +After the filter reads the character '1' from its named pipe, the following +is an example log that is generated from the above TPM filter with the above configuration: ``` @@ -120,4 +142,4 @@ After the filter reads the character '1' from its named pipe, the following is a ... ``` -Note that 3 and 5 are latencies of each transaction in milliseconds. \ No newline at end of file +Note that 3 and 5 are latencies of each transaction in milliseconds. diff --git a/Documentation/Getting-Started/Building-MaxScale-from-Source-Code.md b/Documentation/Getting-Started/Building-MaxScale-from-Source-Code.md index 09cb312ed..787c6b69e 100644 --- a/Documentation/Getting-Started/Building-MaxScale-from-Source-Code.md +++ b/Documentation/Getting-Started/Building-MaxScale-from-Source-Code.md @@ -106,7 +106,8 @@ make test sudo make install ``` -Other useful targets for Make are `documentation`, which generates the Doxygen documentation, and `uninstall` which uninstall MariaDB MaxScale binaries after an install. +Other useful targets for Make are `documentation`, which generates the Doxygen documentation, +and `uninstall` which uninstall MariaDB MaxScale binaries after an install. **Note**: If you configure CMake multiple times, it's possible that you will run into problems when building MaxScale. Most of the time this manifests as a diff --git a/Documentation/Getting-Started/Configuration-Guide.md b/Documentation/Getting-Started/Configuration-Guide.md index 14962a7d1..bedd8a7b3 100644 --- a/Documentation/Getting-Started/Configuration-Guide.md +++ b/Documentation/Getting-Started/Configuration-Guide.md @@ -2,11 +2,10 @@ ## Introduction -The purpose of this document is to describe how to configure MariaDB MaxScale -and to discuss some possible usage scenarios for MariaDB MaxScale. MariaDB -MaxScale is designed with flexibility in mind, and consists of an event -processing core with various support functions and plugin modules that tailor -the behavior of the MariaDB MaxScale itself. +This document describes how to configure MariaDB MaxScale and presents some +possible usage scenarios. MariaDB MaxScale is designed with flexibility in mind, +and consists of an event processing core with various support functions and +plugin modules that tailor the behavior of the program. # Table of Contents @@ -25,23 +24,22 @@ the behavior of the MariaDB MaxScale itself. * [Authentication](#authentication) * [Error Reporting](#error-reporting) -### Terms +## Glossary - -| Term | Description -------------------- | ------------------ - service | A service represents a set of databases with a specific access mechanism that is offered to clients of MariaDB MaxScale. The access mechanism defines the algorithm that MariaDB MaxScale will use to direct particular requests to the individual databases. - server | A server represents an individual database server to which a client can be connected via MariaDB MaxScale. - router | A router is a module within MariaDB MaxScale that will route client requests to the various database servers which MariaDB MaxScale provides a service interface to. -connection routing | Connection routing is a method of handling requests in which MariaDB MaxScale will accept connections from a client and route data on that connection to a single database using a single connection. Connection based routing will not examine individual requests on a connection and it will not move that connection once it is established. -statement routing | Statement routing is a method of handling requests in which each request within a connection will be handled individually. Requests may be sent to one or more servers and connections may be dynamically added or removed from the session. - protocol | A protocol is a module of software that is used to communicate with another software entity within the system. MariaDB MaxScale supports the dynamic loading of protocol modules to allow for increased flexibility. - module | A module is a separate code entity that may be loaded dynamically into MariaDB MaxScale to increase the available functionality. Modules are implemented as run-time loadable shared objects. - monitor | A monitor is a module that can be executed within MariaDB MaxScale to monitor the state of a set of database. The use of an internal monitor is optional, monitoring may be performed externally to MariaDB MaxScale. - listener | A listener is the network endpoint that is used to listen for connections to MariaDB MaxScale from the client applications. A listener is associated to a single service, however, a service may have many listeners. -connection failover| When a connection currently being used between MariaDB MaxScale and the database server fails a replacement will be automatically created to another server by MariaDB MaxScale without client intervention - backend database | A term used to refer to a database that sits behind MariaDB MaxScale and is accessed by applications via MariaDB MaxScale. - filter | A module that can be placed between the client and the MariaDB MaxScale router module. All client data passes through the filter module and may be examined or modified by the filter modules. Filters may be chained together to form processing pipelines. +Word | Description +--------------------|---------------------------------------------------- +service | A service represents a set of databases with a specific access mechanism that is offered to clients of MariaDB MaxScale. The access mechanism defines the algorithm that MariaDB MaxScale will use to direct particular requests to the individual databases. +server | A server represents an individual database server to which a client can be connected via MariaDB MaxScale. +router | A router is a module within MariaDB MaxScale that will route client requests to the various database servers which MariaDB MaxScale provides a service interface to. +connection routing | Connection routing is a method of handling requests in which MariaDB MaxScale will accept connections from a client and route data on that connection to a single database using a single connection. Connection based routing will not examine individual requests on a connection and it will not move that connection once it is established. +statement routing | Statement routing is a method of handling requests in which each request within a connection will be handled individually. Requests may be sent to one or more servers and connections may be dynamically added or removed from the session. +protocol | A protocol is a module of software that is used to communicate with another software entity within the system. MariaDB MaxScale supports the dynamic loading of protocol modules to allow for increased flexibility. +module | A module is a separate code entity that may be loaded dynamically into MariaDB MaxScale to increase the available functionality. Modules are implemented as run-time loadable shared objects. +monitor | A monitor is a module that can be executed within MariaDB MaxScale to monitor the state of a set of database. The use of an internal monitor is optional, monitoring may be performed externally to MariaDB MaxScale. +listener | A listener is the network endpoint that is used to listen for connections to MariaDB MaxScale from the client applications. A listener is associated to a single service, however, a service may have many listeners. +connection failover | When a connection currently being used between MariaDB MaxScale and the database server fails a replacement will be automatically created to another server by MariaDB MaxScale without client intervention +backend database | A term used to refer to a database that sits behind MariaDB MaxScale and is accessed by applications via MariaDB MaxScale. +filter | A module that can be placed between the client and the MariaDB MaxScale router module. All client data passes through the filter module and may be examined or modified by the filter modules. Filters may be chained together to form processing pipelines. ## Configuration @@ -49,7 +47,7 @@ The MariaDB MaxScale configuration is read from a file that MariaDB MaxScale will look for in the following places: 1. By default, the file `maxscale.cnf` in the directory `/etc` -1. The location given with the `--configdir=` command line argument. +2. The location given with the `--configdir=` command line argument. MariaDB MaxScale will further look for a directory with the same name as the configuration file, followed by `.d` (for instance `/etc/maxscale.cnf.d`) and @@ -63,10 +61,10 @@ separate configuration files for _servers_, _filters_, etc. The configuration file itself is based on the [.ini](https://en.wikipedia.org/wiki/INI_file) file format and consists of -various sections that are used to build the configuration; these sections -define services, servers, listeners, monitors and global settings. Parameters, -which expect a comma-separated list of values can be defined on multiple -lines. The following is an example of a multi-line definition. +various sections that are used to build the configuration; these sections define +services, servers, listeners, monitors and global settings. Parameters, which +expect a comma-separated list of values can be defined on multiple lines. The +following is an example of a multi-line definition. ``` [MyService] @@ -77,18 +75,18 @@ servers=server1, server3 ``` -The values of the parameter that are not on the first line need to have at -least one whitespace character before them in order for them to be recognized -as a part of the multi-line parameter. +The values of the parameter that are not on the first line need to have at least +one whitespace character before them in order for them to be recognized as a +part of the multi-line parameter. ### Sizes -Where _specifically noted_, a number denoting a size can be suffixed by a subset of -the IEC binary prefixes or the SI prefixes. In the former case the number will be -interpreted as a certain multiple of 1024 and in the latter case as a certain multiple -of 1000. The supported IEC binary suffixes are `Ki`, `Mi`, `Gi` and `Ti` and the -supported SI suffixes are `k`, `M`, `G` and `T`. In both cases, the matching is -case insensitive. +Where _specifically noted_, a number denoting a size can be suffixed by a subset +of the IEC binary prefixes or the SI prefixes. In the former case the number +will be interpreted as a certain multiple of 1024 and in the latter case as a +certain multiple of 1000. The supported IEC binary suffixes are `Ki`, `Mi`, `Gi` +and `Ti` and the supported SI suffixes are `k`, `M`, `G` and `T`. In both cases, +the matching is case insensitive. For instance, the following entries ``` @@ -134,9 +132,9 @@ used for systems dedicated for running MariaDB MaxScale. threads=1 ``` -It should be noted that additional threads will be created to execute other -internal services within MariaDB MaxScale. This setting is used to configure the -number of threads that will be used to manage the user connections. +Additional threads will be created to execute other internal services within +MariaDB MaxScale. This setting is used to configure the number of threads that +will be used to manage the user connections. #### `auth_connect_timeout` @@ -213,8 +211,7 @@ By default logging to *syslog* is enabled. syslog=1 ``` -To enable logging to syslog use the value 1 and to disable use -the value 0. +To enable logging to syslog use the value 1 and to disable use the value 0. #### `maxlog` @@ -233,15 +230,15 @@ disable use the value 0. #### `log_to_shm` -Enable or disable the writing of the *maxscale.log* file to shared memory. -If enabled, then the actual log file will be created under `/dev/shm` and -a symbolic link to that file will be created in the *MaxScale* log directory. +Enable or disable the writing of the *maxscale.log* file to shared memory. If +enabled, then the actual log file will be created under `/dev/shm` and a +symbolic link to that file will be created in the *MaxScale* log directory. -Logging to shared memory may be appropriate if *log_info* and/or *log_debug* -are enabled, as logging to a regular file may in that case cause performance -degradation, due to the amount of data logged. However, as shared memory is -a scarce resource, logging to shared memory should be used only temporarily -and not regularly. +Logging to shared memory may be appropriate if *log_info* and/or *log_debug* are +enabled, as logging to a regular file may in that case cause performance +degradation, due to the amount of data logged. However, as shared memory is a +scarce resource, logging to shared memory should be used only temporarily and +not regularly. Since *MariaDB MaxScale* can log to both file and *syslog* an approach that provides maximum flexibility is to enable *syslog* and *log_to_shm*, and to @@ -258,8 +255,8 @@ By default, logging to shared memory is disabled. log_to_shm=1 ``` -To enable logging to shared memory use the value 1 and to disable use -the value 0. +To enable logging to shared memory use the value 1 and to disable use the value +0. #### `log_warning` @@ -277,8 +274,8 @@ To disable these messages use the value 0 and to enable them use the value 1. #### `log_notice` Enable or disable the logging of messages whose syslog priority is *notice*. -Messages of this priority provide information about the functioning of -MariaDB MaxScale and are enabled by default. +Messages of this priority provide information about the functioning of MariaDB +MaxScale and are enabled by default. ``` # Valid options are: @@ -290,12 +287,12 @@ To disable these messages use the value 0 and to enable them use the value 1. #### `log_info` -Enable or disable the logging of messages whose syslog priority is *info*. -These messages provide detailed information about the internal workings of -MariaDB MaxScale and should not, due to their frequency, be enabled, unless there -is a specific reason for that. For instance, from these messages it will be -evident, e.g., why a particular query was routed to the master instead of -to a slave. These informational messages are disabled by default. +Enable or disable the logging of messages whose syslog priority is *info*. These +messages provide detailed information about the internal workings of MariaDB +MaxScale and should not, due to their frequency, be enabled, unless there is a +specific reason for that. For instance, from these messages it will be evident, +e.g., why a particular query was routed to the master instead of to a slave. +These informational messages are disabled by default. ``` # Valid options are: @@ -307,9 +304,9 @@ To disable these messages use the value 0 and to enable them use the value 1. #### `log_debug` -Enable or disable the logging of messages whose syslog priority is *debug*. -This kind of messages are intended for development purposes and are disabled -by default. Note that if MariaDB MaxScale has been built in release mode, then +Enable or disable the logging of messages whose syslog priority is *debug*. This +kind of messages are intended for development purposes and are disabled by +default. Note that if MariaDB MaxScale has been built in release mode, then debug messages are excluded from the build and this setting will not have any effect. @@ -346,11 +343,11 @@ To disable the augmentation use the value 0 and to enable it use the value 1. #### `log_throttling` -In some circumstances it is possible that a particular error (or warning) is -logged over and over again, if the cause for the error persistently remains. To -prevent the log from flooding, it is possible to specify how many times a -particular error may be logged within a time period, before the logging of that -error is suppressed for a while. +It is possible that a particular error (or warning) is logged over and over +again, if the cause for the error persistently remains. To prevent the log from +flooding, it is possible to specify how many times a particular error may be +logged within a time period, before the logging of that error is suppressed for +a while. ``` # A valid value looks like @@ -393,9 +390,9 @@ logdir=/tmp/ #### `datadir` -Set the directory where the data files used by MariaDB MaxScale are -stored. Modules can write to this directory and for example the binlogrouter -uses this folder as the default location for storing binary logs. +Set the directory where the data files used by MariaDB MaxScale are stored. +Modules can write to this directory and for example the binlogrouter uses this +folder as the default location for storing binary logs. ``` datadir=/home/user/maxscale_data/ @@ -415,9 +412,9 @@ libdir=/home/user/lib64/ #### `cachedir` Configure the directory MariaDB MaxScale uses to store cached data. An example -of cached data is the authentication data fetched from the backend -servers. MariaDB MaxScale stores this in case a connection to the backend server -is not possible. +of cached data is the authentication data fetched from the backend servers. +MariaDB MaxScale stores this in case a connection to the backend server is not +possible. ``` cachedir=/tmp/maxscale_cache/ @@ -494,21 +491,23 @@ language=/home/user/lang/ The module used by MariaDB MaxScale for query classification. The information provided by this module is used by MariaDB MaxScale when deciding where a -particular statement should be sent. The default query classifier -is _qc_sqlite_. +particular statement should be sent. The default query classifier is +_qc_sqlite_. #### `query_classifier_args` -Arguments for the query classifier. What arguments are accepted depends -on the particular query classifier being used. The default query -classifier - _qc_sqlite_ - supports the following arguments: +Arguments for the query classifier. What arguments are accepted depends on the +particular query classifier being used. The default query classifier - +_qc_sqlite_ - supports the following arguments: ##### `log_unrecognized_statements` An integer argument taking the following values: * 0: Nothing is logged. This is the default. - * 1: Statements that cannot be parsed completely are logged. They may have been partially parsed, or classified based on keyword matching. - * 2: Statements that cannot even be partially parsed are logged. They may have been classified based on keyword matching. + * 1: Statements that cannot be parsed completely are logged. They may have been +partially parsed, or classified based on keyword matching. + * 2: Statements that cannot even be partially parsed are logged. They may have +been classified based on keyword matching. * 3: Statements that cannot even be classified by keyword matching are logged. ``` @@ -516,8 +515,8 @@ query_classifier=qc_sqlite query_classifier_args=log_unrecognized_statements=1 ``` -This will log all statements that cannot be parsed completely. This -may be useful if you suspect that MariaDB MaxScale routes statements to the wrong +This will log all statements that cannot be parsed completely. This may be +useful if you suspect that MariaDB MaxScale routes statements to the wrong server (e.g. to a slave instead of to a master). ### Service @@ -530,12 +529,12 @@ statements or route connections to those backend servers. A service may be considered as a virtual database server that MariaDB MaxScale makes available to its clients. -Several different services may be defined using the same set of backend -servers. For example a connection based routing service might be used by clients -that already performed internal read/write splitting, whilst a different -statement based router may be used by clients that are not written with this -functionality in place. Both sets of applications could access the same data in -the same databases. +Several different services may be defined using the same set of backend servers. +For example a connection based routing service might be used by clients that +already performed internal read/write splitting, whilst a different statement +based router may be used by clients that are not written with this functionality +in place. Both sets of applications could access the same data in the same +databases. A service is identified by a service name, which is the name of the configuration file section and a type parameter of service. @@ -581,9 +580,9 @@ router is included with the documentation of the router itself. #### `router_options` -Option string given to the router module. The value of this parameter -should be a comma-separated list of key-value pairs. See router specific -documentation for more details. +Option string given to the router module. The value of this parameter should be +a comma-separated list of key-value pairs. See router specific documentation for +more details. #### `filters` @@ -643,26 +642,18 @@ The account used must be able to select from the mysql.user table, the following is an example showing how to create this user. ``` -MariaDB [mysql]> CREATE USER 'maxscale'@'maxscalehost' IDENTIFIED BY 'Mhu87p2D'; -Query OK, 0 rows affected (0.01 sec) - -MariaDB [mysql]> GRANT SELECT ON mysql.user TO 'maxscale'@'maxscalehost'; -Query OK, 0 rows affected (0.00 sec) +CREATE USER 'maxscale'@'maxscalehost' IDENTIFIED BY 'maxscale-password'; ``` -Additionally, `SELECT` privileges on the `mysql.db` and `mysql.tables_priv` +Additionally, `SELECT` privileges on the `mysql.user`, `mysql.db` and `mysql.tables_priv` tables and `SHOW DATABASES` privileges are required in order to load databases name and grants suitable for database name authorization. ``` -MariaDB [(none)]> GRANT SELECT ON mysql.db TO 'maxscale'@'maxscalehost'; -Query OK, 0 rows affected (0.00 sec) - -MariaDB [(none)]> GRANT SELECT ON mysql.tables_priv TO 'maxscale'@'maxscalehost'; -Query OK, 0 rows affected (0.00 sec) - -MariaDB [(none)]> GRANT SHOW DATABASES ON *.* TO 'maxscale'@'maxscalehost'; -Query OK, 0 rows affected (0.00 sec) +GRANT SELECT ON mysql.user TO 'maxscale'@'maxscalehost'; +GRANT SELECT ON mysql.db TO 'maxscale'@'maxscalehost'; +GRANT SELECT ON mysql.tables_priv TO 'maxscale'@'maxscalehost'; +GRANT SHOW DATABASES ON *.* TO 'maxscale'@'maxscalehost'; ``` MariaDB MaxScale will execute the following query to retrieve the users. If you @@ -690,6 +681,8 @@ In versions of MySQL 5.7.6 and later, the `Password` column was replaced by `authentication_string`. Change `user.password` above with `user.authentication_string`. +**Note**: If authentication fails, MaxScale will try to refresh the list of +database users used by the service up to 4 times every 30 seconds. #### `passwd` @@ -757,9 +750,10 @@ control the load balancing applied in the router in use by the service. This allows varying weights to be applied to each server to create a non-uniform distribution of the load amongst the servers. -An example of this might be to define a parameter for each server that represents -the amount of resource available on the server, we could call this serversize. -Every server should then have a serversize parameter set for the server. +An example of this might be to define a parameter for each server that +represents the amount of resource available on the server, we could call this +serversize. Every server should then have a serversize parameter set for the +server. ``` serversize=10 @@ -767,8 +761,8 @@ serversize=10 The service would then have the parameter `weightby=serversize`. If there are 4 servers defined in the service (serverA, serverB, serverC and serverD) with the -serversize set as shown in the table below, the connections would balanced -using the percentages in this table. +serversize set as shown in the table below, the connections would balanced using +the percentages in this table. Server |serversize|% connections ---------|----------|------------- @@ -781,8 +775,8 @@ _**Note**: If the value of the weighting parameter of an individual server is zero or the relative weight rounds down to zero, no queries will be routed to that server as long as a server with a positive weight is available._ -Here is an excerpt from an example configuration with the `serv_weight` parameter -used as the weighting parameter. +Here is an excerpt from an example configuration with the `serv_weight` +parameter used as the weighting parameter. ``` [server1] @@ -807,19 +801,19 @@ weightby=serv_weight ``` With this configuration and a heavy query load, the server _server1_ will get -most of the connections and about a third of the remaining queries are routed -to the second server. With server weights, you can assign secondary servers -that are only used when the primary server is under heavy load. +most of the connections and about a third of the remaining queries are routed to +the second server. With server weights, you can assign secondary servers that +are only used when the primary server is under heavy load. Without the weightby parameter, each connection counts as a single connection. -With a weighting parameter, a single connection received its weight from -the server's own weighting parameter divided by the sum of all weighting -parameters in all the configured servers. +With a weighting parameter, a single connection received its weight from the +server's own weighting parameter divided by the sum of all weighting parameters +in all the configured servers. If we use the previous configuration as an example, the sum of the `serv_weight` -parameter is 4. _Server1_ would receive a weight of `3/4=75%` and _server2_ would get -`1/4=25%`. This means that _server1_ would get 75% of the connections and _server2_ -would get 25% of the connections. +parameter is 4. _Server1_ would receive a weight of `3/4=75%` and _server2_ +would get `1/4=25%`. This means that _server1_ would get 75% of the connections +and _server2_ would get 25% of the connections. #### `auth_all_servers` @@ -833,9 +827,9 @@ servers. The strip_db_esc parameter strips escape characters from database names of grants when loading the users from the backend server. -This parameter takes a boolean value and when enabled, will strip all backslash -(`\`) characters from the database names. The default value for this parameter -is true since MaxScale 2.0.1. In previous version, the default value was false. +This parameter takes a boolean value and when enabled, will strip all backslash (`\`) +characters from the database names. The default value for this parameter is true +since MaxScale 2.0.1. In previous version, the default value was false. Some visual database management tools automatically escape some characters and this might cause conflicts when MariaDB MaxScale tries to authenticate users. @@ -991,10 +985,9 @@ able to accept SSL connections. #### `ssl` This enables SSL connections to the server, when set to `required`. If that is -done, the three certificate files mentioned below must also be -supplied. MaxScale connections to this server will then be encrypted with -SSL. If this is not possible, client connection attempts that rely on the server -will fail. +done, the three certificate files mentioned below must also be supplied. +MaxScale connections to this server will then be encrypted with SSL. If this is +not possible, client connection attempts that rely on the server will fail. #### `ssl_key` @@ -1033,10 +1026,10 @@ should be used. #### `ssl_cert_verification_depth` -The maximum length of the certificate authority chain that will be -accepted. Legal values are positive integers. Note that if the client is to -submit an SSL certificate, the `ssl_cert_verification_depth` parameter must not -be 0. If no value is specified, the default is 9. +The maximum length of the certificate authority chain that will be accepted. +Legal values are positive integers. Note that if the client is to submit an SSL +certificate, the `ssl_cert_verification_depth` parameter must not be 0. If no +value is specified, the default is 9. ``` # Example @@ -1081,9 +1074,9 @@ The network socket where the listener listens will have a backlog of connections. The size of this backlog is controlled by the net.ipv4.tcp_max_syn_backlog and net.core.somaxconn kernel parameters. -Increasing the size of the backlog by modifying the kernel parameters -helps with sudden connection spikes and rejected connections. For more -information see [listen(2)](http://man7.org/linux/man-pages/man2/listen.2.html). +Increasing the size of the backlog by modifying the kernel parameters helps with +sudden connection spikes and rejected connections. For more information see +[listen(2)](http://man7.org/linux/man-pages/man2/listen.2.html). ``` [] @@ -1130,14 +1123,14 @@ on both the specific IP address and the Unix socket. #### `authenticator` The authenticator module to use. Each protocol module defines a default -authentication module which is used if no `authenticator` parameter is -found from the configuration. +authentication module which is used if no `authenticator` parameter is found +from the configuration. #### `authenticator_options` -Option string given to the authenticator module. The value of this -parameter should be a comma-separated list of key-value pairs. See -authenticator specific documentation for more details. +Option string given to the authenticator module. The value of this parameter +should be a comma-separated list of key-value pairs. See authenticator specific +documentation for more details. #### Available Protocols @@ -1186,9 +1179,9 @@ SSL/TLS encryption method and the various certificate files involved in it. To enable SSL from client to MaxScale, you must configure the `ssl` parameter to the value `required` and provide the three files for `ssl_cert`, `ssl_key` and `ssl_ca_cert`. After this, MySQL connections to this listener will be encrypted -with SSL. Attempts to connect to the listener with a non-SSL client will -fail. Note that the same service can have an SSL listener and a non-SSL listener -if you wish, although they must be on different ports. +with SSL. Attempts to connect to the listener with a non-SSL client will fail. +Note that the same service can have an SSL listener and a non-SSL listener if +you wish, although they must be on different ports. #### `ssl` @@ -1236,10 +1229,10 @@ TLS 1.2 is also available. MAX will use the best available version. #### `ssl_cert_verification_depth` -The maximum length of the certificate authority chain that will be -accepted. Legal values are positive integers. Note that if the client is to -submit an SSL certificate, the `ssl_cert_verification_depth` parameter must not -be 0. If no value is specified, the default is 9. +The maximum length of the certificate authority chain that will be accepted. +Legal values are positive integers. Note that if the client is to submit an SSL +certificate, the `ssl_cert_verification_depth` parameter must not be 0. If no +value is specified, the default is 9. ``` # Example @@ -1269,7 +1262,6 @@ also specifies that TLSv1.2 should be used as the encryption method. The paths to the server certificate files and the Certificate Authority file are also provided. - ## Routing Modules The main task of MariaDB MaxScale is to accept database connections from client diff --git a/Documentation/Getting-Started/Install-MariaDB-MaxScale-Using-a-Tarball.md b/Documentation/Getting-Started/Install-MariaDB-MaxScale-Using-a-Tarball.md index d8eeb4b3f..b86303acc 100644 --- a/Documentation/Getting-Started/Install-MariaDB-MaxScale-Using-a-Tarball.md +++ b/Documentation/Getting-Started/Install-MariaDB-MaxScale-Using-a-Tarball.md @@ -1,6 +1,8 @@ # Installing MariaDB MaxScale using a tarball -MariaDB MaxScale is also made available as a tarball, which is named like `maxscale-x.y.z.OS.tar.gz` where `x.y.z` is the same as the corresponding version and `OS` identifies the operating system, e.g. `maxscale-2.0.1.centos.7.tar.gz`. +MariaDB MaxScale is also made available as a tarball, which is named like +`maxscale-x.y.z.OS.tar.gz` where `x.y.z` is the same as the corresponding version and `OS` +identifies the operating system, e.g. `maxscale-2.0.1.centos.7.tar.gz`. In order to use the tarball, the following libraries are required: @@ -8,11 +10,14 @@ In order to use the tarball, the following libraries are required: - libaio - OpenSSL -The tarball has been built with the assumption that it will be installed in `/usr/local`. However, it is possible to install it in any directory, but in that case MariaDB MaxScale must be invoked with a flag. +The tarball has been built with the assumption that it will be installed in `/usr/local`. +However, it is possible to install it in any directory, but in that case MariaDB MaxScale +must be invoked with a flag. ## Installing as root in `/usr/local` -If you have root access to the system you probably want to install MariaDB MaxScale under the user and group `maxscale`. +If you have root access to the system you probably want to install MariaDB MaxScale under +the user and group `maxscale`. The required steps are as follows: @@ -24,11 +29,15 @@ The required steps are as follows: $ cd maxscale $ sudo chown -R maxscale var -Creating the symbolic link is necessary, since MariaDB MaxScale has been built with with the assumption that the plugin directory is `/usr/local/maxscale/lib/maxscale`. +Creating the symbolic link is necessary, since MariaDB MaxScale has been built +with the assumption that the plugin directory is `/usr/local/maxscale/lib/maxscale`. -The symbolic link also makes it easy to switch between different versions of MariaDB MaxScale that have been installed side by side in `/usr/local`; just make the symbolic link point to another installation. +The symbolic link also makes it easy to switch between different versions of +MariaDB MaxScale that have been installed side by side in `/usr/local`; +just make the symbolic link point to another installation. -In addition, the first time you install MariaDB MaxScale from a tarball you need to create the following directories: +In addition, the first time you install MariaDB MaxScale from a tarball +you need to create the following directories: $ sudo mkdir /var/log/maxscale $ sudo mkdir /var/lib/maxscale @@ -42,21 +51,28 @@ and make `maxscale` the owner of them: $ sudo chown maxscale /var/run/maxscale $ sudo chown maxscale /var/cache/maxscale -The following step is to create the MariaDB MaxScale configuration file `/etc/maxscale.cnf`. The file `etc/maxscale.cnf.template` can be used as a base. Please refer to [Configuration Guide](Configuration-Guide.md) for details. +The following step is to create the MariaDB MaxScale configuration file `/etc/maxscale.cnf`. +The file `etc/maxscale.cnf.template` can be used as a base. +Please refer to [Configuration Guide](Configuration-Guide.md) for details. When the configuration file has been created, MariaDB MaxScale can be started. $ sudo bin/maxscale --user=maxscale -d -The `-d` flag causes maxscale _not_ to turn itself into a daemon, which is adviseable the first time MariaDB MaxScale is started, as it makes it easier to spot problems. +The `-d` flag causes maxscale _not_ to turn itself into a daemon, +which is adviseable the first time MariaDB MaxScale is started, as it makes it easier to spot problems. -If you want to place the configuration file somewhere else but in `/etc` you can invoke MariaDB MaxScale with the `--config` flag, for instance, `--config=/usr/local/maxscale/etc/maxscale.cnf`. +If you want to place the configuration file somewhere else but in `/etc` +you can invoke MariaDB MaxScale with the `--config` flag, +for instance, `--config=/usr/local/maxscale/etc/maxscale.cnf`. -Note also that if you want to keep _everything_ under `/usr/local/maxscale` you can invoke MariaDB MaxScale using the flag `--basedir`. +Note also that if you want to keep _everything_ under `/usr/local/maxscale` +you can invoke MariaDB MaxScale using the flag `--basedir`. $ sudo bin/maxscale --user=maxscale --basedir=/usr/local/maxscale -d -That will cause MariaDB MaxScale to look for its configuration file in `/usr/local/maxscale/etc` and to store all runtime files under `/usr/local/maxscale/var`. +That will cause MariaDB MaxScale to look for its configuration file in +`/usr/local/maxscale/etc` and to store all runtime files under `/usr/local/maxscale/var`. ## Installing in any Directory @@ -64,16 +80,22 @@ Enter a directory where you have the right to create a subdirectory. Then do as $ tar -xzvf maxscale-x.y.z.OS.tar.gz -The next step is to create the MaxScale configuration file `maxscale-x.y.z/etc/maxscale.cnf`. The file `maxscale-x.y.z/etc/maxscale.cnf.template` can be used as a base. Please refer to [Configuration Guide](Configuration-Guide.md) for details. +The next step is to create the MaxScale configuration file `maxscale-x.y.z/etc/maxscale.cnf`. +The file `maxscale-x.y.z/etc/maxscale.cnf.template` can be used as a base. +Please refer to [Configuration Guide](Configuration-Guide.md) for details. When the configuration file has been created, MariaDB MaxScale can be started. $ cd maxscale-x.y.z.OS $ bin/maxscale -d --basedir=. -With the flag `--basedir`, MariaDB MaxScale is told where the `lib`, `etc` and `var` directories are found. Unless it is specified, MariaDB MaxScale assumes the `lib` directory is found in `/usr/local/maxscale`, and the `var` and `etc` directories in `/`. +With the flag `--basedir`, MariaDB MaxScale is told where the `lib`, `etc` and `var` +directories are found. Unless it is specified, MariaDB MaxScale assumes +the `lib` directory is found in `/usr/local/maxscale`, +and the `var` and `etc` directories in `/`. -It is also possible to specify the directories and the location of the configuration file individually. Invoke MaxScale like +It is also possible to specify the directories and the location of +the configuration file individually. Invoke MaxScale like $ bin/maxscale --help diff --git a/Documentation/Getting-Started/MariaDB-MaxScale-Installation-Guide.md b/Documentation/Getting-Started/MariaDB-MaxScale-Installation-Guide.md index 9106066a2..2c8c29ff0 100644 --- a/Documentation/Getting-Started/MariaDB-MaxScale-Installation-Guide.md +++ b/Documentation/Getting-Started/MariaDB-MaxScale-Installation-Guide.md @@ -2,11 +2,21 @@ ## First Steps With MariaDB MaxScale -In this introduction to MariaDB MaxScale the aim is to take the reader from the point of installation to making the decision as to which of the various setups that are possible with MariaDB MaxScale should be the initial configuration to use. One of the problems that new users to MariaDB MaxScale suffer is deciding exactly what they should consider as a base configuration to start exploring what MariaDB MaxScale is capable of. MariaDB MaxScale is highly configurable, with new plugins expanding the capabilities of MariaDB MaxScale, whilst this makes it a very adaptable tool it does lead to an initial hurdle in configuring MariaDB MaxScale. +In this introduction to MariaDB MaxScale the aim is to take the reader +from the point of installation to making the decision as to which of +the various setups that are possible with MariaDB MaxScale should be +the initial configuration to use. One of the problems that new users to +MariaDB MaxScale suffer is deciding exactly what they should consider +as a base configuration to start exploring what MariaDB MaxScale +is capable of. MariaDB MaxScale is highly configurable, +with new plugins expanding the capabilities of MariaDB MaxScale, +whilst this makes it a very adaptable tool it does lead to an initial +hurdle in configuring MariaDB MaxScale. ## Installation -MariaDB MaxScale can be installed either using the MariaDB Enterprise Repository or directly from a downloaded package. +MariaDB MaxScale can be installed either using the MariaDB Enterprise Repository +or directly from a downloaded package. ### Using the MariaDB Enterprise Repository @@ -40,7 +50,8 @@ $ sudo apt-get install -f ### Starting MariaDB MaxScale -Before starting MariaDB MaxScale, you need to create a configuration file for it; please see further [down](#configuring-mariadb-maxscale). +Before starting MariaDB MaxScale, you need to create a configuration file for it; +please see further [down](#configuring-mariadb-maxscale). Once a configuration file has been created you can start MariaDB MaxScale: @@ -48,7 +59,8 @@ Once a configuration file has been created you can start MariaDB MaxScale: systemctl start maxscale.service ``` -If your system does not support systemd you can start MariaDB MaxScale using the installed init.d script. +If your system does not support systemd you can start MariaDB MaxScale using the +installed init.d script. ``` service maxscale start @@ -56,56 +68,130 @@ service maxscale start Starting with version 2.0.3, MaxScale also supports Upstart. -An example configuration file is installed into the `/etc/` folder. This file should be changed according to your needs. +An example configuration file is installed into the `/etc/` folder. +This file should be changed according to your needs. ## Install MariaDB MaxScale Using a Tarball -MaxScale can also be installed using a tarball. That may be required if you are using a Linux distribution for which there exist no installation package or if you want to install many different MaxScale versions side by side. For instructions on how to do that, please refer to [Install MariaDB MaxScale using a Tarball](Install-MariaDB-MaxScale-Using-a-Tarball.md). +MaxScale can also be installed using a tarball. +That may be required if you are using a Linux distribution for which there +exist no installation package or if you want to install many different +MaxScale versions side by side. For instructions on how to do that, please refer to +[Install MariaDB MaxScale using a Tarball](Install-MariaDB-MaxScale-Using-a-Tarball.md). ## Building MariaDB MaxScale From Source Code -Alternatively you may download the MariaDB MaxScale source and build your own binaries. To do this, refer to the separate document [Building MariaDB MaxScale from Source Code](Building-MaxScale-from-Source-Code.md) +Alternatively you may download the MariaDB MaxScale source and build your own binaries. +To do this, refer to the separate document +[Building MariaDB MaxScale from Source Code](Building-MaxScale-from-Source-Code.md) ## Configuring MariaDB MaxScale -The first step in configuring your MariaDB MaxScale is to determine what it is you want to achieve with your MariaDB MaxScale and what environment it will run in. The later is probably the easiest starting point for choosing which configuration route you wish to take. There are two distinct database environments which the first GA release of MariaDB MaxScale supports; MySQL Master/Slave Replication clusters and Galera Cluster. +The first step in configuring your MariaDB MaxScale is to determine +what it is you want to achieve with your MariaDB MaxScale and what environment +it will run in. The later is probably the easiest starting point for choosing +which configuration route you wish to take. +There are two distinct database environments which the first GA release +of MariaDB MaxScale supports; MySQL Master/Slave Replication clusters and Galera Cluster. For more details, refer to the [Configuration Guide](Configuration-Guide.md). ### Master/Slave Replication Clusters -There are two major configuration options available to use MariaDB MaxScale with a MySQL Replication cluster; connection routing with separate read and write connections, or read/write splitting with a single connection. A separate tutorial is available for each of these configurations that describes how to build the configuration file for MariaDB MaxScale that will work with your environment. +There are two major configuration options available to use MariaDB MaxScale +with a MySQL Replication cluster; connection routing with separate read and +write connections, or read/write splitting with a single connection. +A separate tutorial is available for each of these configurations that +describes how to build the configuration file for MariaDB MaxScale that +will work with your environment. -Using a MySQL Master/Slave Replication cluster will provide one node server within the cluster that is the master server and the remainder of the servers will be slaves. The slaves are read replicas of the master. In a replication cluster like this all write operations must be performed on the master. This can provide not just added security of your data, but also read scalability. In an application environment with a substantial proportions of read operations, directing those read operations to the slave servers can increase the total load which the system can handle by offloading the master server from the burden of these read operations. +Using a MySQL Master/Slave Replication cluster will provide one node server +within the cluster that is the master server and the remainder of the servers +will be slaves. The slaves are read replicas of the master. +In a replication cluster like this all write operations must be performed +on the master. +This can provide not just added security of your data, but also read scalability. +In an application environment with a substantial proportions of read operations, +directing those read operations to the slave servers can increase +the total load which the system can handle by offloading the master server +from the burden of these read operations. -Making the choice between these two setups is relatively simple, if you have an application that understands that there are some database servers that it can only read from and one it must send all of the writes to, then the connection routing option can be used. Applications that are not written to separate read and write statements must use a service within MariaDB MaxScale that will split the incoming stream of SQL statements into operations that can be executed on the master and those that can be set to the slave. These applications should use the statement based routing provided by the Read/Write Splitter router. +Making the choice between these two setups is relatively simple, +if you have an application that understands that there are some database servers +that it can only read from and one it must send all of the writes to, +then the connection routing option can be used. +Applications that are not written to separate read and write statements must use +a service within MariaDB MaxScale that will split the incoming stream of SQL statements +into operations that can be executed on the master and those that can be set to the slave. +These applications should use the statement based routing provided by +the Read/Write Splitter router. ### Galera Cluster -A Galera Cluster provides a true multi-master cluster option for MariaDB and MySQL database environments. In such a setup any node that is part of the cluster can be used to both execute read and write operations. MariaDB MaxScale again offers two different configurations that can be used with Galera; a connection balancing configuration or a statement splitting mechanism that can be used to isolate write operations to a single node within the cluster. Again there is a tutorial guide available for both of these major configurations. +A Galera Cluster provides a true multi-master cluster option for MariaDB and MySQL +database environments. In such a setup any node that is part of the cluster +can be used to both execute read and write operations. +MariaDB MaxScale again offers two different configurations that can be used with Galera; +a connection balancing configuration or a statement splitting mechanism that can be used +to isolate write operations to a single node within the cluster. +Again there is a tutorial guide available for both of these major configurations. -The connection based load balancing configuration is used in an environment in which you have a cluster that you want to be available to an application without the application needing to be aware of the cluster configuration or state of the database nodes. MariaDB MaxScale will monitor the nodes within the database cluster and will route connections from the application to database nodes that are active members of the cluster. MariaDB MaxScale will also keep track of the number of connections to each database node keep equal numbers of connections to each node, at the time the connection is established. +The connection based load balancing configuration is used in an environment in which +you have a cluster that you want to be available to an application without +the application needing to be aware of the cluster configuration or state of +the database nodes. +MariaDB MaxScale will monitor the nodes within the database cluster and will +route connections from the application to database nodes that +are active members of the cluster. +MariaDB MaxScale will also keep track of the number of connections to each +database node keep equal numbers of connections to each node, +at the time the connection is established. -It is also possible to use the Read/Write Splitter with Galera. Although it is not necessary to segregate the write operations to a single node, there are advantages in doing this if you have an application where the write load is not too great to be handled by a single node in the cluster. Galera Cluster uses an optimistic locking strategy that will allow transactions to progress independently on each node within the cluster. It is only when the transaction commits that the transaction is checked for conflicts with other transactions that are committing on the other nodes. At this stage the commit can fail with a deadlock detection error. This can be inconvenient for applications and, some older applications, that are not aware that the transaction can fail at this stage may not check for this failure. Using the Read/Write Splitter will allow this to be avoided since it will isolate the write to one node and no deadlock detection will occur. MariaDB MaxScale provides a monitoring module that will maintain pseudo states of master and slave for the Galera cluster that allows for this type of configuration. +It is also possible to use the Read/Write Splitter with Galera. +Although it is not necessary to segregate the write operations to a single node, +there are advantages in doing this if you have an application where the write load +is not too great to be handled by a single node in the cluster. +Galera Cluster uses an optimistic locking strategy that will allow transactions +to progress independently on each node within the cluster. +It is only when the transaction commits that the transaction is checked for conflicts +with other transactions that are committing on the other nodes. +At this stage the commit can fail with a deadlock detection error. +This can be inconvenient for applications and, some older applications, +that are not aware that the transaction can fail at this stage +may not check for this failure. +Using the Read/Write Splitter will allow this to be avoided since +it will isolate the write to one node and no deadlock detection will occur. +MariaDB MaxScale provides a monitoring module that will maintain pseudo states +of master and slave for the Galera cluster that allows for this type of configuration. ### Other MariaDB MaxScale Configuration -As well as the four major configuration choices outlined above there are also other configurations sub-options that may be mixed with those to provide a variety of different configuration and functionality. The MariaDB MaxScale filter concept allows the basic configurations to be built upon in a large variety of ways. A separate filter tutorial is available that discusses the concept and gives some examples of ways to use filters. +As well as the four major configuration choices outlined above there are also other +configurations sub-options that may be mixed with those to provide a variety of different +configuration and functionality. The MariaDB MaxScale filter concept allows the basic configurations +to be built upon in a large variety of ways. A separate filter tutorial is available +that discusses the concept and gives some examples of ways to use filters. ## Encrypting Passwords -Passwords stored in the maxscale.cnf file may optionally be encrypted for added security. This is done by creation of an encryption key on installation of MariaDB MaxScale. Encryption keys may be created manually by executing the maxkeys utility with the argument of the filename to store the key. The default location MariaDB MaxScale stores the keys is `/var/lib/maxscale`. +Passwords stored in the maxscale.cnf file may optionally be encrypted for added security. +This is done by creation of an encryption key on installation of MariaDB MaxScale. +Encryption keys may be created manually by executing the maxkeys utility with the argument +of the filename to store the key. The default location MariaDB MaxScale stores +the keys is `/var/lib/maxscale`. ``` # Usage: maxkeys [PATH] maxkeys /var/lib/maxscale/ ``` -Changing the encryption key for MariaDB MaxScale will invalidate any currently encrypted keys stored in the maxscale.cnf file. +Changing the encryption key for MariaDB MaxScale will invalidate any currently +encrypted keys stored in the maxscale.cnf file. ### Creating Encrypted Passwords -Encrypted passwords are created by executing the maxpasswd command with the location of the .secrets file and the password you require to encrypt as an argument. +Encrypted passwords are created by executing the maxpasswd command with the location +of the .secrets file and the password you require to encrypt as an argument. ``` # Usage: maxpasswd PATH PASSWORD @@ -113,7 +199,10 @@ maxpasswd /var/lib/maxscale/ MaxScalePw001 61DD955512C39A4A8BC4BB1E5F116705 ``` -The output of the maxpasswd command is a hexadecimal string, this should be inserted into the maxscale.cnf file in place of the ordinary, plain text, password. MariaDB MaxScale will determine this as an encrypted password and automatically decrypt it before sending it the database server. +The output of the maxpasswd command is a hexadecimal string, this should be inserted +into the maxscale.cnf file in place of the ordinary, plain text, password. +MariaDB MaxScale will determine this as an encrypted password and automatically decrypt +it before sending it the database server. ``` [Split Service] @@ -135,8 +224,19 @@ modules it will search using a configurable search path. The priority of these p 2. Look in the directory defined with libdir=PATH in the configuration file under the [maxscale] section 3. Look in default directory in /usr/lib64/maxscale -Configuration is read by default from the file /etc/maxscale.cnf. An example file is included in in the installation and can be found in the /usr/share/maxscale folder within the MariaDB MaxScale installation. The -f flag can be used on the command line to set the name and the location of the configuration file. The -C flag can be used to set the directory where the configuration file is searched for. Without the -f or -C flags, the file is read from the /etc directory. +Configuration is read by default from the file /etc/maxscale.cnf. An example file is +included in in the installation and can be found in the /usr/share/maxscale folder within +the MariaDB MaxScale installation. The -f flag can be used on the command line to set +the name and the location of the configuration file. The -C flag can be used to set +the directory where the configuration file is searched for. Without the -f or -C flags, +the file is read from the /etc directory. ## Administration Of MariaDB MaxScale -There are various administration tasks that may be done with MariaDB MaxScale, a client command, maxadmin, is available that will interact with a running MariaDB MaxScale and allow the status of MariaDB MaxScale to be monitored and give some control of the MariaDB MaxScale functionality. There is [a separate reference guide](../Reference/MaxAdmin.md) for the maxadmin utility and also [a short administration tutorial](../Tutorials/Administration-Tutorial.md) that covers the common administration tasks that need to be done with MariaDB MaxScale. +There are various administration tasks that may be done with MariaDB MaxScale, +a client command, maxadmin, is available that will interact with a running +MariaDB MaxScale and allow the status of MariaDB MaxScale to be monitored and +give some control of the MariaDB MaxScale functionality. +There is [a separate reference guide](../Reference/MaxAdmin.md) for the maxadmin utility +and also [a short administration tutorial](../Tutorials/Administration-Tutorial.md) +that covers the common administration tasks that need to be done with MariaDB MaxScale. diff --git a/Documentation/Monitors/MM-Monitor.md b/Documentation/Monitors/MM-Monitor.md index 039840122..86e31d5bc 100644 --- a/Documentation/Monitors/MM-Monitor.md +++ b/Documentation/Monitors/MM-Monitor.md @@ -2,11 +2,15 @@ ## Overview -The Multi-Master Monitor is a monitoring module for MaxScale that monitors Master-Master replication. It assigns master and slave roles inside MaxScale based on whether the read_only parameter on a server is set to off or on. +The Multi-Master Monitor is a monitoring module for MaxScale that monitors Master-Master replication. +It assigns master and slave roles inside MaxScale based on whether the read_only parameter on a server +is set to off or on. ## Configuration -A minimal configuration for a monitor requires a set of servers for monitoring and a username and a password to connect to these servers. The user requires the REPLICATION CLIENT privilege to successfully monitor the state of the servers. +A minimal configuration for a monitor requires a set of servers for monitoring and an username +and a password to connect to these servers. The user requires the REPLICATION CLIENT privilege +to successfully monitor the state of the servers. ``` [Multi-Master Monitor] @@ -20,7 +24,8 @@ passwd=mypwd ## Common Monitor Parameters -For a list of optional parameters that all monitors support, read the [Monitor Common](Monitor-Common.md) document. +For a list of optional parameters that all monitors support, read +the [Monitor Common](Monitor-Common.md) document. ## Multi-Master Monitor optional parameters @@ -28,9 +33,12 @@ These are optional parameters specific to the Multi-Master Monitor. ### `detect_stale_master` -Allow previous master to be available even in case of stopped or misconfigured replication. This allows services that depend on master and slave roles to continue functioning as long as the master server is available. +Allow previous master to be available even in case of stopped or misconfigured replication. +This allows services that depend on master and slave roles to continue functioning as long as +the master server is available. -This is a situation which can happen if all slave servers are unreachable or the replication breaks for some reason. +This is a situation which can happen if all slave servers are unreachable or the +replication breaks for some reason. ``` detect_stale_master=true diff --git a/Documentation/Reference/Debug-And-Diagnostic-Support.md b/Documentation/Reference/Debug-And-Diagnostic-Support.md deleted file mode 100644 index cec11bd33..000000000 --- a/Documentation/Reference/Debug-And-Diagnostic-Support.md +++ /dev/null @@ -1,1947 +0,0 @@ -MariaDB MaxScale - -Debug & Diagnostic Support - -Mark Riddoch - -Last Updated: 24th November 2014 - -[[TOC]] - -# Change History - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
DateComment
20th June 2013Initial Version
22nd July 2013Updated with new naming MariaDB MaxScale -Addition of description of login process for the debug CLI -Updates debug CLI output examples -Addition of show users, shutdown maxscale, shutdown service, restart service, set server, clear server, reload users, reload config and add user commands.
23rd July 2013Rename of show users command to show dbusers and addition of the show users command to show the admin users. -Addition of example configuration data.
14th November 2013Added enable/disable log commands details -Added Galera Monitor as an example in show monitors
3rd March 2014Added show users details for MySQL users
27th May 2014Document the new debugcli mode switch and command changes in the two modes. -Added the new show server command.
29th May 2014Addition of new list command that gives concise tabular output
4th June 2014Added new ‘show monitors’ and ‘show servers’ details
31st June 2014Added NDB monitor in show monitors
29th August 2014Added new ‘show monitors’ details for MySQL/Galera monitors
- - -# Introduction - -MariaDB MaxScale is a complex application and as such is bound to have bugs and support issues that occur from time to time. There are a number of things we need to consider for the development stages and long term supportability of MariaDB MaxScale - -* Flexible logging of MariaDB MaxScale activity - -* Support for connecting a debugger to MariaDB MaxScale - -* A diagnostic interface to MariaDB MaxScale - -The topic of logging has already been discussed in another document in this series of documents about MariaDB MaxScale and will not be covered further here. - -# Debugger Support - -Beyond the language support for debugging using tools such as gdb, MariaDB MaxScale will also offer convenience functions for the debugger to call and a command line argument that is useful to run MariaDB MaxScale under the debugger. - -## Command Line Option - -Normally when MariaDB MaxScale starts it will place itself in the background and setup the signal masks so that it is immune to the normal set of signals that will cause the process to exit, SIGINT and SIGQUIT. This behavior is normally what is required, however if you wish to run MariaDB MaxScale under the control of a debugger it is useful to suppress this behavior. A command line option, -d is provided to turn off this behavior. - -% gdb maxscale - -(gdb) run -d - -## Convenience Functions - -A set of convenience functions is provided that may be used within the debugger session to extract information from MariaDB MaxScale. - -### Printing Services - -A service within MariaDB MaxScale provides the encapsulation of the port MariaDB MaxScale listen on, the protocol it uses, the set of servers it may route to and the routing method to use. Two functions exists that allow you to display the details of the services and may be executed from within a debugger session. - -The printAllServices() function will print all the defined services within MariaDB MaxScale and is invoked using the call syntax of the debugger. - -(gdb) call printAllServices() - -Service 0x60da20 - - Service: Debug Service - - Router: debugcli (0x7ffff5a7c2a0) - - Started: Thu Jun 20 15:13:32 2013 - - Backend databases - - Total connections: 1 - - Currently connected: 1 - -Service 0x60d010 - - Service: Test Service - - Router: readconnroute (0x7ffff5c7e260) - - Started: Thu Jun 20 15:13:32 2013 - - Backend databases - - 127.0.0.1:3308 Protocol: MySQLBackend - - 127.0.0.1:3307 Protocol: MySQLBackend - - 127.0.0.1:3306 Protocol: MySQLBackend - - Total connections: 1 - - Currently connected: 1 - -(gdb) - -It is possible to print an individual service if you know the memory address of the service. - -(gdb) call printService(0x60da20) - -Service 0x60da20 - - Service: Debug Service - - Router: debugcli (0x7ffff5a7c2a0) - - Started: Thu Jun 20 15:13:32 2013 - - Backend databases - - Total connections: 1 - - Currently connected: 1 - -(gdb) - -### Printing Sessions - -Sessions represent the data for a client that is connecting through MariaDB MaxScale, there will be a session for each client and one for each listener for a specific port/protocol combination. Similarly there are two calls to print all or a particular session. - -(gdb) call printAllSessions() - -Session 0x60fdf0 - - Service: Debug Service (0x60da20) - - Client DCB: 0x60f6c0 - - Connected: Thu Jun 20 15:13:32 2013 - -Session 0x60f620 - - Service: Test Service (0x60d010) - - Client DCB: 0x60ead0 - - Connected: Thu Jun 20 15:13:32 2013 - -(gdb) call printSession(0x60fdf0) - -Session 0x60fdf0 - - Service: Debug Service (0x60da20) - - Client DCB: 0x60f6c0 - - Connected: Thu Jun 20 15:13:32 2013 - -(gdb) - -### Printing Servers - -Servers are a representation of the backend database to which MariaDB MaxScale may route SQL statements. Similarly two calls exist to print server details. - -(gdb) call printAllServers() - -Server 0x60d9a0 - - Server: 127.0.0.1 - - Protocol: MySQLBackend - - Port: 3308 - -Server 0x60d920 - - Server: 127.0.0.1 - - Protocol: MySQLBackend - - Port: 3307 - -Server 0x60d8a0 - - Server: 127.0.0.1 - - Protocol: MySQLBackend - - Port: 3306 - -(gdb) call printServer(0x60d920) - -Server 0x60d920 - - Server: 127.0.0.1 - - Protocol: MySQLBackend - - Port: 3307 - -(gdb) - -### Modules - -MariaDB MaxScale makes significant use of modules, shared objects, that are loaded on demand based on the configuration. A routine exists that will print the currently loaded modules. - -(gdb) call printModules() - -Module Name | Module Type | Version - ------------------------------------------------------ - -telnetd | Protocol | V1.0.0 - -MySQLClient | Protocol | V1.0.0 - -testroute | Router | V1.0.0 - -debugcli | Router | V1.0.0 - -readconnroute | Router | V1.0.0 - -(gdb) - -### Descriptor Control Blocks - -The Descriptor Control Block (DCB) is an important concept within MariaDB MaxScale since it is this block that is passed to the polling system, when an event occurs it is that structure that is available and from this structure it must be possible to navigate to all other structures that contain state regarding the session and protocol in use. - -![image alt text](images/image_0.png) - -Similar print routines exist for the DCB - -(gdb) call printAllDCBs() - -DCB: 0x60ead0 - - DCB state: DCB for listening socket - - Queued write data: 0 - - Statistics: - - No. of Reads: 0 - - No. of Writes: 0 - - No. of Buffered Writes: 0 - - No. of Accepts: 0 - -DCB: 0x60f6c0 - - DCB state: DCB for listening socket - - Queued write data: 0 - - Statistics: - - No. of Reads: 0 - - No. of Writes: 0 - - No. of Buffered Writes: 0 - - No. of Accepts: 0 - -(gdb) call printDCB(0x60ead0) - -DCB: 0x60ead0 - - DCB state: DCB for listening socket - - Queued write data: 0 - - Statistics: - - No. of Reads: 0 - - No. of Writes: 0 - - No. of Buffered Writes: 0 - - No. of Accepts: 0 - -(gdb) - -# Diagnostic Interface - -It is possible to configure a service to run within MariaDB MaxScale that will allow a user to telnet to a port on the machine and be connected to MariaDB MaxScale. This is configured by creating a service that uses the debugcli routing module and the telnetd protocol with an associated listener. The service does not require any backend databases to be configured since the router never forwards any data, it merely accepts commands and executes them, returning data to the user. - -The example below shows the configuration that is required to set-up a debug interface that listens for incoming telnet connections on port 4442. - -[Debug Service] - -type=service - -router=debugcli - -[Debug Listener] - -type=listener - -service=Debug Service - -protocol=telnetd - -port=4442 - -The Debug Service section sets up a service with no backend database servers, but with a debugcli module as the router. This module will implement the commands and send the data back to the client. - -The debugcli accepts router options of either developer or user, these are used to control the mode of the user interface. If no router options are given then the CLI is in user mode by default. - -The Debug Listener section setups the protocol and port combination and links that to the service. - -Assuming a configuration that includes the debug service, with the listening port set to 4442, to connect from the machine that runs MariaDB MaxScale you must first install telnet and then simply call telnet to connect. - --bash-4.1$ telnet localhost 4442 - -Trying 127.0.0.1... - -Connected to localhost. - -Escape character is '^]'. - -Welcome the MariaDB MaxScale Debug Interface (V1.1.0). - -Type help for a list of available commands. - -MaxScale login: admin - -Password: - -MaxScale> - -As delivered MariaDB MaxScale uses a default login name of admin with the password of mariadb for connections to the debug interface. Users may be added to the CLI by use of the add user command. - -This places you in the debug command line interface of MariaDB MaxScale, there is a help system that will display the commands available to you - -**MaxScale> **help - -Available commands: - - add user - - clear server - - disable log - - enable log - - list [listeners|modules|services|servers|sessions] - - reload [config|dbusers] - - remove user - - restart [monitor|service] - - set server - - show [dcbs|dcb|dbusers|epoll|modules|monitors|server|servers|services|service|session|sessions|users] - - shutdown [maxscale|monitor|service] - -Type help command to see details of each command. - -Where commands require names as arguments and these names contain - -whitespace either the \ character may be used to escape the whitespace - -or the name may be enclosed in double quotes ". - -**MaxScale> ** - -Different command help is shown in user mode and developer mode, in user mode the help for the show command is; - -**MaxScale>** help show - -Available options to the show command: - - dcbs Show all descriptor control blocks (network connections) - - dcb Show a single descriptor control block e.g. show dcb 0x493340 - - dbusers Show statistics and user names for a service's user table. - - Example : show dbusers - - epoll Show the poll statistics - - modules Show all currently loaded modules - - monitors Show the monitors that are configured - - server Show details for a named server, e.g. show server dbnode1 - - servers Show all configured servers - - services Show all configured services in MaxScale - - service Show a single service in MaxScale, may be passed a service name - - session Show a single session in MaxScale, e.g. show session 0x284830 - - sessions Show all active sessions in MaxScale - - users Show statistics and user names for the debug interface - -**MaxScale>** - -However in developer mode the help is; - -**MaxScale>** help show - -Available options to the show command: - - dcbs Show all descriptor control blocks (network connections) - - dcb Show a single descriptor control block e.g. show dcb 0x493340 - - dbusers Show statistics and user names for a service's user table - - epoll Show the poll statistics - - modules Show all currently loaded modules - - monitors Show the monitors that are configured - - server Show details for a server, e.g. show server 0x485390 - - servers Show all configured servers - - services Show all configured services in MaxScale - - session Show a single session in MaxScale, e.g. show session 0x284830 - - sessions Show all active sessions in MaxScale - - users Show statistics and user names for the debug interface - -**MaxScale>** - -The commands available are very similar to those described above to print things from the debugger, the advantage being that you do not need a debug version or a debugger to use them. - -## Listing Services - -The list services command is designed to give a concise tabular view of the currently configured services within MaxScale along with key data that summarizes the use being made of the service. - -**MaxScale>** list services - -Service Name | Router Module | #Users | Total Sessions - --------------------------------------------------------------------------- - -Test Service | readconnroute | 1 | 1 - -Split Service | readwritesplit | 1 | 1 - -Debug Service | debugcli | 2 | 2 - -**MaxScale>** - -This provides a useful mechanism to see what is configured and provide the service names that can be passed to a show service command. - -## Listing Listeners - -The list listeners command outputs a table that provides the current set of listeners within the MariaDB MaxScale instance and shows the status of each listener. - -**MaxScale>** list listeners - -Service Name | Protocol Module | Address | Port | State - ---------------------------------------------------------------------------- - -Test Service | MySQLClient | (null) | 4006 | Running - -Split Service | MySQLClient | (null) | 4007 | Running - -Debug Service | telnetd | localhost | 4242 | Running - -**MaxScale>** - -## Listing Servers - -The list servers command will display a table that contains a row for every server defined in the configuration file. The row contains the server name that can be passed to the show server command, the address and port of the server, its current status and the number of connections to that server from MariaDB MaxScale. - -**MaxScale>** list servers - -Server | Address | Port | Status | Connections - -------------------------------------------------------------------------------- - -server1 | 127.0.0.1 | 3306 | Running | 0 - -server2 | 127.0.0.1 | 3307 | Slave, Running | 0 - -server3 | 127.0.0.1 | 3308 | Master, Running | 0 - -server4 | 127.0.0.1 | 3309 | Slave, Running | 0 - -**MaxScale>** - -## Listing Modules - -The list modules command displays a table of all the modules loaded within MariaDB MaxScale. - -**MaxScale> **list modules - -Module Name | Module Type | Version - ------------------------------------------------------ - -telnetd | Protocol | V1.0.1 - -MySQLClient | Protocol | V1.0.0 - -mysqlmon | Monitor | V1.1.0 - -readconnroute | Router | V1.0.2 - -readwritesplit | Router | V1.0.2 - -debugcli | Router | V1.1.1 - -**MaxScale>**** ** - -## Showing Services - -The show services command will show all the services configured currently - -**MaxScale>** show services - -Service 0xf44c10 - - Service: Test Service - - Router: readconnroute (0x7f7fd8afba40) - - Number of router sessions: 0 - - Current no. of router sessions: 0 - - Number of queries forwarded: 0 - - Started: Mon Jul 22 11:24:09 2013 - - Backend databases - - 127.0.0.1:3309 Protocol: MySQLBackend - - 127.0.0.1:3308 Protocol: MySQLBackend - - 127.0.0.1:3307 Protocol: MySQLBackend - - 127.0.0.1:3306 Protocol: MySQLBackend - - Users data: 0xf454b0 - - Total connections: 1 - - Currently connected: 1 - -Service 0xf43910 - - Service: Split Service - - Router: readwritesplit (0x7f7fd8f05460) - - Number of router sessions: 0 - - Current no. of router sessions: 0 - - Number of queries forwarded: 0 - - Number of queries forwarded to master: 0 - - Number of queries forwarded to slave: 0 - - Number of queries forwarded to all: 0 - - Started: Mon Jul 22 11:24:09 2013 - - Backend databases - - 127.0.0.1:3308 Protocol: MySQLBackend - - 127.0.0.1:3307 Protocol: MySQLBackend - - 127.0.0.1:3306 Protocol: MySQLBackend - - Users data: 0xf449b0 - - Total connections: 1 - - Currently connected: 1 - -Service 0xea0190 - - Service: Debug Service - - Router: debugcli (0x7f7fd910d620) - - Started: Mon Jul 22 11:24:09 2013 - - Backend databases - - Users data: 0xea2d80 - - Total connections: 2 - - Currently connected: 2 - -**MaxScale>** - -## Showing Sessions - -There are two options to show sessions, either an individual session or all sessions - -**MaxScale>** show sessions - -Session 0x6f8f20 - - State: Session Ready - - Service: Debug Service (0x649190) - - Client DCB: 0x6f8e20 - - Client Address: 0.0.0.0 - - Connected: Mon Jul 22 11:31:56 2013 - -Session 0x6f83b0 - - State: Session Allocated - - Service: Split Service (0x6ec910) - - Client DCB: 0x64b430 - - Client Address: 127.0.0.1 - - Connected: Mon Jul 22 11:31:28 2013 - -Session 0x6efba0 - - State: Listener Session - - Service: Debug Service (0x649190) - - Client DCB: 0x64b180 - - Connected: Mon Jul 22 11:31:21 2013 - -Session 0x64b530 - - State: Listener Session - - Service: Split Service (0x6ec910) - - Client DCB: 0x6ef8e0 - - Connected: Mon Jul 22 11:31:21 2013 - -Session 0x618840 - - State: Listener Session - - Service: Test Service (0x6edc10) - - Client DCB: 0x6ef320 - - Connected: Mon Jul 22 11:31:21 2013 - -**MaxScale>** show session 0x6f83b0 - -Session 0x6f83b0 - - State: Session Allocated - - Service: Split Service (0x6ec910) - - Client DCB: 0x64b430 - - Client Address: 127.0.0.1 - - Connected: Mon Jul 22 11:31:28 2013 - -**MaxScale> ** - -## Show Servers - -The configured backend databases can be displayed using the show servers command. - -**MaxScale>** show servers - -Server 0x6ec840 (server1) - - Server: 127.0.0.1 - - Status: Running - - Protocol: MySQLBackend - - Port: 3306 - - Number of connections: 0 - - Current no. of connections:0 - -Server 0x6ec770 (server2) - - Server: 127.0.0.1 - - Status: Master, Running - - Protocol: MySQLBackend - - Port: 3307 - - Server Version: 5.5.35-MariaDB-log - - Node Id: 1 - - Master Id: -1 - - Slave Ids: 2,3 - - Repl Depth: 0 - - Last Repl Heartbeat: 1417080906 - - Number of connections: 1 - - Current no. of connections:1 - -Server 0x6ec6a0 (server3) - - Server: 127.0.0.1 - - Status: Slave, Running - - Protocol: MySQLBackend - - Port: 3308 - - Server Version: 5.5.35-MariaDB-log - -Node Id: 2 - - Master Id: 1 - - Slave Ids: - - Repl Depth: 1 - - Slave delay: 8 - - Last Repl Heartbeat: 1417080898 - - Number of connections: 1 - - Current no. of connections:1 - -Server 0x6ec5d0 (server4) - - Server: 127.0.0.1 - - Status: Down - - Protocol: MySQLBackend - - Port: 3309 - - Server Version: 5.5.35-MariaDB-log - - Node Id: 3 - - Master Id: 1 - - Slave Ids: - - Repl Depth: 1 - - Number of connections: 0 - - Current no. of connections:0 - -**MaxScale>** - -* Version string is available in the output only if the node is running. - -* Node Id possible values: - -* the value of server-id from MySQL or MariaDB servers in Master/Slave replication setup. - -* the value of ‘wsrep_local_index’ for Galera cluster nodes - -* the value of ‘Ndb_cluster_node_id’ for SQL nodes in MySQL Cluster - -* the -1 value for a failure getting one of these information - -* Repl Depth is the replication depth level found by MaxScale MySQL Monitor - -* Master Id is the master node, if available, for current server - -* Slave Ids is the slave list for the current node, if available - -Note, the Master Root Server used for routing decision is the server with master role and with lowest replication depth level. All slaves servers even if they are intermediate master are suitable for read statement routing decisions. - -* Slave Delay is the found time difference used for Replication Lag support in routing decision, between the value read by the Slave (it was inserted into the master) and maxscale current time - - Value of 0 or less than monitor interval means there is no replication delay. - -* Last Repl Heartbeat is the MaxScale timestamp read or inserted (if current server is master) - -The Replication Heartbeat table is updated by MySQL replication, starting MariaDB MaxScale when there is a significant slave delay may result that Slave Delay and Last Repl Heartbeat are not available for some time in the slave server details - -## There may be other status description such us: - - Slave of External Server: the node is slave of a server not configured - - in MaxScale (by MySQL monitor) - - Master Stickiness: the Master node is kept (by Galera monitor) - - Stale Status: the master node is kept even if the replication - - is not working (by MySQL monitor) - - Auth Error: Monitor was not able to login into backend - -A few examples: - -Server 0x1a5aae0 (server3) - - Server: 127.0.0.1 - - Status: Master, Slave of External Server, Running - - Protocol: MySQLBackend - - Port: 3308 - - Server Version: 5.5.35-MariaDB-log - - Node Id: 3 - - Master Id: 1 - - Slave Ids: 2 - - Repl Depth: 1 - -Server 0x2d1b5c0 (server2) - - Server: 192.168.122.142 - - Status: Master, Synced, Master Stickiness, Running - - Protocol: MySQLBackend - - Port: 3306 - - Server Version: 5.5.40-MariaDB-wsrep-log - - Node Id: 1 - - Repl Depth: 0 - -## Show Server - -Details of an individual server can be displayed by using the show server command. In user mode the show server command is passed the name of the server to display, these names are the section names used in the configuration file. - -**MaxScale>** show server server4 - -Server 0x6ec5d0 (server4) - - Server: 127.0.0.1 - - Status: Down - - Protocol: MySQLBackend - - Port: 3309 - - Number of connections: 0 - - Current no. of connections:0 - -**MaxScale>** - -In developer mode the show server command is passed the address of a server structure. - -**MaxScale>** show server 0x6ec5d0 - -Server 0x6ec5d0 (server4) - - Server: 127.0.0.1 - - Status: Down - - Protocol: MySQLBackend - - Port: 3309 - - Number of connections: 0 - - Current no. of connections:0 - -**MaxScale>** - -## Show DCBS - -There are two forms of the show command that will give you DCB information, the first will display information for all DCBs within the system. - -**MaxScale>** show dcbs - -DCB: 0x6ef320 - - DCB state: DCB for listening socket - - Service: Test Service - - Queued write data: 0 - - Statistics: - - No. of Reads: 0 - - No. of Writes: 0 - - No. of Buffered Writes: 0 - - No. of Accepts: 0 - -DCB: 0x6ef8e0 - - DCB state: DCB for listening socket - - Service: Split Service - - Queued write data: 0 - - Statistics: - - No. of Reads: 0 - - No. of Writes: 0 - - No. of Buffered Writes: 0 - - No. of Accepts: 1 - -DCB: 0x64b180 - - DCB state: DCB for listening socket - - Service: Debug Service - - Queued write data: 0 - - Statistics: - - No. of Reads: 0 - - No. of Writes: 0 - - No. of Buffered Writes: 0 - - No. of Accepts: 1 - -DCB: 0x64b430 - - DCB state: DCB processing event - - Service: Split Service - - Connected to: 127.0.0.1 - - Queued write data: 0 - - Statistics: - - No. of Reads: 2 - - No. of Writes: 3 - - No. of Buffered Writes: 0 - - No. of Accepts: 0 - -DCB: 0x6f8400 - - DCB state: DCB in the polling loop - - Service: Split Service - - Queued write data: 0 - - Statistics: - - No. of Reads: 3 - - No. of Writes: 1 - - No. of Buffered Writes: 0 - - No. of Accepts: 0 - -DCB: 0x6f8b40 - - DCB state: DCB in the polling loop - - Service: Split Service - - Queued write data: 0 - - Statistics: - - No. of Reads: 2 - - No. of Writes: 0 - - No. of Buffered Writes: 0 - - No. of Accepts: 0 - -DCB: 0x6f8e20 - - DCB state: DCB processing event - - Service: Debug Service - - Connected to: 0.0.0.0 - - Queued write data: 0 - - Statistics: - - No. of Reads: 8 - - No. of Writes: 133 - - No. of Buffered Writes: 0 - - No. of Accepts: 0 - -**MaxScale>** - - - -An individual DCB can be displayed by passing the DCB address to the show dcb command - -**MaxScale>** show dcb 0x64b430 - -DCB: 0x64b430 - - DCB state: DCB processing event - - Connected to: 127.0.0.1 - - Owning Session: 7308208 - - Queued write data: 0 - - Statistics: - - No. of Reads: 2 - - No. of Writes: 3 - - No. of Buffered Writes: 0 - - No. of Accepts: 0 - -**MaxScale>** - -## Show Modules - -The show modules command will display the list of the currently loaded modules - -**MaxScale>** show modules - -Module Name | Module Type | Version - ------------------------------------------------------ - -MySQLBackend | Protocol | V2.0.0 - -telnetd | Protocol | V1.0.1 - -MySQLClient | Protocol | V1.0.0 - -mysqlmon | Monitor | V1.0.0 - -readconnroute | Router | V1.0.2 - -readwritesplit | Router | V1.0.2 - -debugcli | Router | V1.1.0 - -**MaxScale>** - -## Show Polling Statistics - -Display statistics related to the main polling loop. The epoll cycles is the count of the number of times epoll has returned with one or more event. The other counters are for each individual events that has been detected. - -**MaxScale>** show epoll - -Number of epoll cycles: 7928 - -Number of read events: 2000920 - -Number of write events: 2000927 - -Number of error events: 0 - -Number of hangup events: 0 - -Number of accept events: 4 - -**MaxScale>** - - - -## Show Dbusers - -The show dbuser command allows data regarding the table that holds the database users for a service to be displayed. It does not give the actual user data, but rather details of the hashtable distribution. - -The show dbuser command takes different arguments in the two modes of MariaDB MaxScale, in user mode it may be passed the name of a service rather than an address, whilst in developer mode it needs the address of a user structure that has been extracted from a service. - -In developer mode the show users commands must be passed the address of the user table, this can be extracted from the output of a show services command. - -**MaxScale>** show services - -Service 0x6ec910 - - Service: Split Service - - Router: readwritesplit (0x7ffff1698460) - - Number of router sessions: 1 - - Current no. of router sessions: 0 - - Number of queries forwarded: 2 - - Number of queries forwarded to master: 0 - - Number of queries forwarded to slave: 1 - - Number of queries forwarded to all: 1 - - Started: Mon Jul 22 11:31:21 2013 - - Backend databases - - 127.0.0.1:3308 Protocol: MySQLBackend - - 127.0.0.1:3307 Protocol: MySQLBackend - - 127.0.0.1:3306 Protocol: MySQLBackend - - Users data: 0x6ed9b0 - - Total connections: 2 - - Currently connected: 1 - -… - -The following example shows the MySQL users. - -Users are loaded with the host (IPv4 data) as they are created in the backend. - -**MaxScale>** show dbusers 0x6ed9b0 - -Users table data - -Hashtable: 0x19243a0, size 52 - - No. of entries: 16 - - Average chain length: 0.3 - - Longest chain length: 4 - -User names: one@%, new@192.168.56.1, new@127.0.0.1, repluser@%, seven@127.0.0.1, four@% - -**MaxScale>** - -In user mode the command is simply passed the name of the service - -**MaxScale>** show dbusers "Split Service" - -Users table data - -Hashtable: 0x19243a0, size 52 - - No. of entries: 16 - - Average chain length: 0.3 - - Longest chain length: 4 - -User names: one@%, new@192.168.56.1, new@127.0.0.1, repluser@%, seven@127.0.0.1, four@% - -**MaxScale>** - -Please note the use of quotes in the name in order to escape the white space character. - -## Show Users - -The show users command lists the users defined for the administration interface. Note that if there are no users defined, and the default admin user is in use, then no users will be displayed. - -**MaxScale> **show users - -Administration interface users: - -Users table data - -Hashtable: 0x25ef5e0, size 52 - - No. of entries: 2 - - Average chain length: 0.0 - - Longest chain length: 1 - -User names: admin, mark - -**MaxScale>** - -## Show Monitors - -The show monitors show the status of the database monitors. The address of the monitor can be used for the shutdown monitor and restart monitor commands. - -**MaxScale>** show monitors - -Monitor: 0x80a510 - - Name: MySQL Monitor - Monitor running - Sampling interval: 10000 milliseconds - Replication lag: enabled - Detect Stale Master: disabled - Connect Timeout: 3 seconds - Read Timeout: 1 seconds - Write Timeout: 2 seconds - Monitored servers: 127.0.0.1:3306, 127.0.0.1:3307, 127.0.0.1:3308, 127.0.0.1:3309 - -Monitor: 0x73d3d0 - - Name: Galera Monitor - Monitor running - Sampling interval: 7000 milliseconds - Master Failback: off - Connect Timeout: 3 seconds - Read Timeout: 1 seconds - Write Timeout: 2 seconds - Monitored servers: 127.0.0.1:3310, 127.0.0.1:3311, 127.0.0.1:3312 - -Monitor: 0x387b880 - - Name: NDB Cluster Monitor - Monitor running - Sampling interval: 8000 milliseconds - Connect Timeout: 3 seconds - Read Timeout: 1 seconds - Write Timeout: 2 seconds - Monitored servers: 127.0.0.1:3301, 162.243.90.81:3302 - -**MaxScale>** - -Monitor timeouts used in monitors follow the rules of mysql_real_connect C API: - -* Connect Timeout is the connect timeout in seconds. - -* Read Timeout is the timeout in seconds for each attempt to read from the server. There are retries if necessary, so the total effective timeout value is three times the option value. - -* Write Timeout is the timeout in seconds for each attempt to write to the server. There is a retry if necessary, so the total effective timeout value is two times the option value. - -## Shutdown MariaDB MaxScale - -The CLI can be used to shutdown the MariaDB MaxScale server by use of the shutdown command, it may be called with the argument either maxscale or gateway. - -**MaxScale>** shutdown maxscale - -## Shutdown monitor - -The shutdown monitor command stops the thread that is used to run the monitor and will stop any update of the server status flags. This is useful prior to manual setting of the states of the server using the set server and clear server commands. - -**MaxScale>** show monitors - -Monitor: 0x80a510 - - Name: MySQL Monitor - - Monitor running - -Sampling interval: 10000 milliseconds - - Monitored servers: 127.0.0.1:3306, 127.0.0.1:3307, 127.0.0.1:3308, 127.0.0.1:3309 - -**MaxScale>** shutdown monitor 0x80a510 - -**MaxScale>** show monitors - -Monitor: 0x80a510 - - Name: MySQL Monitor - - Monitor stopped - - Sampling interval: 10000 milliseconds - - Monitored servers: 127.0.0.1:3306, 127.0.0.1:3307, 127.0.0.1:3308, 127.0.0.1:3309 - -**MaxScale>** - -It may take some time before a monitor actually stops following the issuing of a shutdown monitor command. Stopped monitors can be restarted by issuing a restart monitor command. - -## Shutdown service - -The shutdown service command can be used to stop the listener for a particular service. This will prevent any new clients from using the service but will not terminate any clients already connected to the service. - -The shutdown service command needs the address of a service to be passed as an argument, this can be obtained by running show services. - -**MaxScale>** show services - -Service 0x6edc10 - - Service: Test Service - - Router: readconnroute (0x7ffff128ea40) - - Number of router sessions: 257 - - Current no. of router sessions: 0 - - Number of queries forwarded: 1000193 - - Started: Mon Jul 22 11:31:21 2013 - - Backend databases - - 127.0.0.1:3309 Protocol: MySQLBackend - - 127.0.0.1:3308 Protocol: MySQLBackend - - 127.0.0.1:3307 Protocol: MySQLBackend - - 127.0.0.1:3306 Protocol: MySQLBackend - - Users data: 0x6ee4b0 - - Total connections: 258 - - Currently connected: 1 - -Service 0x6ec910 - - Service: Split Service - - Router: readwritesplit (0x7ffff1698460) - - Number of router sessions: 1 - - Current no. of router sessions: 0 - - Number of queries forwarded: 2 - - Number of queries forwarded to master: 0 - - Number of queries forwarded to slave: 1 - - Number of queries forwarded to all: 1 - - Started: Mon Jul 22 11:31:21 2013 - - Backend databases - - 127.0.0.1:3308 Protocol: MySQLBackend - - 127.0.0.1:3307 Protocol: MySQLBackend - - 127.0.0.1:3306 Protocol: MySQLBackend - - Users data: 0x6ed9b0 - - Total connections: 2 - - Currently connected: 1 - -Service 0x649190 - - Service: Debug Service - - Router: debugcli (0x7ffff18a0620) - - Started: Mon Jul 22 11:31:21 2013 - - Backend databases - - Users data: 0x64bd80 - - Total connections: 2 - - Currently connected: 2 - -**MaxScale>** shutdown service 0x6edc10 - -In user mode the shutdown service command may be passed the name of the service as defined in configuration file. - -**MaxScale>** shutdown service Split\ Service - -## Restart service - -The restart service command can be used to restart a previously stopped listener for a service. In developer mode the address of the service must be passed. - -**MaxScale>** restart service 0x6edc10 - -**MaxScale>** - -In user mode the name of the service may be passed. - -**MaxScale>** restart service Test\ Service - -**MaxScale>** - -As with shutdown service the address of the service should be passed as an argument. - -## Restart Monitor - -The restart monitor command will restart a previously stopped monitor. - -**MaxScale> **show monitors - -Monitor: 0x80a510 - - Name: MySQL Monitor - - Monitor stopped - - Monitored servers: 127.0.0.1:3306, 127.0.0.1:3307, 127.0.0.1:3308, 127.0.0.1:3309 - -**MaxScale>** restart monitor 0x80a510 - -**MaxScale>** - -## Set server - -The set server command can be used to set the status flags of a server directly from the user interface. The command should be passed a server address that has been obtained from the output of a show servers command. - -**MaxScale>** show servers - -Server 0x6ec840 (server1) - - Server: 127.0.0.1 - - Status: Running - - Protocol: MySQLBackend - - Port: 3306 - - Server Version: 10.0.11-MariaDB-log - - Node Id: 29 - - Number of connections: 0 - - Current n. of conns: 0 - -Server 0x6ec770 (server2) - - Server: 127.0.0.1 - - Status: Master, Running - - Protocol: MySQLBackend - - Port: 3307 - - Server Version: 5.5.35-MariaDB-log - - Node Id: 1 - - Number of connections: 1 - - Current n. of conns: 0 - -Server 0x6ec6a0 (server3) - - Server: 127.0.0.1 - - Status: Slave, Running - - Protocol: MySQLBackend - - Port: 3308 - - Server Version: 5.5.35-MariaDB-log - - Node Id: 2 - - Number of connections: 258 - - Current n. of conns: 0 - -Server 0x6ec5d0 (server4) - - Server: 127.0.0.1 - - Status: Down - - Protocol: MySQLBackend - - Port: 3309 - - Node Id: -1 - - Number of connections: 0 - - Current n. of conns: 0 - -**MaxScale>** set server 0x6ec840 slave - -Valid options that are recognized by the set server command are running, master and slave. Please note that if the monitor is running it will reset the flags to match reality, this interface is really for use when the monitor is disabled. - -In user mode there is no need to find the address of the server structure, the name of the server from the section header in the configuration file make be given. - -**MaxScale>** set server server1 slave - - - -## Clear server - -The clear server command is the complement to the set server command, it allows status bits related to a server to be cleared. - -**MaxScale>** clear server 0x6ec840 slave - -Likewise in user mode the server name may be given. - -**MaxScale>** clear server server1 slave - -## Reload users - -The reload users command is used to force a service to go back and reload the table of database users from the backend database. This is the data used in the transparent authentication mechanism in the MySQL protocol. The command should be passed the address of the service as shown in the output of the show services command. - -**MaxScale>** show services - -Service 0x6edc10 - - Service: Test Service - - Router: readconnroute (0x7ffff128ea40) - - Number of router sessions: 257 - - Current no. of router sessions: 0 - - Number of queries forwarded: 1000193 - - Started: Mon Jul 22 11:31:21 2013 - - Backend databases - - 127.0.0.1:3309 Protocol: MySQLBackend - - 127.0.0.1:3308 Protocol: MySQLBackend - - 127.0.0.1:3307 Protocol: MySQLBackend - - 127.0.0.1:3306 Protocol: MySQLBackend - - Users data: 0x6ee4b0 - - Total connections: 258 - - Currently connected: 1 - -Service 0x6ec910 - - Service: Split Service - - Router: readwritesplit (0x7ffff1698460) - - Number of router sessions: 1 - - Current no. of router sessions: 0 - - Number of queries forwarded: 2 - - Number of queries forwarded to master: 0 - - Number of queries forwarded to slave: 1 - - Number of queries forwarded to all: 1 - - Started: Mon Jul 22 11:31:21 2013 - - Backend databases - - 127.0.0.1:3308 Protocol: MySQLBackend - - 127.0.0.1:3307 Protocol: MySQLBackend - - 127.0.0.1:3306 Protocol: MySQLBackend - - Users data: 0x6ed9b0 - - Total connections: 2 - - Currently connected: 1 - -Service 0x649190 - - Service: Debug Service - - Router: debugcli (0x7ffff18a0620) - - Started: Mon Jul 22 11:31:21 2013 - - Backend databases - - Users data: 0x64bd80 - - Total connections: 2 - - Currently connected: 2 - -**MaxScale>** reload users 0x6edc10 - -Loaded 34 users. - -**MaxScale>** - -If user mode is in use then the service name may be given. - -**MaxScale>** reload users "Test Service" - -Loaded 34 users. - - **MaxScale>** - -## Reload config - -The reload config command can be used to force MariaDB MaxScale to re-read the maxscale.cnf and update itself to the latest configuration defined in that configuration file. It is also possible to force the reading of the configuration file by sending a HangUp signal (SIGHUP) to the maxscale process. - -**MaxScale>** reload config - -Reloading configuration from file. - -**MaxScale>** - -Note, not all configuration elements can be changed dynamically currently. This mechanism can be used to add new services, servers to services, listeners to services and to update passwords. It can not be used to remove services, servers or listeners currently. - -## Add user - -The add user command is used to add new users to the debug CLI of MariaDB MaxScale. The default behavior of the CLI for MariaDB MaxScale is to have a login name of admin and a fixed password of mariadb. Adding new users will disable this default behavior and limit the login access to the users that are added. - -**MaxScale>** add user admin july2013 - -User admin has been successfully added. - -**MaxScale>** add user mark hambleden - -User mark has been successfully added. - -**MaxScale>** - -User names must be unique within the debug CLI, this excludes the admin default user, which may be redefined. - -**MaxScale>** add user mark 22july - -User admin already exists. - -**MaxScale>**** ** - -If you should forget or lose the the account details you may simply remove the passwd file in /var/cache/maxscale and the system will revert to the default behavior with admin/mariadb as the account. - -## Enable/disable log - -The enable/disable log command is used to enable/disable the log facility of MariaDB MaxScale. The default behavior for MariaDB MaxScale is to have all logs enabled in DEBUG version, and only error log in production release. - -Examples: - -**MaxScale>** help enable log - -Available options to the enable command: - - log Enable Log options for MaxScale, options trace | error | message E.g. enable log message. - -**MaxScale>** help disable log - -Available options to the disable command: - - log Disable Log for MaxScale, Options: debug | trace | error | message E.g. disable log debug - -**MaxScale>** disable log trace - -**MaxScale>** - -No output for these commands in the debug interface, but in the affected logs there is a message: - -2013 11/14 16:08:33 --- Logging is disabled -- - -# Logging facility - -MariaDB MaxScale generates output of its behavior to four distinct logs, error, messages, trace and debug log. Error and message logs are enabled by default but all logs can be dynamically enabled and disabled by using maxadmin utility, debug client interface (telnet) or optionally by using your own application through the client API. - -## Log contents - -By default all log files are located in : /var/log/maxscale and named as : - -skygw_errW.log, skygw_msgX.log, skygw_traceY.log and skygw_debugZ.log - -where W, X, Y, and Z are sequence numbers for files within the same directory, - -### Error log - -Error log includes errors and warnings; things that occur during runtime and of which the user should at least be aware of. An entry in error log doesn’t necessarily mean a problem - it may be a notification of failed backend server, for example. - -Example: - -MariaDB Corporation MaxScale /home/jdoe/bin/develop/log/skygw_err1.log Mon Dec 8 13:28:15 2014 - ------------------------------------------------------------------------ - ---- Logging is enabled. - -2014-12-08 13:28:15 Error : Unable to find filter 'testfi' for service 'RW Split Router' - -2014-12-08 13:28:26 MaxScale received signal SIGINT. Shutting down. - -2014-12-08 13:28:27 MaxScale is shut down. - ------------------------------------------------------------------------ - -### Message log - -The content of message log consists of information about loaded modules, opened listen ports and other information about file locations etc. The amount of data written in message log is typically very small. - -Example: - -MariaDB Corporation MaxScale /home/jdoe/bin/develop/log/skygw_msg1.log Tue Dec 9 14:47:05 2014 - ------------------------------------------------------------------------ - ---- Logging is enabled. - -2014-12-09 14:47:05 Home directory : /home/jdoe/bin/develop - -2014-12-09 14:47:05 Data directory : /home/jdoe/bin/develop/data/data5398 - -2014-12-09 14:47:05 Log directory : /home/jdoe/bin/develop/log - -2014-12-09 14:47:05 Configuration file : /home/jdoe/bin/develop/etc/maxscale.cnf - -2014-12-09 14:47:05 Initialise CLI router module V1.0.0. - -2014-12-09 14:47:05 Loaded module cli: V1.0.0 from /home/jdoe/bin/develop/modules/libcli.so - -2014-12-09 14:47:05 Initialise debug CLI router module V1.1.1. - -2014-12-09 14:47:05 Loaded module debugcli: V1.1.1 from /home/jdoe/bin/develop/modules/libdebugcli.so - -2014-12-09 14:47:05 Loaded module testroute: V1.0.0 from /home/jdoe/bin/develop/modules/libtestroute.so - -2014-12-09 14:47:05 Initialise readconnroute router module V1.1.0. - -2014-12-09 14:47:05 Loaded module readconnroute: V1.1.0 from /home/jdoe/bin/develop/modules/libreadconnroute.so - -2014-12-09 14:47:05 Initializing statemend-based read/write split router module. - -2014-12-09 14:47:05 Loaded module readwritesplit: V1.0.2 from /home/jdoe/bin/develop/modules/libreadwritesplit.so - -2014-12-09 14:47:05 Initialise the MySQL Monitor module V1.4.0. - -2014-12-09 14:47:05 Loaded module mysqlmon: V1.4.0 from /home/jdoe/bin/develop/modules/libmysqlmon.so - -2014-12-09 14:47:05 MariaDB Corporation MaxScale 1.0.1-beta (C) MariaDB Corporation Ab 2013-2014 - -2014-12-09 14:47:05 MaxScale is running in process 5398 - -2014-12-09 14:47:05 Encrypted password file /home/jdoe/bin/develop/etc/.secrets can't be accessed (No such file or directory). Password encryption is not used. - -2014-12-09 14:47:05 Loaded 6 MySQL Users for service [RW Split Router]. - -2014-12-09 14:47:05 Loaded module MySQLClient: V1.0.0 from /home/jdoe/bin/develop/modules/libMySQLClient.so - -2014-12-09 14:47:05 Loaded 8 MySQL Users for service [Read Connection Router]. - -2014-12-09 14:47:05 Loaded module telnetd: V1.0.1 from /home/jdoe/bin/develop/modules/libtelnetd.so - -2014-12-09 14:47:05 Loaded module maxscaled: V1.0.0 from /home/jdoe/bin/develop/modules/libmaxscaled.so - -2014-12-09 14:47:05 Info: A Master Server is now available: 127.0.0.1:3000 - -2014-12-09 14:47:10 MaxScale is shut down. - ------------------------------------------------------------------------ - -### Trace log - -Trace log includes information about available servers and their states, client sessions, queries being executed, routing decisions and other routing related data. Trace log can be found from the same directory with other logs but it is physically stored elsewhere, to OS's shared memory to reduce the latency caused by logging. The location of physical file is : /dev/shm//skygw_traceX.log where ‘X’ is the same sequence number as in the file name in the /var/log/maxscale directory. - -Individual trace log entry looks similar to those in other logs but there is some difference too. Some log entries include a number within square brackets to specify which client session they belong to. For example: - -2014-12-09 14:52:36 [6] Session write, routing to all servers. - -Writing trace log for each client may produce so much data that it seriously affects on the performance of MariaDB MaxScale. It may also be difficult to follow a specific session if the log is flooded with data from other sessions. While it is possible to dynamically enable and disable trace log as a whole, one can also choose to explicitly enable trace logging for a specific session by first enabling trace log, finding out the session id of the interesting session, disabling trace log and finally enabling trace log only for a given session: - -1. enable log trace (and examine the session id) - -2. disable log trace - -3. enable sessionlog trace - -Example of trace log: - -MariaDB Corporation MaxScale /dev/shm/5420/skygw_trace1.log Tue Dec 9 14:51:29 2014 - ------------------------------------------------------------------------ - ---- Logging is disabled. - -2014-12-09 14:51:52 --- Logging is enabled -- - -2014-12-09 14:52:03 Servers and router connection counts: - -2014-12-09 14:52:03 current operations : 0 in 127.0.0.1:3003 RUNNING SLAVE - -2014-12-09 14:52:03 current operations : 0 in 127.0.0.1:3002 RUNNING SLAVE - -2014-12-09 14:52:03 current operations : 0 in 127.0.0.1:3000 RUNNING MASTER - -2014-12-09 14:52:03 Selected RUNNING SLAVE in 127.0.0.1:3003 - -2014-12-09 14:52:03 Selected RUNNING SLAVE in 127.0.0.1:3002 - -2014-12-09 14:52:03 Selected RUNNING MASTER in 127.0.0.1:3000 - -... - -2014-12-09 14:52:28 [6] > Autocommit: [enabled], trx is [not open], cmd: COM_QUERY, type: QUERY_TYPE_READ, stmt: select count(*) from user - -2014-12-09 14:52:28 [6] Route query to slave 127.0.0.1:3003 < - -2014-12-09 14:52:36 [6] Disable autocommit : implicit START TRANSACTION before executing the next command. - -2014-12-09 14:52:36 [6] > Autocommit: [disabled], trx is [open], cmd: COM_QUERY, type: QUERY_TYPE_GSYSVAR_WRITE|QUERY_TYPE_BEGIN_TRX|QUERY_TYPE_DISABLE_AUTOCOMMIT, stmt: set autocommit=0 - -2014-12-09 14:52:36 [6] Session write, routing to all servers. - -2014-12-09 14:52:36 [6] Route query to slave 127.0.0.1:3003 - -2014-12-09 14:52:36 [6] Route query to slave 127.0.0.1:3002 - -2014-12-09 14:52:36 [6] Route query to master 127.0.0.1:3000 < - -2014-12-09 14:52:39 [6] > Autocommit: [disabled], trx is [open], cmd: COM_QUERY, type: QUERY_TYPE_BEGIN_TRX, stmt: begin - -2014-12-09 14:52:39 [6] Route query to master 127.0.0.1:3000 < - -2014-12-09 14:52:51 [6] > Autocommit: [disabled], trx is [open], cmd: COM_QUERY, type: QUERY_TYPE_READ, stmt: select count(*) from user - -2014-12-09 14:52:51 [6] Route query to master 127.0.0.1:3000 < - -2014-12-09 14:52:59 Servers and router connection counts: - -2014-12-09 14:52:59 current operations : 0 in 127.0.0.1:3003 RUNNING SLAVE - -2014-12-09 14:52:59 current operations : 0 in 127.0.0.1:3002 RUNNING SLAVE - -2014-12-09 14:52:59 current operations : 0 in 127.0.0.1:3000 RUNNING MASTER - -2014-12-09 14:52:59 Selected RUNNING SLAVE in 127.0.0.1:3003 - -2014-12-09 14:52:59 Selected RUNNING SLAVE in 127.0.0.1:3002 - -2014-12-09 14:52:59 Selected RUNNING MASTER in 127.0.0.1:3000 - -2014-12-09 14:52:59 Started RW Split Router client session [7] for 'maxuser' from 127.0.0.1 - -In the log, session’s life cycle is covered by annotating its beginning and the end. During the session, each statement is surrounded with ‘>’ and ‘<’ characters. Entries without ‘[]’ belong to other than client sessions, monitor, for example. - -## Managing logs - -The log files are located in - -/var/log/maxscale - -by default. If, however, trace and debug logs are enabled, only a soft link is created there. MariaDB MaxScale process creates a directory under - -/dev/shm/maxscale. - -where it stores the physical trace and debug log files. Link and physical files share the same name. These logs consume the main memory of the host they run on so it is important to archive or remove them periodically to avoid unnecessary main-memory consumption. - -## Rotating logs - -Log files may grow very large over time and that is why users may want to split log files into several smaller ones. That is called log rotation. User can rotate all logs by executing - -flush logs - -Specific log file can be rotated by executing - -flush log [error|message|trace|debug] - -The commands above can be executed either by using maxadmin utility or via debug client API with telnet. The sequence number included in the log filename is used to separate files from each other. The logic behind sequence numbering is such that if the log directory is empty when MariaDB MaxScale is started, new log files will be created with sequence number 1 in their names, skygw_err1.log, for example. If files of the same type already exist, the new MariaDB MaxScale process opens the file with largest sequence number and applies into it. If existing log file isn’t writable for the user that MariaDB MaxScale runs on, new log file will be created with bigger sequence number. - -More information about log files and administering them can be found from **MaxScale Administration Tutorial**. - diff --git a/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 d9a1e2bb4..1def7ffb8 100644 --- a/Documentation/Reference/MaxAdmin.md +++ b/Documentation/Reference/MaxAdmin.md @@ -330,34 +330,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 @@ -365,54 +459,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> ``` @@ -431,16 +549,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> ``` @@ -450,16 +567,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> ``` @@ -471,23 +587,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 @@ -502,9 +632,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 @@ -517,8 +648,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> ``` @@ -530,8 +661,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 @@ -539,7 +670,7 @@ MaxScale> A stopped service may be restarted by using the _restart service_ command. ``` -MaxScale> restart service "Split Service" +MaxScale> restart service RWSplit MaxScale> ``` @@ -556,15 +687,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 @@ -574,17 +705,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 @@ -636,6 +770,7 @@ format described below in the DCB section) with a command like: ``` MaxScale> show persistent server1 +Number of persistent DCBs: 0 ``` # Working With Sessions @@ -653,38 +788,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 @@ -693,14 +807,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 @@ -722,20 +837,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 @@ -752,28 +870,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 @@ -831,58 +970,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 @@ -902,12 +1021,12 @@ command. ``` MaxScale> list monitors -+----------------------+--------------------- -| Monitor | Status -+----------------------+--------------------- -| MySQL Monitor | Running -+----------------------+--------------------- -MaxScale> +---------------------+--------------------- +Monitor | Status +---------------------+--------------------- +MySQL-Monitor | Running +---------------------+--------------------- +MaxScale> ``` ## Details Of A Particular Monitor @@ -915,62 +1034,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 @@ -980,14 +1099,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 @@ -996,16 +1115,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 @@ -1024,17 +1141,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 @@ -1043,27 +1164,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 @@ -1074,8 +1174,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 @@ -1088,23 +1188,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 @@ -1142,14 +1244,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> ``` @@ -1205,7 +1305,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 @@ -1213,10 +1315,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 @@ -1228,20 +1336,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 @@ -1255,14 +1364,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 @@ -1273,14 +1385,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 @@ -1294,8 +1409,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 @@ -1309,9 +1430,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 @@ -1321,9 +1443,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 @@ -1341,16 +1468,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) @@ -1364,6 +1490,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 @@ -1374,9 +1502,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 @@ -1389,11 +1524,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 @@ -1402,13 +1541,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 @@ -1419,9 +1571,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 @@ -1433,6 +1592,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. @@ -1441,6 +1612,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. @@ -1505,31 +1691,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 @@ -1548,46 +1738,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/Reference/MaxBinlogCheck.md b/Documentation/Reference/MaxBinlogCheck.md index 9210f379a..e55f813f9 100644 --- a/Documentation/Reference/MaxBinlogCheck.md +++ b/Documentation/Reference/MaxBinlogCheck.md @@ -1,24 +1,21 @@ -# Maxbinlogcheck - -# The MySQL/MariaDB binlog check utility - -Massimiliano Pinto - -Last Updated: 07th December 2016 +# Maxbinlogcheck, the MySQL/MariaDB binlog check utility # Overview -Maxbinlogcheck is a command line utility for checking binlogfiles downloaded by MariaDB MaxScale binlog router or the MySQL/MariaDB binlog files stored in a database server acting as a master in a replication environment. -It checks the binlog file against any corruption and incomplete transaction stored and reports a transaction summary after reading all the events. -It may optionally truncate binlog file. +Maxbinlogcheck is a command line utility for checking binlogfiles. The files may +have been downloaded by the MariaDB MaxScale binlog router or they may be +MySQL/MariaDB binlog files stored in a database server acting as a master in a +replication environment. Maxbinlogcheck checks the binlog files against any +corruption and stored incomplete transactions and reports a transaction summary +after reading all the events. It may optionally truncate the binlog file. -Maxbinlogcheck supports +Maxbinlogcheck supports: * MariaDB 5.5 and MySQL 5.6 - * MariaDB 10.0 and 10.1 with a command line option # Running maxbinlogcheck + ``` # /usr/local/bin/maxbinlogcheck /path_to_file/bin.000002 ``` @@ -34,29 +31,29 @@ The maxbinlogcheck command accepts a number of switches Description - -f - --fix - If the option is set the binlog file will be truncated at last safe transaction pos in case of any error + -f --fix If set the binlog file will be truncated at + last safe transaction pos in case of any error -M --mariadb10 - Check the current binlog against MariaDB 10.0.x events + Checks the current binlog against MariaDB 10.0.x events -d --debug - Set the debug mode. If set the FD Events, Rotate events and opening/closing transactions are displayed. + Sets the debug mode. If set the FD Events, Rotate events and + opening/closing transactions are displayed. -? --help - Print usage information regarding maxbinlogcheck + Prints usage information regarding maxbinlogcheck -V --version - Print the maxbinlogcheck version information + Prints the maxbinlogcheck version information -K @@ -66,12 +63,13 @@ The maxbinlogcheck command accepts a number of switches -A --aes_algo - AES Algorithm for MariaDB 10.1 binlog file decryption (default=AES_CBC, AES_CTR) + AES Algorithm for MariaDB 10.1 binlog file decryption (default=AES_CBC, + AES_CTR) -H --header - Print the binlog event header + Prints the binlog event header @@ -175,7 +173,7 @@ The maxbinlogcheck command accepts a number of switches This file is corrupted, as reported by the utility: ``` -[root@maxscale-02 build]# /usr/local/bin/maxbinlogcheck /servers/binlogs/new-trx/bin.000002 +[root@maxscale-02 build]# /usr/local/bin/maxbinlogcheck /servers/binlogs/new-trx/bin.000002 2015-09-08 10:03:16 maxbinlogcheck 1.0.0 2015-09-08 10:03:16 Checking /servers/binlogs/new-trx/bin.000002 (bin.000002), size 109498 bytes 2015-09-08 10:03:16 Event size error: size 0 at 290. @@ -183,7 +181,7 @@ This file is corrupted, as reported by the utility: 2015-09-08 10:03:16 Check retcode: 1, Binlog Pos = 245 ``` -The suggested safe pos is 245 +The suggested safe pos is 245. Use -f option for fix with debug: @@ -205,7 +203,7 @@ Use -f option for fix with debug: Check it again, last pos will be 245 and no errors will be reported: ``` -[root@maxscale-02 build]# /usr/local/bin/maxbinlogcheck /servers/binlogs/new-trx/bin.000002 -d +[root@maxscale-02 build]# /usr/local/bin/maxbinlogcheck /servers/binlogs/new-trx/bin.000002 -d 2015-09-08 09:56:56 maxbinlogcheck 1.0.0 2015-09-08 09:56:56 Checking /servers/binlogs/new-trx/bin.000002 (bin.000002), size 245 bytes 2015-09-08 09:56:56 - Format Description event FDE @ 4, size 241 @@ -281,8 +279,10 @@ And finally big transaction is now done. 2015-09-08 10:17:16 Check retcode: 0, Binlog Pos = 590760698 ``` -**Note** -with current maxbinlogcheck it's not possible to fix a binlog with incomplete transaction and no other errors +**Note** + +With current maxbinlogcheck it's not possible to fix a binlog with incomplete +transaction and no other errors If that is really desired it will be possible with UNIX command line: @@ -363,8 +363,8 @@ Check result: Key File content example: /var/binlogs/key_file.txt First two bytes are: the encryption scheme, it must be 1, and the ';' separator. -Following bytes are the HEX representation of the key (length must be 16, 24 or 32). -The example shows a 32 bytes key in HEX format (64 bytes): +Following bytes are the HEX representation of the key (length must be 16, 24 or +32). The example shows a 32 bytes key in HEX format (64 bytes): ``` 1;666f6f62617220676f657320746f207468652062617220666f7220636f66666565 diff --git a/Documentation/Reference/Module-Commands.md b/Documentation/Reference/Module-Commands.md index 624ad0af8..b4377b9bf 100644 --- a/Documentation/Reference/Module-Commands.md +++ b/Documentation/Reference/Module-Commands.md @@ -1,14 +1,13 @@ # Module commands Introduced in MaxScale 2.1, the module commands are special, module-specific -commands. They allow the modules to expand beyond the capabilities of the -module API. Currently, only MaxAdmin implements an interface to the module -commands. +commands. They allow the modules to expand beyond the capabilities of the module +API. Currently, only MaxAdmin implements an interface to the module commands. All registered module commands can be shown with `maxadmin list commands` and they can be executed with `maxadmin call command ARGS...` where -__ is the name of the module and __ is the name of the -command. _ARGS_ is a command specific list of arguments. +__ is the name of the module and __ is the name of the command. +_ARGS_ is a command specific list of arguments. ## Developer reference @@ -16,7 +15,8 @@ The module command API is defined in the _modulecmd.h_ header. It consists of various functions to register and call module commands. Read the function documentation in the header for more details. -The following example registers the module command _my_command_ for module _my_module_. +The following example registers the module command _my_command_ for module +_my_module_. ``` #include @@ -53,9 +53,9 @@ int main(int argc, char **argv) } ``` -The array of _modulecmd_arg_type_t_ type is used to tell what kinds of arguments -the command expects. The first argument is a SERVER which will be replaced with a -pointer to a server. The second argument is an optional string argument. +The array _my_args_ of type _modulecmd_arg_type_t_ is used to tell what kinds of +arguments the command expects. The first argument is a boolean and the second +argument is an optional string. Arguments are passed to the parsing function as an array of void pointers. They are interpreted as the types the command expects. diff --git a/Documentation/Release-Notes/MaxScale-2.1.3-Release-Notes.md b/Documentation/Release-Notes/MaxScale-2.1.3-Release-Notes.md new file mode 100644 index 000000000..430931d20 --- /dev/null +++ b/Documentation/Release-Notes/MaxScale-2.1.3-Release-Notes.md @@ -0,0 +1,69 @@ +# MariaDB MaxScale 2.1.3 Release Notes + +Release 2.1.3 is a GA release. + +This document describes the changes in release 2.1.3, when compared to +release [2.1.2](MaxScale-2.1.2-Release-Notes.md). + +If you are upgrading from release 2.0, please also read the following +release notes: +[2.1.2](./MaxScale-2.1.2-Release-Notes.md) +[2.1.1](./MaxScale-2.1.1-Release-Notes.md) +[2.1.0](./MaxScale-2.1.0-Release-Notes.md) + +For any problems you encounter, please consider submitting a bug +report at [Jira](https://jira.mariadb.org). + +## MariaDB 10.2 + +MaxScale 2.1 has not been extended to understand all new features that +MariaDB 10.2 introduces. Please see +[Support for 10.2](About/Support-for-10.2.md) +for details. + +## Changed Features + +### Cache + +* The storage `storage_rocksdb` is no longer built by default and is + not included in the MariaDB MaxScale package. + +### Maxrows + +* It can now be specified whether the _maxrows_ filter should return an + empty resultset, an error packet or an ok packet, when the limit has + been reached. + + Please refer to the + [maxrows documentation](../Filters/Maxrows.md) + for details. + +## Bug fixes + +[Here is a list of bugs fixed since the release of MaxScale 2.1.2.](https://jira.mariadb.org/browse/MXS-1212?jql=project%20%3D%20MXS%20AND%20issuetype%20%3D%20Bug%20AND%20resolution%20in%20(Fixed%2C%20Done)%20AND%20fixVersion%20%3D%202.1.3) + +* [MXS-1227](https://jira.mariadb.org/browse/MXS-1227) Nagios Plugins broken by change in output of "show monitors" in 2.1 +* [MXS-1221](https://jira.mariadb.org/browse/MXS-1221) Nagios plugin scripts does not process -S option properly +* [MXS-1212](https://jira.mariadb.org/browse/MXS-1212) Excessive execution time when maxrows limit has been reached +* [MXS-1202](https://jira.mariadb.org/browse/MXS-1202) maxadmin "show service" counters overflow +* [MXS-1200](https://jira.mariadb.org/browse/MXS-1200) config file lines limited to ~1024 chars + +## Known Issues and Limitations + +There are some limitations and known issues within this version of MaxScale. +For more information, please refer to the [Limitations](../About/Limitations.md) document. + +## Packaging + +RPM and Debian packages are provided for the Linux distributions supported +by MariaDB Enterprise. + +Packages can be downloaded [here](https://mariadb.com/resources/downloads). + +## Source Code + +The source code of MaxScale is tagged at GitHub with a tag, which is identical +with the version of MaxScale. For instance, the tag of version X.Y.Z of MaxScale +is X.Y.Z. Further, *master* always refers to the latest released non-beta version. + +The source code is available [here](https://github.com/mariadb-corporation/MaxScale). diff --git a/Documentation/Routers/Avrorouter.md b/Documentation/Routers/Avrorouter.md index c436071aa..8434f7c9f 100644 --- a/Documentation/Routers/Avrorouter.md +++ b/Documentation/Routers/Avrorouter.md @@ -271,8 +271,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/CLI.md b/Documentation/Routers/CLI.md index 5d088e1fd..48a4a232b 100644 --- a/Documentation/Routers/CLI.md +++ b/Documentation/Routers/CLI.md @@ -1,13 +1,13 @@ # CLI -The command line interface as used by `maxadmin`. The _CLI_ router requires the use -of the `maxscaled` protocol. +The command line interface as used by `maxadmin`. The _CLI_ router requires the +use of the `maxscaled` protocol. ## Configuration -Two components are required in order to run the command line interface for use with -_maxadmin_; a service and a listener. The listener may either use a Unix domain socket -or an internet socket. +Two components are required to run the command line interface for _maxadmin_; a +service and a listener. The listener may either use a Unix domain socket or an +internet socket. The default entries required are shown below. @@ -31,19 +31,20 @@ protocol=maxscaled address=localhost port=6603 ``` + In the example above, two listeners have been specified; one that listens on the -default Unix domain socket and one that listens on the default port. In the latter -case, if the `address=` entry is removed, connections are allowed from any machine -on your network. +default Unix domain socket and one that listens on the default port. In the +latter case, if the `address=` entry is removed, connections are allowed from +any machine on your network. In the former case, if the value of `socket` is changed and in the latter case, if the value of `port` is changed, _maxadmin_ must be invoked with the `-S` and -`-P` options respectively. +`-P` options, respectively. -Note that if Unix domain sockets are used, the connection is secure, but _maxadmin_ -can only be used on the same host where MariaDB MaxScale runs. If internet sockets -are used, the connection is _inherently insecure_ but _maxadmin_ can be used from -another host than the one where MariaDB MaxScale runs. +If Unix domain sockets are used, the connection is secure, but _maxadmin_ can +only be used on the same host where MariaDB MaxScale runs. If internet sockets +are used, the connection is _inherently insecure_ but _maxadmin_ can be used +from another host than the one where MariaDB MaxScale runs. Note that the latter approach is **deprecated** and will be removed in a future version of MariaDB MaxScale. 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/ReadWriteSplit.md b/Documentation/Routers/ReadWriteSplit.md index 5ede6413b..f4c22b4dd 100644 --- a/Documentation/Routers/ReadWriteSplit.md +++ b/Documentation/Routers/ReadWriteSplit.md @@ -1,54 +1,78 @@ # Readwritesplit -This document provides a short overview of the **readwritesplit** router module and its intended use case scenarios. It also displays all router configuration parameters with their descriptions. A list of current limitations of the module is included and examples of the router's use are provided. +This document provides a short overview of the **readwritesplit** router module +and its intended use case scenarios. It also displays all router configuration +parameters with their descriptions. A list of current limitations of the module +is included and use examples are provided. ## Overview -The **readwritesplit** router is designed to increase the read-only processing capability of a cluster while maintaining consistency. This is achieved by splitting the query load into read and write queries. Read queries, which do not modify data, are spread across multiple nodes while all write queries will be sent to a single node. +The **readwritesplit** router is designed to increase the read-only processing +capability of a cluster while maintaining consistency. This is achieved by +splitting the query load into read and write queries. Read queries, which do not +modify data, are spread across multiple nodes while all write queries will be +sent to a single node. -The router is designed to be used with a traditional Master-Slave replication cluster. It automatically detects changes in the master server and will use the current master server of the cluster. With a Galera cluster, one can achieve a resilient setup and easy master failover by using one of the Galera nodes as a Write-Master node, where all write queries are routed, and spreading the read load over all the nodes. +The router is designed to be used with a traditional Master-Slave replication +cluster. It automatically detects changes in the master server and will use the +current master server of the cluster. With a Galera cluster, one can achieve a +resilient setup and easy master failover by using one of the Galera nodes as a +Write-Master node, where all write queries are routed, and spreading the read +load over all the nodes. ## Configuration -Readwritesplit router-specific settings are specified in the configuration file of MariaDB MaxScale in its specific section. The section can be freely named but the name is used later as a reference from listener section. +Readwritesplit router-specific settings are specified in the configuration file +of MariaDB MaxScale in its specific section. The section can be freely named but +the name is used later as a reference in a listener section. -For more details about the standard service parameters, refer to the [Configuration Guide](../Getting-Started/Configuration-Guide.md). +For more details about the standard service parameters, refer to the +[Configuration Guide](../Getting-Started/Configuration-Guide.md). ## Optional parameters ### `max_slave_connections` -**`max_slave_connections`** sets the maximum number of slaves a router session uses at any moment. The default is to use all available slaves. +**`max_slave_connections`** sets the maximum number of slaves a router session +uses at any moment. The default is to use all available slaves. max_slave_connections= ### `max_slave_replication_lag` -**`max_slave_replication_lag`** specifies how many seconds a slave is allowed to be behind the master. If the lag is bigger than configured value a slave can't be used for routing. + +**`max_slave_replication_lag`** specifies how many seconds a slave is allowed to +be behind the master. If the lag is bigger than the configured value a slave +can't be used for routing. This feature is disabled by default. max_slave_replication_lag= -This applies to Master/Slave replication with MySQL monitor and `detect_replication_lag=1` options set. -Please note max_slave_replication_lag must be greater than monitor interval. +This applies to Master/Slave replication with MySQL monitor and +`detect_replication_lag=1` options set. max_slave_replication_lag must be +greater than the monitor interval. This option only affects Master-Slave clusters. Galera clusters do not have a concept of slave lag even if the application of write sets might have lag. - ### `use_sql_variables_in` -**`use_sql_variables_in`** specifies where should queries, which read session variable, be routed. The syntax for `use_sql_variable_in` is: +**`use_sql_variables_in`** specifies where should queries, which read session +variable, be routed. The syntax for `use_sql_variable_in` is: use_sql_variables_in=[master|all] The default is to use SQL variables in all servers. -When value all is used, queries reading session variables can be routed to any available slave (depending on selection criteria). Note, that queries modifying session variables are routed to all backend servers by default, excluding write queries with embedded session variable modifications, such as: +When value `all` is used, queries reading session variables can be routed to any +available slave (depending on selection criteria). Queries modifying session +variables are routed to all backend servers by default, excluding write queries +with embedded session variable modifications, such as: INSERT INTO test.t1 VALUES (@myid:=@myid+1) -In above-mentioned case the user-defined variable would only be updated in the master where query would be routed due to `INSERT` statement. +In above-mentioned case the user-defined variable would only be updated in the +master where the query would be routed to due to the `INSERT` statement. **Note:** As of version 2.1 of MaxScale, all of the router options can also be defined as parameters. The values defined in _router_options_ will have priority @@ -83,21 +107,30 @@ for a long time. ## Router options -**`router_options`** may include multiple **readwritesplit**-specific options. All the options are parameter-value pairs. All parameters listed in this section must be configured as a value in `router_options`. +**`router_options`** may include multiple **readwritesplit**-specific options. +All the options are parameter-value pairs. All parameters listed in this section +must be configured as a value in `router_options`. -Multiple options can be defined as a comma-separated list of parameter-value pairs. +Multiple options can be defined as a comma-separated list of parameter-value +pairs. ``` router_options=