MySQL Router 8.4  /  ...  /  Configuration File Options

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.

General Options

Table 4.7 [DEFAULT]

Option Name Description Type
config_folder Path to configuration files String
connect_timeout Number of seconds before connection attempts to a metadata server are considered timed out Integer
event_source_name Microsoft Windows platforms only. Defines the service name used by MySQL Router when it is run as a service on Microsoft Windows. String
keyring_path Path to keyring file String
logging_folder Path to router logs String
master_key_path Path to master keyring file String
master_key_reader Script that returns the master key to STDOUT String
master_key_writer Script that reads the master key from STDIN String
max_total_connections Total maximum number of allowed client connections from the router Integer
pid_file Location to store the PID file String
plugin_folder Path to router plugins String
runtime_folder Path to runtime files String
sinks Logging method(s) to receive configured log data String
thread_stack_size Size in KB of memory allocated to each thread stack Integer
unknown_config_option Error type sent if an unknown configuration option is encountered String
user System user MySQL Router is run as String

Routing Options

Table 4.8 [routing]

Option Name Description Type
access_mode Splits reads and writes according to the category of transaction. String
bind_address Address router is bound to, also uses bind_port if a port is not defined String
bind_port Default port used by bind_address Integer
client_connect_timeout Maximum number of seconds to receive packets from MySQL server Integer
client_ssl_ca The path to the Certificate Authority (CA) certificate file in PEM format String
client_ssl_capath The path to the directory that contains the trusted SSL Certificate Authority (CA) certificate files in PEM format. String
client_ssl_cert The path to the SSL certificate (PEM) used to encrypt client-to-router communications String
client_ssl_cipher Which ciphers are allowed between client and MySQL Router, defaults to a secure list of SSL ciphers String
client_ssl_crl The path to the file containing the certificate revocation lists in PEM format String
client_ssl_crlpath The path to the directory that contains the certificate revocation list files in PEM format String
client_ssl_curves Which curves are allowed between the client and MySQL Router, defaults to a secure list of SSL curves String
client_ssl_dh_params Filename of the DH parameter file. Not set by default String
client_ssl_key The path to the SSL private key certificate file (PEM) used to encrypt client-to-router communications String
client_ssl_mode Controls if connections from the client to MySQL Router must be encrypted, defaults to PREFERRED if not set String
client_ssl_session_cache_mode Enables or disables the TLS session cache for client connections Boolean
client_ssl_session_cache_size Number of entries in the TLS session cache for client connections Integer
client_ssl_session_cache_timeout Time in seconds until TLS sessions are removed from the client TLS session cache Integer
connect_retry_timeout Number of seconds MySQL Router waits before retrying a connection to a backend Integer
connect_timeout Number of seconds before connection attempts to a MySQL server are considered timed out Integer
connection_sharing Whether to enable connection sharing. Integer
connection_sharing_delay Seconds to wait before moving an idle connection to the connection pool. Integer
destinations Routing destinations as either a comma-separated list of MySQL servers, or a metadata-cache definition String
dynamic_state Path to generated JSON file used to track and store active MySQL InnoDB Cluster Metadata server addresses String
max_connect_errors Maximum number of failed MySQL server connections before giving up Integer
max_connections Maximum number of connections assigned to a routed destination MySQL server Integer
net_buffer_length Set net_buffer_length Integer
protocol Protocol for connecting to MySQL Server String
read_timeout Number of seconds before read operations to a metadata server are considered timed out Integer
router_require_enforce If enabled, retrieves the attributes for the current user and enforces them Boolean
routing_strategy Routing strategy (optional), how router chooses destination MySQL servers String
server_ssl_ca The path to the Certificate Authority (CA) certificate file in PEM format String
server_ssl_capath The path to the directory that contains the trusted SSL Certificate Authority (CA) certificate files in PEM format. String
server_ssl_cert The path to the SSL certificate (PEM) used to encrypt router-to-server communications String
server_ssl_cipher SSL Cipher for Server String
server_ssl_crl The path to the file containing the certificate revocation lists in PEM format String
server_ssl_crlpath The path to the directory that contains the certificate revocation list files in PEM format String
server_ssl_curves SSL Curves for Server String
server_ssl_key The path to the SSL private key certificate file (PEM) used to encrypt router-to-server communications String
server_ssl_mode Controls if connections from router to server must be encrypted String
server_ssl_session_cache_mode Enables or disables the TLS session cache for server connections Boolean
server_ssl_session_cache_size Number of entries in the TLS session cache for server connections Integer
server_ssl_session_cache_timeout Time in seconds until TLS sessions are removed from the server TLS session cache Integer
server_ssl_verify Verification of the SSL certificates presented to the router by the server String
socket Path to Unix domain socket file String
wait_for_my_writes Read-only queries wait for the last written transaction. Integer
wait_for_my_writes_timeout Maximum time in seconds to wait for a read_only destination to apply the written transaction, before falling back to a read_write destination. Integer

