---
name: "mysqlrouter"
section: "1"
platform: "linux"
package: "percona-server"
version: "9.7.2_2-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/mysqlrouter"
---

# mysqlrouter(1)

MySQL Router

## NAME

mysqlrouter - MySQL Router

## SYNOPSIS

**mysqlrouter \[***options***\]**

## DESCRIPTION

• mysqlrouter Option Summaries

• mysqlrouter Option Descriptions

MySQL Router accepts command line options that are passed into **mysqlrouter** to affect its behavior, or to bootstrap router based on an InnoDB Cluster.

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

Bootstrapping command line options affect the generated files and directories that are used when starting MySQL Router. mysqlrouter Option Summariesmysqlrouter Option Descriptions

• **--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)
```

• **--help**, **-?**

| | |
| --- | --- |
| **Command-Line Format** | --help , -? |

Display help and informative information, and exit.

The **--help** option has an added benefit. Along with the explanation of each of the options, the **--help** option also displays the paths used to find the configuration file, and also several default paths. 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.

• **--bootstrap** *URI*, **-B** *URI*

| | |
| --- | --- |
| **Command-Line Format** | --bootstrap URI, -B URI |
| **Type** | String |

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.

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

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

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.

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

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.

**Table 4.2. Conditions that affect default --bootstrap values**

| | |
| --- | --- |
| **Condition** | **Description** |
| **--conf-base-port** | Modifies generated **bind\_port** values for each connection type. By default, generated **bind\_port** values are as follows: 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 the following 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. |
| **--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*

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

This option is different than the **--conf-use-sockets** command line option that sets the **socket** configuration file option during the bootstrap process.

This option is not available on Windows.

• **--core-file**

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

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

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.

• **--master-key-writer**

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

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

| | |
| --- | --- |
| **Command-Line Format** | --master-key-reader file\_path |
| **Type** | String |

This optional bootstrap option accepts a script that writes the master key to *STDOUT*. It also uses the *ROUTER\_ID* environment variable set by MySQL Router before the **master-key-reader** script is called.

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 as the master key is not written to the mysqlrouter.key master key file, and instead 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**

| | |
| --- | --- |
| **Command-Line Format** | --strict |
| **Type** | String |

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

• **--account**

| | |
| --- | --- |
| **Command-Line Format** | --account username |
| **Type** | String |

A bootstrap option to specify the MySQL user to use, which either reuses an existing MySQL user account or creates one; behavior controlled by the related **--account-create** option.

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

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

• **--account-create**

| | |
| --- | --- |
| **Command-Line Format** | --account-create behavior |
| **Type** | String |
| **Default Value** | if-not-exists |
| **Valid Values** | if-not-exists always never |

Specify the account creation policy to help guard against accidentally bootstrapping with the wrong user account. 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**

| | |
| --- | --- |
| **Command-Line Format** | --account-host host\_pattern |
| **Type** | String |
| **Default Value** | % |

The host pattern used for accounts created by MySQL Router during the bootstrap process. This is optional and defaults to '%'.

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

| | |
| --- | --- |
| **Command-Line Format** | --conf-use-sockets |
| **Platform Specific** | Linux |

Enables local Unix domain sockets.

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.

• **--conf-use-gr-notifications**

| | |
| --- | --- |
| **Command-Line Format** | --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.

• **--pid-file** *path*

| | |
| --- | --- |
| **Command-Line Format** | --pid-file path |
| **Type** | String |

Sets location of the PID file. This can be set in three different ways (in order of precedence): this **--pid-file** command-line option, setting **pid\_file** in Router's configuration file, or defining the ROUTER\_PID environment variable.

If **--bootstrap** is specified, then setting --pid-file causes Router to fail. This is unlike ROUTER\_PID and the pid\_file configuration option, which are ignored if --bootstrap is specified.

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.

• **--report-host**

| | |
| --- | --- |
| **Command-Line Format** | --report-host hostname |
| **Type** | String |

Optionally define Router's hostname instead of relying on auto-detection to determine the externally visible hostname registered to metadata during the bootstrap process.

Router does not check or confirm that the supplied hostname is reachable, but does use RFC 1123 to validate host names, and RFC 2181 to validate addresses.

The supplied hostname is written to the host\_name field of the mysql\_innodb\_cluster\_metadata.hosts table in the MySQL InnoDB cluster metadata store.

• **--conf-skip-tcp**

| | |
| --- | --- |
| **Command-Line Format** | --conf-skip-tcp |
| **Platform Specific** | Linux |

Skips configuration of a TCP port for listening to incoming connections. See also **--conf-use-sockets**.

This option is not available on Windows.

• **--conf-base-port** *port\_num*

| | |
| --- | --- |
| **Command-Line Format** | --conf-base-port port\_num |
| **Type** | Integer |
| **Default Value** | 0 |

Base (first) value used for the listening TCP ports by setting **bind\_port** for each bootstrapped route.

This value is used for the classic read-write route, and each additional allocated port is 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:

```
# 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*

