MySQL Router 8.4  /  Configuration  /  Configuration Locations

4.2 Configuration Locations

MySQL Router scans for the default configuration files at startup, and optionally loads user-defined configuration files at runtime from the command line.

Default Configuration File Locations

By default, MySQL Router scans specific locations for its configuration files that depend on the platform and how MySQL Router was set up.

You can alter the default locations at compile time by using the -DROUTER_CONFIGDIR=<path> option. You could also edit cmake/settings.cmake to change the default locations before compiling MySQL Router, thus adding new locations or exceptions for specific platforms.

Execute mysqlrouter --help to see the default configuration file locations (and their availability) on your system. For example:

$> mysqlrouter --help

...

Start MySQL Router.

Configuration read from the following files in the given order (enclosed
in parentheses means not available for reading):
  (/usr/local/mysql-router/mysqlrouter.conf)
  /Users/philip/.mysqlrouter.conf
Plugins Path:
  /usr/local/lib/mysqlrouter
Default Log Directory:
  /usr/local/mysql-router
Default Persistent Data Directory:
  /usr/local/mysql-router/data
Default Runtime State Directory:
  /usr/local/mysql-router/run

Usage: mysqlrouter [-v|--version] [-h|--help]

...
Important

The default configuration file is not loaded if a user-defined configuration file is passed in with the --config option.

On Linux, MySQL Router scans the following locations by default, although these locations are system dependent:

  1. /etc/mysqlrouter/mysqlrouter.conf

    Note

    Unlike MySQL server, the backward compatible path "/etc/mysqlrouter.conf" is not supported.

  2. $HOME/.mysqlrouter.conf

Note

For backward compatibility, MySQL Router also looks for the .ini variant in each directory. In doing so, Router looks in the initial directory for the .conf version, then checks for a .ini version, and then repeats the process in the next directory which is typically the user's home directory on the system.

User-Defined and Extra Configuration Files

Two command line options help control these configuration file locations:

  • --config (or -c): Read the base configuration from this file, and do not use or scan the default file paths.

    Example use: when generating a standalone MySQL Router installation with the --directory bootstrap option, the generated start.sh passes this option to the generated mysqlrouter.conf inside that directory.

  • --extra-config (or -a): Read this additional configuration file after the configuration files are read from either the default locations, or from files specified using the --config option.

For example:

$> mysqlrouter --config /custom/path/to/router.conf --extra-config /another/config.conf

Multiple extra configuration options can be passed in and the files are loaded in the order they are entered, with --config options being loaded before the --extra-config options. For example:

$> mysqlrouter --extra-config a.conf --config b.conf --extra-config c.conf

In the above example, b.conf is loaded first, and then a.conf and c.conf, in that order. Also, the default configuration file, such as /etc/mysqlrouter/mysqlrouter.conf, is not loaded because --config was used.

Each loaded configuration file overrides configuration settings from the previously read configuration files.

Default Configuration File Locations (Linux)

The following lists default file location for the router to read configuration files on popular Linux platforms.

Note

Execute mysqlrouter --help to see the default configuration file locations (and their availability) on your system.

  • Default system-wide installation under /usr/local : /usr/local/etc/mysqlrouter.conf

  • RPM and Debian : /etc/mysqlrouter/mysqlrouter.conf

  • On all systems, a bootstrapped standalone installation using --directory adds mysqlrouter.conf into the directory defined by --directory.

Default Configuration File Locations (Windows)

Default file locations that MySQL Router searches for configuration files on Windows.

Note

Execute mysqlrouter.exe --help to see the default configuration file locations (and their availability) on your system.

  • Default system-wide installation under C:\ProgramData\MySQL\MySQL Router : C:\ProgramData\MySQL\MySQL Router\mysqlrouter.conf

  • In addition: C:\Users\username\AppData\Roaming\mysqlrouter.conf where username is replaced with your system's user.

  • In addition to mysqlrouter.conf, for backwards compatibility the system also looks for mysqlrouter.ini

  • With --directory: a bootstrapped standalone installation using --directory adds mysqlrouter.conf into the directory defined by --directory.

MySQL Router Configuration in Cluster Metadata

As of MySQL Router 8.4, the full configuration of routers bootstrapped against a InnoDB Cluster is stored in the InnoDB Cluster Metadata Schema and can be read by the MySQL Shell operation, object.routerOptions, for Cluster, ClusterSet, and ReplicaSets.

The configuration is stored per router as JSON in the mysql_innodb_cluster_metadata.routers table with one row per router. Each router's row is updated by the router on startup or restart.

For example:

        mysql>  select JSON_PRETTY(attributes->>'$.Configuration') as Configuration from mysql_innodb_cluster_metadata.routers \G
        
        Configuration: {
"io": {
    "backend": "poll",
    "threads": 0
},
"common": {
    "name": "system",
    "user": "",
    "read_timeout": 30,
    "client_ssl_key": "/Users/areliga/dev/server/mysql-trunk/build/pt/data/router-key.pem",
    "client_ssl_cert": "/Users/areliga/dev/server/mysql-trunk/build/pt/data/router-cert.pem",
    "client_ssl_mode": "PREFERRED",
    "connect_timeout": 5,
    "server_ssl_mode": "PREFERRED",
    "server_ssl_verify": "DISABLED",
    "max_total_connections": 512,
    "unknown_config_option": "error",
    "router_require_enforce": true,
    "max_idle_server_connections": 64
},
"loggers": {
    "filelog": {
    "level": "info",
    "filename": "mysqlrouter.log",
    "destination": "",
    "timestamp_precision": "second"
    }
},
"endpoints": {
    "bootstrap_ro": {
    
    ......
    
    }
   }

See Viewing Router Configurations with MySQL Shell for more information.

For backward compatibility, MySQL Router continues to store some configuration parameters in the attributes JSON in mysql_innodb_cluster_metadata.routers.

For example:

select JSON_PRETTY(attributes) from mysql_innodb_cluster_metadata.routers;
| {
  "ROEndpoint": "6447",
  "RWEndpoint": "6446",
  "ROXEndpoint": "6449",
  "RWXEndpoint": "6448",
  "RWSplitEndpoint": "6450",
  "MetadataUser": "mysql_router1_plje99d",
  "Configuration": { /*...*/ },
  "bootstrapTargetType": "cluster"
} |