MySQL Router 8.0  /  ...  /  mysqlrouter — Command Line Options

4.3.1.1 mysqlrouter — Command Line Options

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 Summaries

Table 4.2 General Options

Format Description
--config Read configuration options from the provided file.
--extra-config Read this file after configuration files are read from either default locations or from files specified by the --config option.
--help Display help text and exit.
--user Run mysqlrouter as the user having the defined user name or numeric user id.
--version Display version information and exit.

Table 4.3 Bootstrapping Options

Format Description Introduced
--account-host The host pattern used for bootstrapped accounts 8.0.12
--bootstrap Bootstrap and configure Router for operation with a MySQL InnoDB cluster.
--bootstrap-socket Connect to the MySQL metadata server through a Unix domain socket, used in conjunction with --bootstrap.
--conf-base-port Base port to use for listening Router ports.
--conf-bind-address IP address of the interface to which router's listening sockets should bind.
--conf-skip-tcp Whether to disable binding of a TCP port for incoming connections.
--conf-use-sockets Whether to use Unix domain sockets.
--connect-timeout Number of seconds before connection attempts to a metadata server are considered timed out 8.0.4
--directory Creates a self-contained directory for a new instance of the Router.
--force Force reconfiguration of a possibly existing instance of the router.
--force-password-validation When creating a user account automatically, do not skip the validate_password mechanism.
--master-key-reader Script that returns the master key to STDOUT. 8.0.12
--master-key-writer Script that reads the master key from STDIN. 8.0.12
--name Gives a symbolic name for the router instance.
--password-retries The number of retries to use for generating the Router's user password.
--read-timeout Number of seconds before read operations to a metadata server are considered timed out 8.0.4
--report-host Router's hostname; overrides auto-detection 8.0.12

Table 4.4 SSL Options

Format Description Introduced
--ssl-ca Path to SSL Certificate Authority file to verify server's certificate against.
--ssl-capath Directory that contains trusted SSL Certificate Authority certificate files
--ssl-cert The client-side SSL certificate to facilitate client-side authentication during bootstrap 8.0.4
--ssl-cipher A colon-separated list of SSL ciphers to allow, if SSL is enabled.
--ssl-crl Path to SSL CRL file to use when verifying server certificate.
--ssl-crlpath Path to directory containing SSL CRL files to use when verifying server certificate.
--ssl-key The private SSL key to facilitate client-side authentication during bootstrap 8.0.4
--ssl-mode SSL connection mode for use during bootstrap and normal operation, when connecting to the metadata server. Analogous to --ssl-mode in the mysql client.
--tls-version Comma-separated list of TLS versions to request, if SSL is enabled.

Table 4.5 Windows Services Options

Format Description
--clear-all-credentials Clear all stored credentials
--install-service On Windows, install MySQL Router as a service named MySQLRouter, and set it to automatically start when Windows restarts.
--install-service-manual On Windows, install MySQL Router as a service named MySQLRouter, that can be manually started.
--remove-credentials-section Remove a section's credentials
--remove-service Remove MySQL Router as a Windows service.
--service Start MySQL Router as a Windows service.
--update-credentials-section Update a section's credentials

