/usr/bin/mysqlrouter

MySQL Router  Ver 8.4.2-2 for Linux on x86_64 (Source distribution)
Copyright (c) 2009-2024 Percona LLC and/or its affiliates
Copyright (c) 2015, 2024, Oracle and/or its affiliates.

Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.

Configuration read from the following files in the given order (enclosed
in parentheses means not available for reading):
  (/usr/bin/.././mysqlrouter.conf)
  (/usr/bin/.././mysqlrouter.ini)
  (/tmp/.mysqlrouter.conf)
  (/tmp/.mysqlrouter.ini)
Plugins Path:
  /usr/lib/mysqlrouter

Default Log Directory:
  /usr

Default Persistent Data Directory:
  /usr/var/lib/mysqlrouter

Default Runtime State Directory:
  /usr/run


# Usage

mysqlrouter (-?|--help)

mysqlrouter (-V|--version)

mysqlrouter [--account-host=<account-host>]
            (-B|--bootstrap=<server_url>)
            [--bootstrap-socket=<socket_name>]
            [--client-ssl-cert=<path>]
            [--client-ssl-cipher=<VALUE>]
            [--client-ssl-curves=<VALUE>]
            [--client-ssl-key=<path>]
            [--client-ssl-mode=<mode>]
            [--conf-base-port=<port>] [--conf-skip-tcp]
            [--conf-use-sockets] [--core-file=[<VALUE>]]
            [--connect-timeout=[<VALUE>]]
            [--conf-use-gr-notifications=[<VALUE>]]
            [-d|--directory=<directory>] [--force]
            [--force-password-validation]
            [--master-key-reader=<VALUE>]
            [--master-key-writer=<VALUE>] [--name=[<name>]]
            [--password-retries=[<password-retries>]]
            [--read-timeout=[<VALUE>]]
            [--report-host=<report-host>]
            [--server-ssl-ca=<path>]
            [--server-ssl-capath=<directory>]
            [--server-ssl-cipher=<VALUE>]
            [--server-ssl-crl=<path>]
            [--server-ssl-crlpath=<directory>]
            [--server-ssl-curves=<VALUE>]
            [--server-ssl-mode=<ssl-mode>]
            [--server-ssl-verify=<verify-mode>]
            [--ssl-ca=<path>] [--ssl-cert=<path>]
            [--ssl-cipher=<ciphers>] [--ssl-crl=<path>]
            [--ssl-crlpath=<directory>] [--ssl-key=<path>]
            [--ssl-mode=<mode>] [--tls-version=<versions>]
            [-u|--user=<username>]
            [--conf-set-option=<conf-set-option>]

mysqlrouter [-c|--config=<path>] [--core-file=[<VALUE>]]
            [-a|--extra-config=<path>] [--pid-file=<pidfile>]
            [-u|--user=<username>]

