Merge branch 'develop' into MAX-324

Conflicts:
	server/include/modutil.h

filters/Firewall-Filter.md

@@ -7,11 +7,12 @@ The firewall filter is used to block queries that match a set of rules. It can b
 
 The firewall filter only requires a minimal set of configurations in the MaxScale.cnf file. The actual rules of the firewall filter are located in a separate text file. The following is an example of a firewall filter configuration in the MaxScale.cnf file.
 
-
+```
-    [Firewall]
+[Firewall]
-    type=filter
+type=filter
-    module=fwfilter
+module=fwfilter
-    rules=/home/user/rules.txt
+rules=/home/user/rules.txt
+```
 
 ### Filter Options
 
@@ -25,9 +26,11 @@ The firewall filter has one mandatory parameter that defines the location of the
 
 The rules are defined by using the following syntax.
 
-`         rule NAME deny [wildcard | columns VALUE ... |
+```
-          regex REGEX | limit_queries COUNT TIMEPERIOD HOLDOFF |
+rule NAME deny [wildcard | columns VALUE ... |
-          no_where_clause] [at_times VALUE...] [on_queries [select|update|insert|delete]]`
+     regex REGEX | limit_queries COUNT TIMEPERIOD HOLDOFF |
+      no_where_clause] [at_times VALUE...] [on_queries [select|update|insert|delete]]`
+```
 
 Rules always define a blocking action so the basic mode for the 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.
 
@@ -81,30 +84,38 @@ After this either the keyword `any` `all` or `strict_all` is expected. This defi
 
 After the matching part comes the rules keyword after which a list of rule names is expected. This allows reusing of the rules and enables varying levels of query restriction.
 
-## Examples
+## Use Cases
 
-### Example rule file
+### Use Case 1 - Prevent rapid execution of specific queries
 
-The following is an example of a rule file which defines six rules and applies them to three sets of users. This rule file is used in all of the examples.
+To prevent the excessive use of a database we want to set a limit on the rate of queries. We only want to apply this limit to certain queries that cause unwanted behavior. To achieve this we can use a regular expression.
 
-    rule block_wildcard deny wildcard at_times 8:00:00-17:00:00
+First we define the limit on the rate of queries. The first parameter for the rule sets the number of allowed queries to 10 queries and the second parameter sets the rate of sampling to 5 seconds. If a user executes queries faster than this, any further queries that match the regular expression are blocked for 60 seconds.
-    rule no_personal_info deny columns phone salary address on_queries select|delete at_times  12:00:00-18:00:00
-    rule simple_regex deny regex '.*insert.*into.*select.*'
-    rule dos_block deny limit_queries 10000 1.0 500.0 at_times 12:00:00-18:00:00
-    rule safe_delete deny no_where_clause on_queries delete
-    rule managers_table deny regex '.*from.*managers.*'
-    users John@% Jane@% match any rules no_personal_info block_wildcard
-    users %@80.120.% match any rules block_wildcard dos_block
-    users %@% match all rules safe_delete managers_table
 
-### Example 1 - Deny access to personal information and prevent huge queries during peak hours
+```
+rule limit_rate_of_queries deny limit_queries 10 5 60
+rule query_regex deny regex '.*select.*from.*user_data.*'
+```
 
-Assume that a database cluster with tables that have a large number of columns is under heavy load during certain times of the day. Now also assume that large selects and querying of personal information creates unwanted stress on the cluster. Now we wouldn't want to completely prevent all the users from accessing personal information or performing large select queries, we only want to block the users John and Jane.
+To apply these rules we combine them into a single rule by adding a `users` line to the rule file.
 
-This can be achieved by creating two rules. One that blocks the usage of the wildcard and one that prevents queries that target a set of columns. To apply these rules to the users we define a users line into the rule file with both the rules and all the users we want to apply the rules to. The rules are defined in the example rule file on line 1 and 2 and the users line is defined on line 7.
+```
+users %@% match all rules limit_rate_of_queries query_regex
+```
 
-### Example 2 - Only safe deletes into the managers table
+### Use Case 2 - Only allow deletes with a where clause
 
-We want to prevent accidental deletes into the managers table where the where clause is missing. This poses a problem, we don't want to require all the delete queries to have a where clause. We only want to prevent the data in the managers table from being deleted without a where clause.
+We have a table which contains all the managers of a company. We want to prevent accidental deletes into this table where the where clause is missing. This poses a problem, we don't want to require all the delete queries to have a where clause. We only want to prevent the data in the managers table from being deleted without a where clause.
 
-To achieve this, we need two rules. The first rule can be seen on line 5 in the example rule file. This defines that all delete operations must have a where clause. This rule alone does us no good so we need a second one. The second rule is defined on line 6 and it blocks all queries that match the provided regular expression. When we combine these two rules we get the result we want. You can see the application of these rules on line 9 of the example rule file. The usage of the `all` and `strict_all` matching mode requires that all the rules must match for the query to be blocked. This in effect combines the two rules into a more complex rule.
+To achieve this, we need two rules. The first rule defines that all delete operations must have a where clause. This rule alone does us no good so we need a second one. The second rule blocks all queries that match a regular expression.
+
+```
+rule safe_delete deny no_where_clause on_queries delete
+rule managers_table deny regex '.*from.*managers.*'
+```
+
+When we combine these two rules we get the result we want. To combine these two rules add the following line to the rule file.
+
+```
+users %@% match all rules safe_delete managers_table
+```