Destination Status Options

Table 4.9 [destination_status]

Option Name Description Type
error_quarantine_interval Defines the interval, in seconds, between checks on quarantined destination connectivity. If a connection is possible, the destination is moved out of quarantine and made available for connections. Integer
error_quarantine_threshold Defines the threshold of consecutive, failed attempts to connect to a routing destination before MySQL Router adds the destination to quarantine and stops using it as a destination until it is cleared by the quarantine mechanism. For example, if set to 5, the destination is quarantined after 5 consecutive, failed attempts to connect to it. Integer

Table 4.10 [connection_pool]

Option Name Description Type
idle_timeout Seconds to keep the idling connection in the collection pool before closing it Integer
max_idle_server_connections Connections to keep open after the client disconnects Integer

Metadata Cache Options

Table 4.11 [metadata_cache]

Option Name Description Type
auth_cache_refresh_interval Time between auth-cache refresh attempts Numeric
auth_cache_ttl Time until the cache becomes invalid if not refreshed Numeric
cluster_type Object Router was bootstrapped against String
metadata_cluster InnoDB Cluster name String
router_id Router ID Integer
ssl_ca SSL CA file to verify server's certificate against String
ssl_capath Directory containing SSL CA files to verify server's certificate against String
ssl_crl SSL CRL file to verify server's certificate against String
ssl_crlpath Directory containing SSL CRL files to verify server's certificate against String
ssl_mode SSL connection mode for connecting to the metadata server, defaults to PREFERRED if not set String
tls_version Comma-separated list of TLS versions to request, if SSL is enabled String
ttl Time To Live, in seconds Integer
use_gr_notifications Group Replication notifications behavior Integer
user MySQL user that accesses the MySQL Server's metadata schema String

Logging Options

Table 4.12 [logger]

Option Name Description Type
destination Name of device to log to; optionally used with [consolelog] String
filename Log file name; optionally used with [logger] and [filelog] String
level Logging level String
timestamp_precision Logger timestamp precision String

HTTP Server Options

Table 4.13 [http_server]

Option Name Description Type
bind_address IP address bound to the HTTP port String
port HTTP server TCP port Integer
require_realm [http_auth_realm] name String
ssl_cert SSL certification file name String
ssl_cipher Approved SSL ciphers String
ssl_dh_param DH parameter file name String
ssl Enables TLSv1.2 or later support Integer
ssl_key SSL key filename String
static_folder Directory for HTTP server static file requests String

Table 4.14 [http_auth_realm]

Option Name Description Type
backend Name of the [http_auth_backend] section String
method The HTTP authentication method String
name Realm name for authenticated user String
require Require authentication validation String

Table 4.15 [http_auth_backend]

Option Name Description Type
backend Backend type String
filename Backend storage file name String

Table 4.16 [io]

Option Name Description Type
backend The IO backend String
threads The IO thread count Integer

Table 4.17 [keepalive]

Option Name Description Type
interval The keepalive ping frequency interval, in seconds Integer
runs Limits the number of keepalive executions (runs), or 0 for no limit Integer

