MYSQLROUTER(1)

📦
version 9.7.2_2 · 2 versions
, in arch rolling

MYSQLROUTER(1) 💅

okay bestie, welcome to the MySQL Router manual page — yep, the whole MySQL Router situation, section 1 of the manual, and it's literally a whole vibe. buckle up 🎀

✨ NAME ✨

mysqlrouter — MySQL Router, the icon herself 👑

🌸 SYNOPSIS 🌸

mysqlrouter [options]

🦋 DESCRIPTION 🦋

so first up, there's like a little table of contents moment:

  • mysqlrouter Option Summaries
  • mysqlrouter Option Descriptions

MySQL Router takes command line options that get passed into mysqlrouter to affect how it behaves, or to bootstrap router based on an InnoDB Cluster. lowkey powerful.

When you're starting Router, you can optionally use --config to pass in the main configuration file's location (otherwise the default location is used) — and --extra-config for an additional configuration file. cute, flexible, we love options 💖

Bootstrapping command line options affect the generated files and directories that are used when starting MySQL Router. and yeah, the original does that funny run-together thing — mysqlrouter Option Summariesmysqlrouter Option Descriptions — that's not a typo bestie, that's just how it is 🙈

💜 --version, -V

Command-Line Format: --version , -V

Displays the version number and related information of the application, and exits. For example:

$> mysqlrouter --version
MySQL Router v9.7.0 on Linux (64-bit) (GPL community edition)

slay, short and sweet ✨

💜 --help, -?

Command-Line Format: --help , -?

Display help and informative information, and exit.

okay so the --help option has an added benefit — a little bonus feature, if you will. Along with the explanation of each of the options, --help also displays the paths used to find the configuration file, and also several default paths. iconic behavior honestly 👑

The following excerpt of the --help output shows an example from a Ubuntu 16.04 machine:

$> mysqlrouter --help
...
Start MySQL Router.
Configuration read from the following files in the given order (enclosed
in parentheses means not available for reading):
  (/etc/mysqlrouter/mysqlrouter.conf)
  /home/philip/.mysqlrouter.conf
Plugin Path:
  /usr/lib/x86_64-linux-gnu/mysqlrouter
Default Log Directory:
  /var/log/mysqlrouter
Default Persistent Data Directory:
  /var/lib/mysqlrouter
Default Runtime State Directory:
  /run/mysqlrouter
Usage: mysqlrouter [-V|--version] [-?|--help]
...

The configuration section shows the order for the paths that may be used for reading the configuration file. in this case, only the second file is accessible. the way that little parentheses detail tells you everything 🫶

💜 --bootstrap URI, -B URI

Command-Line Format: --bootstrap URI, -B URI

Type: String

okay this is the main character option, fr fr. The main option to perform a bootstrap of MySQL Router by connecting to the InnoDB Cluster metadata server at the URI provided. MySQL Router configures itself based on the information retrieved from the InnoDB Cluster metadata server. A password is prompted for if needed. If a username is not provided as part of the URI then the default user name "root" is used. See Connecting Using URI-Like Connection Strings[1] for information on using a path to specify a server instance.

Note 💀 While --bootstrap accepts a URI for TCP/IP connections, using the --bootstrap-socket option with a local Unix domain socket name replaces the "host:port" part of the URI passed to the --bootstrap option with the socket on the same machine.

By default, the bootstrap process performs a system-wide configuration of MySQL Router. Only one instance of MySQL Router can be configured for system-wide operation. The system instance of MySQL Router has a router_name of "system". If additional instances are desired, use the --directory option to create self-contained MySQL Router installations. one at a time for the system, that's the rule 🚨

URI: a server instance from an InnoDB Cluster to fetch metadata information from. If the provided URI is a read-only instance, MySQL Router automatically reconnects to a read-write instance in the InnoDB Cluster so it can register MySQL Router. it literally finds a way 💅

If a configuration file already exists when you start MySQL Router with the --bootstrap, the existing router_id in that file is reused, and a reconfiguration process occurs. The configuration file is regenerated from scratch and the MySQL Router's metadata server account is recreated, although with the same name.

During the reconfiguration process, all changes made to an existing configuration file are discarded. 😭 so if you hand-edited stuff, it's gone — to customize a configuration file and still retain the ability of automatic reconfiguration (bootstrapping), you can use the --extra-config command line option to specify an additional configuration file that is read after the main configuration file. These configuration options are used because this extra configuration file is loaded after the main configuration file. order matters, bestie 🎀

The bootstrap process creates a new MySQL user account with a randomly generated password to use by that specific MySQL Router instance. This account is used by MySQL Router when connecting to the metadata server and InnoDB cluster to fetch information about its current state. For detailed information about this user including how its password is stored and the MySQL privilege it requires, see documentation for the MySQL user option.

