Overview

The Consistent Critical Read (CCR) filter allows consistent critical reads to be done through MaxScale while still allowing scaleout of non-critical reads.

When the filter detects a statement that would modify the database, it attaches a routing hint to all following statements done by that connection. This routing hint guides the routing module to route the statement to the primary server where data is guaranteed to be in an up-to-date state. Writes from one session do not, by default, propagate to other sessions.

Note: This filter does not work with prepared statements. Only text protocol queries are handled by this filter.

Controlling the Filter with SQL Comments

The triggering of the filter can be limited further by adding MaxScale supported comments to queries and/or by using regular expressions. The query comments take precedence: if a comment is found it is obeyed even if a regular expression parameter might give a different result. Even a comment cannot cause a SELECT-query to trigger the filter. Such a comment is considered an error and ignored.

The comments must follow the MaxScale hint syntax and the HintFilter needs to be in the filter chain before the CCR-filter. If a query has a MaxScale supported comment line which defines the parameter ccr, that comment is caught by the CCR-filter. Parameter values match and ignore are supported, causing the filter to trigger (match) or not trigger (ignore) on receiving the write query. For example, the query

would normally cause the filter to trigger, but does not because of the comment. The match-comment typically has no effect, since write queries by default trigger the filter anyway. It can be used to override an ignore-type regular expression that would otherwise prevent triggering.

Settings

The CCR filter has no mandatory parameters.

time

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 60s

The time window during which queries are routed to the primary. The duration can be specified as documented here but the value will always be rounded to the nearest second. If no explicit unit has been specified, the value is interpreted as seconds in MaxScale 2.4. In subsequent versions a value without a unit may be rejected. The default value for this parameter is 60 seconds.

When a data modifying SQL statement is processed, a timer is set to the value of_time_. Once the timer has elapsed, all statements are routed normally. If a new data modifying SQL statement is processed within the time window, the timer is reset to the value of time.

Enabling this parameter in combination with the count parameter causes both the time window and number of queries to be inspected. If either of the two conditions are met, the query is re-routed to the primary.

count

• Type: count

• Mandatory: No

• Dynamic: Yes

• Default: 0

The number of SQL statements to route to primary after detecting a data modifying SQL statement. This feature is disabled by default.

After processing a data modifying SQL statement, a counter is set to the value of count and all statements are routed to the primary. Each executed statement after a data modifying SQL statement cause the counter to be decremented. Once the counter reaches zero, the statements are routed normally. If a new data modifying SQL statement is processed, the counter is reset to the value of_count_.

match

• Type: regex

• Mandatory: No

• Dynamic: No

• Default: ""

These regular expression settings control which statements trigger statement re-routing. Only non-SELECT statements are inspected. For CCRFilter, the exclude-parameter is instead named ignore, yet works similarly.

ignore

• Type: regex

• Mandatory: No

• Dynamic: No

• Default: ""

See documentation for match.

options

• Type: enum

• Mandatory: No

• Dynamic: No

• Values: ignorecase, case, extended

• Default: ignorecase

Regular expression options for match and ignore.

global

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

global is a boolean parameter that when enabled causes writes from one connection to propagate to all other connections. This can be used to work around cases where one connection writes data and another reads it, expecting the write done by the other connection to be visible.

This parameter only works with the time parameter. The use of global andcount at the same time is not allowed and will be treated as an error.

Example Configuration

Here is a minimal filter configuration for the CCRFilter which should solve most problems with critical reads after writes.

With this configuration, whenever a connection does a write, all subsequent reads done by that connection will be forced to the primary for 5 seconds.

This prevents read scaling until the modifications have been replicated to the replicas. For best performance, the value of time should be slightly greater than the actual replication lag between the primary and its replicas. If the number of critical read statements is known, the count parameter could be used to control the number reads that are sent to the primary.

_{This page is licensed: CC BY-SA / Gnu FDL}

Configuration

To add the filter to a service, define an instance of the filter and then add it to a service's filters list:

Limitations

• If the SQL in the prepared statement is larger than 1677723 bytes, the prepared statement will not be cached.

• If the same SQL is prepared more than once at the same time, only one of them will succeed. This happens as the prepared statement reuse uses the SQL string in the comparison to detect if a statement is already prepared.

_{This page is licensed: CC BY-SA / Gnu FDL}

session_script

