MySQL Router 2.1  /  ...  /  Command Line Options

4.3.1 Command Line Options

MySQL Router accepts command line options that are passed into mysqlrouter to affect its behavior, or to bootstrap router.

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.

The following tables summarize the MySQL Router options read by the mysqlrouter command. Detailed information about each of these options, such as descriptions and allowed values, is documented below these tables.

General Options

Table 4.2 General

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.

Bootstrapping Options

Table 4.3 Bootstrapping

Format Description
--bootstrap Bootstrap and configure Router for operation with a MySQL InnoDB cluster.
--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.
--directory Creates a self-contained directory for a new instance of the Router.
--force Force reconfiguration of a possibly existing instance of the router.
--name Gives a symbolic name for the router instance.

SSL Options

These options match behaviour and functionality to their counterparts in the mysql client, as described at Command Options for Secure Connections. These options are used during both bootstrapping and during normal router operations. The values can be lower, mixed, or upper case, and is preserved when bootstrap writes to the configuration file.

Table 4.4 SSL

Format Description
--ssl-ca Path to SSL CA file to verify server's certificate against.
--ssl-capath Path to directory containing SSL CA files to verify server's certificate against.
--ssl-cipher 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-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.

Windows Services Options

Specific to Microsoft Windows, these control the configuration of MySQL Router as a service.

Table 4.5 Windows Services

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

MySQL Router Command Line Option Descriptions

The following list contains descriptions of each startup option available for use with mysqlrouter, including allowed and default values. Options noted as boolean need only be specified in order to take effect; you should not try to set a value for them.

  • --version, -v

    Command-Line Format --version

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

    shell> mysqlrouter --version
    
    MySQL Router v2.1.3 on Linux (64-bit) (GPL community edition)
  • --help, -h

    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 v2.1.3 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] [-h|--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, -B

    Command-Line Format --bootstrap server-url
    Permitted Values Type string

    The main option to perform a bootstrap of the router by connecting to the MySQL metadata server at the URI. A password is prompted if needed.

    By default, bootstrap will perform a system-wide configuration of the router. Only one instance of the router may be configured for system-wide operation. The system instance of the router has a router_name of "default". If additional instances are desired, then use the --directory to create self-contained router installations.

    If a configuration file already exists on bootstrap, the existing router_id in that file will be reused, and a reconfiguration process will occur. The configuration file will be regenerated from scratch and the router's metadata server account will be 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 Router instance. This account is used by 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.

    Note

    Bootstrapping was added in MySQL Router 2.1.1.

  • --directory directory, -d

    Command-Line Format --directory directory
    Permitted Values 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.

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

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

    Command-Line Format --conf-base-port port
    Permitted Values 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 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 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

    Command-Line Format --conf-bind-address address
    Permitted Values Type string
    Default 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.

  • --user={user_name|user_id}, -u

    Command-Line Format --user name
    Platform Specific Linux
    Permitted Values 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 name

    Command-Line Format --name name
    Permitted Values 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

    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
    Permitted Values Type string
    Default 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-cipher ciphers

    Command-Line Format --ssl-cipher ciphers
    Permitted Values Type string
    Default

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

  • --tls-version versions

    Command-Line Format --tls-version versions
    Permitted Values Type string
    Default

    A comma-separated (",") list of TLS versions to request, if SSL is enabled.

  • --ssl-ca path

    Command-Line Format --ssl-ca path
    Permitted Values Type string
    Default

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

  • --ssl-capath directory

    Command-Line Format --ssl-capath directory
    Permitted Values Type string
    Default

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

  • --ssl-crl path

    Command-Line Format --ssl-crl path
    Permitted Values Type string
    Default

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

  • --ssl-crlpath directory

    Command-Line Format --ssl-crlpath directory
    Permitted Values Type string
    Default

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

  • --config path, -c

    Command-Line Format --config 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 path, -a

    Command-Line Format --extra-config 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
    Platform Specific Windows

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

    This option is only available on Windows.

  • --install-service-manual

    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

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

    Remove the Router Windows service.

    This option is only available on Windows.

  • --service

    Command-Line Format --service
    Platform Specific Windows

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

  • --remove-credentials-section

    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.


User Comments
Sign Up Login You must be logged in to post a comment.