MySQL Router Configuration File Option Descriptions

  • access_mode

    Type String
    Default Value
    Valid Values auto

    Defines how MySQL Router treats read-only and read-write queries. If enabled, read-only queries are directed to read-only servers, and read-write queries are directed to read-write servers. See Section 3.5, “Read/Write Splitting”.

  • wait_for_my_writes

    Type Integer
    Default Value 1
    Minimum Value 0
    Maximum Value 1

    Read-only queries wait for the last written transaction.

    See Section 3.5, “Read/Write Splitting”.

  • wait_for_my_writes_timeout

    Type Integer
    Default Value 1
    Minimum Value 0
    Maximum Value 4294967295

    Maximum time in seconds to wait for a read_only destination to apply the written transaction, before falling back to a read_write destination.

    See Section 3.5, “Read/Write Splitting”.

  • router_require_enforce

    Type Boolean
    Default Value 0

    If enabled, MySQL Router retrieves the values defined in the user's router_requires attribute in the USER_ATTRIBUTES table.

    The attribute must take the following format: 

            {router_require: {value}}

    The following are the possible values:

    • {}: no requirements.

    • {ssl: true}: MySQL Router requires SSL from the client.

    • {x509: true}: MySQL Router requires SSL and an x509 certificate from the client.

    • {issuer: ""}: MySQL Router requires SSL, an x509 certificate, and the certificate issuer from the client.

    • {ssl: true}: MySQL Router requires SSL, an x509 certificate, and the certificate subject from the client.

  • event_source_name

    Type String
    Default Value

    Microsoft Windows platforms only. Defines the service name used by MySQL Router when it is run as a service on Microsoft Windows. This enables you to differentiate between services when running multiple instances of MySQL Router and between their messages in the Event Log.

    For example: 

    [DEFAULT]
event_source_name = MySQLRouterService

  • 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/mysqlrouter

    When 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
    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
    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

    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,filelog

  • keyring_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.key

  • master_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.key

  • unknown_config_option

    Type String
    Default Value warning
    Valid Values

    warning

    error

    Determines MySQL Router behavior for handling unknown configuration options, such as typos.

    A warning is default behavior, and bootstrapping defines it as error in the generated configuration file. Warning logs a warning message but does not halt, whereas an error means MySQL Router fails to initialize and exits. 

    [DEFAULT]
unknown_config_option=warning

  • user (system)

    Type String

    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 snoopy

    In 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=snoopy
    Note

    This is different from the user definition defined in the [metadata_cache] section, which is a MySQL user.

  • ssl_ca

    Type String

    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

    Type String

    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

    Type String

    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

    Type String

    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

    Type String

    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:7001
    Note

    The bind_address cannot be listed in the destinations list.

  • bind_port

    Type Integer

    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:7001

  • socket

    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:3307

    When 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
destinations = localhost:57121, localhost:57122, localhost:57123
    Note

    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
destinations = 10.20.200.1:33060, 10.20.200.2:33060
protocol = x

    The 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

    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 5
    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.

    Example usage: 

    [routing]
connect_timeout = 5

    Can be set at bootstrap using --conf-set-option=routing.connect_timeout.

  • connect_timeout

    Type Integer
    Default Value 5

    Timeout value used by the MySQL Router when connecting to the MySQL metadata server.

    Example usage: 

    [DEFAULT]
connect_timeout = 5

    Can 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 = 30

  • destinations

    Type String

    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.com
    Note

    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=PRIMARY

    The 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.

    • 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.

    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

    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.

    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.json

    Example 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"
}

  • routing_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.

    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 error_quarantine_interval seconds. All routing strategies except for next-available utilize this behavior.

    • 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.

      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 error_quarantine_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.

    • 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.

    • PRIMARY_AND_SECONDARY: round-robin is default behavior (if routing_strategy is not set). The available strategy values are first-available, round-robin.

  • 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 = 512

    Alternatively, use the newer max_total_connections configuration option that sets one value for all Router sections combined.

    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

    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. 

    [DEFAULT]
