From 40ffc101204c02963a7ecb265a49933f5ed9cae5 Mon Sep 17 00:00:00 2001 From: Markus Makela Date: Mon, 25 Apr 2016 14:19:56 +0300 Subject: [PATCH] Merged documentation changes Merged the documentation changes between the 1.4.1 and 1.4.2 releases from MaxScale-Documentation. --- Documentation/Documentation-Contents.md | 20 +++--- .../Filters/Database-Firewall-Filter.md | 22 ++++--- .../Getting-Started/Configuration-Guide.md | 54 +++++++++++++++- .../MaxScale-1.4.1-Release-Notes.md | 2 +- Documentation/Routers/ReadConnRoute.md | 63 +------------------ Documentation/Routers/ReadWriteSplit.md | 46 +------------- Documentation/Routers/SchemaRouter.md | 44 ++++++++++--- 7 files changed, 117 insertions(+), 134 deletions(-) diff --git a/Documentation/Documentation-Contents.md b/Documentation/Documentation-Contents.md index 0086a95e5..7dfd54c3a 100644 --- a/Documentation/Documentation-Contents.md +++ b/Documentation/Documentation-Contents.md @@ -6,7 +6,7 @@ ## About MaxScale - [About MaxScale](About/About-MaxScale.md) - - [MaxScale 1.4.0 Release Notes](Release-Notes/MaxScale-1.4.0-Release-Notes.md) + - [MaxScale 1.4.1 Release Notes](Release-Notes/MaxScale-1.4.1-Release-Notes.md) - [Changelog](Changelog.md) - [Limitations](About/Limitations.md) - [COPYRIGHT](About/COPYRIGHT.md) @@ -112,13 +112,15 @@ Module specific documentation. ## Earlier Release Notes - - [MaxScale 0.5 Release Notes](Release-Notes/MaxScale-0.5-Release-Notes.md) - - [MaxScale 0.6 Release Notes](Release-Notes/MaxScale-0.6-Release-Notes.md) - - [MaxScale 0.7 Release Notes](Release-Notes/MaxScale-0.7-Release-Notes.md) - - [MaxScale 1.0 Release Notes](Release-Notes/MaxScale-1.0-Release-Notes.md) - - [MaxScale 1.0.1 Release Notes](Release-Notes/MaxScale-1.0.1-Release-Notes.md) - - [MaxScale 1.0.3 Release Notes](Release-Notes/MaxScale-1.0.3-Release-Notes.md) - - [MaxScale 1.1.0 Release Notes](Release-Notes/MaxScale-1.1-Release-Notes.md) - - [MaxScale 1.1.1 Release Notes](Release-Notes/MaxScale-1.1.1-Release-Notes.md) + - [MaxScale 1.4.0 Release Notes](Release-Notes/MaxScale-1.4.0-Release-Notes.md) + - [MaxScale 1.3.0 Release Notes](Release-Notes/MaxScale-1.3.0-Release-Notes.md) - [MaxScale 1.2.0 Release Notes](Release-Notes/MaxScale-1.2.0-Release-Notes.md) + - [MaxScale 1.1.1 Release Notes](Release-Notes/MaxScale-1.1.1-Release-Notes.md) + - [MaxScale 1.1.0 Release Notes](Release-Notes/MaxScale-1.1-Release-Notes.md) + - [MaxScale 1.0.3 Release Notes](Release-Notes/MaxScale-1.0.3-Release-Notes.md) + - [MaxScale 1.0.1 Release Notes](Release-Notes/MaxScale-1.0.1-Release-Notes.md) + - [MaxScale 1.0 Release Notes](Release-Notes/MaxScale-1.0-Release-Notes.md) + - [MaxScale 0.7 Release Notes](Release-Notes/MaxScale-0.7-Release-Notes.md) + - [MaxScale 0.6 Release Notes](Release-Notes/MaxScale-0.6-Release-Notes.md) + - [MaxScale 0.5 Release Notes](Release-Notes/MaxScale-0.5-Release-Notes.md) diff --git a/Documentation/Filters/Database-Firewall-Filter.md b/Documentation/Filters/Database-Firewall-Filter.md index bd5c82a22..34124ec88 100644 --- a/Documentation/Filters/Database-Firewall-Filter.md +++ b/Documentation/Filters/Database-Firewall-Filter.md @@ -79,19 +79,27 @@ logged. The log messages are logged at the notice level. The rules are defined by using the following syntax: ``` -rule NAME deny [wildcard | columns VALUE ... | +rule NAME deny { wildcard | columns VALUE... | regex REGEX | limit_queries COUNT TIMEPERIOD HOLDOFF | - no_where_clause] [at_times VALUE...] [on_queries [select|update|insert|delete]] + no_where_clause } [at_times VALUE...] [on_queries [select | update | insert | delete]] ``` -Rules always define a blocking action so the basic mode for the database firewall filter is to allow all queries that do not match a given set of rules. Rules are identified by their name and have a mandatory part and optional parts. You can add comments to the rule files by adding the `#` character at the beginning of the line. +Rules are identified by their name and have mandatory parts and optional parts. +You can add comments to the rule files by adding the `#` character at +the beginning of the line. Trailing comments are not supported. The first step of defining a rule is to start with the keyword `rule` which identifies this line of text as a rule. The second token is identified as -the name of the rule. After that one of the mandatory action tokens, `deny` or -`allow`, is required to mark the start of the actual rule definition. Both -`deny` and `allow` function in the same way and the actual behavior of -the filter is determined by the `action` parameter. +the name of the rule. After that the mandatory action token `deny` is required +to mark the start of the actual rule definition. + +The rule definition must contain exactly one mandatory rule parameter. It can +also contain one of each type of optional rule parameter. + +**NOTE** +Even though the rules use the `deny` token, the action taken by the filter when +a query matches a rule is controlled _solely_ by the value of the `action` +parameter (_allow_, _block_ or _ignore_). ### Mandatory rule parameters diff --git a/Documentation/Getting-Started/Configuration-Guide.md b/Documentation/Getting-Started/Configuration-Guide.md index f6aef00d0..d15846b71 100644 --- a/Documentation/Getting-Started/Configuration-Guide.md +++ b/Documentation/Getting-Started/Configuration-Guide.md @@ -454,15 +454,23 @@ If not set, the default value is the server version of the embedded MySQL/MariaD #### `weightby` -The weightby parameter is used in conjunction with server parameters in order to control the load balancing applied in the router in use by the service. This allows varying weights to be applied to each server to create a non-uniform distribution of the load amongst the servers. +The weightby parameter is used in conjunction with server parameters in order to +control the load balancing applied in the router in use by the service. This +allows varying weights to be applied to each server to create a non-uniform +distribution of the load amongst the servers. -An example of this might be to define a parameter for each server that represents the amount of resource available on the server, we could call this serversize. Every server should then have a serversize parameter set for the server. +An example of this might be to define a parameter for each server that represents +the amount of resource available on the server, we could call this serversize. +Every server should then have a serversize parameter set for the server. ``` serversize=10 ``` -The service would then have the parameter weightby set. If there are 4 servers defined in the service, serverA, serverB, serverC and serverD, with the serversize set as shown in the table below, the connections would balanced using the percentages in this table. +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. Server |serversize|% connections ---------|----------|------------- @@ -471,6 +479,46 @@ serverB | 15 | 27% serverC | 10 | 18% serverD | 20 | 36% +Here is an excerpt from an example configuration with the `serv_weight` parameter +used as the weighting parameter. + +``` +[server1] +type=server +address=127.0.0.1 +port=3000 +protocol=MySQLBackend +serv_weight=3 + +[server2] +type=server +address=127.0.0.1 +port=3001 +protocol=MySQLBackend +serv_weight=1 + +[Read Service] +type=service +router=readconnroute +servers=server1,server2 +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. + +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. + +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. + #### `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. diff --git a/Documentation/Release-Notes/MaxScale-1.4.1-Release-Notes.md b/Documentation/Release-Notes/MaxScale-1.4.1-Release-Notes.md index aa632d775..b5473db85 100644 --- a/Documentation/Release-Notes/MaxScale-1.4.1-Release-Notes.md +++ b/Documentation/Release-Notes/MaxScale-1.4.1-Release-Notes.md @@ -4,7 +4,7 @@ Release 1.4.1 is a GA release. This document describes the changes in release 1.4.1, when compared to -release 1.4.0. +release [1.4.0](MaxScale-1.4.0-Release-Notes.md). For any problems you encounter, please consider submitting a bug report at [Jira](https://jira.mariadb.org). diff --git a/Documentation/Routers/ReadConnRoute.md b/Documentation/Routers/ReadConnRoute.md index a472acd55..77cdd0c57 100644 --- a/Documentation/Routers/ReadConnRoute.md +++ b/Documentation/Routers/ReadConnRoute.md @@ -10,64 +10,7 @@ The readconnroute router provides simple and lightweight load balancing across a Readconnroute router-specific settings are specified in the configuration file of MaxScale in its specific section. The section can be freely named but the name is used later as a reference from listener section. -The configuration consists of mandatory and optional parameters. - -## Mandatory parameters - -**`type`** specifies the type of service. For readconnroute module the type is `router`: - - type=router - -**`router`** specifies the router module to be used. For readconnroute the value is `readconnroute`: - - router=readconnroute - -**`servers`** provides a list of servers, which the router will connect to: - - servers=server1,server2,server3 - -**NOTE: Each server on the list must have its own section in the configuration file where it is defined.** - -**`user`** is the username the router session uses for accessing backends in order to load the content of the `mysql.user` table (and `mysql.db` and database names as well) and optionally for creating, and using `maxscale_schema.replication_heartbeat` table. - -**`passwd`** specifies corresponding password for the user. Syntax for user and passwd is: - -``` -user= -passwd= -``` - -## Optional parameters - -The **`weightby`** parameter defines the name of the value which is used to calculate the weights of the servers. Here is an example server configuration with the `serv_weight` parameter used as the weighting parameter. - -``` -[server1] -type=server -address=127.0.0.1 -port=3000 -protocol=MySQLBackend -serv_weight=3 - -[server2] -type=server -address=127.0.0.1 -port=3001 -protocol=MySQLBackend -serv_weight=1 - -[Read Service] -type=service -router=readconnroute -servers=server1,server2 -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. - -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. - -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. +For more details about the standard service parameters, refer to the [Configuration Guide](../Getting-Started/Configuration-Guide.md). ## Router Options @@ -95,7 +38,7 @@ For a list of readconnroute limitations, please read the [Limitations](../About/ The most common use for the readconnroute is to provide either a read or write port for an application. This provides a more lightweight routing solution than the more complex readwritesplit router but requires the application to be able to use distinct write and read ports. -To configure a read-only service that tolerates master failures, we first need to add a new section in to the configuration file. +To configure a read-only service that tolerates master failures, we first need to add a new section in to the configuration file. ``` [Read Service] @@ -105,6 +48,6 @@ servers=slave1,slave2,slave3 router_options=slave ``` -Here the `router_options`designates slaves as the only valid server type. With this configuration, the queries are load balanced across the slave servers. +Here the `router_options` designates slaves as the only valid server type. With this configuration, the queries are load balanced across the slave servers. For more complex examples of the readconnroute router, take a look at the examples in the [Tutorials](../Tutorials) folder. diff --git a/Documentation/Routers/ReadWriteSplit.md b/Documentation/Routers/ReadWriteSplit.md index 055918f05..941392772 100644 --- a/Documentation/Routers/ReadWriteSplit.md +++ b/Documentation/Routers/ReadWriteSplit.md @@ -12,41 +12,7 @@ The router is designed to be used with a traditional Master-Slave replication cl Readwritesplit router-specific settings are specified in the configuration file of MaxScale in its specific section. The section can be freely named but the name is used later as a reference from listener section. -The configuration consists of mandatory and optional parameters. - -## Mandatory parameters - -### `type` - -**`type`** specifies the type of service. For **readwritesplit** module the type is `router`: - - type=router - -### `router` - -**`router`** specifies the router module to be used. For **readwritesplit** the value is `readwritesplit`: - - router=readwritesplit - -### `servers` - -**`servers`** provides a list of servers, which must include one master and available slaves: - - servers=server1,server2,server3 - -**NOTE: Each server on the list must have its own section in the configuration file where it is defined.** - -### `user` -**`user`** is the username the router session uses for accessing backends in order to load the content of the `mysql.user` table (and `mysql.db` and database names as well) and optionally for creating, and using `maxscale_schema.replication_heartbeat` table. - -### `passwd` - -**`passwd`** specifies corresponding password for the user. Syntax for user and passwd is: - -``` -user= -passwd= -``` +For more details about the standard service parameters, refer to the [Configuration Guide](../Getting-Started/Configuration-Guide.md). ## Optional parameters @@ -81,16 +47,6 @@ When value all is used, queries reading session variables can be routed to any a In above-mentioned case the user-defined variable would only be updated in the master where query would be routed due to `INSERT` statement. -### `weightby` - -This parameter defines the name of the value which is used to calculate the -weights of the servers. The value should be the name of a parameter in the -server definitions and it should exist in all the servers used by this router. -For more information, see the description of the `weightby` parameter in -the [Configuration Guide](../Getting-Started/Configuration-Guide.md). - -No weighting is used by default. - ## 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`. diff --git a/Documentation/Routers/SchemaRouter.md b/Documentation/Routers/SchemaRouter.md index 01fa4a8f8..12cf1bbeb 100644 --- a/Documentation/Routers/SchemaRouter.md +++ b/Documentation/Routers/SchemaRouter.md @@ -42,16 +42,42 @@ GRANT SELECT,USAGE ON shard.* TO 'john'@'%'; This would in effect allow the user 'john' to only see the database 'shard' on this server. Take notice that these grants are matched against MaxScale's hostname instead of the client's hostname. Only user authentication uses the client's hostname and all other grants use MaxScale's hostname. -The schemarouter supports the following router options: +## Router options -|option |parameter |description| -|-------------------|-----------|-----------| -|max_sescmd_history |integer |Set a limit on the number of session modifying commands a session can execute. This sets an effective cap on the memory consumption of the session.| -|disable_sescmd_history|true, false|Disable the session command history. This will prevent growing memory consumption of a long-running session and allows pooled connections to MaxScale to be used. The drawback of this is the fact that if a server goes down, the session state will not be consistent anymore.| -|refresh_databases|true, false|Enable database map refreshing mid-session. These are triggered by a failure to change the database i.e. `USE ...``queries.| -|refresh_interval|float|The minimum interval between database map refreshes in seconds.| -|ignore_databases|string|List of databases to ignore when checking for duplicate databases.| -|ignore_databases_regex|string|Regular expression that is matched against database names when checking for duplicate databases.| +The following options are options for the `router_options` parameter of the +service. Multiple router options are given as a comma separated list of key +value pairs. + +### `ignore_databases` + +List of databases to ignore when checking for duplicate databases. + +### `ignore_databases_regex` + +Regular expression that is matched against database names when checking for duplicate databases. + +## Router options + +### `max_sescmd_history` + +Set a limit on the number of session modifying commands a session can execute. +This sets an effective cap on the memory consumption of the session. + +### `disable_sescmd_history` + +Disable the session command history. This will prevent growing memory consumption +of a long-running session and allows pooled connections to MaxScale to be used. +The drawback of this is the fact that if a server goes down, the session state +will not be consistent anymore. + +### `refresh_databases` + +Enable database map refreshing mid-session. These are triggered by a failure to +change the database i.e. `USE ...``queries. + +### `refresh_interval` + +The minimum interval between database map refreshes in seconds. ## Limitations