4.3.3 Configuration File Options
When started, MySQL Router reads a list of configuration files that together make up the configuration of the router. At least one configuration file is required.
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. For file syntax information, see Section 4.1, “Configuration File Syntax”.
Options are defined under sections, that dictate the option's meaning. For example, user under the [DEFAULT] section refers to the system user running router, while user under the [metadata_cache] section refers to the MySQL user that accesses metadata.
The following tables are separated by section, and summarize the MySQL Router options defined in a MySQL Router configuration file. Detailed information about each of these options, such as descriptions and allowed values, is documented below these tables.
logging_folder
Type String Default Value $router_basepath 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 sends the messages to the console (stdout).
Note
The default logging_folder value changed from "" to Router's base path in MySQL Router 2.1.
An example that sends logs to /var/log/mysqlrouter/mysqlrouter.log:
[DEFAULT] logging_folder = /var/log/mysqlrouterWhen the --directory bootstrap option is used, the generated configuration file sets it to $directory/log/.
plugin_folder
Type String Default Value (Windows) Default Value (Other) /usr/local/lib/mysqlrouter 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
Type String Default Value (Windows) Default Value (Other) /run/mysqlrouter Path to the MySQL Router runtime files.
Default value: /run/mysqlrouter
master-key-writer
Command-Line Format --master-key-writer file_path Introduced 8.0.12 Type String Script that reads the master key from STDIN. Set using the --master-key-writer command-line bootstrap option.
master-key-reader
Command-Line Format --master-key-reader file_path Introduced 8.0.12 Type String Script that returns the master key to STDOUT. Set using the --master-key-reader command-line bootstrap option.
config_folder
Type String Default Value (Windows) Default Value (Other) /usr/local/etc/mysqlrouter Path to the MySQL Router configuration files.
Note
The config_folder is currently set at compile time. The option could be used by future plugins when they have their own configuration files.
Default value: /usr/local/etc/mysqlrouter
sinks
Introduced 8.0.16 Type String Valid Values (Windows) consolelog
filelog
eventlog
Valid Values (Other) consolelog
filelog
syslog
The sink(s) (different logging methods) that a defined log level are sent to.
Supported sink values are: consolelog, filelog, eventlog (on Windows), and syslog (on Unix-based systems). Use a comma-separated list to define multiple values.
Default value: filelog if the logging_folder option is not empty in the "[DEFAULT]" section, otherwise consolelog.
For example, to configure logger to use the file, console and the event log each using the debug log level configured in the [logger] section:
[logger] level=debug sinks=consolelog,eventlog,filelogkeyring_path
Type String Default Value (Windows) %PROGRAMDATA%\MySQL\MySQL Router\keyring-data Default Value (Other) /run/mysql-router/keyring-data Points to the keyring file's location.
A system-wide bootstrap does not add this option to the generated configuration file, and assumes the keyring file is located in the system-wide runtime state directory. If --directory is also used, then the keyring file is stored under the runtime state directory of that instance, under run/ in the specified directory.
System-wide default paths are used if this option is not defined.
Example usage:
keyring_path = /opt/myrouter/data/keyring master_key_path = /opt/myrouter/mysqlrouter.keymaster_key_path
Type String Default Value (Windows) %PROGRAMDATA%\MySQL\MySQL Router\mysqlrouter.key Default Value (Other) /run/mysql-router/mysqlrouter.key The master key file's location. This option allows unattended decryption, as otherwise its location is requested at startup.
System-wide default paths are used if this option is not specified.
Example usage:
keyring_path = /opt/myrouter/data/keyring master_key_path = /opt/myrouter/mysqlrouter.keyunknown_config_option
Introduced 8.0.29 Type String Default Value warning Valid Values warning
error
Determines MySQL Router behavior for handing unknown configuration options, such as typos.
A warning is default behavior, and bootstrapping defines it as error in the generated configuration file. MySQL Router versions before 8.0.29 ignore unknown configuration options. A warning logs a warning message but does not halt, whereas an error means Router fails to initialize and exits.
[DEFAULT] unknown_config_option=warninguser (system)
Run mysqlrouter as the user having the name user_name or the numeric user ID user_id. “User” in this context refers to a system login account, not a MySQL user listed in the grant tables. This can also be assigned at runtime using the --user command line option.
On Linux, installing Router with official DEB or RPM packages creates a local system user and group named "mysqlrouter" on the host, and MySQL Router runs as this user by default. This account does not have shell access and its home directory points to the directory where the default configuration file is stored.
The purpose of this option is to run MySQL Router as a user with restricted system privileges. If the user does not exist on the system, or if an attempt to start Router as root is made, an error is emitted and Router exits.
MySQL Router can be bootstrapped and executed under any Operating System user and does not require special privileges other than read and write access to its own files. The files it accesses include plugins (read/execute), configuration file, logs, UNIX domain socket files (if enabled), and more.
By default, the configuration and log files are written to a system-wide location such as /etc and /var/log. Alternatively, Router can be bootstrapped to a self-contained directory of its own by using the --directory option. For example:
$> sudo mysqlrouter --bootstrap localhost:3310 --directory /a/path/myrouter --user snoopyIn this example, Router creates /a/path/myrouter and adds all of the generated files and directories here, and these are only writable by the system user snoopy. Additionally, user is defined in the generated configuration file /a/path/myrouter/mysqlrouter.conf:
[DEFAULT] user=snoopyNote
This is different from the user definition defined in the [metadata_cache] section, which is a MySQL user.
ssl_ca
Path to the SSL CA file to verify server's certificate against when connecting to the metadata servers.
Can optionally be set with the --ssl-ca bootstrap option.
ssl_capath
Path to directory containing SSL CA files to verify server's certificate against when connecting to the metadata servers.
Can optionally be set with the --ssl-capath bootstrap option.
ssl_crl
Path to SSL CRL file to use when connecting to metadata servers and verifying their SSL certificate.
Can optionally be set with the --ssl-crl bootstrap option.
ssl_crlpath
Path to directory containing SSL CRL files to use when connecting to metadata servers and verifying their SSL certificate.
Can optionally be set with the --ssl-crlpath bootstrap option.
tls_version
Comma-separated list of TLS versions to request, such as 'TLSv1.2,TLSv1.3', if SSL is enabled.
Can optionally be set with the --tls-version bootstrap option.
bind_address
Type String Default Value 127.0.0.1 Information related to the optional bind_address option:
Routing entries can be bound 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.
By default, --bootstrap sets bind_address=0.0.0.0 for each route in the generated Router configuration file. This value can be changed using --conf-bind-address.
Binding to a specific IPv4 or IPv6 address allows and ensures that MySQL Router is not starting and routing the service on an 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) binds all network interfaces (IPs) on the host. IPv6 addresses can also be used.
Example usage:
bind_address = 127.0.0.1:7001Note
The bind_address cannot be listed in the destinations list.
bind_port
Optionally, you can define a default port for bind_address using bind_port. If a port is not configured in bind_address, then bind_port is required and used.
Optionally set these values by using the --conf-base-port bootstrap option.
The three examples below all result in bind_address = 127.0.0.1:7001
[routing:example_1] bind_port = 7001[routing:example_2] bind_port = 7001 bind_address = 127.0.0.1[routing:example_3] bind_address = 127.0.0.1:7001socket
Platform Specific Linux Type String Sockets are enabled using the socket option, which can be specified with or without the TCP bind_port and bind_address options. An example:
[routing] socket = /tmp/mysqlrouter.sock destinations = a.example.com:3306,b.example.com:3307When launching MySQL Router, Router will refuse to run if either the socket file already exists or it cannot be written to.
Relative paths are acceptable and based on the current working directory where Router is launched.
Router can listen to both TCP sockets and Unix sockets simultaneously. For example, the following [routing] configuration example is valid and configures Router to listen for connections on both localhost:1234 and /tmp/mysqlrouter.sock:
[routing:my_redirect] bind_address = localhost:1234 socket = /tmp/mysqlrouter.sock mode = read-write destinations = localhost:57121, localhost:57122, localhost:57123Note
A Unix domain socket length limit is platform-specific and should not exceed the system's allowed length.
protocol
Type String Default Value classic Valid Values classic
x
Used by the routing plugin when connecting to the destination MySQL server, and can be set to either "classic" (default), or "x" (X Protocol).
Example usage:
[routing:basic_failover] bind_port = 7001 mode = read-write destinations = 10.20.200.1:33060, 10.20.200.2:33060 protocol = xThe protocol option also affects the default port used by each destination. If a destination port is not configured, then the default port is 3306 for "classic" (default), 33060 for "x" (X Protocol).
pid_file
Introduced 8.0.20 Type String Sets location of the PID file. This can be set in three different ways (in order of precedence): the --pid-file command-line option, setting this pid_file option in Router's configuration file, or defining the ROUTER_PID environment variable.
If --bootstrap is specified, then the pid_file and ROUTER_PID definitions are ignored. This is unlike the --pid-file command-line option which causes Router to fail.
If --bootstrap is not specified, then the following cause Router to fail: the --pid-file already exists, pid_file or ROUTER_PID are set but empty, or if Router can't write the PID file.
connect_timeout
Type Integer Default Value (≥ 8.0.29) 5 Default Value (≤ 8.0.28) 1 Minimum Value 1 Maximum Value 65536 Timeout value used by the MySQL Router when connecting to the destination MySQL server. 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 little higher to wait for the PRIMARY to become available. When using read-only mode for secondary connections, a lower value makes more sense because Router selects a new server during connection routing.
Example usage:
[routing] connect_timeout = 5Can be set at bootstrap using --conf-set-option=routing.connect_timeout.
connect_timeout
Type Integer Default Value (≥ 8.0.29) 5 Default Value (≥ 8.0.14, ≤ 8.0.28) 15 Default Value (≤ 8.0.13) 30 Timeout value used by the MySQL Router when connecting to the MySQL metadata server.
Example usage:
[DEFAULT] connect_timeout = 5Can be set at bootstrap using either --connect-timeout or --conf-set-option=DEFAULT.connect_timeout.
read_timeout
Type Integer Default Value 30 Timeout value used by the MySQL Router when reading from the MySQL metadata server. The default value is 30 seconds.
Example usage:
[DEFAULT] read_timeout = 30destinations
Provides host information for establishing connections. It accepts either a comma-separated list of destination addresses or a metadata-cache link to an InnoDB cluster.
Example usage with specific hosts (static routing):
destinations = a.example.com,b.example.com,c.example.comNote
If a destination's port is not explicitly set, then the default port is 3306 if protocol is set to "classic" or not set (default), or port 33060 if protocol is set to "x".
Example usage with InnoDB cluster metadata cache:
destinations=metadata-cache://mycluster/default?role=PRIMARYThe metadata-cache URI options are:
role: Determines the type of instances available to the connection. Acceptable values are PRIMARY, SECONDARY, or PRIMARY_AND_SECONDARY.
The routing_strategy mysqlrouter.conf option defines the specific strategy, and the default metadata-cache routing strategy is round-robin.
disconnect_on_promoted_to_primary: Controls whether existing client connections to a secondary are closed when the secondary is promoted as a primary. The default value is "no", meaning existing client connections to the promoted secondary are not closed after promotion. Set disconnect_on_promoted_to_primary=yes in the URI to close these existing connections.
This option was added in MySQL Router 8.0.12.
disconnect_on_metadata_unavailable: Controls whether existing client connections are closed when the group is overloaded. The default value is "no", meaning existing client connections are not closed when the group is overloaded. Set disconnect_on_metadata_unavailable=yes in the URI to close these existing connections.
This option was added in MySQL Router 8.0.12.
Note
Related, these conditions cause disconnections: connections to a primary after the primary is downgraded to a secondary, and connections to a node that are no longer part of the cluster.
dynamic_state
Introduced 8.0.14 Type String This option tracks and stores active MySQL InnoDB Cluster Metadata server addresses and loads them if Router is restarted. This functionality is activated by --bootstrap and is preferred over the deprecated static bootstrap_server_addresses option.
Bootstrapping defines the dynamic_state option in mysqlrouter.conf file under the [DEFAULT] section. The value is a path to a JSON file named state.json, which is created when Router has been bootstrapped. The state.json is initialized with InnoDB Cluster Metadata server addresses and the Group Replication ID (the group_replication_name returned by the InnoDB Cluster ); additional information is added and updated while Router is running.
Example mysqlrouter.conf entry:
[DEFAULT] dynamic_state=/opt/myrouter/data/state.jsonExample state.json generated by --bootstrap:
{ "metadata-cache": { "group-replication-id": "4b9e817a-0254-11e9-9cc0-080027bb5030", "cluster-metadata-servers": [ "mysql://localhost:3310", "mysql://localhost:3320", "mysql://localhost:3330" ] }, "version": "1.0.0" }The dynamic_state and deprecated bootstrap_server_addresses options cannot be set at the same time. For backwards compatibility, if only bootstrap_server_addresses is set then it functions as it did in previous Router versions and this dynamic configuration functionality is not used.
This option was added in MySQL Router 8.0.14.
mode
Type String Valid Values read-write
read-only
The deprecated mode option sets Router's scheduling, and the two supported mode values are:
Important
MySQL Router 8.0.4 introduced the routing_strategy option as a more flexible way to configure the mode schedule.
Both mode and routing_strategy cannot be set at the same time. Setting one is required for static routing while they are optional with InnoDB cluster.
read-write: Typically used for routing to a master or primary MySQL instance.
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 continues trying each MySQL server on the list. If no more MySQL servers are available on the list then routing is aborted.
Note
With routing_strategy, this same behavior can be defined using routing_strategy=next-available instead of mode=read-write.
The first successful MySQL server contacted is saved in memory as the first to try for future incoming connections. This is a temporary state, meaning this is forgotten after MySQL Router is restarted.
[routing:example_strategy_mode] bind_port = 7001 destinations = primary1.example.com,primary2.example.com,primary3.example.com mode = read-writeBecause mode is deprecated, the previous example should use routing_strategy instead:
[routing:example_strategy] bind_port = 7001 destinations = primary1.example.com,primary2.example.com,primary3.example.com routing_strategy = next-availableread-only: Typically used for routing to a replica or secondary MySQL instance.
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 circles back to the first address after the list is exhausted.
Note
With routing_strategy, this same behavior can be defined using routing_strategy=round-robin instead of mode=read-only.
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 servers are quarantined. Their availability is rechecked and when available they are put back onto the available destinations list. The destinations order is maintained.
[routing:ro_route_mode] bind_port = 7002 destinations = secondary1.example.com,secondary2.example.com,secondary3.example.com mode = read-onlyBecause mode is deprecated, the previous example should use routing_strategy instead:
[routing:ro_route] bind_port = 7002 destinations = secondary1.example.com,secondary2.example.com,secondary3.example.com routing_strategy=round-robin
Alternatively, the previous destinations example could use metadata-cache to utilize InnoDB cluster's metadata cache that dynamically configures host information. For example: .
[routing:ro_route] bind_port = 7002 destinations=metadata-cache://myCluster/default?role=SECONDARY routing_strategy=round-robinrouting_strategy
Type String Valid Values first-available
next-available
round-robin
round-robin-with-fallback
The routing strategy defines how MySQL Router chooses MySQL servers to connect to.
Important
MySQL Router 8.0.4 introduced the routing_strategy option as a more flexible way to define the strategy. Previously this behavior was defined using the now deprecated mode option.
Both routing_strategy and mode cannot be set at the same time. Setting one is required for static routing while they are optional with InnoDB cluster.
Available strategies:
Note
The role documentation following this section describes the available role and routing_strategy combinations and conflicts.
Unreachable destinations are quarantined and skipped, and are probed for availability every unreachable_destination_refresh_interval seconds. All routing strategies except for next-available utilize this behavior. This functionality was added in v8.0.29.
round-robin: for load-balancing, each new connection is made to the next available server in a round-robin fashion.
round-robin-with-fallback: for load-balancing, each new connection is made to the next available secondary server in a round-robin fashion. If a secondary server is not available then servers from the primary list are used in round-robin fashion.
first-available: the new connection is routed to the first available server from the destinations list. In case of failure, the next available server is used. This cycle continues until all servers are unavailable.
next-available: like first-available, in that the new connection is routed to the first available server from the destinations list. Unlike first-available, if a server is marked as unreachable then it gets discarded and is never used again as a destination.
This strategy is backward compatible with MySQL Router 2.x's mode's read-write behavior. Its limitations include:
After all nodes of the selection are discarded, there is no way to add servers back to the list.
Unlike other strategies, unreachable destinations are not probed for availability every unreachable_destination_refresh_interval seconds.
After restarting MySQL Router, all knowledge of what servers are discarded is lost and all servers are available again.
Metadata cache does not support the next-available routing policy, as next-available only functions with static routing.
The role defaults and available combinations:
PRIMARY: round-robin is default behavior (if routing_strategy is not set), whereas bootstrapping adds routing_strategy=first-available to the generated MySQL Router configuration file. The available strategy values are first-available and round-robin.
Note
The bootstrap value changed from round-robin to first-available in v8.0.16.
SECONDARY: round-robin is default behavior (if routing_strategy is not set), whereas bootstrapping adds routing_strategy=round-robin-with-fallback to the generated MySQL Router configuration file. The available strategy values are first-available, round-robin and round-robin-with-fallback.
Note
The bootstrap value changed from round-robin to round-robin-with-fallback in v8.0.16.
PRIMARY_AND_SECONDARY: round-robin is default behavior (if routing_strategy is not set). The available strategy values are first-available, round-robin.
unreachable_destination_refresh_interval
Introduced 8.0.29 Type Integer Default Value 1 Minimum Value 1 Maximum Value 65535 The quarantine mechanism tracks unreachable destinations and later probes them for availability in case they come back online. This option determines how often (in seconds) each unreachable destination candidate is probed for availability before it can be added back to the rotation.
[DEFAULT] unreachable_destination_refresh_interval = 1All routing strategies except for next-available utilize this behavior.
max_connections
Type Integer Default Value 512 Minimum Value 1 Maximum Value 65536 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.
[routing:mycluster_default_rw] max_connections = 512Alternatively, use the newer max_total_connections configuration option that sets one value for all Router sections combined.
MySQL Router 8.0.22 introduced functionality that increases the concurrent connection limit from around 5,000 to 50,000 connections. The maximum depends both on the system's poll (or linux_epoll) limitations and the number of available CPU cores/threads. See also the [IO] backend and threads configuration options.
Optionally setting max_connections in the [DEFAULT] section sets the default value for each routing destination.
max_total_connections
Introduced 8.0.27 Type Integer Default Value 512 Minimum Value 1 Maximum Value 9223372036854775807 The maximum number of client connections handled by Router, to help prevent running out of the file descriptors.
This is similar to MySQL Server's max_connections server system variable.
Note
The legacy max_connections option sets a value per routing instance, such as one value for read-only, and another for write-only. The max_total_connections option sets one value for all routing instances combined.
The default value is 512, and it's set under the [DEFAULT] section. This option was added in MySQL Router 8.0.27.
thread_stack_size
Introduced 8.0.12 Type Integer Default Value 64 Minimum Value 1 Maximum Value 65535 The stack size allocated for each thread. It is measured in kilobytes, and defaults to 64.
[DEFAULT] thread_stack_size=128net_buffer_length
Introduced 8.0.22 Type Integer Sets the net_buffer_length MySQL server option.
max_connect_errors
Type Integer Default Value 100 Minimum Value 1 Maximum Value 4294967295 The default value is 100, and the valid range is between 1 and 2^32 (4294967295, 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 MySQL Router attempts to discover if connection-related errors are present.
A successful connection resets the error counter (as of 8.0.14).
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 = 100client_connect_timeout
Type Integer Default Value 9 Minimum Value 2 Maximum Value 31536000 This is similar to MySQL Server's connect_timeout server system variable.
The default value is 9, which is one less than the MySQL 5.7 default. The valid range is between 2 and 31536000.
client_connect_timeout = 9auth_cache_refresh_interval
Introduced 8.0.20 Type Numeric Default Value 2 Minimum Value 0.001 Maximum Value 3600 Time (in seconds) between the auth-cache refresh attempts. Defaults to 2. The value must be smaller than auth_cache_ttl and larger than ttl else Router won't start.
This option is applied if the http_auth_backend section's backend option is set to metadata_cache; which is a Router REST API feature.
auth_cache_ttl
Introduced 8.0.20 Type Numeric Default Value -1 Minimum Value 0.001 Maximum Value 3600 Time (in seconds) until the cache becomes invalid if not refreshed. Defaults to -1 (infinite). The value must be larger than auth_cache_refresh_interval and ttl else Router won't start.
This option is applied if the http_auth_backend section's backend option is set to metadata_cache; which is a Router REST API feature.
router_id
The MySQL Router ID.
server_ssl_curves
Introduced 8.0.23 Type String Defaults to a secure list of SSL curves. Format this string as a colon separated list of curve names.
server_ssl_cipher
Introduced 8.0.23 Type String Defaults to a secure list of SSL ciphers. Format this string as a colon separated list of cipher names.
server_ssl_verify
Introduced 8.0.23 Type String Default Value DISABLED Valid Values DISABLED
VERIFY_CA
VERIFY_IDENTITY
SSL Verify is set to DISABLED by default.
server_ssl_mode
Introduced 8.0.23 Type String Default Value AS_CLIENT Valid Values AS_CLIENT
DISABLED
PREFERRED
REQUIRED
SSL Mode is set to AS_CLIENT by default. See also Section 4.4, “TLS Configuration” .
client_ssl_dh_params
Introduced 8.0.23 Type String If specified and not empty, the DH parameters from this file are used instead of internal default DH parameters. Format the DH param file in PEM format.
client_ssl_curves
Introduced 8.0.23 Type String Which curves are allowed between the client and MySQL Router, defaults to a secure list of SSL curves. Format this string as a colon separated list of curve names.
client_ssl_cipher
Introduced 8.0.23 Type String Which ciphers are allowed between client and MySQL Router, defaults to a secure list of SSL ciphers. Format this string as a colon separated list of cipher names.
client_ssl_mode
Introduced 8.0.23 Type String Default Value PREFERRED Valid Values PREFERRED
DISABLED
PASSTHROUGH
REQUIRED
Controls if connections from the client to MySQL Router must be encrypted. See also Section 4.4, “TLS Configuration” .
ssl_mode
Type String Default Value PREFERRED Valid Values PREFERRED
DISABLED
REQUIRED
VERIFY_CA
VERIFY_IDENTITY
SSL mode for connecting to the MySQL metadata server. It defaults to PREFERRED if not set.
When set to PREFERRED (the default), bootstrapping will warn when SSL is not used and connection to the metadata server is unencrypted.
Available values are DISABLED, PREFERRED, REQUIRED, VERIFY_CA, and VERIFY_IDENTITY. As with the mysql client, this value is case-insensitive.
There is also a runtime option for bootstrapping; see --ssl-mode.
bootstrap_server_addresses
Deprecated 8.0.14 Type String Points to a list of MySQL servers with metadata that can be connected to. After the metadata has been accessed, the metadata cache switches to the servers that are present in the primary ReplicaSet to fetch the metadata. They are also known as bootstrap servers.
This option is deprecated in MySQL Router 8.0.14 and no longer generated by the bootstrap process. Instead, the dynamic_state option was added as a replacement.
user (MySQL)
A generated MySQL user with privileges to access the MySQL server's metadata schema. This user's password is auto-generated and stored in an encrypted keyring. By default, the encryption key for this keyring is stored in a read protected master key store file, which is defined in the configuration file. Most commonly, this user and associated password are automatically generated during bootstrap. Related command line options are --force-password-validation and --password-retries. By default, the generated password passes the STRONG validate_password strength.
The password is entirely managed by Router and never exposed, and is stored in a local keyring system using the operating system's account that MySQL Router is running as. It can then be used by Router to connect to InnoDB Cluster and retrieve current topology information. Sessions between Router and metadata server are encrypted with SSL by default.
Where the generated keyring files are stored depends on how bootstrap is configured. For self-contained installations (when --directory is used), it is stored under run/ in the self-contained directory. For system-wide installations, it is stored in the system-wide runtime state directory, and that path is platform specific. For additional information, see master_key_path and keyring_path
This user is assigned (and requires) the following privileges:
Privileges needed by the Router account: On Metadata Server: SELECT ON mysql_innodb_cluster_metadata.* On Target Replica Sets: SELECT ON performance_schema.replication_group_members SELECT ON performance_schema.replication_group_member_statsThe generated username follows this pattern: mysql_router_[0-9]{1,6}_[0-9a-z]{12}, where [0-9]{1,6} is the numeric router id and [0-9a-z]{12} is 12 random lowercase alphanumeric characters. The router id is reused if already present in mysqlrouter.conf and its length can not exceed 6 digits.
Note
This user is different from the user definition defined in the [DEFAULT] section, which is a system user.
metadata_cluster
Name of the InnoDB Cluster.
Note
SQL query to list the MySQL InnoDB cluster names: SELECT * FROM mysql_innodb_cluster_metadata.clusters;
use_gr_notifications
Introduced 8.0.17 Type Integer Default Value 0 Valid Values 0
1
Enables Group Replication notifications. When enabled, Router is asynchronously notified about most cluster changes. It can be enabled manually in mysqlrouter.conf or enabled there using the --conf-use-gr-notifications command-line option during bootstrap.
When Router receives any of the following notifications from Group Replication, it refreshes the cluster metadata:
group_replication/membership/quorum_loss
group_replication/membership/view
group_replication/status/role_change
group_replication/status/state_change
Note
The Group Replication notifications feature requires an X Protocol connection from Router to each instance, which must be running X Plugin. If an X Protocol connection is not available, the metadata refresh is carried out at ttl intervals as though the notifications feature was not enabled.
Although the Group Replication notifications rely on an X Protocol connection, received notifications trigger a metadata refresh which uses a classic MySQL protocol connection to the instance.
When enabled, the Group Replication notification feature allows a higher ttl value because the metadata refreshes carried out at ttl intervals become an additional safeguard, rather than the primary means of keeping the information about the cluster state up to date. When disabled, a low ttl value (such as 0.5s, the default) is recommended to avoid the overhead of reconnecting to the instances and querying them for metadata changes often.
ttl
Type (≥ 8.0.12) Numeric Type (8.0.11) Integer Default Value (≥ 8.0.12) 0.5 Default Value (8.0.11) 5 Minimum Value 0 Maximum Value (≥ 8.0.12) 3600 Maximum Value (8.0.11) 4294967295 Time to live (in seconds) of information in the metadata cache.
Accepts either an integer or a floating point value. The granularity is limited to milliseconds, where 0.001 equates to one millisecond. Precision is truncated to the supported range; for example ttl=0.0119 is treated as 11 milliseconds. The value 0 means that the metadata cache module queries the metadata continuously in a tight loop.
The value must be smaller than auth_cache_refresh_interval and auth_cache_ttl else Router won't start.
The only supported decimal separator is '.' (a period) regardless of locale, and scientific notation, such as ttl=1.6E-2, is supported.
Floating point support was added in MySQL Router 8.0.12.
destination
Introduced 8.0.21 Type String Default Value (Windows) CON Default Value (Other) /dev/stderr Valid Values (Windows) CON
NUL
Valid Values (Other) /dev/null
/dev/stderr
/dev/stdout
Direct console log output to this device destination; set under the [consolelog] section. Defaults to /dev/stderr and an empty value uses the default.
Available values are: /dev/stdout, /dev/stderr, and /dev/null; or CON and NUL on Windows.
[DEFAULT] logging_folder= [consolelog] destination=/dev/nullfilename
Introduced 8.0.21 Type String Redirect log output to a specific file named filename that resides in the logging_folder directory. It must be defined as a file name and not a file path, and works with both the [logger] and [filelog] sections.
Using filename with [logger] to define the default value for the [filelog] section, and it also changes Router's log file from mysqlrouter.log to this new value.
[DEFAULT] logging_folder=/path/to/logs/ [logger] filename = router_error.logRouter does not report an error if filename is set under [logger] but no file-based logger is used.
Using filename with [filelog]:
[DEFAULT] logging_folder=/path/to/logs/ [filelog:a] filename = a_router_error.log [filelog:b] filename = b_router_error.logIf filename is empty or not set under [filelog] then the filename definition under [logger] is used; and the default log file is used (mysqlrouter.log) if filename is not set under [logger] either.
Related, directing console output to /dev/null:
[DEFAULT] logging_folder= [consolelog] destination=/dev/nulllevel
Type String Default Value INFO Valid Values (≥ 8.0.20) DEBUG
NOTE
INFO
WARNING
ERROR
SYSTEM
FATAL
Valid Values (≤ 8.0.19) DEBUG
INFO
WARNING
ERROR
FATAL
Use the logger plugin to log notices, errors, and debugging information. The available log levels are DEBUG, NOTE, INFO (default), WARNING, ERROR, SYSTEM, and FATAL. These values are case-insensitive.
The INFO level displays all informational messages, warnings, and error messages. The DEBUG level displays additional diagnostic information from the Router code, including successful routes. SYSTEM includes messages such as startup messages.
[logger] level = DEBUGOutput 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 [DEFAULT] section.
Note
The "SYSTEM" and "NOTE" error levels were added in MySQL Router 8.0.20.
Bootstrapping accepts a configuration file using --config and utilizes the logger level definition.
timestamp_precision
Introduced 8.0.18 Type String The logger timestamp precision; the available definitions with example values are:
second, sec, or s: 2019-05-10 12:10:25
millisecond, msec, or ms: 2019-05-10 12:10:25.428
microsecond, usec, or us: 2019-05-10 12:10:25.428754
nanosecond, nsec, ns: 2019-05-10 12:10:25.428754000
port
Introduced 8.0.16 Type Integer Default Value 8081 The TCP port listening for HTTP requests; it defaults to 8881.
bind_address
Introduced 8.0.16 Type String Default Value 0.0.0.0 IP address bound to the HTTP port; it defaults to 0.0.0.0.
static_folder
Introduced 8.0.16 Type String Base directory for static file requests; it's empty by default. An empty value means no static files are served.
require_realm
Introduced 8.0.16 Type String Name of the [http_auth_realm] instance.
ssl
Introduced 8.0.16 Type Integer Default Value 1 Valid Values 1
0
The value 1 enables SSL, and 0 disables it. TLS clients supporting TLSv1.2 or later are required. This is defined under the [http_server] section.
ssl_cert
Introduced 8.0.16 Type String File name of the certificate and its chain certifications in PEM format; required if ssl=1. This is defined under the [http_server] section.
ssl_key
Introduced 8.0.16 Type String File name of the key in PEM format; required if ssl=1. This is defined under the [http_server] section.
ssl_cipher
Introduced 8.0.16 Type String The cipher-spec (see openssl's 'ciphers' list). Defaults to a comma-separated list of all approved ciphers. Unknown ciphers are silently ignored. Fails if list of ciphers is empty and ssl=1. This is defined under the [http_server] section.
ssl_dh_param
Introduced 8.0.16 Type String Read the DH parameter from this file in PEM format. Uses the dh-param from RFC 5114 by default if ssl=1. This is defined under the [http_server] section.
backend
Introduced 8.0.22 Type String Default Value (Windows) poll Default Value (Other) linux_epoll Valid Values (Windows) poll Valid Values (Other) linux_epoll
poll
The IO backend that handles async operations. The generic poll backend is available on all platforms, while each platform may provide alternative backends.
Options are poll (all platforms) and linux_epoll (Linux). Defaults to linux_epoll on Linux.
Note
Support was added in MySQL Router 8.0.22.
[io] backend=linux_epoll threads=32Router has three 'backend' options, each in a different [section] with different meanings. There's the '[io] backend' (for async operations), '[http_auth_realm] backend' (define a custom name for backend that's associated to a particular realm), and '[http_auth_backend] backend' (type of auth backend). To help avoid confusion, here's an example demonstrating all three:
threads
Introduced 8.0.22 Type Numeric Default Value 0 Minimum Value 0 Maximum Value 1024 The number of IO threads that handles connections.
Defaults to 0 (uses all available CPU cores/threads) but also accepts a number between 1 and 1024. At runtime the system may restrict the upper limit beyond this value.
Note
Support was added in MySQL Router 8.0.22.
[io] backend=linux_epoll threads=32idle_timeout
Introduced 8.0.29 Type Numeric Default Value 5 Minimum Value 1 Maximum Value 4294967296 Seconds to keep the idling connection in the connection pool before closing it. This is set in the [connection_pool] section, and affects all routes in the connection pool. Defaults to 5, accepts a value between 1 and 4294967296.
This option was added in MySQL Router 8.0.29.
max_idle_server_connections
Introduced 8.0.29 Type Numeric Default Value 0 Minimum Value 0 Maximum Value 4294967296 Connections to keep open in the connection pool after the client disconnects; and is set in the [connection_pool] section. Defaults to 0, accepts a value between 0 and 4294967296.
This option was added in MySQL Router 8.0.29.
backend
Introduced 8.0.16 Type String Name of the [http_auth_backend] section.
Router has three 'backend' options, each in a different [section] with different meanings. There's the '[io] backend' (for async operations), '[http_auth_realm] backend' (define a custom name for backend that's associated to a particular realm), and '[http_auth_backend] backend' (type of auth backend).
method
Introduced 8.0.16 Type String Default Value basic The HTTP authentication method; defaults to basic.
name
Introduced 8.0.16 Type String Name of the realm presented to the authentication user.
require
Introduced 8.0.16 Type String Default Value valid-user Requires that the user validates with the authentication backend; defaults to valid-user, which enables this check.
backend
Introduced 8.0.16 Type String Default Value file Name of the backend implementation; accepted values are 'file' (default) or 'metadata_cache'.
Note
metadata_cache support was added in MySQL Router 8.0.20.
[http_auth_backend:name] backend=metadata_cache [metadata_cache] auth_cache_refresh_interval=2 auth_cache_ttl=-1Router has three 'backend' options, each in a different [section] with different meanings. There's the '[io] backend' (for async operations), '[http_auth_realm] backend' (define a custom name for backend that's associated to a particular realm), and '[http_auth_backend] backend' (type of auth backend).
filename
Introduced 8.0.16 Type String Name of the backend storage file, is relative to the data_folder directory.
cluster_type
Introduced 8.0.19 Type String Valid Values gr
rs
The type of AdminAPI object that the Router was bootstrapped against, which is either an InnoDB ReplicaSet (rs) or InnoDB Cluster (gr). Use 'gr' for cluster sets.
Bootstrapping evaluates the target instance and sets this option accordingly in the generated configuration file.
This option was added in MySQL Router 8.0.19; the same version InnoDB ReplicaSet support was added.