hcq/MaxScale
hcq/MaxScale
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merged documentation changes

Browse Source 
Merged the documentation changes between the 1.4.1 and 1.4.2 releases from
MaxScale-Documentation.
This commit is contained in:
Markus Makela 2016-04-25 14:19:56 +03:00
parent 3046b4a46e
commit 40ffc10120
7 changed files with 117 additions and 134 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
Documentation/Documentation-Contents.md
View File

@ -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)

22
Documentation/Filters/Database-Firewall-Filter.md
View File

@ -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

54
Documentation/Getting-Started/Configuration-Guide.md
View File

@ -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.

2
Documentation/Release-Notes/MaxScale-1.4.1-Release-Notes.md
View File

@ -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).

63
Documentation/Routers/ReadConnRoute.md
View File

@ -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=<username>
passwd=<password>
```
## 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.

46
Documentation/Routers/ReadWriteSplit.md
View File

@ -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=<username>
passwd=<password>
```
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`.

44
Documentation/Routers/SchemaRouter.md
View File

@ -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