| | |
| --- | --- |
| **Command-Line Format** | --conf-bind-address address |
| **Type** | String |
| **Default Value** | 0.0.0.0 |

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.

**Note**\
 The default **bind\_address** value is *127.0.0.1* if **bind\_address** is not defined.

• **--read-timeout** *num\_seconds*

| | |
| --- | --- |
| **Command-Line Format** | --read-timeout num\_seconds |
| **Type** | Integer |
| **Default Value** | 30 |

Number of seconds before read operations to a metadata server are considered timed out.

This affects read operations during both the bootstrap process, and 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*

| | |
| --- | --- |
| **Command-Line Format** | --connect-timeout num\_seconds |
| **Type** | Integer |
| **Default Value** | 30 |

Number of seconds before connection attempts to a metadata server are considered timed out.

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. 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***}**

| | |
| --- | --- |
| **Command-Line Format** | --user {user\_name\|user\_id}, -u {user\_name\|user\_id} |
| **Platform Specific** | Linux |
| **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. When bootstrapping, all generated files are owned by this user, and this also sets the associated **user** option.

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 not recommended, forcing the super user is possible by passing its name as an argument, such as *--user=root*.

This option is not available on Windows.

• **--name** *router\_name*

| | |
| --- | --- |
| **Command-Line Format** | --name router\_name |
| **Type** | String |
| **Default Value** | system |

On initial bootstrap, specifies a symbolic name for a self-contained Router instance. This option is optional, and is used with **--directory**. When creating multiple instances, the names must be unique.

• **--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 Router generates and uses a STRONG password based on known validate\_password default settings. This is because validate\_password can be configured by the user and Router can not take into account unusual custom settings.

This option ensures that password validation (validate\_password) is not skipped for generated passwords, and 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 the number of times MySQL Router should attempt to generate a password when creating 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 due to 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.

• **--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 the \[metadata\_cache\] section 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** |  |

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

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

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

Path to the SSL CA file to verify a server's certificate against.

• **--ssl-capath** *dir\_path*

| | |
| --- | --- |
| **Command-Line Format** | --ssl-capath dir\_path |
| **Type** | String |
| **Default Value** |  |

Path to directory containing the SSL CA files to verify a server's certificate against.

• **--ssl-crl** *file\_path*

| | |
| --- | --- |
| **Command-Line Format** | --ssl-crl file\_path |
| **Type** | String |
| **Default Value** |  |

Path to the SSL CRL file to use when verifying a server's certificate.

• **--ssl-crlpath** *dir\_path*

| | |
| --- | --- |
| **Command-Line Format** | --ssl-crlpath dir\_path |
| **Type** | String |
| **Default Value** |  |

Path to the directory containing SSL CRL files to use when verifying a server's certificate.

• **--client-ssl-mode** *mode*

| | |
| --- | --- |
| **Command-Line Format** | --client-ssl-mode |
| **Type** | String |
| **Default Value** | PREFERRED |
| **Valid Values** | PREFERRED DISABLED PASSTHROUGH REQUIRED |

SSL connection mode for use during bootstrap and normal operation when connecting between MySQL Router and client.

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*

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

• **client-ssl-curves**

| | |
| --- | --- |
| **Command-Line Format** | --client-ssl-curves |
| **Type** | String |

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

• **--client-ssl-key** *file\_path*

| | |
| --- | --- |
| **Command-Line Format** | --client-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.

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*

| | |
| --- | --- |
| **Command-Line Format** | --client-ssl-cipher |
| **Type** | String |

A colon-separated (":") list of SSL ciphers to allow, if SSL is enabled.

• **client-ssl-dh-params**

| | |
| --- | --- |
| **Command-Line Format** | --client-ssl-dh-params=filepath |
| **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-ca** *file\_path*

| | |
| --- | --- |
| **Command-Line Format** | --client-ssl-ca file\_path |
| **Type** | String |
| **Default Value** |  |

Path to the SSL CA file to verify a server's certificate against.

• **--client-ssl-capath** *dir\_path*

| | |
| --- | --- |
| **Command-Line Format** | --client-ssl-capath dir\_path |
| **Type** | String |
| **Default Value** |  |

Path to directory containing the SSL CA files to verify a server's certificate against.

• **--client-ssl-crl** *file\_path*

| | |
| --- | --- |
| **Command-Line Format** | --client-ssl-crl file\_path |
| **Type** | String |
| **Default Value** |  |

Path to the SSL CRL file to use when verifying a server's certificate.

• **--client-ssl-crlpath** *dir\_path*

| | |
| --- | --- |
| **Command-Line Format** | --client-ssl-crlpath dir\_path |
| **Type** | String |
| **Default Value** |  |

Path to the directory containing SSL CRL files to use when verifying a server's certificate.

• **--server-ssl-mode** *mode*

| | |
| --- | --- |
| **Command-Line Format** | --server-ssl-mode |
| **Type** | String |
| **Default Value** | PREFERRED |
| **Valid Values** | AS\_CLIENT DISABLED PREFERRED REQUIRED |