The generated configuration file is named mysqlrouter.conf, and its location depends on the type of instance being configured, the system, and the package. For system-wide installations, the generated configuration file is added to the system's configuration directory such as /etc or %PROGRAMDATA%\MySQL\MySQL Router\. Executing mysqlrouter --help will display this location. so that's why the help output is doing the most — it's telling you where your stuff lives ✨

The --user option is required if executing a bootstrap with a super user (uid=0). Although not recommended, forcing the super user is possible by passing its name as an argument such as --user=root. not recommended, for real — consider yourself warned 🚩

The minimum GRANT permissions required to execute --bootstrap are:

GRANT CREATE USER ON *.* TO 'bootstrapuser'@'%' WITH GRANT OPTION;
GRANT SELECT, INSERT, UPDATE, DELETE, EXECUTE ON mysql_innodb_cluster_metadata.* TO 'bootstrapuser'@'%';
GRANT SELECT ON mysql.user TO 'bootstrapuser'@'%';
GRANT SELECT ON performance_schema.replication_group_members TO 'bootstrapuser'@'%';
GRANT SELECT ON performance_schema.replication_group_member_stats TO 'bootstrapuser'@'%';
GRANT SELECT ON performance_schema.global_variables TO 'bootstrapuser'@'%';

Using --bootstrap adds default values to the generated MySQL Router configuration file, and some of these default values depend on other conditions. Listed below are some of the conditions that affect the generated default values, where default is defined by passing in --bootstrap by itself. iykyk 👀

...

more parts coming, bestie — don't go anywhere 🦋