# Options

  --account <account>
        Account (username) to be used by Router when talking to cluster.
        (bootstrap)
  --account-create <mode>
        Specifies account creation policy (useful for guarding against
        accidentally bootstrapping using a wrong account). <mode> is one
        of:
          'always'        - bootstrap only if account doesn't exist
          'never'         - bootstrap only if account exists
          'if-not-exists' - bootstrap either way (default)
        This option can only be used if option '--account' is also used.
        Argument 'never' cannot be used together with option
        '--account-host'
        (bootstrap)
  --account-host <account-host>
        Host pattern to be used when creating Router's database user,
        default='%'. It can be used multiple times to provide multiple
        patterns. (bootstrap)
  -B <server_url>, --bootstrap <server_url>
        Bootstrap and configure Router for operation with a MySQL InnoDB
        cluster.
  --bootstrap-socket <socket_name>
        Bootstrap and configure Router via a Unix socket
  --client-ssl-cert <path>
        name of a PEM file containing a SSL certificate used for
        accepting TLS connections between client and router
  --client-ssl-cipher <VALUE>
        list of one or more colon separated cipher names used for
        accepting TLS connections between client and router
  --client-ssl-curves <VALUE>
        list of one or more colon separated elliptic curve names used
        for accepting TLS connections between client and router
  --client-ssl-key <path>
        name of a PEM file containing a SSL private key used for
        accepting TLS connections between client and router
  --client-ssl-mode <mode>
        SSL mode for connections from client to router. One of DISABLED,
        PREFERRED, REQUIRED or PASSTHROUGH.
  --client-ssl-dh-params <VALUE>
        name of a PEM file containing DH paramaters
  --conf-base-port <port>
        Base port to use for listening router ports. (bootstrap)
  --conf-bind-address <address>
        IP address of the interface to which router's listening sockets
        should bind. (bootstrap)
  --conf-skip-tcp
        Whether to disable binding of a TCP port for incoming
        connections. (bootstrap)
  --conf-use-sockets
        Whether to use Unix domain sockets. (bootstrap)
  -c <path>, --config <path>
        Only read configuration from given file.
  --core-file [ <VALUE>]
        Write a core file if mysqlrouter dies.
  --connect-timeout [ <VALUE>]
        The time in seconds after which trying to connect to metadata
        server should timeout. It is used when bootstrapping and also
        written to the configuration file (bootstrap)
  --conf-use-gr-notifications [ <VALUE>]
        Whether to enable handling of cluster state change GR
        notifications.
  --conf-target-cluster <VALUE>
        Router's target Cluster from the ClusterSet('current' or
        'primary').
  --conf-target-cluster-by-name <VALUE>
        Name of the target Cluster for the Router when bootstrapping
        against the ClusterSet
  -d <directory>, --directory <directory>
        Creates a self-contained directory for a new instance of the
        Router. (bootstrap)
  -a <path>, --extra-config <path>
        Read this file after configuration files are read from either
        default locations or from files specified by the --config
        option.
  --force
        Force reconfiguration of a possibly existing instance of the
        router. (bootstrap)
  --force-password-validation
        When autocreating database account do not use HASHED password -
        this is the default behavior now, this parameter is not needed,
        it is kept for backward compatibility.(bootstrap)
  -?, --help
        Display this help and exit.
  --master-key-reader <VALUE>
        The tool that can be used to read master key, it has to be used
        together with --master-key-writer. (bootstrap)
  --master-key-writer <VALUE>
        The tool that can be used to store master key, it has to be used
        together with --master-key-reader. (bootstrap)
  --name [ <name>]
        Gives a symbolic name for the router instance. (bootstrap)
  --password-retries [ <password-retries>]
        Number of the retries for generating the router's user password.
        (bootstrap)
  --pid-file <pidfile>
        Path and filename of pid file
  --read-timeout [ <VALUE>]
        The time in seconds after which reads from metadata server
        should timeout. It is used when bootstrapping and is also
        written to configuration file. (bootstrap)
  --report-host <report-host>
        Host name of this computer (it will be queried from OS if not
        provided). It is used as suffix (the part after '@') in Router's
        database user name; should match host name as seen by the
        cluster nodes (bootstrap)
  --server-ssl-ca <path>
        path name of the Certificate Authority (CA) certificate file in
        PEM format. Used when forwarding a client connection from router
        to a server.
  --server-ssl-capath <directory>
        path name of the directory that contains trusted SSL Certificate
        Authority (CA) certificate files in PEM format. Used when
        forwarding a client connection from router to a server.
  --server-ssl-cipher <VALUE>
        list of one or more colon separated cipher names. Used when
        forwarding client connection from router to a server.
  --server-ssl-crl <path>
        path name of the file containing certificate revocation lists in
        PEM format. Used when forwarding a client connection from router
        to a server.
  --server-ssl-crlpath <directory>
        path name of the directory that contains certificate
        revocation-list files in PEM format. Used when forwarding a
        client connection from router to a server.
  --server-ssl-curves <VALUE>
        list of one or more colon separated elliptic curve names. Used
        when forwarding a client connection from router to a server.
  --server-ssl-mode <ssl-mode>
        SSL mode to use when forwarding a client connection from router
        to a server. One of DISABLED, PREFERRED, REQUIRED or AS_CLIENT.
  --server-ssl-verify <verify-mode>
        verification mode when forwarding a client connection from
        router to server. One of DISABLED, VERIFY_CA or VERIFY_IDENTITY.
  --ssl-ca <path>
        Path to SSL CA file to verify server's certificate against when
        connecting to the metadata servers
  --ssl-capath <directory>
        Path to directory containing SSL CA files to verify server's
        certificate against when connecting to the metadata servers.
  --ssl-cert <path>
        Path to a SSL certificate, to be used if client certificate
        verification is required when connecting to the metadata
        servers.
  --ssl-cipher <ciphers>
        : separated list of SSL ciphers to allow when connecting to the
        metadata servers, if SSL is enabled.
  --ssl-crl <path>
        Path to SSL CRL file to use when connecting to metadata-servers
        and verifying their SSL certificate
  --ssl-crlpath <directory>
        Path to directory containing SSL CRL files to use when
        connecting to metadata-servers and verifying their SSL
        certificate.
  --ssl-key <path>
        Path to private key for client SSL certificate, to be used if
        client certificate verification is required when connecting to
        metadata-servers.
  --disable-rw-split
        Do not generate routing section for RW Split endpoint
  --disable-rest
        Disable REST web service for Router monitoring
  --https-port <https-port>
        HTTPS port for Router monitoring REST web service
  --ssl-mode <mode>
        SSL connection mode for use during bootstrap and normal
        operation, when connecting to the metadata server. Analogous to
        --ssl-mode in mysql client. One of
        DISABLED|PREFERRED|REQUIRED|VERIFY_CA|VERIFY_IDENTITY. Default =
        PREFERRED. (bootstrap)
  --strict
        Upgrades account verification failure warning into a fatal
        error. (bootstrap)
  --tls-version <versions>
        , separated list of TLS versions to request, if SSL is enabled.
  -u <username>, --user <username>
        Run the mysqlrouter as the user having the name user_name.
  -V, --version
        Display version information and exit.
  --conf-set-option <conf-set-option>
        Allows forcing selected option in the configuration file when
        bootstrapping (--conf-set-option=section_name.option_name=value)

# Examples

Bootstrap for use with InnoDB cluster into system-wide installation

    sudo mysqlrouter --bootstrap root@clusterinstance01 --user=mysqlrouter

Start router

    sudo mysqlrouter --user=mysqlrouter

Bootstrap for use with InnoDb cluster in a self-contained directory

    mysqlrouter --bootstrap root@clusterinstance01 -d myrouter

Start router

    myrouter/start.sh