This document describes how to configure MariaDB MaxScale and presents some
possible usage scenarios. 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 program.
A server represents an individual database server to which a client can be
connected via MariaDB MaxScale. The status of a server varies during the lifetime
of the server and typically the status is updated by some monitor. However, it
is also possible to update the status of a server manually.
For more information on how to manually set these states via MaxCtrl, read the .
A monitor module is capable of monitoring the state of a particular kind
of cluster and making that state available to the routers of MaxScale.
Examples of monitor modules are mariadbmon that is capable of monitoring
a regular primary-replica cluster and in addition of performing both switchover
and failover, galeramon that is capable of monitoring a Galera cluster,
and csmon that is capable of monitoring a Columnstore cluster.
Monitor modules have sections of their own in the MaxScale configuration
file.
A filter module resides in front of routers in the request processing chain
of MaxScale. That is, a filter will see a request before it reaches the router
and before a response is sent back to the client. This allows filters to
reject, handle, alter or log information about a request.
Examples of filters cache that provides query caching according to rules,regexfilter that can rewrite requests according to regular expressions, andqlafilter that logs information about requests.
Filters have sections of their own in the MaxScale configuration file that are
referred to from services.
A router module is capable of routing requests to backend servers according to
the characteristics of a request and/or the algorithm the router
implements. Examples of routers are readconnroute that provides connection
&#xNAN;routing, that is, the server is chosen according to specified rules when the
session is created and all requests are subsequently routed to that server,
and readwritesplit that provides statement routing, that is, each
individual request is routed to the most appropriate server.
Routers do not have sections of their own in the MaxScale configuration file,
but are referred to from services.
A service abstracts a set of databases and makes them appear as a single one
to the client. Depending on what router (e.g. readconnroute orreadwritesplit) the service uses, the servers are used in some particular
way. If the service uses filters, then all requests will be pre-processed in
some way before they reach the router.
Services have sections of their own in the MaxScale configuration file.
A listener defines a port MaxScale listens on. Connection requests arriving on
that port will be forwarded to the service the listener is associated with. A
listener may be associated with a single service, but several listeners may be
associated with the same service.
Listeners have sections of their own in the MaxScale configuration file.
The administation of MaxScale can be divided in two parts:
Writing the MaxScale configuration file, which is described in the following .
Performing runtime modifications using
For detailed information about MaxCtrl please refer to the specific
documentation referred to above. In the following it will only be explained how
MaxCtrl relate to each other, as far as user credentials go.
Note: By default all runtime configuration changes are saved on disk and
loaded on startup. Refer to the section for more details
on how it works and how to disable it.
MaxCtrl can connect using TCP/IP sockets. When connecting with MaxCtrl using
TCP/IP sockets, the user and password must be provided and are checked against a
separate user credentials database. By default, that database contains the useradmin whose password is mariadb.
Note that if MaxCtrl is invoked without explicitly providing a user and password
then it will by default use admin and mariadb. That means that when the
default user is removed, the credentials must always be provided.
Administration audit file
The REST API calls to MaxScale can be logged
by enabling .
For more detail see the admin audit configuration values admin_audit,admin_audit_file and admin_audit_exclude_methods below
and .
Static Configuration Parameters
The following list of global configuration parameters can NOT be changed at
runtime and can only be defined in a configuration file:
All other parameters that relate to objects can be altered at runtime or can be
changed by destroying and recreating the object in question.
MaxScale by default reads configuration from the file /etc/maxscale.cnf. If
the command line argument --configdir=<path> is given, maxscale.cnf is
searched for in <path> instead. If the argument --config=<file> is given,
configuration is read from the file <file>.
MaxScale also looks for a directory with the same name as the configuration
file, followed by ".d" (for example /etc/maxscale.cnf.d). If found, MaxScale
recursively reads all files with the ".cnf" suffix in the directory hierarchy.
Other files are ignored.
After loading normal configuration files, MaxScale reads runtime-generated
configuration files, if any, from the .
Different configuration sections can be arranged with little restrictions.
Global path settings such as logdir, piddir and datadir are only read from
the main configuration file. Other global settings are also best left in the
main file to ensure they are read before other configuration sections are
parsed.
The configuration file format used is , similar to the
MariaDB Server. The files contain sections and each section can contain multiple
key-value pairs.
Comments are defined by prefixing a row with a hash (#). Trailing comments are
not supported.
A parameter can be defined on multiple lines as shown below. A value spread over
multiple lines is simply concatenated. The additional lines of the value
definition need to have at least one whitespace character in the beginning.
Section names may not contain whitespace and must not start with the characters@@.
As the object names are used to form URLs in the MaxScale REST API, they must be
safe for use in URLs. This means that only alphanumeric characters (i.e. a-zA-Z and 0-9) and the special characters _.~- can be used.
Dynamic Configuration
By default all changes done at runtime via the MaxScale GUI, MaxCtrl or the REST
API will be saved on disk, inside the directory. The
changes done at runtime will override the configuration found in the static
configuration files for that particular object.
This means that if an object that is found in /etc/maxscale.cnf is modified at
runtime, all future changes to it must also be done at runtime. Any
modifications done to /etc/maxscale.cnf after a runtime change has been made
are ignored for that object.
To prevent the saving of runtime changes and to make all runtime changes
volatile, add and under the [maxscale]
section. This will make MaxScale behave like the MariaDB server does: any
changes done with SET GLOBAL statements are lost if the process is restarted.
Special Parameter Types
Boolean type parameters interpret the values true, yes, on and 1 as_true_ values and false, no, off and 0 as false values. Starting with
MaxScale 23.02, the REST API also accepts the same boolean values for boolean
type parameters.
Where specifically noted, a number denoting a size can be suffixed by a subset
of the IEC binary prefixes or the SI prefixes. In the former case the number
will be interpreted as a certain multiple of 1024 and in the latter case as a
certain multiple of 1000. The supported IEC binary suffixes are Ki, Mi, Gi
and Ti and the supported SI suffixes are k, M, G and T. In both cases,
the matching is case insensitive.
For instance, the following entries
are equivalent, as are the following
A number denoting a duration can be suffixed by one of the case-insensitive
suffixes h, m or min, s and ms, for specifying durations in hours,
minutes, seconds and milliseconds, respectively.
For instance, the following entries
are equivalent.
Note that if an explicit unit is not specified, then it is specific to the
configuration parameter whether the duration is interpreted as seconds or
milliseconds.
Not providing an explicit unit has been deprecated in MaxScale 2.4.
Regular Expressions
Many modules have settings which accept a regular expression. In most cases, these
settings are named either match or exclude, and are used to filter users or queries.
MaxScale uses the for matching
regular expressions.
When writing a regular expression (regex) type parameter to a MaxScale configuration file,
the pattern string should be enclosed in slashes e.g. ^select -> match=/^select/. This
clarifies where the pattern begins and ends, even if it includes whitespace. Without
slashes the configuration loader trims the pattern from the ends. The slashes are removed
before compiling the pattern. For backwards compatibility, the slashes are not yet
mandatory. Omitting them is, however, deprecated and will be rejected in a future release
of MaxScale. Currently, binlogfilter, ccrfilter, qlafilter, tee and avrorouter
accept parameters in this type of regular expression form. Some other modules may not
handle the slashes yet correctly.
PCRE2 supports a complicated regular expression . MaxScale typically uses
regular expressions simply, only checking whether the pattern and subject match at some
point. For example, using the QLAFilter and setting match=/SELECT/ causes the filter to
accept any query with the text "SELECT" somewhere within. To force the pattern to only
match at the beginning of the query, set match=/^SELECT/. To only match the end, setmatch=/SELECT$/.
Modules which accept regular expression parameters also often accept options which affect
how the patterns are compiled. Typically, this setting is called options and accepts
values such as ignorecase, case and extended.
ignorecase: Causes the regular expression matcher to ignore letter case, and
is often on by default. When enabled, /SELECT/ would match both SELECT andselect.
extended: Ignores whitespace and # comments in the pattern. Note that this
is not the same as the extended regular expression syntax that for example
These settings can also be defined in the pattern itself, so they can be
used even in modules without pattern compilation settings. The pattern
settings are (?i) for ignorecase and (?x) for extended. See the
for more information.
Standard regular expression settings for filters
Many filters use the settings match, exclude and options. Since these settings are
used in a similar way across these filters, the settings are explained here. The
documentation of the filters link here and describe any exceptions to this
generalized explanation.
These settings typically limit the queries the filter module acts on. match and_exclude_ define PCRE2 regular expression patterns while options affects how both of the
patterns are compiled. options works as explained above, accepting the valuesignorecase, case and extended, with ignorecase being the default.
The queries are matched as they arrive to the filter on their way to a routing module. If_match_ is defined, the filter only acts on queries matching that pattern. If match is
not defined, all queries are considered to match.
If exclude is defined, the filter only acts on queries not matching that pattern. If_exclude_ is not defined, nothing is excluded.
If both are defined, the query needs to match match but not match exclude.
Even if a filter does not act on a query, the query is not lost. The query is simply
passed on to the next module in the processing chain as if the filter was not there.
Enumeration type parameters have a pre-defined set of accepted values. For types
declared as enum, only one value is accepted. For enum_mask types, multiple
values can be defined by separating them with commas. All enumeration values in
MaxScale are case-sensitive.
For example the router_options parameter in the readconnroute router is a
mask type enumeration:
A pathlist type parameter expects one or more filesystem paths separated by
colons. The value must not include space between the separators.
Here is an example path list parameter that points to /tmp/something.log and/var/log/maxscale/maxscale.log:
Global Settings
The global settings, in a section named [MaxScale], allow various parameters
that affect MariaDB MaxScale as a whole to be tuned. This section must be
defined in the root configuration file which by default is /etc/maxscale.cnf.
This parameter specifies whether a core file should be generated if MaxScale
crashes. The default is true although usually a core file is not needed,
as MaxScale is capable of logging the full strack trace of all threads
when it crashes.
Values: all or list of auto tunable parameters, separated by ,
An auto tunable parameter is a parameter whose value can be derived from a
particular server variable. With this parameter it can be specified whetherall or a specific set of parameters should automatically be set.
The current auto tunable parameters are:
The values of the server variables are collected by monitors, which means that
if the servers of a service are not monitored by a monitor, then the parameters
of that service will not be auto tuned.
Note that even if auto_tune is set to all, the auto tunable parameters
can still be set in the configuration file and modified with maxctrl.
However, the specified value will be overwritten at the next auto tuning
round, but only if the servers of the service are monitored by a monitor.
This parameter controls the number of worker threads that are handling the
events coming from the kernel. The default is auto which uses as many threads
as there are CPU cores. MaxScale versions older than 6 used one thread by
default.
You can explicitly 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.
Note that if MaxScale is running in a container where the CPU resources
have been limited, the use of auto may cause MaxScale to use more resources
than what is available. In such a situation auto should not be used, but instead
an explicit number that corresponds to the amount of CPU resources available in
the container. As a rule of thumb, an appropriate value for threads is the_vCPU_ of the container rounded up to the nearest integer. For instance, if
the vCPU of the container is 0.5 then 1 is an appropriate value forthreads, if the vCPU is 2.3 then 3 is.
The maximum value for threads is specified by .
From 23.02 onwards it is possible to change the number threads at runtime.
Please see for more details.
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.
This parameter specifies the hard limit for the number of worker threads,
which is specified using .
At startup, if the value of threads is larger than that of threads_max,
the value of threads will be reduced to that. At runtime, an attempt to
increase the value of threads beyond that of threads_max is an error.
rebalance_period
This duration parameter controls how often the load of the worker threads
should be checked. The default value is 0, which means that no checks and
no rebalancing will be performed.
Note that the value of rebalance_period should not be smaller than the
value of rebalance_window whose default value is 10.
If the value of rebalance_period is significantly shorter than that
of rebalance_window, it may lead to oscillation where work is constantly
moved from one thread to another.
rebalance_threshold
This integer parameter controls at which point MaxScale should start
moving work from one worker thread to another.
If the difference in load between the thread with the maximum load and
the thread with the minimum load is larger than the value of this parameter,
then work will be moved from the former to the latter.
Although the load of a thread can vary between 0 and 100, the value of this
parameter must be between 5 and 100.
Note that rebalancing will not be performed unless rebalance_period
has been specified.
rebalance_window
This integer parameter controls how many seconds of load should be
taken into account when deciding whether work should be moved from
one thread to another.
The default value is 10, which means that the load during the last 10
seconds is considered when deciding whether work should be moved.
The minimum value is 1 and the maximum 60.
skip_name_resolve
This parameter controls whether reverse domain name lookups are made to convert
client IP addresses to hostnames. If enabled, client IP addresses will not be
resolved to hostnames during authentication or for the REST API even if requested.
If you have database users that use a hostname in the host part of the user
(i.e. 'user'@'my-hostname.org'), a reverse lookup on the client IP address is
done to see if it matches the host. Reverse DNS lookups can be very slow which
is why it is recommended that they are disabled and that users are defined using
an IP address.
auth_connect_timeout
Duration, default 10s. This setting defines the connection timeout when
attempting to fetch MariaDB/MySQL/Clustrix users from a backend server. The same
value is also used for read and write timeouts. Increasing this value causes
MaxScale to wait longer for a response from a server before user fetching fails.
Other servers may then be attempted.
The value is given as . If no explicit unit is provided,
the value is interpreted as seconds. In subsequent versions a value without a
unit may be rejected. Since the granularity of the timeout is seconds, a timeout
specified in milliseconds will be rejected even if the given value is longer
than a second.
auth_read_timeout
Deprecated and ignored as of MaxScale 2.5.0. See auth_connect_timeout above.
auth_write_timeout
Deprecated and ignored as of MaxScale 2.5.0. See auth_connect_timeout above.
The number of times an interrupted internal query will be retried. The default
is to retry the query once. This feature was added in MaxScale 2.1.10 and was
disabled by default until MaxScale 2.3.0.
An interrupted query is any query that is interrupted by a network
error. Connection timeouts are included in network errors and thus is it
advisable to make sure that the value of query_retry_timeout is set to an
adequate value. Internal queries are only used to retrieve authentication data
and monitor the servers.
query_retry_timeout
The total timeout in seconds for any retried queries. The default value is 5
seconds.
An interrupted query is retried for either the configured amount of attempts or
until the configured timeout is reached.
The value is specified as documented . If no explicit unit
is provided, the value is interpreted as seconds in MaxScale 2.4. In subsequent
versions a value without a unit may be rejected. Note that since the granularity
of the timeout is seconds, a timeout specified in milliseconds will be rejected,
even if the duration is longer than a second.
Controls whether MaxScale is a passive node in a cluster of multiple MaxScale
instances.
This parameter is intended to be used with multiple MaxScale instances that use
failover functionality to manipulate the cluster in some form. Passive nodes
only observe the clusters being monitored and take no direct actions.
The following functionality is disabled when passive mode is enabled:
Automatic failover in the mariadbmon module
Automatic rejoin in the mariadbmon module
Launching of monitor scripts
NOTE: Even if MaxScale is in passive mode, it will still accept clients and
route any traffic sent to it. The only operations affected by the passive
mode are the ones listed above.
Enable or disable the high precision timestamps in logfiles. Enabling this adds
millisecond precision to all logfile timestamps.
skip_permission_checks
Skip service and monitor user permission checks. This is useful when you know
the permissions are OK and you want to speed up the startup process.
It is recommended to not disable the permission checks so that any missing
privileges are detected when maxscale is starting up. If you are experiencing a
slow startup of MaxScale due to large amounts of connection timeouts when
permissions are checked, disabling the permission checks could speed up the
startup process.
Log messages to the system journal. This logs messages using the native SystemD
journal interface. The logs can be viewed with journalctl.
MaxScale 22.08 changed the default value of syslog from true tofalse. This was done to remove the redundant logging that it caused as bothsyslog and maxlog were enabled by default. This caused each message to be
logged twice: once into the system journal and once into MaxScale's own logfile.
Log messages to MariaDB MaxScale's log file. The name of the log file ismaxscale.log and it is located in the directory pointed by .
Log messages whose syslog priority is warning.
MaxScale logs warning level messages whenever a condition is encountered that
the user should be notified of but does not require immediate action or it
indicates a minor problem.
Log messages whose syslog priority is notice.
These messages contain information that is helpful for the user and they usually
do not indicate a problem. These are logged whenever something worth nothing
happens in either MaxScale or in the servers it monitors.
Log messages whose syslog priority is info.
These messages provide detailed information about the internal workings of
MariaDB MaxScale. These messages should only be enabled when there is a need to
inspect the internal logic of MaxScale. A common use-case is to see why a
particular query was handled in a certain way. Almost all modules log some
messages on the info level and this can be very helpful when trying to solve
routing related problems.
Log messages whose syslog priority is debug.
These messages are intended for development purposes and are disabled by
default. These are rarely useful outside of debugging core MaxScale issues.
Note: If MariaDB MaxScale has been built in release mode, then debug
messages are excluded from the build and this setting will not have any
effect. If an attempt to enable these is made, a warning is logged.
log_warn_super_user
When enabled, a warning is logged whenever a client with SUPER-privilege
successfully authenticates. This also applies to COM_CHANGE_USER-commands. The
setting is intended for diagnosing situations where a client interferes with a
primary server switchover. Super-users bypass the read_only-flag which
switchover uses to block writes to the primary.
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.
To disable the augmentation use the value 0 and to enable it use the value 1.
Default: 10, 1000ms, 10000ms
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 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, 1000ms, 10000ms, 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.
Whenever an error message that is being throttled is logged within the
triggering window (the second argument), the suppression window is
extended. This continues until there is a pause in the messages that is longer
than the triggering window.
For example, with the default configuration the messages must pause for at least
one second in order for the throttling to eventually stop. This mechanism
prevents long-lasting error conditions from slowly filling up the log with short
bursts of messages.
To disable log throttling, add an entry with an empty value
or one where any of the integers is 0.
The durations can be specified as documented . If no explicit
unit is provided, the value is interpreted as milliseconds in MaxScale 2.4. In
subsequent versions a value without a unit may be rejected.
Note that notice, info and debug messages are never throttled.
Default: /var/log/maxscale
Set the directory where the logfiles are stored. The folder needs to be both
readable and writable by the user running MariaDB MaxScale.
Default: /var/lib/maxscale
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.
This is also the directory where the password encryption key is read from that
is generated by maxkeys.
The location where the .secrets file is read from. If secretsdir is not
defined, the file is read from .
This parameter was added in MaxScale 6.4.16, 22.08.13, 23.02.10, 23.08.6
and 24.02.2.
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.
The default value depends on the operating system. For RHEL versions the value
is /usr/lib64/maxscale/. For Debian and Ubuntu it is/usr/lib/x86_64-linux-gnu/maxscale/
Default: /usr/share/maxscale
Sets the directory where static data assets are loaded.
The MaxScale GUI static files are located in the gui/ subdirectory. If the GUI
files have been manually moved somewhere else, this path must be configured to
point to the parent directory of the gui/ subdirectory.
The MaxScale REST API only serves files for the GUI that are located in thegui/ subdirectory of the configured sharedir. Any files whose real path
resolves to outside of this directory are not served by the MaxScale GUI: this
is done to prevent other files from being accessible via the MaxScale REST
API. This means that path to the GUI source directory can contain symbolic links
but all parts after the /gui/ directory must reside inside it.
Default: /var/cache/maxscale
Configure the directory MariaDB MaxScale uses to store cached data.
Default: /var/run/maxscale
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 where the executable files reside. All internal
processes which are launched will use this directory to look for executable
files.
connector_plugindir
Location of the MariaDB Connector-C plugin directory. The MariaDB Connector-C
used in MaxScale can use this directory to load authentication plugins. The
versions of the plugins must be binary compatible with the connector version
that MaxScale was built with.
Starting with version 6.2.0, the plugins are bundled with MaxScale and the
default value now points to the bundled plugins. The location where the plugins
are stored depends on the operating system. For RHEL versions the value is/usr/lib64/maxscale/plugin/. For Debian and Ubuntu it is/usr/lib/x86_64-linux-gnu/maxscale/plugin/.
Older versions of MaxScale used /usr/lib/mysql/plugin/ as the default value.
Default: /var/lib/maxscale/maxscale.cnf.d/
Configure the directory where persisted configurations are stored. When a new
object is created via MaxCtrl, it will be stored in this directory. Do not use
this directory for normal configuration files, use /etc/maxscale.cnf.d/
instead. The user MaxScale is running as must be able to write into this
directory.
module_configdir
Default: /etc/maxscale.modules.d/
Configure the directory where module configurations are stored. Path arguments
are resolved relative to this directory. This directory should be used to store
module specific configurations.
Any configuration parameter that is not an absolute path will be interpreted as
a relative path. The relative paths use the module configuration directory as
the working directory.
For example, the configuration parameter file=my_file.txt would be interpreted
as /etc/maxscale.modules.d/my_file.txt whereas file=/home/user/my_file.txt would
be interpreted as /home/user/my_file.txt.
Default: /var/lib/maxscale/
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.
query_classifier
The module used by MariaDB MaxScale for query classification. The information
provided by this module is used by MariaDB MaxScale when deciding where a
particular statement should be sent. The default query classifier is_qc_sqlite_.
query_classifier_cache_size
Default: System Dependent
Specifies the maximum size of the query classifier cache. The default limit is
15% of total system memory starting with MaxScale 2.3.7. In older versions the
default limit was 40% of total system memory. This feature was added in MaxScale
2.3.0.
When the query classifier cache has been enabled, MaxScale will, after a
statement has been parsed, store the classification result using the
canonicalized version of the statement as the key.
If the classification result for a statement is needed, MaxScale will first
canonicalize the statement and check whether the result can be found in the
cache. If it can, the statement will not be parsed at all but the cached result
is used.
The configuration parameter takes one integer that specifies the maximum size of
the cache. The size of the cache can be specifed as explained .
Note that MaxScale uses a separate cache for each worker thread. To obtain the
amount of memory available for each thread, divide the cache size with the value
of threads. If statements are evicted from the cache (visible in the
diagnostic output), consider increasing the cache size.
Note also that limit is not a hard limit, but an approximate one. Namely, although
the memory needed for storing the canonicalized statement and the classification
result is correctly accounted for, there is additional overhead whose size is not
exactly known and over which we do not have direct control.
Using maxctrl show threads it is possible to check what the actual size of
the cache is and to see performance statistics.
query_classifier_args
Arguments for the query classifier. What arguments are accepted depends on the
particular query classifier being used. The default query classifier -qc_sqlite - supports the following arguments:
log_unrecognized_statements
An integer argument taking the following values:
0: Nothing is logged. This is the default.
1: Statements that cannot be parsed completely are logged. They may have been
partially parsed, or classified based on keyword matching.
2: Statements that cannot even be partially parsed are logged. They may have
been classified based on keyword matching.
This will log all statements that cannot be parsed completely. This may be
useful if you suspect that MariaDB MaxScale routes statements to the wrong
server (e.g. to a replica instead of to a primary).
substitute_variables
Enable or disable the substitution of environment variables in the MaxScale
configuration file. If the substitution of variables is enabled and a
configuration line like
is encountered, then $SOME_VALUE will be replaced with the actual value
of the environment variable SOME_VALUE. Note:Variable substitution will be made only if '$' is the first character
&#xNAN;of the value. Everything following '$' is interpreted as the name of the environment
variable.
Referring to a non-existing environment variable is a fatal error.
The setting of substitute_variables will have an effect on all parameters
in the all other sections, irrespective of where the [maxscale] section
is placed in the configuration file. However, in the [maxscale] section,
to ensure that substitution will take place, place thesubstitute_variables=true line first.
Specifies whether the query classifier parser should initially expect MariaDB
or PL/SQL kind of SQL.
The allowed values are:default: The parser expects regular MariaDB SQL.oracle : The parser expects PL/SQL.
NOTE If sql_mode is set to oracle, then MaxScale will also assume
that autocommit initially is off.
At runtime, MariaDB MaxScale will recognize statements like
and
and change mode accordingly.
NOTE If set sql_mode=oracle; is encountered, then MaxScale will also
behave as if autocommit had been turned off and conversely, ifset sql_mode=default; is encountered, then MaxScale will also behave
as if autocommit had been turned on.
Note that MariaDB MaxScale is not explicitly aware of the sql mode of
the server, so the value of sql_mode should reflect the sql mode used
when the server is started.
What specific local address/interface to use when connecting to servers.
This can be used for ensuring that MaxScale uses a particular interface
when connecting to servers, in case the computer MaxScale is running on
has multiple interfaces.
users_refresh_time
How often, in seconds, MaxScale at most may refresh the users from the
backend server.
MaxScale will at startup load the users from the backend server, but if
the authentication of a user fails, MaxScale assumes it is because a new
user has been created and will thus refresh the users. By default, MaxScale
will do that at most once per 30 seconds and with this configuration option
that can be changed. A value of 0 allows infinite refreshes and a negative
value disables the refreshing entirely.
The value is specified as documented . If no explicit unit
is provided, the value is interpreted as seconds in MaxScale 2.4. In subsequent
versions a value without a unit may be rejected. Note that since the granularity
of the timeout is seconds, a timeout specified in milliseconds will be rejected,
even if the duration is longer than a second.
In MaxScale 2.3.9 and older versions, the minimum allowed value was 10 seconds
but, due to a bug, the default value was 0 which allowed infinite refreshes.
users_refresh_interval
How often, in seconds, MaxScale will automatically refresh the users from the
backend server.
This configuration is used to periodically refresh the backend users, making sure
they are up to date. The default value for this setting is 0, meaning the users
are not periodically refreshed. However, they can still be refreshed in case of
failed authentication depending on users_refresh_time.
retain_last_statements
How many statements MaxScale should store for each session. This is for
debugging purposes, as in case of problems it is often of value to be able
to find out exactly what statements were sent before a particular
problem turned up.
Note: See also dump_last_statements using which the actual dumping
of the statements is enabled. Unless both of the parameters are defined,
the statement dumping mechanism doesn't work.
dump_last_statements
With this configuration item it is specified in what circumstances MaxScale
should dump the last statements that a client sent. The allowed values arenever, on_error and on_close. With never the statements are never
logged, with on_error they are logged if the client closes the connection
improperly, and with on_close they are always logged when a client session
is closed.
Note that you need to specify with retain_last_statements how many statements
MaxScale should retain for each session. Unless it has been set to another value
than 0, this configuration setting will not have an effect.
How many log entries are stored in the session specific trace log. This log is
written to disk when a session ends abnormally and can be used for debugging
purposes. Currently the session trace log is written to the log in the following situations:
When MaxScale receives a fatal signal and is about to crash.
Whenever an unexpected response is read from a server
If the session is not closed gracefully (i.e. client doesn't send a COM_QUIT packet)
Whenever readwritesplit receives a responce that is was not expecting.
It would be good to enable this if a session is disconnected and the log is not
detailed enough. In this case the info log might reveal the true cause of why
the connection was closed.
Default is 0.
The session trace log is also exposed by REST API and is shown withmaxctrl show sessions.
The order in which the session trace messages are logged into the log changed in
MaxScale 6.4.9 (MXS-4716). Newer versions will log the messages in the "normal
log order" of older events coming first and newer events appearing later in the
file. Older versions of MaxScale logged the trace dump in the reverse order with
the newest messages first and oldest ones last.
session_trace_match
If both session_trace and session_trace_match are defined, and a trace log
entry of a session matches the regular expression, the trace log is written to
disk. The check for the match is done when the session is stopping.
The most effective way to debug MaxScale related issues is to turn on log_info
and observe the events written into the MaxScale log. The only problem with this
approach is that it can cause a severe performance bottleneck and can easily
fill up the disk as the amount of data written to it is significant. Withsession_trace and session_trace_match, the content that actually gets logged
can be filtered to only what is needed.
For example, the following configuration would only log the trace log messages
from sessions that execute SQL queries with syntax errors:
This could be used to easily identify which applications execute the queries
without having to gather the info level log output from all the sessions that
connect to MaxScale. For every session that ends up logging a syntax error
message, the last 1000 lines of log output done by that session is written into
the MaxScale log.
writeq_high_water
High water mark for network write buffer. When the size of the outbound network
buffer in MaxScale for a single connection exceeds this value, network traffic
throtting for that connection is started. The parameter accepts . The default value was 16777216 bytes before 22.08.4.
More specifically, if the client side write queue is above this value, it will
block traffic coming from backend servers. If the backend side write queue is
above this value, it will block traffic from client.
The buffer that this parameter controls is the buffer internal to MaxScale and
is not the kernel TCP send buffer. This means that the total amount of buffered
data is determined by both the kernel TCP buffers and the value ofwriteq_high_water.
Network throttling is only enabled when both writeq_high_water andwriteq_low_water have a non-zero value. To disable throttling, set the value
to 0.
writeq_low_water
Low water mark for network write buffer. Once the traffic throttling is enabled,
it will only be disabled when the network write buffer is belowwriteq_low_water bytes. The parameter accepts . The
default value was 8192 bytes before 22.08.4.
The value of writeq_high_water must always be greater than the value ofwriteq_low_water.
Network throttling is only enabled when both writeq_high_water andwriteq_low_water have a non-zero value. To disable throttling, set the value
to 0.
persist_runtime_changes
Persist changes done at runtime. This parameter was added in MaxScale 22.08.0.
When persist_runtime_changes is enabled, runtime configuration changes done
with the GUI, MaxCtrl or via the REST API cause a new configuration file to be
saved in /var/lib/maxscale/maxscale.cnf.d/. If load_persisted_configs is
enabled, these files will be applied on top of any existing values found in
static configuration files whenever MaxScale is starting up.
load_persisted_configs
Load persisted runtime changes on startup. This parameter was added in MaxScale
2.3.6.
All runtime configuration changes are persisted in generated configuration files
located by default in /var/lib/maxscale/maxscale.cnf.d/ and are loaded on
startup after main configuration files have been read. To make runtime
configurations volatile (i.e. they are lost when maxscale is restarted), useload_persisted_configs=false. All changes are still persisted since it stores
the current runtime state of MaxScale. This makes problem analysis easier if an
unexpected outage happens.
max_auth_errors_until_block
The maximum number of authentication failures that are tolerated before a host
is temporarily blocked. The default value is 10 failures. After a host is
blocked, connections from it are rejected for 60 seconds. To disable this
feature, set the value to 0.
Note that the configured value is not a hard limit. The number of tolerated
failures is between max_auth_errors_until_block and threads * max_auth_errors_until_block where max_auth_errors_until_block is the
configured value of this parameter and threads is the number of configured
threads.
Define debug options from the --debug command line option. Either the command
line option or the parameter should be used, not both. The debug options are
only for testing purposes and are not to be used in production.
REST API Configuration
The MaxScale REST API is an HTTP interface that provides JSON format data
intended to be consumed by monitoring appllications and visualization tools.
The following options must be defined under the [maxscale] section in the
configuration file.
The network interface where the REST API listens on. The default value is the
IPv4 address 127.0.0.1 which only listens for local connections.
The port where the REST API listens on. The default value is port 8989.
Enable REST API authentication using HTTP Basic Access
authentication. This is not a secure method of authentication without HTTPS but
it does add a small layer of security.
For more information, read the .
The path to the TLS private key in PEM format for the admin interface.
If the admin_ssl_key and admin_ssl_cert options are all defined, the admin
interface will use encrypted HTTPS instead of plain HTTP.
The path to the TLS public certificate in PEM format. See admin_ssl_key
documentation for more details.
admin_ssl_ca_cert
Deprecated since MariaDB MaxScale 22.08. See admin_ssl_ca.
The path to the TLS CA certificate in PEM format. If defined, the client
certificate, if provided, will be validated against it. This parameter is
optional starting with MaxScale 2.3.19.
NOTE Up until MariaDB MaxScale 6, the parameter was called admin_ssl_ca_cert,
which is still accepted as an alias for admin_ssl_ca.
admin_ssl_version
This parameter controls the enabled TLS versions in the REST API. Accepted
values are:
MaxScale versions 6.4.16, 22.08.13, 23.02.10, 23.08.6, 24.02.2 and all newer
releases accept also the following alias values:
The default value is MAX which negotiates the highest level of encryption that
both the client and server support. The list of supported TLS versions depends
on the operating system and what TLS versions the GnuTLS library supports.
For example, to enable only TLSv1.1 and TLSv1.3, useadmin_ssl_version=TLSv1.1,TLSv1.3.
This parameter was added in MaxScale 2.5.7.
Older versions of MaxScale interpreted admin_ssl_version as the minimum
allowed TLS version. In those versions, admin_ssl_version=TLSv1.2 allowed both
TLSv1.2 and TLSv1.3. In MaxScale 6.4.16, 22.08.13, 23.02.10, 23.08.6, 24.02.2
and all newer versions, the value is a enumeration of accepted TLS protocol
versions. In these versions, admin_ssl_version=TLSv1.2 only allows TLSv1.2. To
retain the old behavior, specify all the accepted values withadmin_ssl_version=TLSv1.2,TLSv1.3
Enable or disable the admin interface. This allows the admin interface to
be completely disabled to prevent access to it.
Enable or disable the admin graphical user interface.
MaxScale provides a GUI for administrative operations via the REST API. When the
GUI is enabled, the root REST API resource (i.e. http://localhost:8989/) will
serve the GUI. When disabled, the REST API will respond with a 200 OK to the
request. By disabling the GUI, the root resource can be used as a low overhead
health check.
admin_secure_gui
Whether to serve the GUI only over secure HTTPS connections.
To be secure by default, the GUI is only served over HTTPS connections as
it uses a token authentication scheme. This also controls whether the/auth endpoint requires an encrypted connection.
To allow use of the GUI without having to configure TLS certificates for
the MaxScale REST API, set this parameter to false.
admin_log_auth_failures
Log authentication failures for the admin interface.
admin_pam_readwrite_service/admin_pam_readonly_service
Use Pluggable Authentication Modules (PAM) for REST API authentication. The settings
accept a PAM service name which is used during authentication if normal authentication
fails. admin_pam_readwrite_service should accept users who can do any
MaxCtrl/REST-API-operation. admin_pam_readonly_service should accept users who can only
do read operations. Because REST-API does not support back and forth communication between
the client and MaxScale, the PAM services must be simple. They should only ask for the
password and nothing else.
If only admin_pam_readwrite_service is configured, both read and write operations can be
authenticated by PAM. If only admin_pam_readonly_service is configured, only read
operations can be authenticated by PAM. If both are set, the service used is determined by
the requested operation. Leave or set both empty to disable PAM for REST-API.
admin_jwt_algorithm
The signature algorithm used by the MaxScale REST API when generating JSON Web
Tokens.
For more information about the tokens and how they work, refer to .
If a symmetric algorithm is used (i.e. HS256, HS384 or HS512), MaxScale
will generate a random encryption key on startup and use that to sign the
messages. The symmetric key can also be retrieved from an if the admin_jwt_key parameter is defined.
If an asymmetric algorithm (i.e. public key authentication) is used, both theadmin_ssl_cert and admin_ssl_key parameters must be defined and they must
contain a private key and a public certificate of the correct type. If the wrong
key type, key length or elliptic curve is used, MaxScale will refuse to start.
Asymmetric key algorithms make it possible for the clients of the REST API to
validate that the token was indeed generated by the correct entity.
Symmetric algorithms make it easy to share the same tokens between
multiple MaxScale instaces as the shared secret can be stored in a key
management system.
The possible values for this parameter are:
MaxScale will attempt to detect the best algorithm to use for
signatures. The algorithm used depends on the private key type: RSA keys usePS256, EC keys use the ES256, ES384 or ES512 depending on the curve,
Ed25519 keys use ED25519 and Ed448 keys uses ED448
The ID for the encryption key used to sign the JSON Web Tokens. If configured,
an must also be configured
and it must contain the key with the given ID. If no key is defined, MaxScale
will use a random encryption key whenever a symmetric signature algorithm is
used.
Currently, the encryption key is only read on startup. This means that the
tokens will be signed by the latest key version that is available on startup:
rotating the encryption key in the key management system will not cause the JWTs
to be signed with newer versions of the key.
admin_jwt_max_age
The maximum lifetime of a token generated by the /auth endpoint.
If a client requests for a token with a lifetime that exceeds the configured
value, the token lifetime is silently truncated to this value. This can be used
to control the maximum length of a MaxGUI session.
This also acts as the effective maximum age of any database connection created
from the /sql endpoint.
The URL to a OpenID Connect server that is used for JWT validation.
If defined, any tokens signed by this server are accepted as valid bearer tokens
for the MaxScale REST API. The "sub" field of the token is assumed to be the
username of an administrative user in MaxScale and the "account" claim is
assumed to be the type of the user: "admin" for administrative users with full
access to the REST-API and "basic" for users with read-only access to the
REST-API. This means that all users must be first created with maxctrl create user before the tokens are accepted if the OIDC provider is not able to add the"account" claim.
If this URL is changed at runtime, the new certificates will not be
fetched until a maxctrl reload tls command is executed.
admin_verify_url
URL to a server to which the REST API token verification is delegated.
If the URL is defined, any tokens passed to the REST API will be validated by
doing a GET request to the URL with the client's token as a bearer token. TheReferer header of the request is set to the URL being requested by the client
and the custom X-Referrer-Method header is set to the HTTP method being used
(PUT, GET etc.).
Note: When admin_verify_url is used and the remote server cannot
be accessed, all REST API access that uses tokens will be disabled. The
only way to use the REST API with tokens is to remove admin_verify_url
from the configuration which requires restarting MaxScale. The REST API
still accepts HTTP Basic Access authentication even if the remote server
cannot be reached.
By delegating the authentication and authorization of the REST API to an
external server, users can implement custom access control systems for the
MaxScale REST API.
Enable logging of incoming REST API calls.
admin_audit_file
Default: /var/log/maxscale/admin_audit.csv
The file where the REST API auditing information is logged.
If a non-default value is used, the directory where the file resides must
exist. For example, with /var/log/maxscale/audit_files/audit.csv, the
directory /var/log/maxscale/audit_files must exist.
admin_audit_exclude_methods
List of comma separated HTTP methods to exclude from logging
Currently MaxScale does not use CONNECT or TRACE.
Resetting to log all methods can be done in the configuration file by
writing admin_audit_exclude_methods= or at runtime withmaxctrl alter maxscale admin_audit_exclude_methods=.
Remember that once a runtime change has been made, the entry for that
setting is ignored in the main configuration file (usually maxscale.cnf).
config_sync_cluster
This parameter controls which cluster (i.e. monitor) is used to synchronize
configuration changes between MaxScale instances. The first server labeledMaster will be used for the synchronization.
By default configuration synchronization is not enabled and it must be
explicitly enabled by defining a monitor name for config_sync_cluster.
When config_sync_cluster is defined, config_sync_user andconfig_sync_password must also be defined.
For a detailed description of this feature, refer to the section.
config_sync_user
The username for the account that is used to synchronize configuration changes
across MaxScale instances. Both this parameter and config_sync_password are
required if config_sync_cluster is configured.
This account must have the following grants:
The mysql.maxscale_config table can be pre-created in which case the CREATE
grant is not needed by the user configured in config_sync_user. The following
SQL is used to create the table.
If the database where the table is created is changed with config_sync_db, the
grants must be adjusted to target that database instead.
config_sync_password
The password for config_sync_user. Both this parameter and config_sync_user
are required if config_sync_cluster is configured. This password can
optionally be encrypted using maxpasswd.
The database where the maxscale_config table is created. By default the table
is created in the mysql database. This parameter was added in MaxScale
versions 6.4.6 and 22.08.5.
As tables in the mysql database cannot have triggers on them, the database
must be changed to a user-created one in order to create triggers on the table.
An example use-case for triggers on this table is to track all configuration
changes done to MaxScale by inserting them into a separate table.
config_sync_interval
How often to synchronize the configuration with the cluster.
As the synchronization involves selecting the configuration version from the
database, this value should not be set to an unreasonably low value. The default
value of 5 second should provide a good compromise between responsiveness and
how much load it places on the database.
config_sync_timeout
Timeout for all SQL operations done during the configuration synchronization. If
an operation exceeds this timeout, the configuration change is treated as failed
and an error is reported to the client that did the change.
Values: none, file, kmip, vault
The encryption key manager to use. The available encryption key managers are:
none - No key manager, encryption keys are not available.
Refer to the section for
more information on how to configure the key managers. The key managers each
have their configuration in their own namespace and must have their name as a
prefix.
For example to configure the file key manager, the following must be used:
MaxScale logs warnings and errors for various reasons and often it is self-
evident and generally applicable whether some occurence should warrant a
warning or an error, or perhaps just an info-level message.
However, there are events whose seriousness is not self-evident. For
instance, in some environments an authentication failure may simply indicate
that someone has made a typo, while in some other environment that can only
happen in case there has been a security breech.
To handle events like these, MaxScale defines events whose logging
facility and level can be controlled by the administrator. Given an eventX, its facility and level are controlled in the following manner:
The above means that if event X occurs, then that is logged using the
facility LOG_LOCAL0 and the level LOG_ERR.
The valid values of facilityare the facility values reported byman
syslog, e.g.LOG_AUTH,LOG_LOCAL0andLOG_USER. Likewise, the valid values forlevelare the ones also reported byman syslog, e.g.LOG_WARNING,LOG_ERRandLOG_CRIT`.
Note that MaxScale does not act upon the level, that is, even if the level
of a particular event is defined to be LOG_EMERG, MaxScale will not shut
down if that event occurs.
The default facility is LOG_USER and the default level is LOG_WARNING.
Note that you may also have to configure rsyslog to ensure that the
event can be logged to the intended log file. For instance, if the facility
is chosen to be LOG_AUTH, then /etc/rsyslog.conf should contain a line
like
for the logged events to end up in /var/log/auth.log, where the initialauth is the relevant entry.
The available events are:
'authentication_failure'
This event occurs when there is an authentication failure.
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.
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.
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.
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.
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.
A more complete description of router options and what is available for a given
router is included with the documentation of the router itself.
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 requests pass through the filters from left to right in the order defined in
the configuration parameter.
The targets parameter is a comma separated list of server and/or service names
that comprise the routing targets of the service. This parameter was added in
MaxScale 2.5.0.
This parameter allows nested service configurations to be defined without having
to configure listeners for all services. For example, one use-case is to use
multiple readwritesplit services behind a schemarouter service to have both the
sharding of schemarouter with the high-availability of readwritesplit.
NOTE: The targets parameter is mutually exclusive with the cluster andservers parameters.
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).
NOTE: The servers parameter is mutually exclusive with the cluster andtargets parameters.
The servers the service uses are defined by the monitor specified as value
of this configuration parameter.
NOTE: The cluster parameter is mutually exclusive with the servers andtargets parameters.
This setting defines the user the service uses to fetch user account
information from backends. A password is specified using .
See
for more information (such as required grants) and troubleshooting tips
regarding user account management and client authentication.
This settings defines the password the service uses to fetch user account
information from backends. The password may be either a plain text password or
an . The user is specified
using .
See
for more information (such as required grants) and troubleshooting tips
regarding user account management and client authentication.
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.
localhost_match_wildcard_host
Deprecated and ignored.
This parameter sets a custom version string that is sent in the MySQL Handshake
from MariaDB MaxScale to clients.
Example:
If not set, MaxScale will attempt to use a version string from the
backend databases by selecting the version string of the database with
the lowest version number. If the selected version is from the MariaDB
10 series, a 5.5.5- prefix will be added to it similarly to how the
MariaDB 10 series versions added it.
If MaxScale has not been able to connect to a single database and the
versions are unknown, the default value of 5.5.5-10.4.32 <MaxScale version>-maxscale is used where <MaxScale version> is the version of
MaxScale.
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.
By default MaxScale uses the first server labeled as Master as the source of
the authentication data. When this option is enabled, the authentication data is
loaded from all the servers and combined into one big data set.
This setting controls whether escape characters (\) are removed from database
names when loading user grants from a backend server. When enabled, a grant
such as grant select on test_.* to 'user'@'%'; is read as grant select on test_.* to 'user'@'%';
This setting has no effect on database-level grants fetched from a MariaDB
Server. The database names of a MariaDB Server are compared using the LIKE
operator to properly handle wildcards and escaped wildcards. This setting may
affect database names in table and column level grants, although these typically
do not contain backlashes.
Some visual database management tools automatically escape some characters and
this might cause conflicts when MaxScale tries to authenticate users.
log_auth_warnings
Enable or disable the logging of authentication failures and warnings. If
enabled, messages about failed authentication attempts will be logged with
details about who tried to connect to MariaDB MaxScale and from where.
When enabled, this allows a service to log warning messages even if the global
log level configuration disables them.
Note that disabling the service level logging does not override the global
logging configuration: with log_warning=false in the service andlog_warning=true globally, warnings will still be logged for all services.
When enabled, this allows a service to log notice messages even if the global
log level configuration disables them.
When enabled, this allows a service to log info messages even if the global log
level configuration disables them.
When enabled, this allows a service to log debug messages even if the global log
level configuration disables them.
Debug messages are only enabled for debug builds. Enabling log_debug in a
release build does nothing.
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. A value of zero is interpreted as no timeout, the same
as if the parameter is not defined.
The value is specified as documented . If no explicit unit
is provided, the value is interpreted as seconds in MaxScale 2.4. In subsequent
versions a value without a unit may be rejected. Note that since the granularity
of the timeout is seconds, a timeout specified in milliseconds will be rejected,
even if the duration is longer than a second.
This parameter only takes effect in top-level services. A top-level service is
the service where the listener that the client connected to points (i.e. the
value of service in the listener). If a service defines other services in itstargets parameter, the connection_timeout for those is not used.
The value of connection_timeout should be lower than the lowest wait_timeout
value on the backend servers. This way idle clients are disconnected by MaxScale
before the backend servers have to close them. Any client-side idle timeouts
(e.g. maximum lifetime for connection pools) should be lower than bothconnection_timeout and wait_timeout. This way the client application will
end up closing the connection itself which most of the time results in better
and more helpful error messages.
Warning: If a connection is idle for longer than the configured connection
timeout, it will be forcefully disconnected and a warning will be logged in the
MaxScale log file.
In MaxScale versions 6.2.0 and older, if long-running operations (e.g. ALTER TABLE) were performed, MaxScale would close the connections if they look longer
than connection_timeout seconds to execute
(). In MaxScale 6.2.1 this
has been fixed and the active operations are now correctly tracked.
Example:
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.
Warning: In MaxScale 2.5, it is possible that the number of concurrent
connections temporarily exceeds the value of max_connections. This has been
fixed in MaxScale 6.
Example:
session_track_trx_state
Enable transaction state tracking by offloading it to the backend servers.
Getting the transaction state from the server will be more accurate for stored
procedures or multi-statement SQL that modifies the transaction state
non-atomically.
In general, it is better to avoid using this type of SQL as tracking the
transaction state via the server responses is not compatible with features such
as transaction_replay in readwritesplit. session_track_trx_state should only
be enabled if the default transaction tracking done by MaxScale does not produce
the desired outcome.
This is only supported by MariaDB versions 10.3 or newer. The following must be
configured in the MariaDB server in order for this feature to work. Not
configuring the MariaDB server with it can result in the transaction state being
wrong in MaxScale which can result in data inconsistency.
retain_last_statements
How many statements MaxScale should store for each session of this service.
This overrides the value of the global setting with the same name. Ifretain_last_statements has been specified in the global section of the
MaxScale configuration file, then if it has not been explicitly specified
for the service, the global value holds, otherwise the service specific
value rules. That is, it is possible to enable the setting globally and
turn it off for a specific service, or just enable it for specific services.
The value of this parameter can be changed at runtime using maxctrl and the
new value will take effect for sessions created thereafter.
connection_keepalive
Keep idle connections alive by sending pings to backend servers. This feature
was introduced in MaxScale 2.5.0 where it was changed from a
readwritesplit-specific feature to a generic service feature. The default value
for this parameter is 300 seconds. To disable this feature, set the value to 0.
The keepalive interval is specified as documented . If no
explicit unit is provided, the value is interpreted as seconds in MaxScale
2.5. In subsequent versions a value without a unit may be rejected. Note that
since the granularity of the keepalive is seconds, a keepalive specified in
milliseconds will be rejected, even if the duration is longer than a second.
The parameter value is the interval in seconds between each keepalive ping. A
keepalive ping will be sent to a backend server if the connection has been idle
for longer than the configured keepalive interval.
Starting with MaxScale 2.5.21 and 6.4.0, the keepalive pings are not sent if the client
has been idle for longer than the configured value ofconnection_keepalive. Older versions of MaxScale sent the keepalive pings
regardless of the client state.
This parameter only takes effect in top-level services. A top-level service is
the service where the listener that the client connected to points (i.e. the
value of service in the listener). If a service defines other services in itstargets parameter, the connection_keepalive for those is not used.
If the value of connection_keepalive is changed at runtime, the change in the
value takes effect immediately.
As the connection keepalive pings must be done only when there's no ongoing
query, all requests and responses must be tracked by MaxScale. In the case ofreadconnroute, this will incur a small drop in performance. For routers that
rely on result tracking (e.g. readwritesplit and schemarouter), the
performance will be the same with or without connection_keepalive.
If you want to avoid the performance cost and you don't need the connection
keepalive feature, you can disable it with connection_keepalive=0s.
force_connection_keepalive
By default, connection keepalive pings are only sent if the client is either
executing a query or has been idle for less than the duration configured inconnection_keepalive. When this parameter is enabled, keepalive pings are
unconditionally sent to any backends that have been idle for longer thanconnection_keepalive seconds. This option was added in MaxScale 6.4.9 and can
be used to emulate the pre-2.5.21 behavior if long-lived application connections
rely on the old unconditional keepalive pings.
Note: if force_connection_keepalive is enabled and connection_keepalive in
MaxScale is set to a lower value than the wait_timeout on the database, the
client idle timeouts that wait_timeout control are no longer effective. This
happens because MaxScale unconditionally sends the pings which make the client
behave like it is not idle and thus the connections will never be killed due towait_timeout.
net_write_timeout
This parameter controls how long a network write to the client can stay
buffered. This feature is disabled by default.
When net_write_timeout is configured and data is buffered on the client
network connection, if the time since the last successful network write exceeds
the configured limit, the client connection will be disconnected.
The value is specified as documented . If no explicit unit
is provided, the value is interpreted as seconds in MaxScale 2.4. In subsequent
versions a value without a unit may be rejected. Note that since the granularity
of the timeout is seconds, a timeout specified in milliseconds will be rejected,
even if the duration is longer than a second.
max_sescmd_history
max_sescmd_history sets a limit on how many distinct session commands are
stored in the session command history. When the history limit is exceeded, the
history is either pruned to the last max_sescmd_history command (whenprune_sescmd_history is enabled) or the history is disabled and server
reconnections are no longer possible.
The required history size can be estimated by counting the total number of
session state modifying commands (e.g SET NAMES) that are used by a
client. Note that connectors usually add some commands that aren't visible to
the application developer which means a safety margin should be added. A good
rule of thumb is to count the expected number of statements and double that
number. The default value of 50 is a value that'll work for most applications
that do not rely heavily on user variables.
Starting with MaxScale versions 21.06.18, 22.08.15, 23.02.12, 23.08.8, 24.02.4
and 24.08.1, binary protocol prepared statements do not count towards themax_sescmd_history limit. In practice this means that all binary protocol
prepared statements opened by the client are also kept open by MaxScale and are
restored whenever a reconnection to a server happens. The limits imposed bymax_sescmd_history apply to other text protocol commands e.g. SET NAMES.
Note that text protocol prepared statements count as text protocol commands and
are thus potentially pruned when history pruning happens. If an application uses
a lot of PREPARE stmt FROM <sql> commands, it is recommended that the value ofmax_sescmd_history is increased accordingly.
In older versions of MaxScale, binary protocol prepared statements were limited
by max_sescmd_history and were also pruned by prune_sescmd_history but this
caused problems when the binary protocol prepared statment were pruned while
they were still open from the client's point of view. In older versions, the
recommended value of max_sescmd_history is the number of state modifying
commands plus the maximum number of open prepared statments that any application
may use.
This parameter was moved into the MaxScale core in MaxScale 6.0. The parameter
can be configured for all routers that support the session command
history. Currently only readwritesplit and schemarouter support it.
In addition to limiting the number of commands to store, it also acts as a hard
limit on the number of packets that may be queued up on a backend before it is
closed. Packets are queued while the TCP socket is being opened and when
prepared statements are being prepared. In certain rare cases, a slow server may
fall behind and not catch up to the rest of the cluster and a backlog of packets
forms. In these cases, if more than max_sescmd_history packets are queued, the
connection to the server is closed.
prune_sescmd_history
This option enables pruning of the session command history when it exceeds the
value configured in max_sescmd_history. When this option is enabled, only a
set number of statements are stored in the history. This limits the per-session
memory use while still allowing safe reconnections.
This parameter is intended to be used with pooled connections that remain in use
for a very long time. Most connection pool implementations do not reset the
session state and instead re-initialize it with new values. This causes the
session command history to grow at roughly a constant rate for the lifetime of
the pooled connection.
Each client-side session that uses a pooled connection only executes a finite
amount of session commands. By retaining a shorter history that encompasses all
session commands the individual clients execute, the session state of a pooled
connection can be accurately recreated on another server.
When the session command history pruning is enabled, there is a theoretical
possibility that upon server reconnection the session states of the connections
are inconsistent. This can only happen if the length of the stored history is
shorter than the list of relevant statements that affect the session state. In
practice the default value of 50 session commands is a fairly reasonable value
and the risk of inconsistent session state is relatively low.
In case the default history length is too short for safe pruning, set the value
of max_sescmd_history to the total number of commands that affect the session
state plus a safety margin of 10. The safety margin reserves some extra space
for new commands that might be executed due to changes in the client side
application.
This parameter was moved into the MaxScale core in MaxScale 6.0. The parameter
can be configured for all routers that support the session command
history. Currently only readwritesplit and schemarouter support it.
disable_sescmd_history
This option disables the session command history. This way no history is stored
and if a replica server fails, the router will not try to replace the failed
replica. Disabling session command history will allow long-lived connections
without causing a constant growth in the memory consumption.
This parameter should only be used when either the memory footprint must be as
small as possible or when the pruning of the session command history is not
acceptable.
This parameter was moved into the MaxScale core in MaxScale 6.0. The parameter
can be configured for all routers that support the session command
history. Currently only readwritesplit and schemarouter support it.
user_accounts_file
Defines path to a file with additional user accounts for incoming clients.
Default value is empty, which disables the feature.
In addition to querying the backends, MaxScale can read users from a file. This
feature is useful when backends have limitations on the type of users that can
be created, or if MaxScale needs to allow users to log in even
when backends are down (e.g. binlog router). The users read from the file are
only present on MaxScale, so logging into backends can still fail. The format of
the file is protocol-specific. The following only applies to MariaDB-protocol,
which is also the only protocol supporting this feature.
The file contains json text. Three objects are read from it: user, db and_roles_mapping_, none of which are mandatory. These objects must be arrays which
contain user information similar to the mysql.user, mysql.db and_mysql.roles_mapping_ tables on the server. Each array element must define at
least the string fields user and host, which define the user account to add
or modify.
The elements in the user-array may contain the following additional fields. If
a field is not defined, it is assumed either empty (string) or false (boolean).
password: String. Password hash, similar to the equivalent column on server.
plugin: String. Authentication plugin used by client, similar to server.
authentication_string: String. Additional authentication info, similar to
server.
The elements in the db-array must contain the following additional field:
db: String. Database which the user can access. Can contain % and _
wildcards.
The elements in the roles_mapping-array must contain the following additional
field:
role: String. Role the user can access.
When users are read from both servers and the file, the server takes priority.
That is, if user 'joe'@'%' is defined on both, the file-version is discarded.
The file can still affect the database grants and roles of 'joe'@'%', as the_db_ and roles_mapping-arrays are read separately and added to existing grant
and role lists.
An example users file is below.
user_accounts_file_usage
Defines when user_accounts_file is read. The value is an enum, either
"add_when_load_ok" (default) or "file_only_always".
"add_when_load_ok" means that the file is only read when users are successfully
read from a server. The file contents are then added to the server-based data.
If reading from server fails (e.g. servers are down), the file is ignored.
"file_only_always" means that users are not read from the servers at all and the
file contents is all that matters. The state of the servers is ignored. This
mode can be useful with the binlog router, as it allows clients to log in and
fetch binary logs from MaxScale even when backend servers are down.
idle_session_pool_time
Normally, MaxScale only pools backend connections when
a session is closed (controlled by server settings persistpoolmax and_persistmaxtime_). Other sessions can use the pooled connections
instead of creating new connections to backends. If connection sharing is enabled,
MaxScale can pool backend connections also from running sessions, and
re-attach a pooled connection when a session is doing a query. This effectively
allows multiple sessions to share backend connections.
idle_session_pool_time defines the amount of time a session must be idle
before its backend connections may be pooled. To enable connection sharing, set_idle_session_pool_time_ to zero or greater. The value can be given in
seconds or milliseconds.
This feature has a significant drawback: when a backend connection is reused, it
needs to be restored to the correct state. This means reauthenticating and
replaying session commands. This can add a significant delay before the
connection is actually ready for a query. If the session command history size
exceeds the value of max_sescmd_history, connection sharing is disabled for
the session.
This feature should only be used when limiting the backend connection count is
a priority, even at the cost of query delay and throughput. This feature only
works when the following server settings are also set in MaxScale configuration:
Since reusing a backend connection is an expensive operation, MaxScale only
pools connections when another session requires them. idle_session_pool_time
thus effectively limits the frequency at which a connection can be moved from
one session to another. Setting idle_session_pool_time=0ms causes MaxScale to
move connections as soon as possible.
See below for more information on configuring connection sharing.
Details, limitations and suggestions for connection sharing
As noted above, when a connection is pooled and reused its state is lost.
Although session variables and prepared statements are restored by replaying
session commands, some state information cannot be transferred.
The most common such state is a transaction. When a transaction is on,
connection sharing is disabled for that session until the transaction completes.
Other similar situations may not be properly detected, and it's the
responsibility of the user to avoid introducing such state to the session when
using connection sharing. This means that the following should not be used:
Statements such as LOCK TABLES and GET LOCK or any other statement that
introduces state into the connection.
Temporary tables and some problematic user or session variables such asLAST_INSERT_ID(). For LAST_INSERT_ID(), the value returned by the connector
must be used instead of the variable.
Several settings affect connection sharing and its effectiveness. Reusing a
connection is an expensive operation so its frequency should be minimized. The
important configuration settings in addition to idle_session_pool_time are
MaxScale server settings , and .
The service settings , and also have an effect. These
settings should be tuned according to the use case.
persistpoolmax limits how many connections can be kept in a pool for a given
server. If the pool is full, no more connections are detached from sessions even
if they are idle and required. The pool size should be large enough to contain
any connections being transferred between sessions, but not be greater thanmax_routing_connections. Using the value of max_routing_connections is a
reasonable starting point.
persistmaxtime limits the time a connection may stay in the pool. This should
be high enough so that pooled connections are not unnecessarily closed. Cleaning
up clearly unneeded connections from the pool may be useful whenmax_routing_connections is restrictively tuned. Because each MaxScale routing
thread has its own connection pool, one thread can monopolize access to a
server. For example, if the pool of thread 1 has 100 connections to ServerA
with max_routing_connections=100, other threads can no longer connect to the
server. In such a situation, reducing persistmaxtime of ServerA may help as
it would cause unneeded connections in the pool to be closed faster. Such
connection slots then become available to other routing threads. Reducing the
number of may also help, as it reduces pool
fragmentation. This may reduce overall throughput, though. When using connection
sharing, backend connections are only in the pool momentarily. Consequently,persistmaxtime can be set quite low, e.g. 10s.
If a client session exceeds max_sescmd_history (default 50), pooling is
disabled for that session. If many sessions do this and_max_routing_connections_ is set, other sessions will stall as they cannot find
a backend connection. This can be avoided with prune_sescmd_history. However,
pruning means that old session commands will not be replayed when a pooled
connection is reused. If the pruned commands are important
(e.g. statement preparations), the session may fail later on.
If the number of clients actively running queries is greater thanmax_routing_connections, query throughput will suffer as clients will need to
take turns. In this situation, it's imperative to minimize the number of
backend connections a single session uses. The settings to achieve this depend
on the router. For ReadWriteSplit the following should be used:
The above settings mean that MaxScale can process roughly
(number of replica servers X max_routing_connections) read queries
simultaneously. Write queries will still need to take turns as there is only one
primary server.
The following configuration snippet shows example server and service
configurations for connection sharing with ReadWriteSplit.
multiplex_timeout
When connection sharing (as described above) is on, clients
may have to wait for their turn to use a backend connection. If too much time
passes without a connection becoming available, MaxScale returns an error to
the client, usually also ending the session. multiplex_timeout sets this
timeout. Increase it if queries are failing with "Timed out when waiting for a
connection". Decrease it if failing early is preferable to stalling.
Server sections define the backend database servers MaxScale uses. A server is
identified by its section name in the configuration file. The only mandatory
parameter of a server is type, but address and port are also usually
defined. A server may be a member of one or more services. A server may only be
monitored by at most one monitor.
Mandatory: Yes, if socket is not provided.
The IP-address or hostname of the machine running the database server. MaxScale
uses this address to connect to the server.
Either address or socket must be defined, but not both.
The port the backend server listens on for incoming connections. MaxScale uses
this port to connect to the server.
Mandatory: Yes, if address is not provided.
The absolute path to a UNIX domain socket the MariaDB server is listening
on.
Either address or socket must be defined, but not both.
This setting together with define server-specific
credentials for monitoring the server. Monitors typically use the credentials in their
own configuration sections to connect to all servers. If server-specific settings are
given, the monitor uses those instead.
This setting together with define server-specific
credentials for monitoring the server. Monitors typically use the credentials in their
own configuration sections to connect to all servers. If server-specific settings are
given, the monitor uses those instead.
monitorpw may be either a plain text password or an encrypted password. See
the section for more information.
An alternative port used for administrative connections to the server. If this
setting is defined, MaxScale uses it for monitoring the server and to fetch user
accounts. Client sessions will still use the normal port.
Defining extra_port allows MaxScale to connect even when max_connections on
the backend server has been reached. Extra-port connections have their own
connection limit, which is one by default. This needs to be increased to allow
both monitor and user account manager to connect.
If the connection to the extra-port fails due to connection number limit or if
the port is not open on the server, normal port is used.
For more information, see
and .
Sets the size of the server connection pool. Disabled by default. When enabled,
MaxScale places unused connections to the server to a pool and reuses them
later. Connections typically become unused when a session closes. If the size of
the pool reaches persistpoolmax, unused connections are closed instead.
Every routing thread has its own pool. As of version 6.3.0, MaxScale will round
up persistpoolmax so that every thread has an equal size pool.
When a MariaDB-protocol connection is taken from the pool to be used in a new
session, the state of the connection is dependent on the router. ReadWriteSplit
restores the connection to match the session state. Other routers do not.
The persistmaxtime parameter defaults to zero but can be set to a duration as
documented . If no explicit unit is provided, the value is
interpreted as seconds in MaxScale 2.4. In subsequent versions a value without a
unit may be rejected. Note that since the granularity of the parameter is
seconds, a value specified in milliseconds will be rejected, even if the
duration is longer than a second.
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.
max_routing_connections
Maximum number of routing connections to this server. Connections held in a pool
also count towards this maximum. Does not limit monitor connections or user
account fetching. A value of 0 (default) means no limit.
Since every client session can generate a connection to a server, the server may
run out of memory when the number of clients is high enough. This setting limits
server memory use caused by MaxScale. The effect depends on if the service
setting , i.e. connection
sharing, is enabled or not.
If connection sharing is not on, max_routing_connections simply sets a limit.
Any sessions attempting to exceed this limit will fail to connect to the
backend. The client can still connect to MaxScale, but queries will fail.
If connection sharing is on, sessions exceeding the limit will be put on hold
until a connection is available. Such sessions will appear unresponsive, as
queries will hang, possibly for a long time. The timeout is controlled by .
If proxy_protocol is enabled, MaxScale will send a
header when connecting client sessions to the server. The header contains the
original client IP address and port, as seen by MaxScale. The server will then
read the header and perform authentication as if the connection originated from
this address instead of MaxScale's IP address. With this feature, the user
accounts on the backend server can be simplified to only contain the actual
client hosts and not the MaxScale host.
NOTE: If you use a cloud load balancer like AWS ELB that supports the proxy
protocol in front of a MaxScale, you need to configure in MaxScale. This also needs
to be done whenever one MaxScale may connect to another Maxscale and the
connecting MaxScale has proxy_protocol enabled.
PROXY protocol will be supported by MariaDB 10.3, which this feature has been
tested with. To use it, enable the PROXY protocol in MaxScale for every
compatible server and configure the MariaDB servers themselves to accept the
protocol headers from MaxScale's IP address. On the server side, the protocol
should be enabled only for trusted IPs, as it allows the sender to spoof the
connection origin. If a proxy header is sent to a server not expecting it, the
connection will fail. Usually PROXY protocol should be enabled for every
server in a cluster, as they typically have similar grants.
Other SQL-servers may support PROXY protocol as well, but the implementation may
be highly restricting. Strict adherence to the protocol requires that the
backend server does not allow mixing of un-proxied and proxied connections from
a given IP. MaxScale requires normal connections to backends for monitoring and
authentication data queries, which would be blocked. To bypass this restriction,
the server monitor needs to be disabled and the service listener needs to be
configured to disregard authentication errors (skip_authentication=true).
Server states also need to be set manually in MaxCtrl. These steps are not
required for MariaDB 10.3, since its implementation is more flexible and allows
both PROXY-headered and headerless connections from a proxy-enabled IP.
disk_space_threshold
This parameter specifies how full a disk may be, before MaxScale should start
logging warnings or take other actions (e.g. perform a switchover). This
functionality will only work with MariaDB server versions 10.1.32, 10.2.14 and
10.3.6 onwards, if the DISKS information schema plugin has been installed.
NOTE: Since MariaDB 10.4.7, MariaDB 10.3.17 and MariaDB 10.2.26, the
information will be available only if the monitor user has the FILE
privilege.
A limit is specified as a path followed by a colon and a percentage specifying
how full the corresponding disk may be, before action is taken. E.g. an entry like
specifies that the disk that has been mounted on /data may be used until 80%
of the total space has been consumed. Multiple entries can be specified by
separating them by a comma. If the path is specified using *, then the limit
applies to all disks. However, the value of * is only applied if there is not
an exact match.
Note that if a particular disk has been mounted on several paths, only one path
need to be specified. If several are specified, then the one with the smallest
percentage will be applied.
Examples:
The last line means that the disk mounted at /data1 may be used up to
80%, the disk mounted at /data2 may be used up to 60% and all other disks
mounted at any paths may be used up until 90% of maximum capacity, before
MaxScale starts to warn to take action.
Note that the path to be used, is one of the paths returned by:
There is no default value, but this parameter must be explicitly specified
if the disk space situation should be monitored.
This parameter controls the order in which servers are used. Valid values for
this parameter are primary and secondary. The default value isprimary.
This behavior depends on the router implementation but the general rule of thumb
is that primary servers will be used before secondary servers.
Readconnroute will always use primary servers before secondary servers as long
as they match the configured server type.
Readwritesplit will pick servers that have the same rank as the current
primary. Read the
for a detailed description of the behavior.
The following example server configuration demonstrates how rank can be used
to exclude DR-site servers from routing.
The main-site-primary and main-site-replica servers will be used as long as
they are available. When they are no longer available, the DR-site-primary andDR-site-replica will be used.
Server priority. Currently only used by galeramon to choose the order in which
nodes are selected as the current primary server. Refer to the
section of the galeramon documentation for more information on how to use it.
Starting with MaxScale 2.5.21, this parameter also accepts negative values. In
older versions, the parameter only accepted non-negative values.
replication_custom_options
Server-specific custom string added to "CHANGE MASTER TO"-commands sent by
MariaDB Monitor. Overrides replication_custom_options setting set in
the monitor. This setting affects the server where the command is ran at, not
the source of the replication. That is, if monitor sends a "CHANGE MASTER TO"-
command to server A telling it to replicate from server B, the setting value
from MaxScale configuration for server A would be used.
See
for more information.
Monitor sections are used to define the monitoring module that watches a set of
servers. Each server can only be monitored by one monitor.
Common monitor parameters .
A listener defines a port MaxScale listens on for incoming connections. Accepted
connections are linked with a MaxScale service. Multiple listeners can feed the
same service. Mandatory parameters are type, service and protocol.address is optional, it limits connections to a certain network interface
only. socket is also optional and is used for Unix socket connections.
The network socket where the listener listens may have a backlog of
connections. The size of this backlog is controlled by the_net.ipv4.tcp_max_syn_backlog_ and net.core.somaxconn kernel parameters.
Increasing the size of the backlog by modifying the kernel parameters helps with
sudden connection spikes and rejected connections. For more information see .
The service to which the listener is associated. This is the name of a service
that is defined elsewhere in the configuration file.
The name of the protocol module used for communication between the client and
MaxScale. The same protocol is also used for backend communication.
Usually this does not need to be defined as the default protocol is the MariaDB
network protocol that is used by SQL connections.
For NoSQL client connections, the protocol must be set toprotocol=nosqlprotocol. For more details on how to configure the NoSQL
protocol, refer to the module
documentation.
This sets the address the listening socket is bound to. The address may be
specified as an IP address in 'dot notation' or as a hostname. If left undefined
the listener will bind to all network interfaces.
Mandatory: Yes, if socket is not provided.
The port the listener listens on. If left undefined a default port for the
protocol is used.
Mandatory: Yes, if port is not provided.
If defined, the listener uses Unix domain sockets to listen for incoming
connections. The parameter value is the name of the socket to use.
If you want to use both network ports and UNIX domain sockets with a service,
define two separate listeners that connect to the same service.
The authenticator module to use. Each protocol module defines a default
authentication module, which is used if the setting is left undefined.MariaDBClient-protocol supports multiple authenticators and they can be used
simultaneously by giving a comma-separated list e.g.authenticator=PAMAuth,mariadbauth,gssapiauth
authenticator_options
This defines additional options for authentication. As of MaxScale 2.5.0, only_MariaDBClient_ and its authenticators support additional options. The value of
this parameter should be a comma-separated list of key-value pairs. See
authenticator specific documentation for more details.
Specify the sql mode for the listener similarly to global sql_mode setting.
If both are used this setting will override the global setting for this listener.
proxy_protocol_networks
Define an IP-address or a subnetwork which may send a
when connecting. The proxy header contains the original client IP-address and
port, and MaxScale will use that information in its internal bookkeeping.
This means the client is authenticated as if it was connecting from the host
in the proxy header. If proxy protocol is also enabled in MaxScale server
settings, MaxScale will relay the original client address and port to
the server. See for more information.
This setting may be useful if a compatible load balancer is relaying client
connections to MaxScale. If proxy headers are used, both MaxScale and the
backends will know where the client originally came from.
The proxy_protocol_networks-setting works similarly to the equivalent setting
in .
The value can be a single IP or subnetwork, or a comma-separated list of them.
Subnetworks are given in CIDR-format, e.g. "192.168.0.0/16". "*" is a valid
value, allowing anyone to send the header. "localhost" allows proxy headers
from domain socket connections.
Only trusted IPs should be added to the list, as the proxy header may affect
authentication results.
Similar to MariaDB Server, MaxScale will also accept normal connections even
if proxy_protocol_networks is configured for the listener.
connection_init_sql_file
Path to a text file with sql queries. Any sessions created from the listener
will send the contents of the file to backends after authentication. Each
non-empty line in the file is interpreted as a query. Each query must succeed
for the backend connection to be usable for client queries. The queries should
not return any data.
Example query file:
user_mapping_file
Path to a json-text file with user and group mapping, as well as server
credentials. Only affects MariaDB-protocol based listeners. Default value is
empty, which disables the feature.
Should not be used together with
settings pam_backend_mapping or pam_mapped_pw_file, as these may overwrite
the mapped credentials. Is most powerful when combined with service settinguser_accounts_file, as then MaxScale can accept users that do not exist on
backends and map them to backend users.
This file functions very similar to .
Both user-to-user and group-to-user mappings can be defined. Also, the password
and authentication plugin for the mapped users can be added. The file is only
read during listener creation (typically MaxScale start) or when a listener is
modified during runtime. When a client logs into MaxScale, their username is
searched from the mapping data. If the name matches either a name mapping or a
Linux group mapping, the username is replaced by the mapped name. The mapped
name is then used when logging into backends. If the file also contains
credentials for the mapped user, then those are used. Otherwise, MaxScale tries
to log in with an empty password and default MariaDB authentication.
Three arrays are read from the file: user_map, group_map and_server_credentials_, none of which are mandatory.
Each array element in the user_map-array must define the following fields:
original_user: String. Incoming client username.
mapped_user: String. Username the client is mapped to.
Each array element in the group_map-array must define the following fields:
original_group: String. Incoming client Linux group.
mapped_user: String. Username the client is mapped to.
Each array element in the server_credentials-array can define the following
fields:
mapped_user: String. The mapped username this password is for.
password: String. Backend server password. Can be encrypted with
maxpasswd.
plugin: String, optional. Authentication plugin to use. Must be enabled on
the listener. Defaults to empty, which results in standard MariaDB
authentication.
When a client successfully logs into MaxScale, MaxScale first searches for
name-based mapping. The incoming client does not need to be a Linux user for
name-based mapping to take place. If the name is not found, MaxScale checks if
the client is a Linux user with a group membership matching an element in the
group mapping array. If the client is a member of more than 100 groups, this
check may fail.
If a mapping is found, MaxScale searches the credentials array for a matching
username, and uses the password and plugin listed. The plugin need not be the
same as the one the original user used. Currently, "mysql_native_password" and
"pam" are supported as mapped plugins.
An example mapping file is below.
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.
This is the implementation of the MySQL-protocol. When defined for a listener,
the listener will accept MySQL-connections from clients, assign them to a
MaxScale service and route the queries from the client to backend servers. Any
backends used by the service should be MariaDB/MySQL-servers or compatible.
See for more information.
TLS/SSL encryption
This section describes configuration parameters for both servers and listeners
that control the TLS/SSL encryption method and the various certificate files
involved in it.
To enable TLS/SSL for a listener, you must set the ssl parameter totrue and provide at least the ssl_cert and ssl_key parameters.
To enable TLS/SSL for a server, you must set the ssl parameter totrue. If the backend database server has certificate verification
enabled, the ssl_cert and ssl_key parameters must also be defined.
Custom CA certificates can be defined with the ssl_ca parameter.
After this, MaxScale connections between the server and/or the client will be
encrypted. Note that the database must also be configured to use TLS/SSL
connections if backend connection encryption is used.
Note: MaxScale does not allow mixed use of TLS/SSL and normal connections on
the same port.
If TLS encryption is enabled for a listener, any unencrypted connections to it
will be rejected. MaxScale does this to improve security by preventing
accidental creation of unencrypted connections.
The separation of secure and insecure connections differs from the MariaDB
server which allows both secure and insecure connections on the same port. As
MaxScale is the gateway through which all connections go, in order to guarantee
a more secure system MaxScale enforces a stricter security policy than what the
server does.
TLS encryption must be enabled for listeners when they are created. For servers,
the TLS can be enabled after creation but it cannot be disabled or altered.
Starting with MaxScale 2.5.20, if the TLS certificate given to MaxScale has the
X509v3 extended key usage information, MaxScale will check it and refuse to use
a certificate with the wrong usage. This means that a certificate with only
clientAuth can only be used with servers and a certificate with only serverAuth
can only be used with listeners. In order to use the same certificate for both
listeners and servers, it must have both the clientAuth and serverAuth usages.
This enables SSL connections when set to true. The legacy values required anddisabled were removed in MaxScale 6.0.
If enabled, the certificate files mentioned above must also be
supplied. MaxScale connections to will then be encrypted with TLS/SSL.
Starting with MaxScale 21.06.18, 22.08.15, 23.02.12, 23.08.8, 24.02.4 and
24.08.1, if ssl is disabled for a listener, MariaDB user accounts that require
ssl cannot log in through that listener. Any user account with a non-empty_ssl_type_-field in mysql.user-table is blocked. This includes users created
with REQUIRE SSL or REQUIRE X509.
A string giving a file path that identifies an existing readable file. The file
must be the SSL client private key MaxScale should use. This is a required
parameter for listeners but an optional parameter for servers.
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. The
certificate must match the key defined in ssl_key. This is a required
parameter for listeners but an optional parameter for servers.
Deprecated since MariaDB MaxScale 22.08. See ssl_ca.
A string giving a file path that identifies an existing readable file. The file
must be the Certificate Authority (CA) certificate for the CA that signed the
certificate referred to in the previous parameter. It will be used to verify
that the certificate is valid. This is a required parameter for both listeners
and servers. The CA certificate can consist of a certificate chain.
NOTE Up until MariaDB MaxScale 6, the parameter was called ssl_ca_cert,
which is still accepted as an alias for ssl_ca.
This parameter controls the allowed TLS version. Accepted values are:
MaxScale versions 6.4.16, 22.08.13, 23.02.10, 23.08.6, 24.02.2 and all newer
releases accept also the following alias values:
The default setting (MAX) allows all supported versions. MaxScale supports
TLSv1.0, TLSv1.1, TLSv1.2 and TLSv1.3 depending on the OpenSSL library version.
TLSv1.0 and TLSv1.1 are considered deprecated and should not be used, so settingssl_version=TLSv1.2,TLSv1.3 or ssl_version=TLSv1.3 is recommended.
In MaxScale versions 6.4.13, 22.08.11, 23.02.7, 23.08.3 and earlier, this
setting defined the only allowed TLS version, e.g. ssl_version=TLSv12 would
only enable TLSv12. The interpretation changed in MaxScale versions 6.4.14,
22.08.12, 23.02.8, 23.08.4 to enable the user to disable old versions while
allowing multiple recent TLS versions. In these versions, ssl_version=TLSv1.2
enabled both TLSv1.2 and TLSv1.3.
The interpretation changed again in MaxScale versions 6.4.16, 22.08.13,
23.02.10, 23.08.6, 24.02.2. In these versions the value of ssl_version is an
enumeration of accepted TLS protocol versions. This means thatadmin_ssl_version=TLSv1.2 again only allows TLSv1.2. To retain the behavior
from the previous releases where the newer versions were automatically enabled,
the protocol versions must be explicitly listed, for exampleadmin_ssl_version=TLSv1.2,TLSv1.3. The change was done to make thessl_version behave identically to how the MariaDB
parameter works.
Set the list of TLS ciphers. By default, no explicit ciphers are defined and the
system defaults are used. Note that this parameter does not modify TLSv1.3
ciphers.
ssl_cert_verify_depth
The maximum length of the certificate authority chain that will be accepted. The
default value is 9, same as the OpenSSL default. The configured value must be
larger than 0.
ssl_verify_peer_certificate
Peer certificate verification. This functionality is disabled by default. In
versions prior to 2.3.17 the feature was enabled by default.
When this feature is enabled, the peer must send a certificate. The certificate
sent by the peer is verified against the configured Certificate Authority to
make sure the peer is who they claim to be. For listeners, this behaves as ifREQUIRE X509 was defined for all users. For servers, this behaves like the--ssl-verify-server-cert command line option for the mysql client.
ssl_verify_peer_host
Peer host verification.
When this feature is enabled, the peer hostname or IP is verified against the
certificate that is sent by the peer. If the IP address or the hostname does not
match the one in the certificate returned by the peer, the connection will be
closed. If the peer does not provide a certificate, the host verification is not
done. To require peer certificates, use ssl_verify_peer_certificate.
A string giving a file path that identifies an existing readable file. The file
must be a Certificate Revocation List in the PEM format that defines the revoked
certificates. This parameter is only accepted by listeners.
Example SSL enabled server configuration
This example configuration requires all connections to this server to be
encrypted with SSL. The paths to the certificate files and the Certificate
Authority file are also provided.
Example SSL enabled listener configuration
This example configuration requires all connections to be encrypted with
SSL. The paths to the 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.
Currently a number of routing modules are available, these are designed for a
range of different needs.
Connection based load balancing:
Read/Write aware statement based router:
Simple sharding on database level:
Binary log server:
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.
The use of monitors in MaxScale is not absolutely mandatory: it is possible to
run MariaDB MaxScale without a monitor module. In this case an external
monitoring system must the status of each server via MaxCtrl or the REST
API. Only do this if you know what you are doing.
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 document shows how you
can add a filter to a service and combine multiple filters in one service.
Encrypting Passwords
Passwords stored in the maxscale.cnf file may optionally be encrypted for added security.
This is done by creation of an encryption key on installation of MariaDB MaxScale.
Encryption keys may be created manually by executing the maxkeys utility with the argument
of the filename to store the key. The default location MariaDB MaxScale stores
the keys is /var/lib/maxscale. The passwords are encrypted using 256-bit AES CBC encryption.
Changing the encryption key for MariaDB MaxScale will invalidate any currently
encrypted keys stored in the maxscale.cnf file.
Note: The password encryption format changed in MaxScale 2.5. All
encrypted passwords created with MaxScale 2.4 or older need to be
re-encrypted.
Creating Encrypted Passwords
Encrypted passwords are created by executing the maxpasswd command with the location
of the .secrets file and the password you require to encrypt as an argument.
The output of the maxpasswd command is a hexadecimal string, this should be inserted
into the maxscale.cnf file in place of the ordinary, plain text, password.
MariaDB MaxScale will determine this as an encrypted password and automatically decrypt
it before sending it the database server.
Runtime Configuration Changes
Read the following documents for different methods of altering the MaxScale
configuration at runtime.
All changes to the configuration done via MaxCtrl are persisted as individual
configuration files in /var/lib/maxscale/maxscale.cnf.d/. The content of these
files will override any configurations found in the main configuration file or
any auxiliary configuration files.
Refer to the section for more
details on how this mechanism works and how to disable it.
Configuration Synchronization
The configuration synchronization mechanism is intended for synchronizing
configuration changes done on one MaxScale to all other MaxScales. This is done
by propagating the changes via the database cluster used by Maxscale.
When configuring configuration synchronization for the first time, the same
static configuration files should be used on all MaxScale instances that use the
same cluster: the value of config_sync_cluster must be the same on all
MaxScale instances and the cluster (i.e. the monitor) pointed by it and its
servers must be the same in every configuration.
Whenever the MaxScale configuration is modified at runtime, the latest
configuration is stored in the database cluster in the mysql.maxscale_config
table. The table is created when the first modification to the configuration is
done. A local copy of the configuration is stored in the data directory to allow
MaxScale to function even if a connection to the cluster cannot be made. By
default this file is stored at /var/lib/maxscale/maxscale-config.json.
Whenever MaxScale starts up, it checks if a local version of this configuration
exists. If it does and it is a valid cached configuration, the static
configuration file as well as any other generated configuration files are
ignored. The exception is the [maxscale] section of the main static
configuration file which is always read.
Each configuration has a version number with the initial configuration being
version 0. Each time the configuration is modified, the version number is
incremented. This version number is used to detect when MaxScale needs to update
its configuration.
Error Handling in Configuration Synchronization
When doing a configuration change on the local MaxScale, if the configuration
change completes on MaxScale but fails to be committed to the database, MaxScale
will attempt to revert the local configuration change. If this attempt fails,
MaxScale will discard the cached configuration and abort the process.
When synchronizing with the cluster, if MaxScale fails to apply a configuration
retrieved from the cluster, it attempts to revert the configuration to the
previous version. If successful, the failed configuration update is ignored. If
the configuration update that fails cannot be reverted, the MaxScale
configuration will be in an indeterminate state. When this happens, MaxScale
will discard the cached configuration and abort the process.
When loading a locally cached configuration during startup, if any errors are
found in the cached configuration, it is discarded and the MaxScale process will
attempt to restart by exiting with code 75 from the main process. If MaxScale is
being used as a SystemD service, this will automatically trigger a restart of
MaxScale and no further actions are needed.
The most common reason for a failed configuration update is missing files. For
example, if a configuration update adds encrypted connections to a server and
the TLS certificates it uses were not copied over to all MaxScale nodes before
the change was done, the operation will fail on all nodes that do not have these
files.
If the synchronization of the configuration change fails at the step when the
database transaction is being committed, the new configuration can be
momentarily visible to the local MaxScale. This means the changes are not
guaranteed to be atomic on the local MaxScale but are atomic from the cluster's
point of view.
Synchronization of Encrypted Passwords
Starting with MaxScale 6.4.9, any passwords that are transmitted by the
configuration synchronization are encrypted if password encryption has been
enabled in MaxScale. This means that all MaxScale nodes in the same
configuration cluster must be configured to use password encryption and they
need to all use the same encryption keys that were created with maxkeys.
Managing Configuration Synchronization
The output of maxctrl show maxscale contains the Config Sync field with
information about the current configuration state of the local Maxscale as well
as the state of any other nodes using this cluster.
The version field is the logical configuration version and the origin is the
node that originates the latest configuration change. The checksum field is
the checksum of the logical configuration and can be used to compare whether two
Maxscale instances are in the same configuration state. The nodes field
contains the status of each MaxScale instance mapped to the hostname of the
server. This field is updated whenever MaxScale reads the configuration from the
cluster and can thus be used to detect which MaxScales have updated their
configuration.
The mysql.maxscale_config table where the configuration changes are stored
must not be modified manually. The only case when the table should be modified
is when resetting the configuration synchronization.
To reset the configuration synchronization:
Stop all MaxScale instances
Remove the cached configuration file stored at/var/lib/maxscale/maxscale-config.json on all MaxScale instances
Drop the mysql.maxscale_config table
To disable configuration synchronization, remove config_sync_cluster from the
configuration file or set it to an empty string: config_sync_cluster="". This
can be done at runtime with MaxCtrl by passing an empty string toconfig_sync_cluster:
If MaxScale cannot create a connection to the database cluster, configuration
changes are not possible until communication with the database is possible. To
override this behavior and force the changes to be done, use the --skip-sync
option for maxctrl or the sync=false HTTP parameter for the REST API. Any
updates done with --skip-sync will overwritten by changes coming from the
cluster.
Limitations in Configuration Synchronization
Only the MaxScale configuration is synchronized. Any external files (TLS
certificates, configuration files for modules or data generated by MaxScale) are
not synchronized. For example, the rule files for the cache filter must be
synchronized separately if the filter itself is modified.
Starting with MaxScale 22.08, the Maintenance and Draining states of servers
and modifications to the administrative users will be synchronized. In older
versions servers had to be put into maintenance mode and users had to be
modified separately on each MaxScale.
() External files are not
synchronized.
() The --export-config
option will not export the cluster configuration and instead exports only the
static configuration files. To start a new MaxScale based off of a clustered
configuration, copy the static configuration files as well as the JSON
configuration in /var/lib/maxscale/maxscale-config.json to the new MaxScale
instance.
Backing Up Configuration Changes
The combination of configuration files can be done either manually
(e.g. rsync) or with the maxscale --export-config=FILE command line
option. See maxscale --help for more information about how to use the--export-config flag.
For example, to export the current runtime configuration, run the following
command.
This will create the /tmp/maxscale.cnf.combined file and write the current
configuration into the it. This allows new MaxScale instances to be easily set
up without requiring copying of all runtime configuration files. The user
executing the command must be able to read all MaxScale configuration files as
well as create and write the provided filename.
Encryption Key Managers
The encryption key managers are how MaxScale retrieves symmetric encryption keys
from a key management system. Some parts of MaxScale require the key_manager
to be configured in order to work. The key manager that is used is selected with
the parameter and the key manager itself is
configured by placing the parameters in the [maxscale] section.
The encryption key managers can be enabled at runtime using maxctrl alter maxscale but cannot be disabled once enabled. To disable the encryption key
management, stop Maxscale, remove any persisted configuration files and removekey_manager as well as any key manager options from the static configuration
files.
File-based Key Manager
The encryption keys are stored in a text file stored on a local filesystem.
The file uses the same format as the MariaDB server : a file
consisting of an encryption key ID number and the hex-encoded encryption key
separated by a semicolon. Read
for more details on how to create the file.
For example, to configure encryption for the nosqlprotocol shared credentials
using the file-based encryption key:
Create the key file with (echo -n '1;' ; openssl rand -hex 32) | cat > /var/lib/maxscale/encryption.key
Give MaxScale read permissions on it with chown maxscale:maxscale /var/lib/maxscale/encryption.key
Configure MaxScale with the following:
Key versioning is not supported
file.keyfile
Path to the file that contains the encryption keys. The user MaxScale runs as
(almost always maxscale) must be able to read this file. Encryption keys are
read from disk only during startup or when any global MaxScale parameter is
modified at runtime.
KMIP Key Manager
Encryption keys are read from a KMIP server.
The KMIP key manager has been verified to work with the PyKMIP server.
Key versioning is not supported
Encryption keys are not cached locally: whenever MaxScale needs an encryption
key, it retrieves it from the KMIP server.
kmip.host
The host where the KMIP server is.
kmip.port
The port on which the KMIP server listens on.
kmip.cert
The client public certificate used when connecting to the KMIP server.
kmip.key
The client private key used when connecting to the KMIP server.
kmip.ca
The CA certificate to use. By default the system default certificates are used.
HashiCorp Vault Key Manager
Encryption keys are read from a local or remote Vault server using the secret
engine included in the Vault. This key manager supports versioned keys. Only
version 2 key-value stores are supported.
The encryption keys use the same format as the MariaDB :
The key-value secret for each encryption key ID must contain the field data
which must contain a hex-encoded string that is either 32, 48 or 64 characters
long.
An easy way to generate a correct encryption key is to use the vault andopenssl command line clients. The following command creates a 256-bit
encryption key using openssl and stores it using the key ID 1:
Encryption keys are not cached locally: whenever MaxScale needs an encryption
key, it retrieves it from the Vault server.
vault.token
The authentication token used to connect to the Vault server. This can be
encrypted using maxpasswd, similar to how other passwords are encrypted.
vault.host
The host where the Vault server is.
vault.port
The port on which the Vault server listens on.
vault.ca
The CA certificate to use. By default the system default certificates are used.
vault.tls
Whether to use encrypted connections (i.e. HTTPS or HTTP) when communicating
with the Vault server.
vault.mount
The Key-Value mount where the secret is stored. By default the secret mount is
used which is present by default in most Vault installations.
vault.timeout
The connection and request timeout used with the Vault server.
For routing, MaxScale uses asynchronous I/O and a fixed number of threads
(aka routing workers), whose number up until 23.02 was fixed at startup.
From 23.02 onwards the number of threads can be altered at runtime, which
is convenient, for instance, if MaxScale is running in a container whose
properties are changed during the lifetime of the container.
A thread can be in three different states:
Active: The thread is routing client traffic and is listening
for new connections.
Draining: The thread is routing client traffic but is not
listening for new connections.
Dormant: The thread is not routing client traffic (all sessions
have ended), and is not listening for new connections, and is waiting
to be terminated.
All threads start as Active and may become Draining if the number of
threads is reduced. A draining thread will eventually become Dormant,
unless the number of threads is increased while the thread is still Draining.
Note that it is not possible to terminate a specific thread, but it is only
possible to specify the number of threads that MaxScale should use, and
that the threads will be terminated from the end. This has implications
if the number of threads is reduced by more than 1, as a Dormant thread
will not be terminated before it is the last thread.
In the following, MaxScale has been started with threads=4.
All threads are Active. If we now decrease the number of threads
we will see that the threads 2 and 3 are now Draining. The reason is
that threads 2 and 3 still handle client sessions. If some client sessions
now end, the situation may become like
That is, thread 2 is Dormant and thread 3 is Draining. All client sessions
that were handled by thread 2 have ended and the thread is ready to be
terminated. However, as thread 3 is still Draining, thread 2 will not be
terminated but stay Dormant.
If the sessions handled by thread 3 end, then it will become Dormant at
which point first thread 3 will be terminatad and immediately after that
thread 2.
If the situation is like
that is, the number of threads was 4 but has been reduced to 2, and while
thread 2 has become drained it stays as Dormant since thread 3 is stillDraining, it is possible to make thread 2 Active again by increasing the
number of threads to 3.
Once the sessions of thread 3 ends, we will have
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 and the system log.
The current limitations of MaxScale are listed in the document.
Performance Optimization
Tune query_classifier_cache_size to allow maximal use of the query
classifier cache. Increase the value and/or system memory until the set of
unique SQL patterns fits into memory. By default at most 15% of the system
memory is used for this cache. To detect if the SQL statements fit into
memory, monitor the QC cache evictions value in maxctrl show threads to
see how many evictions take place. If it keeps increasing, increase the size
of the query classifier cache. Using the query classifier cache with a CPU
bound workload gives a roughly 20% improvement in performance compared to when
it is turned off.
A faster CPU with more CPU cores is better. This is true for most applications
but especially for MaxScale as it is mostly limited by the speed of the
CPU. Using threads=auto
MaxScale Diagnostics using MaxCtrl
From 22.08.2 onwards, maxctrl show maxscale shows a System object with
information about the system MaxScale is running on. The fields are:
In addition there is an os object that contains what the Linux command uname displays.
threads
If threads has not been specified at all in the MaxScale configuration file,
or if its value is auto, then MaxScale will use as many routing threads as
there are physical cores on the machine. This is the right choice, if MaxScale
is running on a dedicated machine or in a container that has not been restriced
in any way.
However, if the number of cores available to MaxScale have been restricted or
if MaxScale is running in a container whose CPU quota and period have been
limited, then it will lead to MaxScale using more routing threads than what
is appropriate in the environment where it is running.
If machine.cores_virtual is less than machine.cores_physical, then threads
should be specified explicitly in the MaxScale configuration file and its value
should be that of machine.cores_virtual rounded up to the nearest integer. If
that value is 1 it may be beneficial to check whether 2 gives better performance.
query_classifier_cache_size
If query_classifier_cache_size has not been specified in the MaxScale
configuration file, then MaxScale will use at most 15% of the amount of physical
memory in the machine for the cache. This is a good starting point, if MaxScale
is running on a dedicated machine or in a container that has not been restriced
in any way. Note that the amount specifies how much memory the cache at maximum
is allowed to use, not what would immediately be allocated for the cache.
However, if the amount of memory available to MaxScale has been restricted,
which may be the case if MaxScale is running in a container, this may cause the
cache to grow beyond what is available, which will lead to a crash or MaxScale
being killed.
If the value of machine.memory_available is less than that ofmachine.memory_physical, then query_classifier_cache_size should be explicitly
set to 15% of maxscale.memory_available. The value can be larger, but must not
be a bigger share of machine.memory_available than what is reasonable.
As can be seen, maxscale.threads is larger than machine.cores_virtual and thus,threads=4 should explicitly be specified in the MaxScale configuration file.
maxscale.query_classifier_cache_size is the default 15% of machine.memory_physical
but as machine.memory_available is just half of that, something likequery_classifier_cache_size=3100000000 (~15% of machine.memory_available) should be
added to the configuration file.
Troubleshooting
For a list of common problems and their solutions, read the
article on the MariaDB documentation.
Systemd Watchdog
If MaxScale is running as a systemd service, the systemd Watchdog will be
enabled by default. To configure it, change the WatchdogSec option in the
Service section of the maxscale systemd configuration file located in/lib/systemd/system/maxscale.service:
It is not recommended to use a watchdog timeout less than 30 seconds. When
enabled MaxScale will check that all threads are running and notify systemd
with a "keep-alive ping".
Systemd reference:
This page is licensed: CC BY-SA / Gnu FDL