Table 4.2. Conditions that affect default --bootstrap values — bestie, this is the cheat sheet for what actually changes those generated defaults 👀

  • --conf-base-port — modifies the generated bind_port values for each connection type. By default, generated bind_port values work like this: for the classic protocol, Read-Write uses 6446 and Read-Only uses 6447, and for the X protocol Read-Write uses 6448 and Read-Only uses 6449. Setting --conf-base-port to 0 changes the default bind_port values to these defaults: for the classic protocol, Read-Write uses 6446 and Read-Only uses 6447, and for the X protocol Read-Write uses 64460 and Read-Only uses 64470. (yes those numbers are real, don't come for me 💀)
  • --conf-use-sockets — inserts socket definitions for each connection type.
  • --conf-skip-tcp — TCP/IP connection definitions are not defined.
  • --directory — affects all file paths, and also generates additional files.
  • Other — this list is not exhaustive, other options and conditions also affect the generated values.
  • --bootstrap-socket socket_name — the Unix-socket glow-up for bootstrapping 🔌
    • Command-Line Format: --bootstrap-socket socket_name
    • Platform Specific: Linux

Used in conjunction with --bootstrap to bootstrap using a local Unix domain socket instead of TCP/IP. The --bootstrap-socket value replaces the "host:port" part in the --bootstrap definition with the assigned socket name for connecting to the MySQL metadata server using Unix domain sockets. This is the MySQL instance that is being bootstrapped from, and this instance must be on the same machine if sockets are used. For additional details about how bootstrapping works, see --bootstrap.

Heads up: this option is different than the --conf-use-sockets command line option that sets the socket configuration file option during the bootstrap process. Two different things, don't mix them up 🫶

This option is not available on Windows.

  • --core-file — for when mysqlrouter dies and you want the receipts 💀
    • Command-Line Format: --core-file[={0|1}]
    • Type: Boolean
    • Default Value: 0

Write a core file if mysqlrouter dies. The name and location of the core file is system dependent. On Linux, a core file named core.pid is written to the current working directory of the process. pid represents the process ID of the server process. On macOS, a core file named core.pid is written to the /cores directory, if the process has the com.apple.security.get-task-allow entitlement. On Solaris, use the coreadm command to specify where to write the core file and how to name it. On Windows, a minidump file named mysqlrouter.{pid}.dmp is written to the current working directory of the process.

  • --directory dir_path, -d dir_path — your own lil self-contained Router world 🎀
    • Command-Line Format: --directory dir_path, -d dir_path
    • Type: String

Specifies that a self-contained MySQL Router installation will be created at the defined directory instead of configuring the system-wide router instance. This also allows multiple router instances to be created on the same system. Slay, multitasking icon behavior ✨

The self-contained directory structure for Router is:

$path/start.sh
$path/stop.sh
$path/mysqlrouter.pid
$path/mysqlrouter.conf
$path/mysqlrouter.key
$path/run
$path/run/keyring
$path/data
$path/log
$path/log/mysqlrouter.log

If this option is specified, the keyring file is stored under the runtime state directory of that instance, under run/ in the specified directory, as opposed to the system-wide runtime state directory.

If --conf-use-sockets is also enabled then the generated socket files are also added to this directory. Cozy.

  • --master-key-writer file_path — hand off your master key to a script, very main character of you 🔑
    • Command-Line Format: --master-key-writer file_path
    • Type: String

This optional bootstrap option accepts a script that reads the master key from STDIN. It also uses the ROUTER_ID environment variable set by MySQL Router before the master-key-writer script is called.

The master-key-writer and master-key-reader options must be used together, and using them means the master_key_file option must not be defined in mysqlrouter.conf as the master key is not written to the mysqlrouter.key master key file. That's a hard rule, not a vibe suggestion 🙈

This is also written to the generated MySQL Router configuration file as the master-key-writer [DEFAULT] option.

Example contents of a bash script named writer.sh used in our example:

#!/bin/bash
KID_=$(keyctl padd user ${ROUTER_ID} @us <&0)

Example usage:

$> mysqlrouter --bootstrap=127.0.0.1:3310 --master-key-reader=./reader.sh
  --master-key-writer=./writer.sh

This also affects the generated mysqlrouter.conf, for example:

[DEFAULT]
...
master-key-reader=reader.sh
master-key-writer=writer.sh
  • --master-key-reader — a bootstrap option (optional btw, you don't have to) that takes a script which writes the master key to STDOUT. ✨ It also makes use of the ROUTER_ID environment variable, which MySQL Router sets before your master-key-reader script gets called.
    • Command-Line Format: --master-key-reader file_path
    • Type: String

Okay so listen bestie, the master-key-reader and master-key-writer options must be used together, and using them means the master_key_file option must not be defined in mysqlrouter.conf. Why? Because the master key is not written to the mysqlrouter.key master key file in that case — instead it uses the value provided by this option's script. 💅

This is also written to the generated MySQL Router configuration file as the master-key-reader [DEFAULT] option.

Example contents of a bash script named reader.sh, used in our example:

#!/bin/bash
KID_=$(keyctl search @us user ${ROUTER_ID} 2>/dev/null)
if [ ! -z $KID_ ]; then
  keyctl pipe $KID_
fi

Example usage:

$> mysqlrouter --bootstrap=127.0.0.1:3310 --master-key-reader=./reader.sh
  # Or, multiple hosts--master-key-writer=./writer.sh

This also affects the generated mysqlrouter.conf, for example:

[DEFAULT]
...
master-key-reader=reader.sh
master-key-writer=writer.sh
  • --strict — turns on strict mode 🫶 Which for example causes the bootstrap --account user verification check to stop the bootstrap process rather than only emit a warning and continue if the supplied user does not pass the check. Like, no more "eh whatever, keep going" energy.
    • Command-Line Format: --strict
    • Type: String
  • --account — a bootstrap option to specify the MySQL user to use, which either reuses an existing MySQL user account or creates one. Behavior is controlled by the related --account-create option. 🌸
    • Command-Line Format: --account username
    • Type: String

With --account, usage favors ease of management over ease of deployment, because multiple routers may share the same account, and the username and password are manually defined rather than auto-generated. iykyk.

Setting this option triggers a password prompt for this account regardless of whether the password is available in the keyring. 👑

Bootstrapping without passing --account does not recreate an existing MySQL server account.

Using this option assumes the user has sufficient access rights for Router, because the bootstrap process does not attempt to add missing grants to existing accounts. The bootstrap process does verify the permissions and outputs information to the console of the failed check. The bootstrap process continues despite these failed checks unless the optional --strict option is also used. Example required permissions:

GRANT USAGE ON *.* TO `theuser`@`%`
GRANT SELECT, EXECUTE ON `mysql_innodb_cluster_metadata`.* TO `theuser`@`%`
GRANT INSERT, UPDATE, DELETE ON `mysql_innodb_cluster_metadata`.`routers` TO `theuser`@`%`
GRANT INSERT, UPDATE, DELETE ON `mysql_innodb_cluster_metadata`.`v2_routers` TO `theuser`@`%`
GRANT SELECT ON `performance_schema`.`global_variables` TO `theuser`@`%`
GRANT SELECT ON `performance_schema`.`replication_group_member_stats` TO `theuser`@`%`
GRANT SELECT ON `performance_schema`.`replication_group_members` TO `theuser`@`%`
A password is not accepted from the command-line. For example, passing in "foo:bar" assumes "foo:bar" is the desired username rather than user foo with the password bar. 😭 Do not do that.
  • --account-create — specify the account creation policy, which helps guard against accidentally bootstrapping with the wrong user account. Very "protect yourself" of it. 💜
    • Command-Line Format: --account-create behavior
    • Type: String
    • Default Value: if-not-exists
    • Valid Values: if-not-exists, always, never

Potential values are:

  • if-not-exists (default): Bootstrap either way; reuse the account if it exists, otherwise create it.
  • always: Only bootstrap if the account does not already exist; and create it.
  • never: Only bootstrap if the account already exists; and reuse it.

This option requires that the --account option is also used, and that --account-host is not used. ⭐

  • --account-host — the host pattern used for accounts created by MySQL Router during the bootstrap process. This is optional and defaults to %. 🎀
    • Command-Line Format: --account-host host_pattern
    • Type: String
    • Default Value: %

Pass in this option multiple times to define multiple patterns, in which case the generated MySQL accounts use the same password.

Note: Router does not perform sanity checking and does not ensure that the pattern authorizes Router to connect. 🙈
Note: Bootstrapping reuses existing Router accounts by dropping and recreating the user, and this user recreation process applies to every host. 💀

Examples:

# One host
$> mysqlrouter --bootstrap localhost:3310 --account-host host1
# Or, multiple hosts
$> mysqlrouter --bootstrap localhost:3310 --account-host host1 --account-host host2
  --account-host host3
  • --conf-use-sockets — enables local Unix domain sockets. 🦋
    • Command-Line Format: --conf-use-sockets
    • Platform Specific: Linux

This option is used while bootstrapping, and enabling it adds the socket option to the generated configuration file.

The name of the generated socket file depends on the protocol option. With the classic protocol enabled, the file is named mysql.sock for read-write connections, and mysqlro.sock for read-only connections. With the X Protocol enabled, the file is named mysqlx.sock for read-write connections, and mysqlxro.sock for read-only connections.

This option is not available on Windows. Sorry Windows besties. 💔
  • --conf-use-gr-notifications — enables the use_gr_notifications [metadata_cache] option during bootstrap. When enabled, Router is asynchronously notified about most cluster changes. See use_gr_notifications for more information. In addition, using this option sets ttl=60 and auth_cache_refresh_interval=60. 🔥
    • Command-Line Format: --conf-use-gr-notifications
  • --pid-file path — the pid file path option, literally right here in the list, giving "to be continued" energy 🧚
    • Command-Line Format: --pid-file path
    • Type: String

Sets where the PID file lives, bestie. And there are like, three ways to set it — in order of precedence: this --pid-file command-line option, then setting pid_file in Router's configuration file, or defining the ROUTER_PID environment variable.

Okay so heads up: if --bootstrap is specified, then setting --pid-file makes Router literally fail. Which is not like ROUTER_PID and the pid_file configuration option, because those two just get ignored when --bootstrap is specified. Different energy entirely, iykyk.

And if --bootstrap is not specified, then these things make Router fail: the --pid-file already exists, pid_file or ROUTER_PID are set but empty, or Router just can't write the PID file. That's it, that's the list 🫶

  • --report-host — optionally define Router's hostname instead of relying on auto-detection to figure out the externally visible hostname registered to metadata during the bootstrap process
    • Command-Line Format: --report-host hostname
    • Type: String
    • Router does not check or confirm that the supplied hostname is reachable — no vibe check, no nothing — but it does use RFC 1123 to validate host names, and RFC 2181 to validate addresses
    • The supplied hostname gets written to the host_name field of the mysql_innodb_cluster_metadata.hosts table in the MySQL InnoDB cluster metadata store
  • --conf-skip-tcp — skips configuration of a TCP port for listening to incoming connections. See also --conf-use-sockets
    • Command-Line Format: --conf-skip-tcp
    • Platform Specific: Linux
    • This option is not available on Windows 🪟
  • --conf-base-port port_num — the base (first) value used for the listening TCP ports, set by setting bind_port for each bootstrapped route
    • Command-Line Format: --conf-base-port port_num
    • Type: Integer
    • Default Value: 0
    • This value is used for the classic read-write route, and each additional allocated port gets incremented by a value of one. The port order set is classic read-write / read-only, and then x read-write / read-only
    • Setting --conf-base-port to 0 changes the default bind_port values to the following defaults, which were as follows: for the classic protocol, Read-Write uses 6446 and Read-Only uses 6447, and for the X protocol Read-Write uses 64460 and Read-Only uses 64470
    • Example usage, and yes we're copying it exactly:
# Example without --conf-base-port
$> mysqlrouter --bootstrap root@localhost:3310
...
Classic MySQL protocol connections to cluster 'devCluster':
- Read/Write Connections: localhost:6446
- Read/Only Connections: localhost:6447
X protocol connections to cluster 'devCluster':
- Read/Write Connections: localhost:6448
- Read/Only Connections: localhost:6449
# Example demonstrating --conf-base-port set to 0
$> mysqlrouter --bootstrap root@localhost:3310 --conf-base-port 0
...
Classic MySQL protocol connections to cluster 'devCluster':
- Read/Write Connections: localhost:6446
- Read/Only Connections: localhost:6447
X protocol connections to cluster 'devCluster':
- Read/Write Connections: localhost:64460
- Read/Only Connections: localhost:64470
  • --conf-bind-address address — modifies the bind_address value set by --bootstrap in the generated Router configuration file. By default, bootstrapping sets bind_address=0.0.0.0 for each route, and this option changes that value
    • Command-Line Format: --conf-bind-address address
    • Type: String
    • Default Value: 0.0.0.0
Note ✨ the default bind_address value is 127.0.0.1 if bind_address is not defined. Slight plot twist, but we move.
  • --read-timeout num_seconds — number of seconds before read operations to a metadata server are considered timed out
    • Command-Line Format: --read-timeout num_seconds
    • Type: Integer
    • Default Value: 30
    • This affects read operations during both the bootstrap process, and it also affects normal MySQL Router operations by setting the associated read_timeout option in the generated mysqlrouter.conf
    • This option is set under the [DEFAULT] namespace
  • --connect-timeout num_seconds — number of seconds before connection attempts to a metadata server are considered timed out
    • Command-Line Format: --connect-timeout num_seconds
    • Type: Integer
    • Default Value: 30
    • This affects connections during both the bootstrap process, and also affects normal MySQL Router operations by setting the associated connect_timeout option in the generated mysqlrouter.conf
    • There are two connect_timeout variants, okay bestie, don't mix them up: the metadata server variant is defined under the [DEFAULT] namespace, while the MySQL server variant is defined under the [routing] namespace
  • --user {user_name|user_id}, -u {user_name|user_id} — 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. When bootstrapping, all generated files are owned by this user, and this also sets the associated user option
    • Command-Line Format: --user {user_name|user_id}, -u {user_name|user_id}
    • Platform Specific: Linux
    • Type: String
    • This system user is defined in the configuration file under the [DEFAULT] namespace. For additional information, see the user option's documentation that --user configures
    • The --user option is required if executing a bootstrap as a super user (uid=0). Although it's not recommended, forcing the super user is possible by passing its name as an argument, such as --user=root. Like… you can, but bestie, think about it first 🙈
    • This option is not available on Windows 🪟
  • --name router_name — Command-Line Format: --name router_name, Type: String, Default Value: system
  • --name name — On initial bootstrap, this gives your self-contained Router instance a symbolic name. It's optional, and it's used with --directory. When you're creating multiple instances, the names must be unique — no twinning, bestie 💅
  • --force-password-validation
    • Command-Line Format: --force-password-validation
    • Platform Specific: Linux
    • By default, MySQL Router skips the MySQL Server's validate_password mechanism and instead generates and uses a STRONG password based on known validate_password default settings. Why? Because validate_password can be configured by the user, and Router can't take unusual custom settings into account 😭
    • This option makes sure password validation (validate_password) is not skipped for generated passwords. It is disabled by default.
  • --password-retries num_retries
    • Command-Line Format: --password-retries num_retries
    • Type: Integer
    • Default Value: 20
    • Minimum Value: 1
    • Maximum Value: 10000
    • Specifies how many times MySQL Router should attempt to generate a password when creating a user account with the password validation rules. The default value is 20. The valid range is 1 to 10000.
    • The most likely reason for failure is custom validate_password settings with unusual requirements, such as a 50 character minimum. In that fail scenario, it is likely that --force-password-validation is set to true.
  • --force
    • Command-Line Format: --force
    • Force a reconfiguration over a previously configured router instance on the host. Like, override the old setup, no cap 🔥
  • --ssl-mode mode
    • Command-Line Format: --ssl-mode mode
    • Type: String
    • Default Value: PREFERRED
    • Valid Values: PREFERRED, DISABLED, REQUIRED, VERIFY_CA, VERIFY_IDENTITY
    • SSL connection mode for use during bootstrap and normal operation when connecting to the metadata server. Analogous to --ssl-mode in the mysql client.
    • During bootstrap, all connections to metadata servers made by the Router will use the SSL options specified. If ssl_mode is not specified in the configuration, it will default to PREFERRED. During normal operation, after Router is launched, its Metadata Cache plugin will read and honor all configured SSL settings.
    • When set to a value other than the default (PREFERRED), an ssl_mode entry is inserted under [metadata_cache] in the generated configuration file.
    • Available values are DISABLED, PREFERRED, REQUIRED, VERIFY_CA, and VERIFY_IDENTITY. PREFERRED is the default value. As with the mysql client, this value is case-insensitive.
    • The configuration file equivalent is documented separately at ssl_mode.
  • --ssl-cert file_path
    • Command-Line Format: --ssl-cert file_path
    • Type: String
    • Default Value: (empty)
    • 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. This directly matches and uses functionality of the MySQL client's --ssl-cert option.
    • Like --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 🫶
  • --ssl-key file_path
    • Command-Line Format: --ssl-key file_path
    • Type: String
    • The path name of the SSL private key file in PEM format. This is used to facilitate client-side authentication during the bootstrap process. This directly matches and uses functionality of the MySQL client's --ssl-key option.
    • Like --ssl-cert, this option is only used during a bootstrap process 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.
  • --ssl-cipher ciphers
    • Command-Line Format: --ssl-cipher ciphers
    • Type: String
    • Default Value: (empty)
    • A colon-separated (":") list of SSL ciphers to allow, if SSL is enabled.
  • --tls-version versions
    • Command-Line Format: --tls-version versions
    • Type: String
    • Default Value: (empty)
    • A comma-separated (",") list of TLS versions to request, if SSL is enabled.
  • --ssl-ca file_path
    • Command-Line Format: --ssl-ca file_path
    • Type: String
    • Default Value: (empty)
    • Path to the SSL CA file to verify a server's certificate against.
  • --ssl-capath dir_path — Path to directory containing the SSL CA files to verify a server's certificate against. 🎀
    • Command-Line Format: --ssl-capath dir_path
    • Type: String
    • Default Value: (empty)
  • --ssl-crl file_path — Path to the SSL CRL file to use when verifying a server's certificate. 🦋
    • Command-Line Format: --ssl-crl file_path
    • Type: String
    • Default Value: (empty)
  • --ssl-crlpath dir_path — Path to the directory containing SSL CRL files to use when verifying a server's certificate. 💜
    • Command-Line Format: --ssl-crlpath dir_path
    • Type: String
    • Default Value: (empty)
  • --client-ssl-mode mode — SSL connection mode for use during bootstrap and normal operation when connecting between MySQL Router and client. ✨
    • Command-Line Format: --client-ssl-mode
    • Type: String
    • Default Value: PREFERRED
    • Valid Values: PREFERRED, DISABLED, PASSTHROUGH, REQUIRED

During bootstrap, all connections to clients made by the Router will use the SSL options specified. If client_ssl_mode is not specified in the configuration, it defaults to PREFERRED. 🫶

The configuration file equivalent is documented separately at client_ssl_mode. 👑

  • --client-ssl-cert file_path — 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. 🎀
    • Command-Line Format: --client-ssl-cert file_path
    • Type: String
    • Default Value: (empty)

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

  • client-ssl-curves — Defaults to a secure list of SSL curves. Format this string as a colon separated list of curve names. 🌸
    • Command-Line Format: --client-ssl-curves
    • Type: String
  • --client-ssl-key file_path — The path name of the SSL private key file in PEM format. This is used to facilitate client-side authentication during the bootstrap process. 🦋
    • Command-Line Format: --client-ssl-key file_path
    • Type: String

Like --client-ssl-cert, this option is only used during a bootstrap process 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. 🔥

  • --client-ssl-cipher ciphers — A colon-separated (:) list of SSL ciphers to allow, if SSL is enabled. 🌈
    • Command-Line Format: --client-ssl-cipher
    • Type: String
  • client-ssl-dh-params — 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. 🍓
    • Command-Line Format: --client-ssl-dh-params=filepath
    • Type: String
  • --client-ssl-ca file_path — Path to the SSL CA file to verify a server's certificate against. 💖
    • Command-Line Format: --client-ssl-ca file_path
    • Type: String
    • Default Value: (empty)
  • --client-ssl-capath dir_path — Path to directory containing the SSL CA files to verify a server's certificate against. 🎀
    • Command-Line Format: --client-ssl-capath dir_path
    • Type: String
    • Default Value: (empty)
  • --client-ssl-crl file_path — the path to the SSL CRL file to use when verifying a server's certificate. 🎀
    • Command-Line Format: --client-ssl-crl file_path
    • Type: String
    • Default Value: (empty)
  • --client-ssl-crlpath dir_path — path to the directory that's holding your SSL CRL files, used when verifying a server's certificate. like same vibe as the one above but it's giving "folder" instead of "file" ✨
    • Command-Line Format: --client-ssl-crlpath dir_path
    • Type: String
    • Default Value: (empty)

🌸 the server-side ssl era 🌸

  • --server-ssl-mode mode — the SSL connection mode used during bootstrap and normal operation, when MySQL Router is connecting to a server. 💅
    • Command-Line Format: --server-ssl-mode
    • Type: String
    • Default Value: PREFERRED
    • Valid Values:
      • AS_CLIENT
      • DISABLED
      • PREFERRED
      • REQUIRED

okay so here's the tea: during bootstrap, every connection the Router makes to servers uses the SSL options you specified. and if server_ssl_mode isn't specified in the configuration, it defaults to PREFERRED, no cap.

the config-file equivalent of this one is documented separately, over at server_ssl_mode — go look there for that flavor 🫶
  • --server-ssl-cipher ciphers — a colon-separated (":") list of the SSL ciphers you're allowing, if SSL is enabled. that's it, that's the whole thing 🦋
    • Command-Line Format: --server-ssl-cipher
    • Type: String
  • --server-ssl-ca file_path — path to the SSL CA file you verify a server's certificate against. 🔥
    • Command-Line Format: --server-ssl-ca file_path
    • Type: String
    • Default Value: (empty)
  • --server-ssl-capath dir_path — path to the directory containing the SSL CA files you verify a server's certificate against. 💖
    • Command-Line Format: --server-ssl-capath dir_path
    • Type: String
    • Default Value: (empty)
  • --server-ssl-crl file_path — path to the SSL CRL file to use when verifying a server's certificate. 💀
    • Command-Line Format: --server-ssl-crl file_path
    • Type: String
    • Default Value: (empty)
  • --server-ssl-crlpath dir_path — path to the directory containing SSL CRL files to use when verifying a server's certificate. 🍓
    • Command-Line Format: --server-ssl-crlpath dir_path
    • Type: String
    • Default Value: (empty)
  • server-ssl-curves — defaults to a secure list of SSL curves, bestie, we don't do insecure here. format the string as a colon-separated list of curve names and you're golden 🌈
    • Command-Line Format: --server-ssl-curves
    • Type: String
ngl, the manpage writes this one without the leading -- in the option list but the Command-Line Format says --server-ssl-curves. iykyk, keep both in mind 🧚
  • --server-ssl-verify string — verification of the SSL certificates that the server presents to the Router. this is the vibe check for certificates, periodt. 👑
    • Command-Line Format: --server-ssl-verify
    • Type: String
    • Default Value: DISABLED
    • Valid Values:
      • DISABLED
      • VERIFY_CA
      • VERIFY_IDENTITY

and what each one means, because this part actually matters:

  • DISABLED: the connection fails if the server doesn't provide a certificate in the handshake. 😭
  • VERIFY_CA: the connection fails if the server's certificate doesn't match a CA trusted by MySQL Router. 🦋
  • VERIFY_IDENTITY: the connection fails if the server's certificate doesn't match a CA trusted by MySQL Router, or if the server certificate's subject doesn't match the hostname or IP address that MySQL Router connected to. highkey the strictest one 💅

okay so we’re still deep in the option menu, and these next ones are giving config-file glow-up and Windows-service realness 💅

  • --config file_path, -c file_path — bestie, this is your “my config file is not in the usual spot” button. It gives Router a path and file name for the configuration file to use. Use it when you want a config file located in a folder other than the default locations. 💖 Command-Line Format: --config file_path, -c file_path When it’s used with --bootstrap, and the configuration file already exists, a copy of the current file is saved with a .bak extension if the generated configuration file contents is different than the original. Existing .bak files are overwritten. no cap, they really do get overwritten.
  • --extra-config file_path, -a file_path — this one gives you an optional, additional configuration file to use. Reach for it if you want to split the configuration file into two parts for testing, multiple instances of the application running on the same machine, etc. 🎀 Command-Line Format: --extra-config file_path, -a file_path This configuration file is read after the main configuration file. If there are conflicts — like an option is set in multiple configuration files — values from the file that is loaded last is used.
  • --install-service — Windows only, bestie. 🪟 Command-Line Format: --install-service [service_name] Platform Specific: Windows It installs Router as a Windows service that automatically starts when Windows starts. The service name defaults to MySQLRouter. This installation process does not validate configuration files passed in via --config. 🙈 This option is only available on Windows.
  • --install-service-manual — also Windows only, and it’s giving “you start me yourself” energy. ✨ Command-Line Format: --install-service-manual [service_name] Platform Specific: Windows It installs MySQL Router as a Windows service that can be manually started. The service name defaults to MySQLRouter. This option is only available on Windows.
  • --remove-service — Windows only, and yes, it removes the Router Windows service. 💅 Command-Line Format: --remove-service [service_name] Platform Specific: Windows The service name defaults to MySQLRouter. This option is only available on Windows.
  • --service — Windows only, and it starts Router as a Windows service. 👑 Command-Line Format: --service Platform Specific: Windows This is a private option, meaning it is only meant to be used by the Windows Service when launching Router as a service. This option is only available on Windows.
  • --update-credentials-section — Windows only, and it’s about the Windows password vault. 🫶 Command-Line Format: --update-credentials-section section_name Platform Specific: Windows This option is only available on Windows, and refers to its password vault.
  • --conf-target-cluster — sets the target_cluster metadata MySQL Router option. 🦋 Command-Line Format: --conf-target-cluster value Type: String Valid Values: current, primary

It accepts one of these strings:

  • current: sets target_cluster to the cluster containing the node being bootstrapped against. It defines it as the cluster’s UUID value. If this is also the Primary, it does not dynamically follow role changes like the primary does; instead it remains static.
  • primary: sets target_cluster to the primary cluster, including when it changes at runtime.

See also --config-target-cluster-by-name, which sets the target_cluster to a specific static cluster name.

Note — Bootstrapping against a ClusterSet[2] requires the cluster_type Router configuration option set to gr. ⭐
  • --conf-set-option — this bad boy sets a value for a generated configuration option during bootstrap. You can set a value for any bootstrapped option, for example: 🔥 Command-Line Format: --conf-set-option section_name[:optional_section_key].option=value Type: String
$> mysqlrouter -B 127.0.0.1:5000 \
               --directory=dir1  \
               --conf-set-option=logger.level=debug \
               --conf-set-option=routing:test_rw.max_connect_errors=0 \
               --conf-set-option=routing:test_ro.max_connect_errors=0

Those commands alter the default values for those specific options by defining them as such:

[logger]
level=debug
[routing:test_rw]
...
max_connect_errors=0
...
[routing:test_ro]
...
max_connect_errors=0
...

--conf-set-option definitions take precedence over option specific parameters to set specific value. For example, if both --connect-timeout=X and --conf-set-option=DEFAULT.connect_timeout=Y are specified when bootstrapping, the connect_timeout is set to Y in the generated configuration file. periodt.

  • --conf-target-cluster-by-name — sets the target_cluster metadata MySQL Router option to a specific cluster name. 🌸 Command-Line Format: --conf-target-cluster-by-name clusterName Type: String

Or, instead use --conf-target-cluster to assign a dynamic cluster type, such as primary. 💜

  • --remove-credentials-section section_name — yeets the credentials for a given section out of existence 💅
    • Command-Line Format: --remove-credentials-section section_name
    • Platform Specific: Windows

This one is Windows-only bestie, and it's talking about the Windows password vault, okay? It removes the credentials for whatever section you name. That's it, that's the whole vibe.

  • --clear-all-credentials — nukes everything in the password vault, like a full factory reset but for stored credentials 😭
    • Command-Line Format: --clear-all-credentials
    • Platform Specific: Windows

Clears the password vault by removing all credentials stored in it. Again: Windows-only, and again it's the Windows password vault we're talking about. No survivors, periodt.

  • --disable-rest — tells bootstrap not to write the REST API web service config into your generated mysqlrouter.conf 🙈
    • Command-Line Format: --disable-rest

Okay so by default, config details for the MySQL Router REST API web service functionality get added to the generated mysqlrouter.conf file at bootstrap — and this parameter means those details are not added. And before you panic: this does not disable REST API functionality itself, because you can manually configure the REST API (to enable it) later on. It's giving "not now" not "never", iykyk ✨

  • --https-port — pick the HTTP server port for the REST API under [http_server] in the generated mysqlrouter.conf 🔥
    • Command-Line Format: --https-port value
    • Type: Integer
    • Default Value: 8443
    • Minimum Value: 1
    • Maximum Value: 65535

Optionally define the HTTP server's port for the MySQL Router REST API under the [http_server] section in generated mysqlrouter.conf at bootstrap. It defaults to 8443. And heads up: availability of the port is not checked. Nobody's knocking on that door to see if anyone's home, so pick wisely bestie 🫶

Copyright © 2006, 2026, Oracle and/or its affiliates.

This documentation is free software; you can redistribute it and/or modify it only under the terms of the GNU General Public License as published by the Free Software Foundation; version 2 of the License.

This documentation is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with the program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA or see http://www.gnu.org/licenses/.

Fr fr read the license, it's the main character of this section 👑

🔗 NOTES 🔗

  1. Connecting Using URI-Like Connection Strings https://dev.mysql.com/doc/refman/9.7/en/connecting-using-uri-or-key-value-pairs.html#connecting-using-uri
  2. ClusterSet https://dev.mysql.com/doc/mysql-shell/9.7/en/innodb-clusterset.html

🦋 AUTHOR 🦋

Oracle Corporation (http://dev.mysql.com/).

And that's the whole page, bestie — you ate that 💅✨ This one's from MySQL 9.7, dated 06/24/2026, and it's MYSQLROUTER(1) all day. Go configure something iconic 🌈🎀

📦 where this page comes from