mysqlrouter Option Descriptions
  • --version, -V

    Property Value
    Command-Line Format --version , -V

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

    shell> mysqlrouter --version
    
    MySQL Router v8.0.12 on Linux (64-bit) (GPL community edition)
  • --help, -?

    Property Value
    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:

    shell> mysqlrouter --help
    
    MySQL Router v8.0.12 on Linux (64-bit) (GPL community edition)
    Copyright (c) 2015, 2017, Oracle and/or its affiliates. All rights reserved.
    
    Oracle is a registered trademark of Oracle Corporation and/or its
    affiliates. Other names may be trademarks of their respective
    owners.
    
    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

    Property Value
    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 a URI String 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 "default". 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.

    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.6 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 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.
    Single primary mode is disabled If the group_replication_single_primary_mode MySQL Server option is disabled (it is enabled by default), only Read-Write (and not Read-Only) connections are defined. For additional information, see Bootstrapping and group_replication_single_primary_mode.
    Other This list is not exhaustive, other options and conditions also affect the generated values.

  • --bootstrap-socket socket_name

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

  • --directory dir_path, -d dir_path

    Property Value
    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

    Property Value
    Command-Line Format --master-key-writer file_path
    Introduced 8.0.12
    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:

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

    Property Value
    Command-Line Format --master-key-reader file_path
    Introduced 8.0.12
    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:

    shell> 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
  • --account-host

    Property Value
    Command-Line Format --account-host host_pattern
    Introduced 8.0.12
    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
    shell> mysqlrouter --bootstrap localhost:3310 --account-host host1
    
    # Or, multiple hosts
    shell> mysqlrouter --bootstrap localhost:3310 --account-host host1 --account-host host2 --account-host host3
  • --conf-use-sockets

    Property Value
    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 mode and protocol options. With the classic protocol enabled, the file is named mysql.sock in read-write mode, and mysqlro.sock in read-only mode. With the X Protocol enabled, the file is named mysqlx.sock in read-write mode, and mysqlxro.sock in read-only mode.

    This option is not available on Windows.

  • --report-host

    Property Value
    Command-Line Format --report-host hostname
    Introduced 8.0.12
    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, and it only checks the hostname string for illegal characters. Only alphanumeric, '-', '.', and '_' characters are allowed.

    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

    Property Value
    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

    Property Value
    Command-Line Format --conf-base-port port_num
    Type Integer

    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.

    Example usage:

    # Example without --conf-base-port
    shell> 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:64460
    - Read/Only Connections: localhost:64470
    
    # Example demonstrating --conf-base-port behavior
    shell> mysqlrouter --bootstrap root@localhost:3310 --conf-base-port 6446
    ...
    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
  • --conf-bind-address address

    Property Value
    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

    Property Value
    Command-Line Format --read-timeout num_seconds
    Introduced 8.0.4
    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

    Property Value
    Command-Line Format --connect-timeout num_seconds
    Introduced 8.0.4
    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}

    Property Value
    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

    Property Value
    Command-Line Format --name router_name
    Type String

    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

    Property Value
    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

    Property Value
    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, either --force-password-validation is set to true and/or the mysql_native_password MySQL Server plugin is disabled (this plugin allows bypassing validation).

  • --force

    Property Value
    Command-Line Format --force

    Force a reconfiguration over a previously configured router instance on the host.

  • --ssl-mode mode

    Property Value
    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

    Property Value
    Command-Line Format --ssl-key file_path
    Introduced 8.0.4
    Type String

    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

    Property Value
    Command-Line Format --ssl-key file_path
    Introduced 8.0.4
    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

    Property Value
    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

    Property Value
    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

    Property Value
    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

    Property Value
    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

    Property Value
    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

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

  • --config file_path, -c file_path

    Property Value
    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

    Property Value
    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

    Property Value
    Command-Line Format --install-service
    Platform Specific Windows

    Install Router as a Windows service that automatically starts when Windows starts. The service name is MySQLRouter.

    This installation process does not validate configuration files passed in via --config.

    This option is only available on Windows.

  • --install-service-manual

    Property Value
    Command-Line Format --install-service-manual
    Platform Specific Windows

    Install MySQL Router as a Windows service that can be manually started. The service name is MySQLRouter.

    This option is only available on Windows.

  • --remove-service

    Property Value
    Command-Line Format --remove-service
    Platform Specific Windows

    Remove the Router Windows service.

    This option is only available on Windows.

  • --service

    Property Value
    Command-Line Format --service
    Platform Specific Windows

    Start Router as a Windows service.

    This option is only available on Windows.

  • --update-credentials-section

    Property Value
    Command-Line Format --update-credentials-section section_name
    Platform Specific Windows

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

  • --remove-credentials-section section_name

    Property Value
    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

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


User Comments
User comments in this section are, as the name implies, provided by MySQL users. The MySQL documentation team is not responsible for, nor do they endorse, any of the information provided here.
  Posted by clé ment on April 11, 2018
For the -install--service option on a windows server, it install the service with the "log on" account option set to "Local Service", which is not good.
Service will start, but the process could never be loaded. So the best is to switch the "Log On" account to "Local System Account" or "NETWORK SERVICE".

That work better for me (tested on Windows 2008R2).
Sign Up Login You must be logged in to post a comment.