max_total_connections = 512
    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.

  • thread_stack_size

    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=128

  • net_buffer_length

    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.

    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

  • client_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 = 9

  • auth_cache_refresh_interval

    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

    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

    Type Integer
    Maximum Value 4294967295

    The MySQL Router ID.

  • server_ssl_cert

    Type String
    Default Value

    The path name of the SSL public key certificate file in PEM format. This is used to facilitate server-side authentication during the bootstrap process.

  • server_ssl_key

    Type String
    Default Value

    The path name of the SSL private key file in PEM format used to encrypt router-to-server connections. See also Section 4.4, “TLS Configuration” .

  • server_ssl_curves

    Type String

    Defaults to a secure list of SSL curves. Format this string as a colon separated list of curve names.

  • server_ssl_cipher

    Type String

    Defaults to a secure list of SSL ciphers. Format this string as a colon separated list of cipher names.

  • server_ssl_verify

    Type String
    Default Value DISABLED
    Valid Values

    DISABLED

    VERIFY_CA

    VERIFY_IDENTITY

    Verification of the SSL certificates presented to the router by the server.

    • DISABLED: the connection fails if the server does not provide a certificate in the handshake.

    • VERIFY_CA: the connection fails if the server's certificate does not match a CA trusted by MySQL Router.

    • VERIFY_IDENTITY: the connection fails if the server's certificate does not match a CA trusted by MySQL Router, or the server certificate's subject does not match the hostname or IP address MySQL Router connected to.

  • server_ssl_mode

    Type String
    Default Value AS_CLIENT
    Valid Values

    AS_CLIENT

    DISABLED

    PREFERRED

    REQUIRED

    SSL connection mode to use when connecting between MySQL Router and server. See also Section 4.4, “TLS Configuration” .

  • server_ssl_ca

    Command-Line Format --server-ssl-ca file_path
    Type String
    Default Value

    The path name of the Certificate Authority (CA) certificate file in PEM format. The file contains a list of trusted SSL Certificate Authorities. See also Section 4.4, “TLS Configuration” .

  • server_ssl_capath

    Command-Line Format --server-ssl-capath dir_path
    Type String
    Default Value

    The path name of the directory that contains trusted SSL Certificate Authority (CA) certificate files in PEM format. See also Section 4.4, “TLS Configuration” .

  • client_ssl_cert

    Command-Line Format --client-ssl-cert file_path
    Type String
    Default Value

    The path name of the SSL public key certificate file in PEM format. This is used to facilitate client-side authentication during the bootstrap process.

    Like -client_ssl_key, this option is only used during bootstrap that uses a root account. It is useful when the root account was created with REQUIRE X509, and therefore logging in as root requires the client to authenticate itself.

  • server_ssl_crlpath

    Command-Line Format --server-ssl-crlpath dir_path
    Type String
    Default Value

    The path of the directory that contains certificate revocation-list files in PEM format. See also Section 4.4, “TLS Configuration” .

  • server_ssl_crl

    Command-Line Format --server-ssl-crl file_path
    Type String
    Default Value

    The path name of the file containing certificate revocation lists in PEM format. See also Section 4.4, “TLS Configuration” .

  • client_ssl_key

    Command-Line Format --client-ssl-key file_path
    Type String
    Default Value

    The path name of the SSL private key file in PEM format used to encrypt client-to-router connections. See also Section 4.4, “TLS Configuration” .

  • client_ssl_dh_params

    Type String

    Filename of the DH parameter file. 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

    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

    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

    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.

  • user (MySQL)

    Type String

    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_stats

    The generated username follows this pattern: mysql_router_{router_id}_[0-9a-z]{7}, where {router_id} is the numeric router id and [0-9a-z]{7} is 7 random lowercase alphanumeric characters. The router id is reused if already present in mysqlrouter.conf and its value can not exceed 4294967295 (2^32-1).

    Note

    This user is different from the user definition defined in the [DEFAULT] section, which is a system user.

    This structure changed in MySQL Router 8.4.1, previously it was mysql_router_[0-9]{1,6}_[0-9a-z]{12}.

  • metadata_cluster

    Type String

    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

    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 Numeric
    Default Value 0.5
    Minimum Value 0
    Maximum Value 3600

    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.

  • destination

    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/null

  • filename

    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.log

    Router 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.log

    If 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/null

  • level

    Type String
    Default Value INFO
    Valid Values

    DEBUG

    NOTE

    INFO

    WARNING

    ERROR

    SYSTEM

    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 = DEBUG

    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 [DEFAULT] section.

    Bootstrapping accepts a configuration file using --config and utilizes the logger level definition.

  • timestamp_precision

    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

    Type Integer
    Default Value 8081

    The TCP port listening for HTTP requests; it defaults to 8081.

  • bind_address

    Type String
    Default Value 0.0.0.0

    IP address bound to the HTTP port; it defaults to 0.0.0.0.

  • static_folder

    Type String

    Base directory for static file requests; it's empty by default. An empty value means no static files are served.

  • require_realm

    Type String

    Name of the [http_auth_realm] instance.

  • ssl

    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

    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

    Type String

    File name of the key in PEM format; required if ssl=1. This is defined under the [http_server] section.

  • ssl_cipher

    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

    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.

  • interval

    Type Integer
    Default Value 60

    Determines the frequency (in seconds) that MySQL Router sends a keepalive ping message. The total number of pings is determiend by the runs configuration option. 

    [keepalive]