SSL connection mode for use during bootstrap and normal operation when connecting between MySQL Router and server.

During bootstrap, all connections to servers made by the Router will use the SSL options specified. If **server\_ssl\_mode** is not specified in the configuration, it defaults to PREFERRED.

The configuration file equivalent is documented separately at **server\_ssl\_mode**.

• **--server-ssl-cipher** *ciphers*

| | |
| --- | --- |
| **Command-Line Format** | --server-ssl-cipher |
| **Type** | String |

A colon-separated (":") list of SSL ciphers to allow, if SSL is enabled.

• **--server-ssl-ca** *file\_path*

| | |
| --- | --- |
| **Command-Line Format** | --server-ssl-ca file\_path |
| **Type** | String |
| **Default Value** |  |

Path to the SSL CA file to verify a server's certificate against.

• **--server-ssl-capath** *dir\_path*

| | |
| --- | --- |
| **Command-Line Format** | --server-ssl-capath dir\_path |
| **Type** | String |
| **Default Value** |  |

Path to directory containing the SSL CA files to verify a server's certificate against.

• **--server-ssl-crl** *file\_path*

| | |
| --- | --- |
| **Command-Line Format** | --server-ssl-crl file\_path |
| **Type** | String |
| **Default Value** |  |

Path to the SSL CRL file to use when verifying a server's certificate.

• **--server-ssl-crlpath** *dir\_path*

| | |
| --- | --- |
| **Command-Line Format** | --server-ssl-crlpath dir\_path |
| **Type** | String |
| **Default Value** |  |

Path to the directory containing SSL CRL files to use when verifying a server's certificate.

• **server-ssl-curves**

| | |
| --- | --- |
| **Command-Line Format** | --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-verify** *string*

| | |
| --- | --- |
| **Command-Line Format** | --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.

• **--config** *file\_path*, **-c** *file\_path*

| | |
| --- | --- |
| **Command-Line Format** | --config file\_path, -c file\_path |

Used to provide a path and file name for the configuration file to use. Use this option if you want to use a configuration file located in a folder other than the default locations.

When used with **--bootstrap**, and if 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.

• **--extra-config** *file\_path*, **-a** *file\_path*

| | |
| --- | --- |
| **Command-Line Format** | --extra-config file\_path, -a file\_path |

Used to provide an optional, additional configuration file to use. Use this option if you want to split the configuration file into two parts for testing, multiple instances of the application running on the same machine, etc.

This configuration file is read after the main configuration file. If there are conflicts (an option is set in multiple configuration files), values from the file that is loaded last is used.

• **--install-service**

| | |
| --- | --- |
| **Command-Line Format** | --install-service \[service\_name\] |
| **Platform Specific** | Windows |

Install 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**

| | |
| --- | --- |
| **Command-Line Format** | --install-service-manual \[service\_name\] |
| **Platform Specific** | Windows |

Install 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**

| | |
| --- | --- |
| **Command-Line Format** | --remove-service \[service\_name\] |
| **Platform Specific** | Windows |

Remove the Router Windows service; service name defaults to MySQLRouter.

This option is only available on Windows.

• **--service**

| | |
| --- | --- |
| **Command-Line Format** | --service |
| **Platform Specific** | Windows |

Start Router as a Windows service. 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**

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

| | |
| --- | --- |
| **Command-Line Format** | --conf-target-cluster value |
| **Type** | String |
| **Valid Values** | current primary |

Sets the **target\_cluster** metadata MySQL Router option. Accepts one of the following 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**

| | |
| --- | --- |
| **Command-Line Format** | --conf-set-option section\_name\[:optional\_section\_key\].option=value |
| **Type** | String |

Sets a value for a generated configuration option during bootstrap; this can set a value for any bootstrapped option, for example:

```
$> 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.

• **--conf-target-cluster-by-name**

| | |
| --- | --- |
| **Command-Line Format** | --conf-target-cluster-by-name clusterName |
| **Type** | String |

Sets the **target\_cluster** metadata MySQL Router option to a specific cluster name.

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

• **--remove-credentials-section** *section\_name*

| | |
| --- | --- |
| **Command-Line Format** | --remove-credentials-section section\_name |
| **Platform Specific** | Windows |

Remove the credentials for a given section.

This option is only available on Windows, and refers to its password vault.

• **--clear-all-credentials**

| | |
| --- | --- |
| **Command-Line Format** | --clear-all-credentials |
| **Platform Specific** | Windows |

Clear the password vault by removing all credentials stored in it.

This option is only available on Windows, and refers to its password vault.

• **--disable-rest**

| | |
| --- | --- |
| **Command-Line Format** | --disable-rest |

By default, configuration details for the MySQL Router REST API web service functionality are added to the generated mysqlrouter.conf file at bootstrap; and this parameter means those details are not added. This does not disable REST API functionality, as the REST API functionality can be manually configured (to enable it) later on.

• **--https-port**

| | |
| --- | --- |
| **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. Availability of the port is not checked.

## COPYRIGHT

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

## 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/).