Table of Contents
The format of the configuration file resembles the traditional INI file format with sections and options.
MySQL Router scans for the default configuration files at startup, and optionally loads user-defined configuration files runtime from the command line.
By default, MySQL Router scans specific locations for its configuration files.
You can alter the default locations at compile time by using the
-DROUTER_CONFIGDIR=<path> option. You
could also edit cmake/settings.cmake to
change the default locations before compiling MySQL Router, thus
adding new locations or exceptions for specific platforms.
Execute mysqlrouter --help to see the default
configuration file locations (and their availability) on your
system.
shell>mysqlrouter --helpMySQL Router v2.0.3 on Linux (64-bit) (GPL community edition) Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved. Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners. Start MySQL Router. Configuration read from the following files in the given order (enclosed in parentheses means not available for reading):/etc/mysqlrouter/mysqlrouter.ini(/home/myusername/.mysqlrouter.ini) Usage: mysqlrouter [-v|--version] [-h|--help] [-c|--config=<path>] [-a|--extra-config=<path>] ...
The default configuration file is not loaded if a user-defined
configuration file is passed in with the --config,
-c option.
On Linux and OS X, MySQL Router scans the following locations, although these locations are system dependent:
/etc/mysqlrouter/mysqlrouter.ini
Unlike MySQL server, the backward compatible path
"/etc/mysqlrouter.ini" is not
supported.
$HOME/.mysqlrouter.ini
Two command line options help control these configuration file locations:
-c, --config: Read the base configuration from this file, and not use or scan the default file paths.
Only one -c, --config configuration file
can be loaded at any given time.
-a, --extra-config: Read
this additional configuration file after the configuration
files are read from either the default locations, or from
files specified using the -c, --config
option.
For example:
shell> mysqlrouter -c /custom/path/to/router.ini -a /another/config.ini
Multiple extra configuration options can be passed in, and the
files are loaded in the order they are entered, with
--config options being loaded before
--extra-config options. For example:
shell> mysqlrouter -a a.ini -c b.ini -a c.ini -a d.ini
In the above example, b.ini is loaded
first, and then a.ini,
c.ini and d.ini, in
that order. Because -c, --config was used, the
default configuration file, such as
/etc/mysqlrouter/mysqlrouter.ini, is not
loaded.
Each loaded configuration file will override configuration settings from previously read files.
The following lists default file location for the router to read configuration files on popular Linux platforms.
Generic Linux (standalone‐layout) :
./mysqlrouter.ini
Default, installing under /usr/local :
/usr/local/etc/mysqlrouter.ini
RPM and Debian :
/etc/mysqlrouter/mysqlrouter.ini
MySQL Router reads options from configuration files that closely resemble the traditional INI file format, with sections and options. These specify the options set when MySQL Router starts.
An example router ini file is added to the system's share/doc/ directory for MySQL Router.
Below are the available configuration options divided by section, with an example configuration file to follow. There is one additional section specific to using the Fabric integration connection routing with the Fabric Cache plugin. These options are discussed in the Fabric Cache Plug-in section below.
The following options are available for the general section
identified by [DEFAULT].
Information related to the folder options, and setting these is optional.
logging_folder: path to the MySQL Router log
file directory. The log file is named
mysqlrouter.log, and it is either
generated or appended to if this file already exists.
Setting logging_folder to an empty value,
or not setting it, sends the messages to the console
(stdout).
Default value: ""
plugin_folder: path to the MySQL Router
plugins. This folder must match the MySQL Router installation
directory. You should only set this if you have a custom
installation where the plugins are not in the standard
installation location.
Default value:
/usr/local/lib/mysqlrouter
runtime_folder: path to the MySQL Router
runtime files.
Default value:
/usr/local/
config_folder: path to the MySQL Router
configuration files.
The config_folder is currently set at
compile time. The option could be used by future plugins
when they have there own configuration files.
Default value:
/usr/local/etc/mysqlrouter
An example mysqlrouter.ini file that
relies on most defaults, and is set to send logs to
/var/log/mysqlrouter/mysqlrouter.log:
[DEFAULT] logging_folder = /var/log/mysqlrouter
The following options are available to routing strategy sections
identified by [routing:<section_key>].
Information related to the bind_address
option:
Routing entries can bind to a network interface (NIC). The
default bind_address is
127.0.0.1. If a port is not defined
here, then setting bind_port is required.
Binding to a specific IPv4 or IPv6 address allows and ensures that MySQL Router is not starting and routing the service on a NIC on which nothing is allowed to execute.
It is not possible to specify more than one binding
address, per routing configuration group. However, using
0.0.0.0:$port (where you define
$port) will bind to all network interfaces (IPs) on the
host. You can also use IPv6 addresses.
bind_address = 127.0.0.1:7001
The bind_address cannot be listed in the
destinations list.
Optionally, you can define a default port using
bind_port. If a port is not configured in
bind_address, then bind_port
is required and used.
The four examples below all result in bind_address = 127.0.0.1:7001
[routing:example_1] bind_port = 7001
[routing:example_2] bind_port = 7001
[routing:example_3] bind_port = 8001
[routing:example_4] bind_address = 127.0.0.1:7001
Information related to the connect_timeout
option. This is used by the routing plugin when connecting to
the destination MySQL server. The default value is 1 second.
The value cannot be unlimited, and an invalid value results in
a configuration error. The valid range is between 1 and 65536.
You should keep this value low.
For example, when using read-write mode,
the value can be a bit higher if you want to wait for the
server (Master) to become available. When using
read-only mode, connecting to a slave it is
good to use a lower value since the Router will select a new
server during connection routing.
connect_timeout = 1
Information related to the destinations
option:
Provides a comma-separated list of destination addresses that should be used when establishing connections. The default port is 3306.
destinations = a.example.com,b.example.com,c.example.com
Behavior depends on the mode option.
Information related to the mode option.
Setting this parameter is
required, and each mode has
different scheduling. Two modes are supported:
read-write: Typically used for routings to a MySQL master.
Mode Schedule: In read-write mode, all traffic is directed to the initial address on the list. If that fails, then MySQL Router will try the next entry on the list, and will continue trying each MySQL server on the list. If no more MySQL servers are available on the list, then routing is aborted. This method is also known as "first-available".
The first successful MySQL server contacted is saved in memory as the first to try for future incoming connections. This is a temporary state, in that it won't be remembered after MySQL Router is restarted.
[routing:example_strategy]
bind_port = 7001
destinations = master1.example.com,master2.example.com,master3.example.com
mode = read-write
read-only: Typically used for routings to a MySQL slave.
Mode Schedule: Mode read-only uses a simple round-robin method to go through the list of MySQL Servers. It sends the first connection to the first address on the list, the next connection to the second address, and so on, and will circle back to the first address after the list is exhausted.
If a MySQL server is not available, then the next server is tried. When none of the MySQL servers on the list are available, then the routing is aborted.
Unavailable MySQL server's are quarantined. Their availability is checked, and when available they are put back on the available destinations list. The destinations order is maintained.
[routing:ro_route]
bind_port = 7002
destinations = slave1.example.com,slave2.example.com,slave3.example.com
mode = read-only
Both modes are available for connection routing with or without MySQL Fabric (standalone or Fabric integration).
Information related to the max_connections
option. Each routing can limit the number of routes or
connections. One possible use is to help prevent possible
Denial-Of-Service (DOS) attacks. The default value is 512, and
the valid range is between 1 and 65536.
This is similar to MySQL Server's max_connections server system variable.
max_connections = 512
Information related to the max_connect_errors
option. The default value is 100, and the valid range is
between 1 and 2^32 (an unsigned int).
This is similar to MySQL Server's max_connect_errors server system variable.
This can cause a slight performance penalty if an application performs frequent reconnections, because Router attempts to discover if connection related errors are present.
Each routing has its own list of blocked hosts. Blocked clients receive the MySQL Server error 1129 code with a slightly different error message: "1129: Too many connection errors from fail.example.com". The Router logs contain extra information for blocked clients, such as: INFO [...] 1 authentication errors for fail.example.com (max 100) WARNING [...] blocking client host fail.example.com
max_connect_errors = 100
This option was added in Router 2.0.3.
Information related to the
client_connect_timeout option. The default
value is 9, which is one less than the MySQL 5.7 default. The
valid range is between 2 and 31536000.
This is similar to MySQL Server's connect_timeout server system variable.
client_connect_timeout = 9
This option was added in Router 2.0.3.
The following options are available for the logging section
identified by [logger]
Use the logger plugin to log notices, errors, and debugging information. The available log levels are INFO (default) and DEBUG. These values are case-insensitive.
The INFO level will display all informational messages, warnings, and error messages. The DEBUG level displays additional diagnostic information from the Router code, including successful routes.
The MySQL Harness plugin also supports logging modes of WARNING, ERROR, and FATAL, but these are not available in MySQL Router 2.0.2.
[logger] level = DEBUG
By default, level=INFO is set and used if [logger] is not set in your configuration file.
Output behavior depends on the logging_folder
option. Setting logging_folder to a folder
saves a log file named mysqlrouter.log to
that folder. Setting logging_folder to an
empty value, or not setting it, outputs the log to the
console. It is set in the [DEFAULTS]
section, and for additional information see
Folder Paths.
Here is a basic example using connection routing to multiple
masters. In this setup, all traffic will go to a.example.com,
unless it is down (fails) then traffic will go to the next
address on the list, which is b.example.com. If that fails, then
c.example.com. This behavior is dictated by the
read-write mode.
The section key (we use "failover" below) is optional, but such descriptions are helpful for debugging, and it allows multiple configuration sections for the plugin.
[DEFAULT] logging_folder = /var/log/mysqlrouter [logger] level = DEBUG [routing:failover] bind_port = 7001 mode = read-write destinations = a.example.com,b.example.com,c.example.com
In a similar example, we change the mode from
read-write to read-only to
implement a form of round-robin load-balancing:
[DEFAULT] logging_folder = /var/log/mysqlrouter [logger] level = DEBUG [routing:balancing] bind_port = 7002 mode = read-only destinations = x.example.com,y.example.com,z.example.com
In that case, the connections are distributed over the available servers (destinations) in a round-robin fashion rather than sending all connections to the first server.