diff --git a/Documentation/Filters/CCRFilter.md b/Documentation/Filters/CCRFilter.md index b900ec2f7..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 an 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/RabbitMQ-Filter.md b/Documentation/Filters/RabbitMQ-Filter.md index 83f5da6a7..3fd5e7ee9 100644 --- a/Documentation/Filters/RabbitMQ-Filter.md +++ b/Documentation/Filters/RabbitMQ-Filter.md @@ -2,13 +2,25 @@ ## 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 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. +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] @@ -42,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 c0a1e3d47..8e1155351 100644 --- a/Documentation/Filters/Tee-Filter.md +++ b/Documentation/Filters/Tee-Filter.md @@ -2,11 +2,16 @@ ## Overview -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. +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 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 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 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. +Set up a service in MariaDB MaxScale, called Orders, to communicate with the +order processing system with the tee filter applied to it. Also set up a service +to talk to the datamart server, using the DataMart service. The tee filter would +have as it’s service entry the DataMart service, by adding a match parameter of +"insert into orders" would then result in all requests being sent to the order +processing system, and insert statements that include the orders table being +additionally sent to the datamart server. ``` [Orders] diff --git a/Documentation/Getting-Started/Configuration-Guide.md b/Documentation/Getting-Started/Configuration-Guide.md index ec3eefd51..15f47bbc6 100644 --- a/Documentation/Getting-Started/Configuration-Guide.md +++ b/Documentation/Getting-Started/Configuration-Guide.md @@ -2,11 +2,10 @@ ## Introduction -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. +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 @@ -48,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 @@ -62,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] @@ -76,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 ``` @@ -133,9 +132,9 @@ used for systems dedicated for running MariaDB MaxScale. threads=1 ``` -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` @@ -212,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` @@ -232,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 @@ -257,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` @@ -276,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: @@ -289,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: @@ -306,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. @@ -345,11 +343,11 @@ To disable the augmentation use the value 0 and to enable it use the value 1. #### `log_throttling` -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 @@ -392,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/ @@ -414,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/ @@ -493,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. ``` @@ -515,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 @@ -529,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. @@ -580,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` @@ -756,9 +756,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 @@ -766,8 +767,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 ---------|----------|------------- @@ -780,8 +781,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] @@ -806,19 +807,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` @@ -832,9 +833,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. @@ -978,10 +979,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` @@ -1020,10 +1020,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 @@ -1068,9 +1068,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). ``` [] @@ -1117,14 +1117,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 @@ -1173,9 +1173,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` @@ -1223,10 +1223,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 @@ -1256,7 +1256,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/Reference/Debug-And-Diagnostic-Support.md b/Documentation/Reference/Debug-And-Diagnostic-Support.md deleted file mode 100644 index a9e1557f4..000000000 --- a/Documentation/Reference/Debug-And-Diagnostic-Support.md +++ /dev/null @@ -1,1941 +0,0 @@ -# MariaDB MaxScale Debug & Diagnostic Support - -[[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/MaxBinlogCheck.md b/Documentation/Reference/MaxBinlogCheck.md index 3041cd79a..e55f813f9 100644 --- a/Documentation/Reference/MaxBinlogCheck.md +++ b/Documentation/Reference/MaxBinlogCheck.md @@ -1,8 +1,13 @@ -# Maxbinlogcheck, the MySQL/MariaDB binlog check utility +# Maxbinlogcheck, the MySQL/MariaDB binlog check utility # Overview -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 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: @@ -26,9 +31,8 @@ The maxbinlogcheck command accepts a number of switches Description - -f - --fix - If 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 @@ -38,7 +42,8 @@ The maxbinlogcheck command accepts a number of switches -d --debug - Sets 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. -? @@ -58,7 +63,8 @@ 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 @@ -167,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. @@ -197,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 @@ -275,7 +281,8 @@ And finally big transaction is now done. **Note** -With current maxbinlogcheck it's not possible to fix a binlog with incomplete transaction and no other errors +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: @@ -356,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 2fffa4b33..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,8 +53,9 @@ int main(int argc, char **argv) } ``` -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. +The array _my_args_ of type _modulecmd_arg_type_t_ is used to tell what kinds of +arguments the command expects. The first argument is a boolean and the second +argument is an optional string. Arguments are passed to the parsing function as an array of void pointers. They are interpreted as the types the command expects. diff --git a/Documentation/Routers/CLI.md b/Documentation/Routers/CLI.md index 706e2b4b7..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 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. +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. @@ -33,18 +33,18 @@ 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. -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/ReadWriteSplit.md b/Documentation/Routers/ReadWriteSplit.md index 4fe082241..c4cd6ac2c 100644 --- a/Documentation/Routers/ReadWriteSplit.md +++ b/Documentation/Routers/ReadWriteSplit.md @@ -1,52 +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 use examples 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 in a 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 the 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. max_slave_replication_lag must be greater than the 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. +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). 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 the query would be routed to due to the `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 @@ -65,15 +91,19 @@ master_failure_mode=fail_on_write ## 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=