interval = 42
runs = 0
    Note

    The keepalive plugin exists for testing purposes and is safe to remove after MySQL Router is configured. Because at least one active plugin is required to launch, the default configuration file enables the keepalive plugin so MySQL Router does not immediately exit. The keepalive plugin is not active if another plugin is enabled.

  • runs

    Type Integer
    Default Value 0

    Limits the number of intervals MySQL Router sends a keepalive ping message. Setting it to 0 (default) means it executes until MySQL Router is shut down. The frequency is determined by the interval option. 

    [keepalive]
interval = 42
runs = 0
    Note

    The keepalive plugin exists for testing purposes and is safe to remove after MySQL Router is configured. Because at least one active plugin is required to launch, the default configuration file enables the keepalive plugin so MySQL Router does not immediately exit. The keepalive plugin is not active if another plugin is enabled.

  • backend

    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. 

    [io]
backend=linux_epoll
threads=32
    Note

    This is one of several backend options, each in a different [section] with a different purpose:

  • threads

    Type Integer
    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. 

    [io]
backend=linux_epoll
threads=32

  • connection_sharing_delay

    Type Integer
    Default Value 1
    Minimum Value 0
    Maximum Value 2^63-1

    Seconds to wait before an idle server connection is available for reuse by another client connection.

    See Section 3.4, “Connection Sharing and Reuse”.

  • connection_sharing

    Type Integer
    Default Value 0
    Minimum Value 0
    Maximum Value 1

    Whether to enable connection sharing.

    See Section 3.4, “Connection Sharing and Reuse”.

  • idle_timeout

    Type Integer
    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.

  • max_idle_server_connections

    Type Integer
    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. The default is 0, which disables connection pooling.

  • client_ssl_session_cache_mode

    Type Boolean
    Default Value 1

    Enables or disables the cache for client-router TLS sessions.

    Note

    Enabled by default. If this parameter is not set, the cache is enabled. To disable the cache, you must explicitly define it.

  • client_ssl_session_cache_size

    Type Integer
    Default Value 1024
    Minimum Value 1
    Maximum Value 2^31-1

    Defines the maximum number of sessions cached. If adding a new session to the cache causes the number of cached sessions to exceed the defined maximum, the oldest cached session is dropped to allow the newest to be cached.

  • client_ssl_session_cache_timeout

    Type Integer
    Default Value 300
    Minimum Value 1
    Maximum Value 84600

    Defines the maximum amount of time, in seconds, a session remains in the cache. If the timeout is reached, and this season is not reused, the session is removed from the cache and the connection is closed.

  • server_ssl_session_cache_mode

    Type Boolean
    Default Value 1

    Enables or disables the cache for router-server TLS sessions.

    Note

    Enabled by default. If this parameter is not set, the cache is enabled. To disable the cache, you must explicitly define it.

  • server_ssl_session_cache_size

    Type Integer
    Default Value 1024
    Minimum Value 1
    Maximum Value 2^31-1

    Defines the maximum number of sessions cached. If adding a new session to the cache causes the number of cached sessions to exceed the defined maximum, the oldest cached session is dropped to allow the newest to be cached.

  • server_ssl_session_cache_timeout

    Type Integer
    Default Value 300
    Minimum Value 1
    Maximum Value 84600

    Time in seconds until TLS sessions are removed from the server TLS session cache.

  • connect_retry_timeout

    Type Integer
    Default Value 7
    Minimum Value 1
    Maximum Value 3600

    If a classic connection fails with a transient error, such as max-connections reached, MySQL Router waits the defined number of seconds before retrying the connection. The connection is retried according to the defined routing strategy.

    If connect_retry_timeout is not defined, it defaults to 7 seconds. If the value of connect_retry_timeout is defined outside of the valid range of values, MySQL Router will fail to start.

    Note

    If connection sharing is enabled, the retried connection is to the same server as the initial connection attempt.

    If a connection fails with a transient error after authentication has occurred, the connection can only be retried if the client-router connection is TLS encrypted or has a public key.

    Table 4.18 SSL Modes and Retry

    client_ssl_mode

    server_ssl_mode

    Supports Retry

    PASSTHROUGH

    Any

    No

    DISABLED

    Any

    No

    PREFERRED

    AS_CLIENT

    No

    PREFERRED

    Any other mode

    Yes

    REQUIRED

    Any

    Yes


  • backend

    Type String

    Name of the [http_auth_backend] section.

    Note

    This is one of several backend options, each in a different [section] with a different purpose:

  • method

    Type String
    Default Value basic

    The HTTP authentication method; defaults to basic.

  • name

    Type String

    Name of the realm presented to the authentication user.

  • require

    Type String
    Default Value valid-user

    Requires that the user validates with the authentication backend; defaults to valid-user, which enables this check.

  • backend

    Type String
    Default Value file

    Name of the backend implementation; accepted values are file (default) or metadata_cache. 

    [http_auth_backend:name]
