From d63f8727c27b0e4c93fa5a881580fc2d149c55f5 Mon Sep 17 00:00:00 2001 From: Johan Wikman Date: Mon, 23 Jan 2017 10:05:31 +0200 Subject: [PATCH] Wrap Configuration-Guide.md Lines wrapped at 80 chars. No other changes. --- .../Getting-Started/Configuration-Guide.md | 591 +++++++++++++----- 1 file changed, 446 insertions(+), 145 deletions(-) diff --git a/Documentation/Getting-Started/Configuration-Guide.md b/Documentation/Getting-Started/Configuration-Guide.md index 2c94cc660..6cf52a806 100644 --- a/Documentation/Getting-Started/Configuration-Guide.md +++ b/Documentation/Getting-Started/Configuration-Guide.md @@ -2,7 +2,11 @@ ## Introduction -The purpose of this document is to describe how to configure MariaDB MaxScale and to discuss some possible usage scenarios for MariaDB MaxScale. MariaDB MaxScale is designed with flexibility in mind, and consists of an event processing core with various support functions and plugin modules that tailor the behavior of the MariaDB MaxScale itself. +The purpose of this document is to describe how to configure MariaDB MaxScale +and to discuss some possible usage scenarios for MariaDB MaxScale. MariaDB +MaxScale is designed with flexibility in mind, and consists of an event +processing core with various support functions and plugin modules that tailor +the behavior of the MariaDB MaxScale itself. # Table of Contents @@ -57,12 +61,12 @@ but the strong suggestion is to place global settings into the configuration file MariaDB MaxScale is invoked with, and then, if deemed necessary, create 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. +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. ``` [MyService] @@ -73,11 +77,14 @@ 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. ### Global Settings -The global settings, in a section named `[MaxScale]`, allow various parameters that affect MariaDB MaxScale as a whole to be tuned. +The global settings, in a section named `[MaxScale]`, allow various parameters +that affect MariaDB MaxScale as a whole to be tuned. #### `threads` @@ -89,9 +96,9 @@ processor cores does not improve the performance, rather is likely to degrade it, and can consume resources needlessly. You can enable automatic configuration of this value by setting the value to -`auto`. This way MariaDB MaxScale will detect the number of available processors and -set the amount of threads to be equal to that number. This should only be used -for systems dedicated for running MariaDB MaxScale. +`auto`. This way MariaDB MaxScale will detect the number of available processors +and set the amount of threads to be equal to that number. This should only be +used for systems dedicated for running MariaDB MaxScale. ``` # Valid options are: @@ -101,11 +108,17 @@ for systems dedicated for running MariaDB MaxScale. threads=1 ``` -It should be noted that additional threads will be created to execute other internal services within MariaDB MaxScale. This setting is used to configure the number of threads that will be used to manage the user connections. +It should be noted that additional threads will be created to execute other +internal services within MariaDB MaxScale. This setting is used to configure the +number of threads that will be used to manage the user connections. #### `auth_connect_timeout` -The connection timeout in seconds for the MySQL connections to the backend server when user authentication data is fetched. Increasing the value of this parameter will cause MariaDB MaxScale to wait longer for a response from the backend server before aborting the authentication process. The default is 3 seconds. +The connection timeout in seconds for the MySQL connections to the backend +server when user authentication data is fetched. Increasing the value of this +parameter will cause MariaDB MaxScale to wait longer for a response from the +backend server before aborting the authentication process. The default is 3 +seconds. ``` auth_connect_timeout=10 @@ -113,7 +126,13 @@ auth_connect_timeout=10 #### `auth_read_timeout` -The read timeout in seconds for the MySQL connection to the backend database when user authentication data is fetched. Increasing the value of this parameter will cause MariaDB MaxScale to wait longer for a response from the backend server when user data is being actively fetched. If the authentication is failing and you either have a large number of database users and grants or the connection to the backend servers is slow, it is a good idea to increase this value. The default is 1 second. +The read timeout in seconds for the MySQL connection to the backend database +when user authentication data is fetched. Increasing the value of this parameter +will cause MariaDB MaxScale to wait longer for a response from the backend +server when user data is being actively fetched. If the authentication is +failing and you either have a large number of database users and grants or the +connection to the backend servers is slow, it is a good idea to increase this +value. The default is 1 second. ``` auth_read_timeout=10 @@ -121,7 +140,9 @@ auth_read_timeout=10 #### `auth_write_timeout` -The write timeout in seconds for the MySQL connection to the backend database when user authentication data is fetched. Currently MariaDB MaxScale does not write or modify the data in the backend server. The default is 2 seconds. +The write timeout in seconds for the MySQL connection to the backend database +when user authentication data is fetched. Currently MariaDB MaxScale does not +write or modify the data in the backend server. The default is 2 seconds. ``` auth_write_timeout=10 @@ -129,7 +150,8 @@ auth_write_timeout=10 #### `ms_timestamp` -Enable or disable the high precision timestamps in logfiles. Enabling this adds millisecond precision to all logfile timestamps. +Enable or disable the high precision timestamps in logfiles. Enabling this adds +millisecond precision to all logfile timestamps. ``` # Valid options are: @@ -195,12 +217,12 @@ 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 disable -*maxlog*. That way messages will normally be logged to *syslog*, but if -there is something to investigate, *log_info* and *maxlog* can be enabled -from *maxadmin*, in which case informational messages will be logged to -the *maxscale.log* file that resides in shared memory. +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 +disable *maxlog*. That way messages will normally be logged to *syslog*, but if +there is something to investigate, *log_info* and *maxlog* can be enabled from +*maxadmin*, in which case informational messages will be logged to the +*maxscale.log* file that resides in shared memory. By default, logging to shared memory is disabled. @@ -283,7 +305,10 @@ To disable these messages use the value 0 and to enable them use the value 1. #### `log_augmentation` -Enable or disable the augmentation of messages. If this is enabled, then each logged message is appended with the name of the function where the message was logged. This is primarily for development purposes and hence is disabled by default. +Enable or disable the augmentation of messages. If this is enabled, then each +logged message is appended with the name of the function where the message was +logged. This is primarily for development purposes and hence is disabled by +default. ``` # Valid options are: @@ -295,27 +320,28 @@ To disable the augmentation use the value 0 and to enable it use the value 1. #### `log_throttling` -In some circumstances it is possible that a particular error (or warning) is logged -over and over again, if the cause for the error persistently remains. To prevent the log -from flooding, it is possible to specify how many times a particular error may be logged -within a time period, before the logging of that error is suppressed for a while. +In some circumstances it is possible that a particular error (or warning) is +logged over and over again, if the cause for the error persistently remains. To +prevent the log from flooding, it is possible to specify how many times a +particular error may be logged within a time period, before the logging of that +error is suppressed for a while. ``` # A valid value looks like # log_throttling = X, Y, Z # -# where each value is a positive integer and X means the number of times a specific -# error may be logged within a time period of Y milliseconds, before the logging of -# that error is suppressed for Z milliseconds. +# where each value is a positive integer and X means the number of times a +# specific error may be logged within a time period of Y milliseconds, before +# the logging of that error is suppressed for Z milliseconds. log_throttling=8, 2000, 15000 ``` -In the example above, the logging of a particular error will be suppressed for 15 seconds -if the error has been logged 8 times in 2 seconds. +In the example above, the logging of a particular error will be suppressed for +15 seconds if the error has been logged 8 times in 2 seconds. -The default is `10, 1000, 10000`, which means that if the same error is logged 10 -times in one second, the logging of that error is suppressed for the following -10 seconds. +The default is `10, 1000, 10000`, which means that if the same error is logged +10 times in one second, the logging of that error is suppressed for the +following 10 seconds. To disable log throttling, add an entry with an empty value @@ -332,7 +358,8 @@ Note that *notice*, *info* and *debug* messages are never throttled. #### `logdir` -Set the directory where the logfiles are stored. The folder needs to be both readable and writable by the user running MariaDB MaxScale. +Set the directory where the logfiles are stored. The folder needs to be both +readable and writable by the user running MariaDB MaxScale. ``` logdir=/tmp/ @@ -340,7 +367,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/ @@ -348,7 +377,10 @@ datadir=/home/user/maxscale_data/ #### `libdir` -Set the directory where MariaDB MaxScale looks for modules. The library directory is the only directory that MariaDB MaxScale uses when it searches for modules. If you have custom modules for MariaDB MaxScale, make sure you have them in this folder. +Set the directory where MariaDB MaxScale looks for modules. The library +directory is the only directory that MariaDB MaxScale uses when it searches for +modules. If you have custom modules for MariaDB MaxScale, make sure you have +them in this folder. ``` libdir=/home/user/lib64/ @@ -356,7 +388,10 @@ 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. +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. ``` cachedir=/tmp/maxscale_cache/ @@ -364,7 +399,8 @@ cachedir=/tmp/maxscale_cache/ #### `piddir` -Configure the directory for the PID file for MariaDB MaxScale. This file contains the Process ID for the running MariaDB MaxScale process. +Configure the directory for the PID file for MariaDB MaxScale. This file +contains the Process ID for the running MariaDB MaxScale process. ``` piddir=/tmp/maxscale_cache/ @@ -372,7 +408,9 @@ piddir=/tmp/maxscale_cache/ #### `execdir` -Configure the directory where the executable files reside. All internal processes which are launched will use this directory to look for executable files. +Configure the directory where the executable files reside. All internal +processes which are launched will use this directory to look for executable +files. ``` execdir=/usr/local/bin/ @@ -408,7 +446,8 @@ module_configdir=/var/lib/maxscale/ #### `language` -Set the folder where the errmsg.sys file is located in. MariaDB MaxScale will look for the errmsg.sys file installed with MariaDB MaxScale from this folder. +Set the folder where the errmsg.sys file is located in. MariaDB MaxScale will +look for the errmsg.sys file installed with MariaDB MaxScale from this folder. ``` language=/home/user/lang/ @@ -446,38 +485,62 @@ server (e.g. to a slave instead of to a master). ### Service -A service represents the database service that MariaDB MaxScale offers to the clients. In general a service consists of a set of backend database servers and a routing algorithm that determines how MariaDB MaxScale decides to send statements or route connections to those backend servers. +A service represents the database service that MariaDB MaxScale offers to the +clients. In general a service consists of a set of backend database servers and +a routing algorithm that determines how MariaDB MaxScale decides to send +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. +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 +A service is identified by a service name, which is the name of the +configuration file section and a type parameter of service. ``` [Test Service] type=service ``` -In order for MariaDB MaxScale to forward any requests it must have at least one service defined within the configuration file. The definition of a service alone is not enough to allow MariaDB MaxScale to forward requests however, the service is merely present to link together the other configuration elements. +In order for MariaDB MaxScale to forward any requests it must have at least one +service defined within the configuration file. The definition of a service alone +is not enough to allow MariaDB MaxScale to forward requests however, the service +is merely present to link together the other configuration elements. #### `router` -The router parameter of a service defines the name of the router module that will be used to implement the routing algorithm between the client of MariaDB MaxScale and the backend databases. Additionally routers may also be passed a comma separated list of options that are used to control the behavior of the routing algorithm. The two parameters that control the routing choice are router and router_options. The router options are specific to a particular router and are used to modify the behavior of the router. The read connection router can be passed options of master, slave or synced, an example of configuring a service to use this router and limiting the choice of servers to those in slave state would be as follows. +The router parameter of a service defines the name of the router module that +will be used to implement the routing algorithm between the client of MariaDB +MaxScale and the backend databases. Additionally routers may also be passed a +comma separated list of options that are used to control the behavior of the +routing algorithm. The two parameters that control the routing choice are router +and router_options. The router options are specific to a particular router and +are used to modify the behavior of the router. The read connection router can be +passed options of master, slave or synced, an example of configuring a service +to use this router and limiting the choice of servers to those in slave state +would be as follows. ``` router=readconnroute router_options=slave ``` -To change the router to connect on to servers in the master state as well as slave servers, the router options can be modified to include the master state. +To change the router to connect on to servers in the master state as well as +slave servers, the router options can be modified to include the master state. ``` router=readconnroute router_options=master,slave ``` -A more complete description of router options and what is available for a given router is included with the documentation of the router itself. +A more complete description of router options and what is available for a given +router is included with the documentation of the router itself. #### `router_options` @@ -487,17 +550,24 @@ documentation for more details. #### `filters` -The filters option allow a set of filters to be defined for a service; requests from the client are passed through these filters before being sent to the router for dispatch to the backend server. The filters parameter takes one or more filter names, as defined within the filter definition section of the configuration file. Multiple filters are separated using the | character. +The filters option allow a set of filters to be defined for a service; requests +from the client are passed through these filters before being sent to the router +for dispatch to the backend server. The filters parameter takes one or more +filter names, as defined within the filter definition section of the +configuration file. Multiple filters are separated using the | character. ``` filters=counter | QLA ``` -The requests pass through the filters from left to right in the order defined in the configuration parameter. +The requests pass through the filters from left to right in the order defined in +the configuration parameter. #### `servers` -The servers parameter in a service definition provides a comma separated list of the backend servers that comprise the service. The server names are those used in the name section of a block with a type parameter of server (see below). +The servers parameter in a service definition provides a comma separated list of +the backend servers that comprise the service. The server names are those used +in the name section of a block with a type parameter of server (see below). ``` servers=server1,server2,server3 @@ -505,22 +575,35 @@ servers=server1,server2,server3 #### `user` -The user parameter, along with the passwd parameter are used to define the credentials used to connect to the backend servers to extract the list of database users from the backend database that is used for the client authentication. +The user parameter, along with the passwd parameter are used to define the +credentials used to connect to the backend servers to extract the list of +database users from the backend database that is used for the client +authentication. ``` user=maxscale passwd=Mhu87p2D ``` -Authentication of incoming connections is performed by MariaDB MaxScale itself rather than by the database server to which the client is connected. The client will authenticate itself with MariaDB MaxScale, using the username, hostname and password information that MariaDB MaxScale has extracted from the backend database servers. For a detailed discussion of how this impacts the authentication process please see the "Authentication" section below. +Authentication of incoming connections is performed by MariaDB MaxScale itself +rather than by the database server to which the client is connected. The client +will authenticate itself with MariaDB MaxScale, using the username, hostname and +password information that MariaDB MaxScale has extracted from the backend +database servers. For a detailed discussion of how this impacts the +authentication process please see the "Authentication" section below. -The host matching criteria is restricted to IPv4, IPv6 will be added in a future release. +The host matching criteria is restricted to IPv4, IPv6 will be added in a future +release. -Existing user configuration in the backend databases must be checked and may be updated before successful MariaDB MaxScale authentication: +Existing user configuration in the backend databases must be checked and may be +updated before successful MariaDB MaxScale authentication: -In order for MariaDB MaxScale to obtain all the data it must be given a username it can use to connect to the database and retrieve that data. This is the parameter that gives MariaDB MaxScale the username to use for this purpose. +In order for MariaDB MaxScale to obtain all the data it must be given a username +it can use to connect to the database and retrieve that data. This is the +parameter that gives MariaDB MaxScale the username to use for this purpose. -The account used must be able to select from the mysql.user table, the following is an example showing how to create this user. +The account used must be able to select from the mysql.user table, the following +is an example showing how to create this user. ``` MariaDB [mysql]> CREATE USER 'maxscale'@'maxscalehost' IDENTIFIED BY 'Mhu87p2D'; @@ -530,7 +613,9 @@ MariaDB [mysql]> GRANT SELECT ON mysql.user TO 'maxscale'@'maxscalehost'; Query OK, 0 rows affected (0.00 sec) ``` -Additionally, `SELECT` privileges on the `mysql.db` and `mysql.tables_priv` tables and `SHOW DATABASES` privileges are required in order to load databases name and grants suitable for database name authorization. +Additionally, `SELECT` privileges on the `mysql.db` and `mysql.tables_priv` +tables and `SHOW DATABASES` privileges are required in order to load databases +name and grants suitable for database name authorization. ``` MariaDB [(none)]> GRANT SELECT ON mysql.db TO 'maxscale'@'maxscalehost'; @@ -543,7 +628,9 @@ MariaDB [(none)]> GRANT SHOW DATABASES ON *.* TO 'maxscale'@'maxscalehost'; Query OK, 0 rows affected (0.00 sec) ``` -MariaDB MaxScale will execute the following query to retrieve the users. If you suspect that you might have problems with grants, it is recommended to run this query and see the results it returns. +MariaDB MaxScale will execute the following query to retrieve the users. If you +suspect that you might have problems with grants, it is recommended to run this +query and see the results it returns. ``` SELECT DISTINCT @@ -562,12 +649,18 @@ SELECT DISTINCT WHERE user.user IS NOT NULL AND user.user <> '' ``` -In versions of MySQL 5.7.6 and later, the `Password` column was replaced by `authentication_string`. Change `user.password` above with `user.authentication_string`. +In versions of MySQL 5.7.6 and later, the `Password` column was replaced by +`authentication_string`. Change `user.password` above with +`user.authentication_string`. #### `passwd` -The passwd parameter provides the password information for the above user and may be either a plain text password or it may be an encrypted password. See the section on encrypting passwords for use in the maxscale.cnf file. This user must be capable of connecting to the backend database and executing these SQL statements to load database names and grants from the backends: +The passwd parameter provides the password information for the above user and +may be either a plain text password or it may be an encrypted password. See the +section on encrypting passwords for use in the maxscale.cnf file. This user must +be capable of connecting to the backend database and executing these SQL +statements to load database names and grants from the backends: * `SELECT user, host, password,Select_priv FROM mysql.user`. * `SELECT user, host, db FROM mysql.db` @@ -576,9 +669,11 @@ The passwd parameter provides the password information for the above user and ma #### `enable_root_user` -This parameter controls the ability of the root user to connect to MariaDB MaxScale and hence onwards to the backend servers via MariaDB MaxScale. +This parameter controls the ability of the root user to connect to MariaDB +MaxScale and hence onwards to the backend servers via MariaDB MaxScale. -The default value is `0`, disabling the ability of the root user to connect to MariaDB MaxScale. +The default value is `0`, disabling the ability of the root user to connect to +MariaDB MaxScale. Example for enabling root user: @@ -586,7 +681,8 @@ Example for enabling root user: enable_root_user=1 ``` -Values of `on` or `true` may also be given to enable the root user and `off` or `false` may be given to disable the use of the root user. +Values of `on` or `true` may also be given to enable the root user and `off` or +`false` may be given to disable the use of the root user. ``` enable_root_user=true @@ -594,7 +690,11 @@ enable_root_user=true #### `localhost_match_wildcard_host` -This parameter enables matching of "127.0.0.1" (localhost) against "%" wildcard host for MySQL protocol authentication. The default value is `0`, so in order to authenticate a connection from the same machine as the one on which MariaDB MaxScale is running, an explicit user@localhost entry will be required in the MySQL user table. +This parameter enables matching of "127.0.0.1" (localhost) against "%" wildcard +host for MySQL protocol authentication. The default value is `0`, so in order to +authenticate a connection from the same machine as the one on which MariaDB +MaxScale is running, an explicit user@localhost entry will be required in the +MySQL user table. #### `version_string` @@ -686,7 +786,10 @@ would get 25% of the connections. #### `auth_all_servers` -This parameter controls whether only a single server or all of the servers are used when loading the users from the backend servers. This takes a boolean value and when enabled, creates a union of all the users and grants on all the servers. +This parameter controls whether only a single server or all of the servers are +used when loading the users from the backend servers. This takes a boolean value +and when enabled, creates a union of all the users and grants on all the +servers. #### `strip_db_esc` @@ -702,17 +805,28 @@ this might cause conflicts when MariaDB MaxScale tries to authenticate users. #### `retry_on_failure` -The retry_on_failure parameter controls whether MariaDB MaxScale will try to restart failed services and accepts a boolean value. This functionality is enabled by default to prevent services being permanently disabled if the starting of the service failed due to a network outage. Disabling the restarting of the failed services will cause them to be permanently disabled if the services can't be started when MariaDB MaxScale is started. +The retry_on_failure parameter controls whether MariaDB MaxScale will try to +restart failed services and accepts a boolean value. This functionality is +enabled by default to prevent services being permanently disabled if the +starting of the service failed due to a network outage. Disabling the restarting +of the failed services will cause them to be permanently disabled if the +services can't be started when MariaDB MaxScale is started. #### `log_auth_warnings` -Enable or disable the logging of authentication failures and warnings. This parameter takes a boolean value. +Enable or disable the logging of authentication failures and warnings. This +parameter takes a boolean value. -MariaDB MaxScale normally suppresses warning messages about failed authentication. Enabling this option will log those messages into the message log with details about who tried to connect to MariaDB MaxScale and from where. +MariaDB MaxScale normally suppresses warning messages about failed +authentication. Enabling this option will log those messages into the message +log with details about who tried to connect to MariaDB MaxScale and from where. #### `connection_timeout` -The connection_timeout parameter is used to disconnect sessions to MariaDB MaxScale that have been idle for too long. The session timeouts are disabled by default. To enable them, define the timeout in seconds in the service's configuration section. +The connection_timeout parameter is used to disconnect sessions to MariaDB +MaxScale that have been idle for too long. The session timeouts are disabled by +default. To enable them, define the timeout in seconds in the service's +configuration section. Example: @@ -723,7 +837,10 @@ connection_timeout=300 #### `max_connections` -The maximum number of simultaneous connections MaxScale should permit to this service. If the parameter is zero or is omitted, there is no limit. Any attempt to make more connections after the limit is reached will result in a "Too many connections" error being returned. +The maximum number of simultaneous connections MaxScale should permit to this +service. If the parameter is zero or is omitted, there is no limit. Any attempt +to make more connections after the limit is reached will result in a "Too many +connections" error being returned. Example: @@ -735,7 +852,11 @@ max_connections=100 ### Server -Server sections are used to define the backend database servers that can be formed into a service. A server may be a member of one or more services within MariaDB MaxScale. Servers are identified by a server name which is the section name in the configuration file. Servers have a type parameter of server, plus address port and protocol parameters. +Server sections are used to define the backend database servers that can be +formed into a service. A server may be a member of one or more services within +MariaDB MaxScale. Servers are identified by a server name which is the section +name in the configuration file. Servers have a type parameter of server, plus +address port and protocol parameters. ``` [server1] @@ -747,19 +868,26 @@ protocol=MySQLBackend #### `address` -The IP address or hostname of the machine running the database server that is being defined. MariaDB MaxScale will use this address to connect to the backend database server. +The IP address or hostname of the machine running the database server that is +being defined. MariaDB MaxScale will use this address to connect to the backend +database server. #### `port` -The port on which the database listens for incoming connections. MariaDB MaxScale will use this port to connect to the database server. +The port on which the database listens for incoming connections. MariaDB +MaxScale will use this port to connect to the database server. #### `protocol` -The name for the protocol module to use to connect MariaDB MaxScale to the database. Currently only one backend protocol is supported, the MySQLBackend module. +The name for the protocol module to use to connect MariaDB MaxScale to the +database. Currently only one backend protocol is supported, the MySQLBackend +module. #### `monitoruser` -The monitor has a username and password that is used to connect to all servers for monitoring purposes, this may be overridden by supplying a monitoruser statement for each individual server +The monitor has a username and password that is used to connect to all servers +for monitoring purposes, this may be overridden by supplying a monitoruser +statement for each individual server. ``` monitoruser=mymonitoruser @@ -767,50 +895,81 @@ monitoruser=mymonitoruser #### `monitorpw` -The monitor has a username and password that is used to connect to all servers for monitoring purposes, this may be overridden by supplying a monpasswd statement for the individual servers +The monitor has a username and password that is used to connect to all servers +for monitoring purposes, this may be overridden by supplying a monpasswd +statement for the individual servers. ``` monitorpw=mymonitorpasswd ``` -The monpasswd parameter may be either a plain text password or it may be an encrypted password. See the section on encrypting passwords for use in the maxscale.cnf file. +The monpasswd parameter may be either a plain text password or it may be an +encrypted password. See the section on encrypting passwords for use in the +maxscale.cnf file. #### `persistpoolmax` -The `persistpoolmax` parameter defaults to zero but can be set to an integer value for a back end server. -If it is non zero, then when a DCB connected to a back end server is discarded by the -system, it will be held in a pool for reuse, remaining connected to the back end server. -If the number of DCBs in the pool has reached the value given by `persistpoolmax` then -any further DCB that is discarded will not be retained, but disconnected and discarded. +The `persistpoolmax` parameter defaults to zero but can be set to an integer +value for a back end server. If it is non zero, then when a DCB connected to a +back end server is discarded by the system, it will be held in a pool for reuse, +remaining connected to the back end server. If the number of DCBs in the pool +has reached the value given by `persistpoolmax` then any further DCB that is +discarded will not be retained, but disconnected and discarded. #### `persistmaxtime` -The `persistmaxtime` parameter defaults to zero but can be set to an integer value -indicating a number of seconds. A DCB placed in the persistent pool for a server will -only be reused if the elapsed time since it joined the pool is less than the given -value. Otherwise, the DCB will be discarded and the connection closed. +The `persistmaxtime` parameter defaults to zero but can be set to an integer +value indicating a number of seconds. A DCB placed in the persistent pool for a +server will only be reused if the elapsed time since it joined the pool is less +than the given value. Otherwise, the DCB will be discarded and the connection +closed. -For more information about persistent connections, please read the [Administration Tutorial](../Tutorials/Administration-Tutorial.md). +For more information about persistent connections, please read the +[Administration Tutorial](../Tutorials/Administration-Tutorial.md). ### Server and SSL -This section describes configuration parameters for servers that control the SSL/TLS encryption method and the various certificate files involved in it when applied to back end servers. To enable SSL between MaxScale and a back end server, you must configure the `ssl` parameter in the relevant server section to the value `required` and provide the three files for `ssl_cert`, `ssl_key` and `ssl_ca_cert`. After this, MaxScale connections to this server will be encrypted with SSL. Attempts to connect to the server without using SSL will cause failures. Hence, the database server in question must have been configured to be able to accept SSL connections. +This section describes configuration parameters for servers that control the +SSL/TLS encryption method and the various certificate files involved in it when +applied to back end servers. To enable SSL between MaxScale and a back end +server, you must configure the `ssl` parameter in the relevant server section to +the value `required` and provide the three files for `ssl_cert`, `ssl_key` and +`ssl_ca_cert`. After this, MaxScale connections to this server will be encrypted +with SSL. Attempts to connect to the server without using SSL will cause +failures. Hence, the database server in question must have been configured to be +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. +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. #### `ssl_key` -A string giving a file path that identifies an existing readable file. The file must be the SSL client private key MaxScale should use with the server. This will be the private key that is used as the client side private key during a MaxScale-server SSL handshake. This is currently a required parameter for SSL enabled servers. +A string giving a file path that identifies an existing readable file. The file +must be the SSL client private key MaxScale should use with the server. This +will be the private key that is used as the client side private key during a +MaxScale-server SSL handshake. This is currently a required parameter for SSL +enabled servers. #### `ssl_cert` -A string giving a file path that identifies an existing readable file. The file must be the SSL client certificate MaxScale should use with the server. This will be the public certificate that is used as the client side certificate during a MaxScale-server SSL handshake. This is a required parameter for SSL enabled servers. The certificate must be compatible with the key defined above. +A string giving a file path that identifies an existing readable file. The file +must be the SSL client certificate MaxScale should use with the server. This +will be the public certificate that is used as the client side certificate +during a MaxScale-server SSL handshake. This is a required parameter for SSL +enabled servers. The certificate must be compatible with the key defined above. #### `ssl_ca_cert` -A string giving a file path that identifies an existing readable file. The file must be the SSL Certificate Authority (CA) certificate for the CA that signed the client certificate referred to in the previous parameter. It will be used to verify that the client certificate is valid. This is a required parameter for SSL enabled listeners. +A string giving a file path that identifies an existing readable file. The file +must be the SSL Certificate Authority (CA) certificate for the CA that signed +the client certificate referred to in the previous parameter. It will be used to +verify that the client certificate is valid. This is a required parameter for +SSL enabled listeners. #### `ssl_version` @@ -820,11 +979,15 @@ This parameter controls the level of encryption used. Accepted values are: * TLSv12 * MAX -Not all backend servers will support TLSv11 or TLSv12. If available, TLSv12 should be used. +Not all backend servers will support TLSv11 or TLSv12. If available, TLSv12 +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 @@ -849,11 +1012,21 @@ ssl_ca_cert=/usr/local/mariadb/maxscale/ssl/crt.ca.maxscale.pem ``` -This example configuration requires all connections to this server to be encrypted with SSL. It also specifies that TLSv1.0 should be used as the encryption method. The paths to the server certificate files and the Certificate Authority file are also provided. +This example configuration requires all connections to this server to be +encrypted with SSL. It also specifies that TLSv1.0 should be used as the +encryption method. The paths to the server certificate files and the Certificate +Authority file are also provided. ### Listener -The listener defines a port and protocol pair that is used to listen for connections to a service. A service may have multiple listeners associated with it, either to support multiple protocols or multiple ports. As with other elements of the configuration the section name is the listener name and it can be selected freely. A type parameter is used to identify the section as a listener definition. Address is optional and it allows the user to limit connections to certain interface only. Socket is also optional and used for Unix socket connections. +The listener defines a port and protocol pair that is used to listen for +connections to a service. A service may have multiple listeners associated with +it, either to support multiple protocols or multiple ports. As with other +elements of the configuration the section name is the listener name and it can +be selected freely. A type parameter is used to identify the section as a +listener definition. Address is optional and it allows the user to limit +connections to certain interface only. Socket is also optional and used for Unix +socket connections. The network socket where the listener listens will have a backlog of connections. The size of this backlog is controlled by the @@ -875,25 +1048,35 @@ socket= #### `service` -The service to which the listener is associated. This is the name of a service that is defined elsewhere in the configuration file. +The service to which the listener is associated. This is the name of a service +that is defined elsewhere in the configuration file. #### `protocol` -The name of the protocol module that is used for the communication between the client and MariaDB MaxScale itself. +The name of the protocol module that is used for the communication between the +client and MariaDB MaxScale itself. #### `address` -The address option sets the address that will be used to bind the listening socket. The address may be specified as an IP address in 'dot notation' or as a hostname. If the address option is not included in the listener definition the listener will bind to all network interfaces. +The address option sets the address that will be used to bind the listening +socket. The address may be specified as an IP address in 'dot notation' or as a +hostname. If the address option is not included in the listener definition the +listener will bind to all network interfaces. #### `port` -The port to use to listen for incoming connections to MariaDB MaxScale from the clients. If the port is omitted from the configuration a default port for the protocol will be used. +The port to use to listen for incoming connections to MariaDB MaxScale from the +clients. If the port is omitted from the configuration a default port for the +protocol will be used. #### `socket` -The `socket` option may be included in a listener definition, this configures the listener to use Unix domain sockets to listen for incoming connections. The parameter value given is the name of the socket to use. +The `socket` option may be included in a listener definition, this configures +the listener to use Unix domain sockets to listen for incoming connections. The +parameter value given is the name of the socket to use. -If a socket option and an address option is given then the listener will listen on both the specific IP address and the Unix socket. +If a socket option and an address option is given then the listener will listen +on both the specific IP address and the Unix socket. #### `authenticator` @@ -909,47 +1092,84 @@ authenticator specific documentation for more details. #### Available Protocols -The protocols supported by MariaDB MaxScale are implemented as external modules that are loaded dynamically into the MariaDB MaxScale core. They allow MariaDB MaxScale to communicate in various protocols both on the client side and the backend side. Each of the protocols can be either a client protocol or a backend protocol. Client protocols are used for client-MariaDB MaxScale communication and backend protocols are for MariaDB MaxScale-database communication. +The protocols supported by MariaDB MaxScale are implemented as external modules +that are loaded dynamically into the MariaDB MaxScale core. They allow MariaDB +MaxScale to communicate in various protocols both on the client side and the +backend side. Each of the protocols can be either a client protocol or a backend +protocol. Client protocols are used for client-MariaDB MaxScale communication +and backend protocols are for MariaDB MaxScale-database communication. ##### `MySQLClient` -This is the implementation of the MySQL protocol that is used by clients of MariaDB MaxScale to connect to MariaDB MaxScale. +This is the implementation of the MySQL protocol that is used by clients of +MariaDB MaxScale to connect to MariaDB MaxScale. ##### `MySQLBackend` -The MySQLBackend protocol module is the implementation of the protocol that MariaDB MaxScale uses to connect to the backend MySQL, MariaDB and Percona Server databases. This implementation is tailored for the MariaDB MaxScale to MySQL Database traffic and is not a general purpose implementation of the MySQL protocol. +The MySQLBackend protocol module is the implementation of the protocol that +MariaDB MaxScale uses to connect to the backend MySQL, MariaDB and Percona +Server databases. This implementation is tailored for the MariaDB MaxScale to +MySQL Database traffic and is not a general purpose implementation of the MySQL +protocol. ##### `telnetd` -The telnetd protocol module is used for connections to MariaDB MaxScale itself for the purposes of creating interactive user sessions with the MariaDB MaxScale instance itself. Currently this is used in conjunction with a special router implementation, the debugcli. +The telnetd protocol module is used for connections to MariaDB MaxScale itself +for the purposes of creating interactive user sessions with the MariaDB MaxScale +instance itself. Currently this is used in conjunction with a special router +implementation, the debugcli. ##### `maxscaled` -The protocol used used by the maxadmin client application in order to connect to MariaDB MaxScale and access the command line interface. +The protocol used used by the maxadmin client application in order to connect to +MariaDB MaxScale and access the command line interface. ##### `HTTPD` -This protocol module is currently still under development, it provides a means to create HTTP connections to MariaDB MaxScale for use by web browsers or RESTful API clients. +This protocol module is currently still under development, it provides a means +to create HTTP connections to MariaDB MaxScale for use by web browsers or +RESTful API clients. ### Listener and SSL -This section describes configuration parameters for listeners that control the 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. +This section describes configuration parameters for listeners that control the +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. #### `ssl` -This enables SSL connections to the listener, when set to `required`. If that is done, the three certificate files mentioned below must also be supplied. Client connections to this listener will then be encrypted with SSL. Non-SSL connections will get an error when they try to connect to the listener. +This enables SSL connections to the listener, when set to `required`. If that is +done, the three certificate files mentioned below must also be supplied. Client +connections to this listener will then be encrypted with SSL. Non-SSL +connections will get an error when they try to connect to the listener. #### `ssl_key` -A string giving a file path that identifies an existing readable file. The file must be the SSL private key the listener should use. This will be the private key that is used as the server side private key during a client-server SSL handshake. This is a required parameter for SSL enabled listeners. +A string giving a file path that identifies an existing readable file. The file +must be the SSL private key the listener should use. This will be the private +key that is used as the server side private key during a client-server SSL +handshake. This is a required parameter for SSL enabled listeners. #### `ssl_cert` -A string giving a file path that identifies an existing readable file. The file must be the SSL certificate the listener should use. This will be the public certificate that is used as the server side certificate during a client-server SSL handshake. This is a required parameter for SSL enabled listeners. The certificate must be compatible with the key defined above. +A string giving a file path that identifies an existing readable file. The file +must be the SSL certificate the listener should use. This will be the public +certificate that is used as the server side certificate during a client-server +SSL handshake. This is a required parameter for SSL enabled listeners. The +certificate must be compatible with the key defined above. #### `ssl_ca_cert` -A string giving a file path that identifies an existing readable file. The file must be the SSL Certificate Authority (CA) certificate for the CA that signed the server certificate referred to in the previous parameter. It will be used to verify that the server certificate is valid. This is a required parameter for SSL enabled listeners. +A string giving a file path that identifies an existing readable file. The file +must be the SSL Certificate Authority (CA) certificate for the CA that signed +the server certificate referred to in the previous parameter. It will be used to +verify that the server certificate is valid. This is a required parameter for +SSL enabled listeners. #### `ssl_version` @@ -959,11 +1179,18 @@ This parameter controls the level of encryption used. Accepted values are: * TLSv12 * MAX -If possible, use TLSv12 for best security. Recent Linux systems will include a version of OpenSSL that supports TLS version 1.2. Only if you are using MaxScale on a system that does not have OpenSSL with support for this should earlier versions be used. It is unlikely that TLS 1.1 will be available unless TLS 1.2 is also available. MAX will use the best available version. +If possible, use TLSv12 for best security. Recent Linux systems will include a +version of OpenSSL that supports TLS version 1.2. Only if you are using +MaxScale on a system that does not have OpenSSL with support for this should +earlier versions be used. It is unlikely that TLS 1.1 will be available unless +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 @@ -988,14 +1215,20 @@ ssl_version=TLSv12 ssl_cert_verify_depth=9 ``` -This example configuration requires all connections to be encrypted with SSL. It 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. +This example configuration requires all connections to be encrypted with SSL. It +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 applications and route the connections or the statements sent over those connections to the various services supported by MariaDB MaxScale. +The main task of MariaDB MaxScale is to accept database connections from client +applications and route the connections or the statements sent over those +connections to the various services supported by MariaDB MaxScale. -Currently a number of routing modules are available, these are designed for a range of different needs. +Currently a number of routing modules are available, these are designed for a +range of different needs. Connection based load balancing: * [ReadConnRoute](../Routers/ReadConnRoute.md) @@ -1011,16 +1244,24 @@ Binary log server: ## Diagnostic modules -These modules are used for diagnostic purposes and can tell about the status of MariaDB MaxScale and the cluster it is monitoring. +These modules are used for diagnostic purposes and can tell about the status of +MariaDB MaxScale and the cluster it is monitoring. * [MaxAdmin Module](../Routers/CLI.md) * [Telnet Module](../Routers/Debug-CLI.md) ## Monitor Modules -Monitor modules are used by MariaDB MaxScale to internally monitor the state of the backend databases in order to set the server flags for each of those servers. The router modules then use these flags to determine if the particular server is a suitable destination for routing connections for particular query classifications. The monitors are run within separate threads of MariaDB MaxScale and do not affect MariaDB MaxScale's routing performance. +Monitor modules are used by MariaDB MaxScale to internally monitor the state of +the backend databases in order to set the server flags for each of those +servers. The router modules then use these flags to determine if the particular +server is a suitable destination for routing connections for particular query +classifications. The monitors are run within separate threads of MariaDB +MaxScale and do not affect MariaDB MaxScale's routing performance. -The use of monitors is highly recommended but it is also possible to run MariaDB MaxScale without a monitor module. In this case an external monitoring system which sets the status of each server via MaxAdmin is needed. +The use of monitors is highly recommended but it is also possible to run MariaDB +MaxScale without a monitor module. In this case an external monitoring system +which sets the status of each server via MaxAdmin is needed. * [Mysql Monitor](../Monitors/MySQL-Monitor.md) * [Galera Monitor](../Monitors/Galera-Monitor.md) @@ -1031,9 +1272,12 @@ The use of monitors is highly recommended but it is also possible to run MariaDB ![image alt text](images/image_10.png) -Filters provide a means to manipulate or process requests as they pass through MariaDB MaxScale between the client side protocol and the query router. A full explanation of each filter's functionality can be found in its documentation. +Filters provide a means to manipulate or process requests as they pass through +MariaDB MaxScale between the client side protocol and the query router. A full +explanation of each filter's functionality can be found in its documentation. -The [Filter Tutorial](../Tutorials/Filter-Tutorial.md) document shows how you can add a filter to a service and combine multiple filters in one service. +The [Filter Tutorial](../Tutorials/Filter-Tutorial.md) document shows how you +can add a filter to a service and combine multiple filters in one service. * [Query Log All (QLA) Filter](../Filters/Query-Log-All-Filter.md) * [Regular Expression Filter](../Filters/Regex-Filter.md) @@ -1070,19 +1314,41 @@ and _monpw_, can also be updated at runtime. ### Limitations -Services that are removed via the configuration update mechanism can not be physically removed from MariaDB MaxScale until there are no longer any connections using the service. +Services that are removed via the configuration update mechanism can not be +physically removed from MariaDB MaxScale until there are no longer any +connections using the service. -When the number of threads is decreased the threads will not actually be terminated until such time as they complete the current operation of that thread. +When the number of threads is decreased the threads will not actually be +terminated until such time as they complete the current operation of that +thread. Monitors can not be completely removed from the running MariaDB MaxScale. ## Authentication -MySQL uses username, passwords and the client host in order to authenticate a user, so a typical user would be defined as user X at host Y and would be given a password to connect. MariaDB MaxScale uses exactly the same rules as MySQL when users connect to the MariaDB MaxScale instance, i.e. it will check the address from which the client is connecting and treat this in exactly the same way that MySQL would. MariaDB MaxScale will pull the authentication data from one of the backend servers and use this to match the incoming connections, the assumption being that all the backend servers for a particular service will share the same set of user credentials. +MySQL uses username, passwords and the client host in order to authenticate a +user, so a typical user would be defined as user X at host Y and would be given +a password to connect. MariaDB MaxScale uses exactly the same rules as MySQL +when users connect to the MariaDB MaxScale instance, i.e. it will check the +address from which the client is connecting and treat this in exactly the same +way that MySQL would. MariaDB MaxScale will pull the authentication data from +one of the backend servers and use this to match the incoming connections, the +assumption being that all the backend servers for a particular service will +share the same set of user credentials. -It is important to understand, however, that when MariaDB MaxScale itself makes connections to the backend servers the backend server will see all connections as originating from the host that runs MariaDB MaxScale and not the original host from which the client connected to MariaDB MaxScale. Therefore the backend servers should be configured to allow connections from the MariaDB MaxScale host for every user that can connect from any host. Since there is only a single password within the database server for a given host, this limits the configuration such that a given user name must have the same password for every host from which they can connect. +It is important to understand, however, that when MariaDB MaxScale itself makes +connections to the backend servers the backend server will see all connections +as originating from the host that runs MariaDB MaxScale and not the original +host from which the client connected to MariaDB MaxScale. Therefore the backend +servers should be configured to allow connections from the MariaDB MaxScale host +for every user that can connect from any host. Since there is only a single +password within the database server for a given host, this limits the +configuration such that a given user name must have the same password for every +host from which they can connect. -To clarify, if a user *X* is defined as using password *pass1* from host *a* and *pass2* from host *b* then there must be an entry in the `user` table for user *X* from the MariaDB MaxScale host, say *pass1*. +To clarify, if a user *X* is defined as using password *pass1* from host *a* and +*pass2* from host *b* then there must be an entry in the `user` table for user +*X* from the MariaDB MaxScale host, say *pass1*. This would result in rows in the user table as follows @@ -1093,21 +1359,45 @@ Username|Password|Client Host X | pass1 | MaxScale -In this case the user *X* would be able to connect to MariaDB MaxScale from host a giving the password of *pass1*. In addition MariaDB MaxScale would be able to create connections for this user to the backend servers using the username *X* and password *pass1*, since the MariaDB MaxScale host is also defined to have password *pass1*. User *X* would not however be able to connect from host *b* since they would need to provide the password *pass2* in order to connect to MariaDB MaxScale, but then MariaDB MaxScale would not be able to connect to the backends as it would also use the password *pass2* for these connections. +In this case the user *X* would be able to connect to MariaDB MaxScale from host +a giving the password of *pass1*. In addition MariaDB MaxScale would be able to +create connections for this user to the backend servers using the username *X* +and password *pass1*, since the MariaDB MaxScale host is also defined to have +password *pass1*. User *X* would not however be able to connect from host *b* +since they would need to provide the password *pass2* in order to connect to +MariaDB MaxScale, but then MariaDB MaxScale would not be able to connect to the +backends as it would also use the password *pass2* for these connections. ### Wildcard Hosts -Hostname mapping in MariaDB MaxScale works in exactly the same way as for MySQL, if the wildcard is used for the host then any host other than the localhost (127.0.0.1) will match. It is important to consider that the localhost check will be performed at the MariaDB MaxScale level and at the MySQL server level. +Hostname mapping in MariaDB MaxScale works in exactly the same way as for MySQL, +if the wildcard is used for the host then any host other than the localhost +(127.0.0.1) will match. It is important to consider that the localhost check +will be performed at the MariaDB MaxScale level and at the MySQL server level. -If MariaDB MaxScale and the databases are on separate hosts there are two important changes in behavior to consider: +If MariaDB MaxScale and the databases are on separate hosts there are two +important changes in behavior to consider: -1. Clients running on the same machine as the backend database now may access the database using the wildcard entry. The localhost check between the client and MariaDB MaxScale will allow the use of the wildcard, since the client is not running on the MariaDB MaxScale host. Also the wildcard entry can be used on the database host as MariaDB MaxScale is making that connection and it is not running on the same host as the database. +1. Clients running on the same machine as the backend database now may access +the database using the wildcard entry. The localhost check between the client +and MariaDB MaxScale will allow the use of the wildcard, since the client is not +running on the MariaDB MaxScale host. Also the wildcard entry can be used on the +database host as MariaDB MaxScale is making that connection and it is not +running on the same host as the database. -2. Clients running on the same host as MariaDB MaxScale can not access the database via MariaDB MaxScale using the wildcard entry since the connection to MariaDB MaxScale will be from the localhost. These clients are able to access the database directly, as they will use the wildcard entry. +2. Clients running on the same host as MariaDB MaxScale can not access the +database via MariaDB MaxScale using the wildcard entry since the connection to +MariaDB MaxScale will be from the localhost. These clients are able to access +the database directly, as they will use the wildcard entry. -If MariaDB MaxScale is running on the same host as one or more of the database nodes to which it is routing statements then the wildcard host entries can be used to connect to MariaDB MaxScale but not to connect onwards to the database running on the same node. +If MariaDB MaxScale is running on the same host as one or more of the database +nodes to which it is routing statements then the wildcard host entries can be +used to connect to MariaDB MaxScale but not to connect onwards to the database +running on the same node. -In all these cases the issue may be solved by adding an explicit entry for the localhost address that has the same password as the wildcard entry. This may be done using a statement as below for each of the databases that are required: +In all these cases the issue may be solved by adding an explicit entry for the +localhost address that has the same password as the wildcard entry. This may be +done using a statement as below for each of the databases that are required: ``` MariaDB [mysql]> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP ON employee.* 'user1'@'localhost' IDENTIFIED BY 'xxx'; @@ -1116,7 +1406,9 @@ Query OK, 0 rows affected (0.00 sec) ### Limitations -At the time of writing the authentication mechanism within MariaDB MaxScale does not support IPV6 address matching in connections rules. This is also in line with the current protocol modules that do not support IPV6. +At the time of writing the authentication mechanism within MariaDB MaxScale does +not support IPV6 address matching in connections rules. This is also in line +with the current protocol modules that do not support IPV6. Wildcard address supported in the current version of MariaDB MaxScale are: @@ -1130,19 +1422,27 @@ and short notations 192.%.% 192.168.% -Note that currently wildcards are only supported in conjunction with IP-addresses, not with domain names. +Note that currently wildcards are only supported in conjunction with +IP-addresses, not with domain names. ## Error Reporting -MariaDB MaxScale is designed to be executed as a service, therefore all error reports, including configuration errors, are written to the MariaDB MaxScale error log file. By default, MariaDB MaxScale will log to a file in `/var/log/maxscale`, the only exception to this is if the log directory is not writable, in which case a message is sent to the standard error descriptor. +MariaDB MaxScale is designed to be executed as a service, therefore all error +reports, including configuration errors, are written to the MariaDB MaxScale +error log file. By default, MariaDB MaxScale will log to a file in +`/var/log/maxscale`, the only exception to this is if the log directory is not +writable, in which case a message is sent to the standard error descriptor. ### Troubleshooting MariaDB MaxScale binds on TCP ports and UNIX sockets as well. -If there is a local firewall in the server where MariaDB MaxScale is installed, the IP and port must be configured in order to receive connections from outside. +If there is a local firewall in the server where MariaDB MaxScale is installed, +the IP and port must be configured in order to receive connections from +outside. -If the firewall is a network facility among all the involved servers, a configuration update is required as well. +If the firewall is a network facility among all the involved servers, a +configuration update is required as well. Example: @@ -1156,4 +1456,5 @@ socket=/servers/maxscale/galera.sock TCP/IP Traffic must be permitted to 192.168.3.33 port 4408 -For Unix socket, the socket file path (example: `/servers/maxscale/galera.sock`) must be writable by the Unix user MariaDB MaxScale runs as. +For Unix socket, the socket file path (example: `/servers/maxscale/galera.sock`) +must be writable by the Unix user MariaDB MaxScale runs as.