• After the session script is loaded, the newSession function in the Lua scripts is called. The first parameter is the username of the client and the second parameter is the client's network address.

Overview

The throttle filter is used to limit the maximum query frequency (QPS - queries per second) of a database session to a configurable value. The main use cases are to prevent a rogue session (client side error) and a DoS attack from overloading the system.

The throttling is dynamic. The query frequency is not limited to an absolute value. Depending on the configuration the throttle will allow some amount of high frequency queries, or especially short bursts with no frequency limitation.

Configuration

Basic Configuration

This configuration states that the query frequency will be throttled to around 500 qps, and that the time limit a query is allowed to stay at the maximum frequency is 60 seconds. All values involving time are configured in milliseconds. With the basic configuration the throttling will be nearly immediate, i.e. a session will only be allowed very short bursts of high frequency querying.

When a session has been continuously throttled for throttling_duration milliseconds, or 60 seconds in this example, MaxScale will disconnect the session.

Allowing high frequency bursts

The two parameters max_qps and sampling_duration together define how a session is throttled.

Suppose max qps is 400 qps and sampling duration is 10 seconds. Since QPS is not an instantaneous measure, but one could say it has a granularity of 10 seconds, we see that over the 10 seconds 10*400 = 4000 queries are allowed before throttling kicks in.

With these values, a fresh session can start off with a speed of 2000 qps, and maintain that speed for 2 seconds before throttling starts.

If the client continues to query at high speed and throttling duration is set to 10 seconds, Maxscale will disconnect the session 12 seconds after it started.

Settings

max_qps

• Type: number

• Mandatory: Yes

• Dynamic: Yes

Maximum queries per second.

This is the frequency to which a session will be limited over a given time period. QPS is not measured as an instantaneous value but over a configurable sampling duration (see sampling_duration).

throttling_duration

• Type: duration

• Mandatory: Yes

• Dynamic: Yes

This defines how long a session is allowed to be throttled before MaxScale disconnects the session.

sampling_duration

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 250ms

Sampling duration defines the window of time over which QPS is measured. This parameter directly affects the amount of time that high frequency queries are allowed before throttling kicks in.

The lower this value is, the more strict throttling becomes. Conversely, the longer this time is, the longer bursts of high frequency querying is allowed.

continuous_duration

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 2s

This value defines what continuous throttling means. Continuous throttling starts as soon as the filter throttles the frequency. Continuous throttling ends when no throttling has been performed in the past continuous_duration time.

_{This page is licensed: CC BY-SA / Gnu FDL}

The examples will use Rewrite Filter file format. See below.

Syntax

Native syntax

Rewriter native syntax uses placeholders to grab and replace parts of text.

Placeholders

The syntax for a plain placeholder is @{N} where N is a positive integer.

The syntax for a placeholder regex is @{N:regex}. It allows more control when needed.

The below is a valid entry in rf format. For demonstration, all options are set. This entry is a do-nothing entry, but illustrates placeholders.

If the input sql is select id, name from my_table where id = 42 then @{2} = "id, name" and @{3} = "42". Since the replace template is identical to the match template the end result is that the output sql will be the same as the input sql.

Placeholders can be used as forward references.@{1:^}select @{2}, count(*) from @{3} group by @{2}. For a match, the two @{2} text grabs must be equal.

Match template

The match template is used to match against the sql to be rewritten.

The match template can be partial from mytable. But the actual underlying regex match is always for the whole sql. If the match template does not start or end with a placeholder, placeholders are automatically added so that the above becomes @{1}from mytable@{2}. The automatically added placeholders cannot be used in the replace template.

Matching the whole input also means that Native syntax does not support (and is not intended to support) scan and replace. Only the first occurrence of the above from mytable can be modified in the replace template. However, one can selectively choose to modify e.g. the first through third occurrence of from mytable by writingfrom mytable @{1} from mytable @{2} from mytable @{3}.

For scan and replace use a different regex_grammar (see below).

Replace template

The replace template uses the placeholders from the match template to rewrite sql.

An important option for smooth matching is ignore_whitespace, which is on (true) by default. It creates the match regex in such a way that the amount and kind of whitespace does not affect matching. However, to make ignore_whitespace always work, it is important to add whitespace where allowed. If "id=42" is in the match template then only the exact "id=42" can match. But if "id = 42" is used, andignore_whitespace is on, both "id=42" and "id = 42" will match.

Another example, and what not to do:

That works, but because the match lacks specific detail about the expected sql, things are likely to break. In this caseshow indexes from my_table would no longer work.

The minimum detail in this case could be:

but if more detail is known, like something specific in the where clause, that too should be added.

Placeholder Regex

Syntax: @{N:regex}

In a placeholder regex the character } must be escaped to \} (for literal matching). Plain parenthesis "()" indicate capturing groups, which are internally used by the Native grammar. Thus plain parentheses in a placeholder regex will break matching. However, non-capturing groups can be used: e.g. @{1:(:?Jane|Joe)}. To match a literal parenthesis use an escape, e.g. \(.

Suppose an application is misbehaving after an upgrade and a quick fix is needed. This query select zip from address_book where str_id = "AZ-124" is correct, but if the id is an integer the where clause should be id = 1234.

Using plain regular expressions

For scan and replace the regex_grammar must be set to something else than Native. An example will illustrate the usage.

Replace all occurrences of "wrong_table_name" with "correct_table_name". Further, if the replacement was made then replace all occurrences of wrong_column_name with correct_column_name.

Configuration

Adding a rewrite filter.

Settings

template_file

• Type: string

• Mandatory: Yes

• Dynamic: Yes

• Default: No default value

Path to the template file.

regex_grammar

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: Native

• Values: Native, ECMAScript, Posix, EPosix, Awk, Grep, EGrep

Default regex_grammar for templates

case_sensitive

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: true

Default case sensitivity for templates

log_replacement

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

Log replacements at NOTICE level.

Settings per template in the template file

regex_grammar

• Type: string

• Values: Native, ECMAScript, Posix, EPosix, Awk, Grep, EGrep

• Default: From maxscale.cnf

Overrides the global regex_grammar of a template.

case_sensitive

• Type: boolean

• Default: From maxscale.cnf

Overrides the global case sensitivity of a template.

ignore_whitespace

• Type: boolean

• Default: true

Ignore whitespace differences in the match template and input sql.

continue_if_matched

• Type: boolean

• Default: false

If a template matches and the replacement is done, continue to the next template and apply it to the result of the previous rewrite.

what_if

• Type: boolean

• Default: false

Do not make the replacement, only log what would have been replaced (NOTICE level).

Rewrite file format

The rf format for an entry is:

The character # starts a single line comment when it is the first character on a line.

Empty lines are ignored.

The rf format does not need any additional escaping to what the basic format requires (see Placeholder Regex).

Options are specified as follows:

The colon must stick to the option name.

The separators % and %% must be the exact content of their respective separator lines.

The templates can span multiple lines. Whitespace does not matter as long as ignore_whitespace = true. Always use space where space is allowed to maximize the utility ofignore_whitespace.

Example

Json file format

The json file format is harder to read and edit manually. It will be needed if support for editing of rewrite templates is added to the GUI.

All double quotes and escape characters have to be escaped in json, i.e '"' and '\'.

The same example as above is:

Reload template file

The configuration is re-read if any dynamic value is updated even if the value does not change.

Reference

• ECMAScript ECMAScript

• Posix V1_chap09.html#tag_09_03

• EPosix V1_chap09.html#tag_09_04

• Awk

• Grep Same as Posix with the addition of newline '\n' as an alternation separator.

• EGrep Same as EPosix with the addition of newline '\n' as an alternation separator in addition to '|'.

_{This page is licensed: CC BY-SA / Gnu FDL}

Overview

The Regex filter is a filter module for MariaDB MaxScale that is able to rewrite query content using regular expression matches and text substitution. The regular expressions use the PCRE2 syntax.

PCRE2 library uses a different syntax than POSIX to refer to capture groups in the replacement string. The main difference is the usage of the dollar character instead of the backslash character for references e.g. $1 instead of\1. For more details about the replacement string differences, please read the Creating a new string with substitutions chapter in the PCRE2 manual.

Configuration

The following demonstrates a minimal configuration.

Settings

The Regex filter has two mandatory parameters: match and replace.

match

• Type: regex

• Mandatory: Yes

• Dynamic: Yes

Defines the text in the SQL statements that is replaced.

options

• Type: enum

• Mandatory: No

• Dynamic: Yes

• Values: ignorecase, case, extended

• Default: ignorecase

The options-parameter affects how the patterns are compiled as usual.

replace

• Type: string

• Mandatory: Yes

• Dynamic: Yes

This is the text that should replace the part of the SQL-query matching the pattern defined in match.

source

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: None

The optional source parameter defines an address that is used to match against the address from which the client connection to MariaDB MaxScale originates. Only sessions that originate from this address will have the match and replacement applied to them.

user

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: None

The optional user parameter defines a username that is used to match against the user from which the client connection to MariaDB MaxScale originates. Only sessions that are connected using this username will have the match and replacement applied to them.

log_file

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: None

The optional log_file parameter defines a log file in which the filter writes all queries that are not matched and matching queries with their replacement queries. All sessions will log to this file so this should only be used for diagnostic purposes.

log_trace

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: None

The optional log_trace parameter toggles the logging of non-matching and matching queries with their replacements into the log file on the info level. This is the preferred method of diagnosing the matching of queries since the log level can be changed at runtime. For more details about logging levels and session specific logging, please read the Configuration Guide.

Examples

Example 1 - Replace MySQL 5.1 create table syntax with that for later versions

MySQL 5.1 used the parameter TYPE = to set the storage engine that should be used for a table. In later versions this changed to be ENGINE =. Imagine you have an application that you cannot change for some reason, but you wish to migrate to a newer version of MySQL. The regexfilter can be used to transform the create table statements into the form that could be used by MySQL 5.5

_{This page is licensed: CC BY-SA / Gnu FDL}

Overview

The Maxrows filter is capable of restricting the amount of rows that a SELECT, a prepared statement or stored procedure could return to the client application.

If a resultset from a backend server has more rows than the configured limit or the resultset size exceeds the configured size, an empty result will be sent to the client.

Configuration

The Maxrows filter is easy to configure and to add to any existing service.

Settings

The Maxrows filter has no mandatory parameters. Optional parameters are:

max_resultset_rows

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: (no limit)

Specifies the maximum number of rows a resultset can have in order to be returned to the user.

If a resultset is larger than this an empty result will be sent instead.

max_resultset_size

• Type: size

• Mandatory: No

• Dynamic: Yes

• Default: 64Ki

Specifies the maximum size a resultset can have in order to be sent to the client. A resultset larger than this, will not be sent: an empty resultset will be sent instead.

max_resultset_return

• Type: enum

• Mandatory: No

• Dynamic: Yes

• Values: empty, error, ok

• Default: empty

Specifies what the filter sends to the client when the rows or size limit is hit, possible values:

• an empty result set

• an error packet with input SQL

• an OK packet

Example output with ERR packet:

debug

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: 0

An integer value, using which the level of debug logging made by the Maxrows filter can be controlled. The value is actually a bitfield with different bits denoting different logging.

• 0 (0b00000) No logging is made.

• 1 (0b00001) A decision to handle data form server is logged.

• 2 (0b00010) Reached max_resultset_rows or max_resultset_size is logged.

To log everything, give debug a value of 3.

Example Configuration

Here is an example of filter configuration where the maximum number of returned rows is 10000 and maximum allowed resultset size is 256KB

_{This page is licensed: CC BY-SA / Gnu FDL}

Overview

With the masking filter it is possible to obfuscate the returned value of a particular column.

For instance, suppose there is a table person that, among other columns, contains the column ssn where the social security number of a person is stored.

With the masking filter it is possible to specify that when the ssn field is queried, a masked value is returned unless the user making the query is a specific one. That is, when making the query

instead of getting the real result, as in

the ssn would be masked, as in

Note that the masking filter should be viewed as a best-effort solution intended for protecting against accidental misuse rather than malicious attacks.

Security

From MaxScale 2.3 onwards, the masking filter will reject statements that use functions in conjunction with columns that should be masked. Allowing function usage provides a way for circumventing the masking, unless a firewall filter is separately configured and installed.

Please see the configuration parameter prevent_function_usage for how to change the default behaviour.

From MaxScale 2.3.5 onwards, the masking filter will check the definition of user variables and reject statements that define a user variable using a statement that refers to columns that should be masked.

Please see the configuration parameter check_user_variables for how to change the default behaviour.

From MaxScale 2.3.5 onwards, the masking filter will examine unions and if the second or subsequent SELECT refer to columns that should be masked, the statement will be rejected.

Please see the configuration parameter check_unions for how to change the default behaviour.

From MaxScale 2.3.5 onwards, the masking filter will examine subqueries and if a subquery refers to columns that should be masked, the statement will be rejected.

Please see the configuration parameter check_subqueries for how to change the default behaviour.

Note that in order to ensure that it is not possible to get access to masked data, the privileges of the users should be minimized. For instance, if a user can create tables and perform inserts, he or she can execute something like

to get access to the cleartext version of a masked field ssn.

From MaxScale 2.3.5 onwards, the masking filter will, if any of theprevent_function_usage, check_user_variables, check_unions orcheck_subqueries parameters is set to true, block statements that cannot be fully parsed.

Please see the configuration parameter require_fully_parsed for how to change the default behaviour.

From MaxScale 2.3.7 onwards, the masking filter will treat any strings passed to functions as if they were fields. The reason is that as the MaxScale query classifier is not aware of whether ANSI_QUOTES is enabled or not, it is possible to bypass the masking by turning that option on.

Before this change, the content of the field ssn would have been returned in clear text even if the column should have been masked.

Note that this change will mean that there may be false positives if ANSI_QUOTES is not enabled and a string argument happens to be the same as the name of a field to be masked.

Please see the configuration parameter [treat_string_arg_as_field(#treat_string_arg_as_field) for how to change the default behaviour.

Limitations

The masking filter can only be used for masking columns of the following types: BINARY, VARBINARY, CHAR, VARCHAR, BLOB, TINYBLOB,MEDIUMBLOB, LONGBLOB, TEXT, TINYTEXT, MEDIUMTEXT, LONGTEXT,ENUM and SET. If the type of the column is something else, then no masking will be performed.

Currently, the masking filter can only work on packets whose payload is less than 16MB. If the masking filter encounters a packet whose payload is exactly that, thus indicating a situation where the payload is delivered in multiple packets, the value of the parameter large_payloads specifies how the masking filter should handle the situation.

Configuration

The masking filter is taken into use with the following kind of configuration setup.

Settings

The masking filter has one mandatory parameter - rules.

rules

• Type: path

• Mandatory: Yes

• Dynamic: Yes

Specifies the path of the file where the masking rules are stored. A relative path is interpreted relative to the module configuration directory of MariaDB MaxScale. The default module configuration directory is_/etc/maxscale.modules.d_.

warn_type_mismatch

• Type: enum

• Mandatory: No

• Dynamic: Yes

• Values: never, always

• Default: never

With this optional parameter the masking filter can be instructed to log a warning if a masking rule matches a column that is not of one of the allowed types.

large_payload

• Type: enum

• Mandatory: No

• Dynamic: Yes

• Values: ignore, abort

• Default: abort

This optional parameter specifies how the masking filter should treat payloads larger than 16MB, that is, payloads that are delivered in multiple MySQL protocol packets.

The values that can be used are ignore, which means that columns in such payloads are not masked, and abort, which means that if such payloads are encountered, the client connection is closed. The default is abort.

Note that the aborting behaviour is applied only to resultsets that contain columns that should be masked. There are no limitations on resultsets that do not contain such columns.

prevent_function_usage

• Type: bool

• Mandatory: No

• Dynamic: Yes

• Default: true

This optional parameter specifies how the masking filter should behave if a column that should be masked, is used in conjunction with some function. As the masking filter works only on the basis of the information in the returned result-set, if the name of a column is not present in the result-set, then the masking filter cannot mask a value. This means that the masking filter basically can be bypassed with a query like:

If the value of prevent_function_usage is true, then all statements that contain functions referring to masked columns will be rejected. As that means that also queries using potentially harmless functions, such as LENGTH(masked_column), are rejected as well, this feature can be turned off. In that case, the firewall filter should be setup to allow or reject the use of certain functions.

require_fully_parsed

• Type: bool

• Mandatory: No

• Dynamic: Yes

• Default: true

This optional parameter specifies how the masking filter should behave in case any of prevent_function_usage, check_user_variables,check_unions or check_subqueries is true and it encounters a statement that cannot be fully parsed,

If true, then statements that cannot be fully parsed (due to a parser limitation) will be blocked.

Note that if this parameter is set to false, then prevent_function_usage,check_user_variables, check_unions and check_subqueries are rendered less effective, as it with a statement that cannot be fully parsed may be possible to bypass the protection that they are intended to provide.

treat_string_arg_as_field

• Type: bool

• Mandatory: No

• Dynamic: Yes

• Default: true

This optional parameter specifies how the masking filter should treat strings used as arguments to functions. If true, they will be handled as fields, which will cause fields to be masked even if ANSI_QUOTES has been enabled and " is used instead of backtick.

check_user_variables

• Type: bool

• Mandatory: No

• Dynamic: Yes

• Default: true

This optional parameter specifies how the masking filter should behave with respect to user variables. If true, then a statement like

will be rejected if ssn is a column that should be masked.

check_unions

• Type: bool

• Mandatory: No

• Dynamic: Yes

• Default: true

This optional parameter specifies how the masking filter should behave with respect to UNIONs. If true, then a statement like

will be rejected if b is a column that should be masked.

check_subqueries

• Type: bool

• Mandatory: No

• Dynamic: Yes

• Default: true

This optional parameter specifies how the masking filter should behave with respect to subqueries. If true, then a statement like

will be rejected if a is a column that should be masked.

Rules

The masking rules are expressed as a JSON object.

The top-level object is expected to contain a key rules whose value is an array of rule objects.

Each rule in the rules array is a JSON object, expected to contain the keys replace, with, applies_to andexempted. The two former ones are obligatory and the two latter ones optional.

replace

The value of this key is an object that specifies the column whose values should be masked. The object must contain the keycolumn and may contain the keys table and database. The value of these keys must be a string.

If only column is specified, then a column with that name matches irrespective of the table and database. If table is specified, then the column matches only if it is in a table with the specified name, and if database is specified when the column matches only if it is in a database with the specified name.

NOTE If a rule contains a table/database then if the resultset does not contain table/database information, it will always be considered a match if the column matches. For instance, given the rule above, if there is a table person2, also containing an ssn field, then a query like

will not return masked values, but a query like

will only return masked values, even if the ssn values fromperson2 in principle should not be masked. The same effect is observed even with a nonsensical query like

even if nothing from person2 should be masked. The reason is that as the resultset contains no table information, the values must be masked if the column name matches, as otherwise the masking could easily be circumvented with a query like

The optional key match makes partial replacement of the original value possible: only the matched part would be replaced with the fill character. The match value must be a valid pcre2 regular expression.

obfuscate

The obfuscate rule allows the obfuscation of the value by passing it through an obfuscation algorithm. Current solution uses a non-reversible obfuscation approach.

However, note that although it is in principle impossible to obtain the original value from the obfuscated one, if the range of possible original values is limited, it is straightforward to figure out the possible original values by running all possible values through the obfuscation algorithm and then comparing the results.

The minimal configuration is:

Output example for Db field name = 'remo'

with

The value of this key is an object that specifies what the value of the matched column should be replaced with for the replace rule. Currently, the object is expected to contain either the key value or the key fill. The value of both must be a string with length greater than zero. If both keys are specified, value takes precedence. If fill is not specified, the default X is used as its value.

If value is specified, then its value is used to replace the actual value verbatim and the length of the specified value must match the actual returned value (from the server) exactly. If the lengths do not match, the value offill is used to mask the actual value.

When the value of fill (fill-value) is used for masking the returned value, the fill-value is used as many times as necessary to match the length of the return value. If required, only a part of the fill-value may be used in the end of the mask value to get the lengths to match.

applies_to

With this optional key, whose value must be an array of strings, it can be specified what users the rule is applied to. Each string should be a MariaDB account string, that is, % is a wildcard.

If this key is not specified, then the masking is performed for all users, except the ones exempted using the key exempted.

exempted

With this optional key, whose value must be an array of strings, it can be specified what users the rule is not applied to. Each string should be a MariaDB account string, that is, % is a wildcard.

Module commands

Read Module Commands documentation for details about module commands.

The masking filter supports the following module commands.

reload

Reload the rules from the rules file. The new rules are taken into use only if the loading succeeds without any errors.

MyMaskingFilter refers to a particular filter section in the MariaDB MaxScale configuration file.

Example

In the following we configure a masking filter MyMasking that should always log a warning if a masking rule matches a column that is of a type that cannot be masked, and that should abort the client connection if a resultset package is larger than 16MB. The rules for the masking filter are in the file masking_rules.json.

Configuration

masking_rules.json

The rules specify that the data of a column whose name is ssn, should be replaced with the string 012345-ABCD. If the length of the data is not exactly the same as the length of the replacement value, then the data should be replaced with as many X characters as needed.

_{This page is licensed: CC BY-SA / Gnu FDL}