backend=metadata_cache

[metadata_cache]
auth_cache_refresh_interval=2
auth_cache_ttl=-1
    Note

    This is one of several backend options, each in a different [section] with a different purpose:

  • filename

    Type String

    Name of the backend storage file, is relative to the data_folder directory.

  • cluster_type

    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.

  • error_quarantine_interval

    Type Integer
    Default Value 1
    Minimum Value 1
    Maximum Value 65535

    Defines the interval, in seconds, between checks on quarantined destination connectivity. If a connection is possible, the destination is moved out of quarantine and made available for connections.

    If an invalid value is defined, MySQL Router fails to start and an error is logged.

    For example: 

            [destination_status]
         error_quarantine_threshold=5
         error_quarantine_interval=20
    Note

    If undefined in the configuration file, the default value, 1, is used.

  • error_quarantine_threshold

    Type Integer
    Default Value 1
    Minimum Value 1
    Maximum Value 3600

    Defines the threshold of consecutive, failed attempts to connect to a routing destination before MySQL Router adds the destination to quarantine and stops using it as a destination until it is cleared by the quarantine mechanism. For example, if set to 5, the destination is quarantined after 5 consecutive, failed attempts to connect to it.

    If an invalid value is defined, MySQL Router fails to start and an error is logged.

    For example: 

            [destination_status]
         error_quarantine_threshold=5
         error_quarantine_interval=20
    Note

    If undefined in the configuration file, the default value, 1, is used.


PREV   HOME   UP   NEXT
Related Documentation
MySQL Router Release Notes
Download this Manual
PDF (US Ltr) - 0.6Mb
PDF (A4) - 0.6Mb