'\" t .\" Title: mysqlrouter .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] .\" Generator: DocBook XSL Stylesheets v1.79.1 .\" Date: 03/11/2024 .\" Manual: MySQL Router .\" Source: MySQL 8.4 .\" Language: English .\" .TH "MYSQLROUTER" "1" "03/11/2024" "MySQL 8\&.4" "MySQL Router" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" mysqlrouter \- MySQL Router .SH "SYNOPSIS" .HP \w'\fBmysqlrouter\ [\fR\fB\fIoptions\fR\fR\fB]\fR\ 'u \fBmysqlrouter [\fR\fB\fIoptions\fR\fR\fB]\fR .SH "DESCRIPTION" .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} mysqlrouter Option Summaries .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} mysqlrouter Option Descriptions .RE .PP MySQL Router accepts command line options that are passed into \fBmysqlrouter\fR to affect its behavior, or to bootstrap router based on an InnoDB Cluster\&. .PP When starting Router, you can optionally use \fB\-\-config\fR to pass in the main configuration file\*(Aqs location (otherwise the default location is used) and \fB\-\-extra\-config\fR for an additional configuration file\&. .PP Bootstrapping command line options affect the generated files and directories that are used when starting MySQL Router\&. mysqlrouter Option Summariesmysqlrouter Option Descriptions .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-version\fR, \fB\-V\fR .TS allbox tab(:); lB l. T{ Command-Line Format T}:T{ --version , -V T} .TE .sp 1 Displays the version number and related information of the application, and exits\&. For example: .sp .if n \{\ .RS 4 .\} .nf $> \fBmysqlrouter \-\-version\fR MySQL Router v8\&.4\&.0 on Linux (64\-bit) (GPL community edition) .fi .if n \{\ .RE .\} .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-help\fR, \fB\-?\fR .TS allbox tab(:); lB l. T{ Command-Line Format T}:T{ --help , -? T} .TE .sp 1 Display help and informative information, and exit\&. .sp The \fB\-\-help\fR option has an added benefit\&. Along with the explanation of each of the options, the \fB\-\-help\fR option also displays the paths used to find the configuration file, and also several default paths\&. The following excerpt of the \fB\-\-help\fR output shows an example from a Ubuntu 16\&.04 machine: .sp .if n \{\ .RS 4 .\} .nf $> \fBmysqlrouter \-\-help\fR \&.\&.\&. 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] \&.\&.\&. .fi .if n \{\ .RE .\} .sp 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\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-bootstrap \fR\fB\fIURI\fR\fR, \fB\-B \fR\fB\fIURI\fR\fR .TS allbox tab(:); lB l lB l. T{ Command-Line Format T}:T{ --bootstrap URI, -B URI T} T{ Type T}:T{ String T} .TE .sp 1 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 \m[blue]\fBConnecting Using URI\-Like Connection Strings\fR\m[]\&\s-2\u[1]\d\s+2 for information on using a path to specify a server instance\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br While \fB\-\-bootstrap\fR accepts a URI for TCP/IP connections, using the \fB\-\-bootstrap\-socket\fR option with a local Unix domain socket name replaces the "host:port" part of the URI passed to the \fB\-\-bootstrap\fR option with the socket on the same machine\&. .sp .5v .RE 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 \fB\-\-directory\fR option to create self\-contained MySQL Router installations\&. .sp \fIURI\fR: a server instance from an InnoDB Cluster to fetch metadata information from\&. If the provided \fIURI\fR is a read\-only instance, MySQL Router automatically reconnects to a read\-write instance in the InnoDB Cluster so it can register MySQL Router\&. .sp If a configuration file already exists when you start MySQL Router with the \fB\-\-bootstrap\fR, 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\*(Aqs metadata server account is recreated, although with the same name\&. .sp 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 \fB\-\-extra\-config\fR 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\&. .sp 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 \fBMySQL user option\fR\&. .sp 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\*(Aqs configuration directory such as /etc or %PROGRAMDATA%\eMySQL\eMySQL Router\e\&. Executing mysqlrouter \-\-help will display this location\&. .sp The \fB\-\-user\fR 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 \fI\-\-user=root\fR\&. .sp The minimum GRANT permissions required to execute \fB\-\-bootstrap\fR are: .sp .if n \{\ .RS 4 .\} .nf GRANT CREATE USER ON *\&.* TO \*(Aq\fIbootstrapuser\fR\*(Aq@\*(Aq%\*(Aq WITH GRANT OPTION; GRANT SELECT, INSERT, UPDATE, DELETE, EXECUTE ON mysql_innodb_cluster_metadata\&.* TO \*(Aq\fIbootstrapuser\fR\*(Aq@\*(Aq%\*(Aq; GRANT SELECT ON mysql\&.user TO \*(Aq\fIbootstrapuser\fR\*(Aq@\*(Aq%\*(Aq; GRANT SELECT ON performance_schema\&.replication_group_members TO \*(Aq\fIbootstrapuser\fR\*(Aq@\*(Aq%\*(Aq; GRANT SELECT ON performance_schema\&.replication_group_member_stats TO \*(Aq\fIbootstrapuser\fR\*(Aq@\*(Aq%\*(Aq; GRANT SELECT ON performance_schema\&.global_variables TO \*(Aq\fIbootstrapuser\fR\*(Aq@\*(Aq%\*(Aq; .fi .if n \{\ .RE .\} .sp Using \fB\-\-bootstrap\fR 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 \fB\-\-bootstrap\fR by itself\&. .sp .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .B Table\ \&4.2.\ \&Conditions that affect default \-\-bootstrap values .TS allbox tab(:); lB lB. T{ Condition T}:T{ Description T} .T& l l l l l l l l l l. T{ \fB--conf-base-port\fR T}:T{ .PP Modifies generated \fBbind_port\fR values for each connection type. .PP By default, generated \fBbind_port\fR 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. .PP Setting \fB--conf-base-port\fR to 0 changes the default \fBbind_port\fR 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. T} T{ \fB--conf-use-sockets\fR T}:T{ Inserts \fBsocket\fR definitions for each connection type. T} T{ \fB--conf-skip-tcp\fR T}:T{ TCP/IP connection definitions are not defined. T} T{ \fB--directory\fR T}:T{ Affects all file paths, and also generates additional files. T} T{ Other T}:T{ This list is not exhaustive, other options and conditions also affect the generated values. T} .TE .sp 1 .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-bootstrap\-socket \fR\fB\fIsocket_name\fR\fR .TS allbox tab(:); lB l lB l. T{ Command-Line Format T}:T{ --bootstrap-socket socket_name T} T{ Platform Specific T}:T{ Linux T} .TE .sp 1 Used in conjunction with \fB\-\-bootstrap\fR to bootstrap using a local Unix domain socket instead of TCP/IP\&. The \fB\-\-bootstrap\-socket\fR value replaces the "host:port" part in the \fB\-\-bootstrap\fR 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 \fB\-\-bootstrap\fR\&. .sp This option is different than the \fB\-\-conf\-use\-sockets\fR command line option that sets the \fBsocket\fR configuration file option during the bootstrap process\&. .sp This option is not available on Windows\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-directory \fR\fB\fIdir_path\fR\fR, \fB\-d \fR\fB\fIdir_path\fR\fR .TS allbox tab(:); lB l lB l. T{ Command-Line Format T}:T{ --directory dir_path, -d dir_path T} T{ Type T}:T{ String T} .TE .sp 1 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\&. .sp The self\-contained directory structure for Router is: .sp .if n \{\ .RS 4 .\} .nf $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 .fi .if n \{\ .RE .\} .sp 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\&. .sp If \fB\-\-conf\-use\-sockets\fR is also enabled then the generated socket files are also added to this directory\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-master\-key\-writer\fR .TS allbox tab(:); lB l lB l. T{ Command-Line Format T}:T{ --master-key-writer file_path T} T{ Type T}:T{ String T} .TE .sp 1 This optional bootstrap option accepts a script that reads the master key from \fISTDIN\fR\&. It also uses the \fIROUTER_ID\fR environment variable set by MySQL Router before the \fBmaster\-key\-writer\fR script is called\&. .sp The \fBmaster\-key\-writer\fR and \fBmaster\-key\-reader\fR options must be used together, and using them means the \fBmaster_key_file\fR option must not be defined in mysqlrouter\&.conf as the master key is not written to the mysqlrouter\&.key master key file\&. .sp This is also written to the generated MySQL Router configuration file as the \fBmaster\-key\-writer\fR [DEFAULT] option\&. .sp Example contents of a bash script named writer\&.sh used in our example: .sp .if n \{\ .RS 4 .\} .nf #!/bin/bash KID_=$(keyctl padd user ${ROUTER_ID} @us <&0) .fi .if n \{\ .RE .\} .sp Example usage: .sp .if n \{\ .RS 4 .\} .nf $> mysqlrouter \-\-bootstrap=127\&.0\&.0\&.1:3310 \-\-master\-key\-reader=\&./reader\&.sh \-\-master\-key\-writer=\&./writer\&.sh .fi .if n \{\ .RE .\} .sp This also affects the generated mysqlrouter\&.conf, for example: .sp .if n \{\ .RS 4 .\} .nf [DEFAULT] \&.\&.\&. master\-key\-reader=reader\&.sh master\-key\-writer=writer\&.sh .fi .if n \{\ .RE .\} .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-master\-key\-reader\fR .TS allbox tab(:); lB l lB l. T{ Command-Line Format T}:T{ --master-key-reader file_path T} T{ Type T}:T{ String T} .TE .sp 1 This optional bootstrap option accepts a script that writes the master key to \fISTDOUT\fR\&. It also uses the \fIROUTER_ID\fR environment variable set by MySQL Router before the \fBmaster\-key\-reader\fR script is called\&. .sp The \fBmaster\-key\-reader\fR and \fBmaster\-key\-writer\fR options must be used together, and using them means the \fBmaster_key_file\fR 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\*(Aqs script\&. .sp This is also written to the generated MySQL Router configuration file as the \fBmaster\-key\-reader\fR [DEFAULT] option\&. .sp Example contents of a bash script named reader\&.sh used in our example: .sp .if n \{\ .RS 4 .\} .nf #!/bin/bash KID_=$(keyctl search @us user ${ROUTER_ID} 2>/dev/null) if [ ! \-z $KID_ ]; then keyctl pipe $KID_ fi .fi .if n \{\ .RE .\} .sp Example usage: .sp .if n \{\ .RS 4 .\} .nf $> mysqlrouter \-\-bootstrap=127\&.0\&.0\&.1:3310 \-\-master\-key\-reader=\&./reader\&.sh # Or, multiple hosts\-\-master\-key\-writer=\&./writer\&.sh .fi .if n \{\ .RE .\} .sp This also affects the generated mysqlrouter\&.conf, for example: .sp .if n \{\ .RS 4 .\} .nf [DEFAULT] \&.\&.\&. master\-key\-reader=reader\&.sh master\-key\-writer=writer\&.sh .fi .if n \{\ .RE .\} .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-strict\fR .TS allbox tab(:); lB l lB l. T{ Command-Line Format T}:T{ --strict T} T{ Type T}:T{ String T} .TE .sp 1 Enables strict mode, which for example causes the bootstrap \fB\-\-account\fR 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\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-account\fR .TS allbox tab(:); lB l lB l. T{ Command-Line Format T}:T{ --account username T} T{ Type T}:T{ String T} .TE .sp 1 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 \fB\-\-account\-create\fR option\&. .sp With \fB\-\-account\fR, 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\&. .sp Setting this option triggers a password prompt for this account regardless of whether the password is available in the keyring\&. .sp Bootstrapping without passing \fB\-\-account\fR does not recreate an existing MySQL server account\&. .sp 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 \fB\-\-strict\fR option is also used\&. Example required permissions: .sp .if n \{\ .RS 4 .\} .nf 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`@`%` .fi .if n \{\ .RE .\} .sp 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 \fIfoo\fR with the password \fIbar\fR\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-account\-create\fR .TS allbox tab(:); lB l lB l lB l lB l. T{ Command-Line Format T}:T{ --account-create behavior T} T{ Type T}:T{ String T} T{ Default Value T}:T{ if-not-exists T} T{ Valid Values T}:T{ .PP if-not-exists .PP always .PP never T} .TE .sp 1 Specify the account creation policy to help guard against accidentally bootstrapping with the wrong user account\&. Potential values are: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} if\-not\-exists (default): Bootstrap either way; reuse the account if it exists, otherwise create it\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} always: Only bootstrap if the account does not already exist; and create it\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} never: Only bootstrap if the account already exists; and reuse it\&. .RE .sp This option requires that the \fB\-\-account\fR option is also used, and that \fB\-\-account\-host\fR is not used\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-account\-host\fR .TS allbox tab(:); lB l lB l lB l. T{ Command-Line Format T}:T{ --account-host host_pattern T} T{ Type T}:T{ String T} T{ Default Value T}:T{ % T} .TE .sp 1 The host pattern used for accounts created by MySQL Router during the bootstrap process\&. This is optional and defaults to \*(Aq%\*(Aq\&. .sp Pass in this option multiple times to define multiple patterns, in which case the generated MySQL accounts use the same password\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br Router does not perform sanity checking and does not ensure that the pattern authorizes Router to connect\&. .sp .5v .RE .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br Bootstrapping reuses existing Router accounts by dropping and recreating the user, and this user recreation process applies to every host\&. .sp .5v .RE Examples: .sp .if n \{\ .RS 4 .\} .nf # 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 .fi .if n \{\ .RE .\} .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-conf\-use\-sockets\fR .TS allbox tab(:); lB l lB l. T{ Command-Line Format T}:T{ --conf-use-sockets T} T{ Platform Specific T}:T{ Linux T} .TE .sp 1 Enables local Unix domain sockets\&. .sp This option is used while bootstrapping, and enabling it adds the \fBsocket\fR option to the generated configuration file\&. .sp The name of the generated socket file depends on the \fBprotocol\fR 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\&. .sp This option is not available on Windows\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-conf\-use\-gr\-notifications\fR .TS allbox tab(:); lB l. T{ Command-Line Format T}:T{ --conf-use-gr-notifications T} .TE .sp 1 Enables the \fBuse_gr_notifications\fR [metadata_cache] option during bootstrap\&. When enabled, Router is asynchronously notified about most cluster changes\&. See \fBuse_gr_notifications\fR for more information\&. In addition, using this option sets \fBttl\fR=60 and \fBauth_cache_refresh_interval\fR=60\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-pid\-file \fR\fB\fIpath\fR\fR .TS allbox tab(:); lB l lB l. T{ Command-Line Format T}:T{ --pid-file path T} T{ Type T}:T{ String T} .TE .sp 1 Sets location of the PID file\&. This can be set in three different ways (in order of precedence): this \fB\-\-pid\-file\fR command\-line option, setting \fBpid_file\fR in Router\*(Aqs configuration file, or defining the ROUTER_PID environment variable\&. .sp If \fB\-\-bootstrap\fR 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\&. .sp If \fB\-\-bootstrap\fR 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\*(Aqt write the PID file\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-report\-host\fR .TS allbox tab(:); lB l lB l. T{ Command-Line Format T}:T{ --report-host hostname T} T{ Type T}:T{ String T} .TE .sp 1 Optionally define Router\*(Aqs hostname instead of relying on auto\-detection to determine the externally visible hostname registered to metadata during the bootstrap process\&. .sp 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\&. .sp 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\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-conf\-skip\-tcp\fR .TS allbox tab(:); lB l lB l. T{ Command-Line Format T}:T{ --conf-skip-tcp T} T{ Platform Specific T}:T{ Linux T} .TE .sp 1 Skips configuration of a TCP port for listening to incoming connections\&. See also \fB\-\-conf\-use\-sockets\fR\&. .sp This option is not available on Windows\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-conf\-base\-port \fR\fB\fIport_num\fR\fR .TS allbox tab(:); lB l lB l. T{ Command-Line Format T}:T{ --conf-base-port port_num T} T{ Type T}:T{ Integer T} .TE .sp 1 Base (first) value used for the listening TCP ports by setting \fBbind_port\fR for each bootstrapped route\&. .sp 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\&. .sp Setting \fB\-\-conf\-base\-port\fR to 0 changes the default \fBbind_port\fR 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\&. .sp Example usage: .sp .if n \{\ .RS 4 .\} .nf \fB# Example without \-\-conf\-base\-port\fR $> mysqlrouter \-\-bootstrap root@localhost:3310 \&.\&.\&. Classic MySQL protocol connections to cluster \*(AqdevCluster\*(Aq: \- Read/Write Connections: localhost:6446 \- Read/Only Connections: localhost:6447 X protocol connections to cluster \*(AqdevCluster\*(Aq: \- Read/Write Connections: localhost:6448 \- Read/Only Connections: localhost:6449 \fB# Example demonstrating \-\-conf\-base\-port set to 0\fR $> mysqlrouter \-\-bootstrap root@localhost:3310 \-\-conf\-base\-port 0 \&.\&.\&. Classic MySQL protocol connections to cluster \*(AqdevCluster\*(Aq: \- Read/Write Connections: localhost:6446 \- Read/Only Connections: localhost:6447 X protocol connections to cluster \*(AqdevCluster\*(Aq: \- Read/Write Connections: localhost:64460 \- Read/Only Connections: localhost:64470 .fi .if n \{\ .RE .\} .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-conf\-bind\-address \fR\fB\fIaddress\fR\fR .TS allbox tab(:); lB l lB l lB l. T{ Command-Line Format T}:T{ --conf-bind-address address T} T{ Type T}:T{ String T} T{ Default Value T}:T{ 0.0.0.0 T} .TE .sp 1 Modifies the \fBbind_address\fR value set by \fB\-\-bootstrap\fR in the generated Router configuration file\&. By default, bootstrapping sets \fBbind_address=0\&.0\&.0\&.0\fR for each route, and this option changes that value\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br The default \fBbind_address\fR value is \fI127\&.0\&.0\&.1\fR if \fBbind_address\fR is not defined\&. .sp .5v .RE .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-read\-timeout \fR\fB\fInum_seconds\fR\fR .TS allbox tab(:); lB l lB l lB l. T{ Command-Line Format T}:T{ --read-timeout num_seconds T} T{ Type T}:T{ Integer T} T{ Default Value T}:T{ 30 T} .TE .sp 1 Number of seconds before read operations to a metadata server are considered timed out\&. .sp This affects read operations during both the bootstrap process, and also affects normal MySQL Router operations by setting the associated \fBread_timeout\fR option in the generated mysqlrouter\&.conf\&. .sp This option is set under the [DEFAULT] namespace\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-connect\-timeout \fR\fB\fInum_seconds\fR\fR .TS allbox tab(:); lB l lB l lB l. T{ Command-Line Format T}:T{ --connect-timeout num_seconds T} T{ Type T}:T{ Integer T} T{ Default Value T}:T{ 30 T} .TE .sp 1 Number of seconds before connection attempts to a metadata server are considered timed out\&. .sp This affects connections during both the bootstrap process, and also affects normal MySQL Router operations by setting the associated \fBconnect_timeout\fR option in the generated mysqlrouter\&.conf\&. .sp There are two \fIconnect_timeout\fR variants\&. The metadata server variant is defined under the [DEFAULT] namespace, while the MySQL server variant is defined under the [routing] namespace\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-user {\fR\fB\fIuser_name\fR\fR\fB|\fR\fB\fIuser_id\fR\fR\fB}\fR, \fB\-u {\fR\fB\fIuser_name\fR\fR\fB|\fR\fB\fIuser_id\fR\fR\fB}\fR .TS allbox tab(:); lB l lB l lB l. T{ Command-Line Format T}:T{ --user {user_name|user_id}, -u {user_name|user_id} T} T{ Platform Specific T}:T{ Linux T} T{ Type T}:T{ String T} .TE .sp 1 Run \fBmysqlrouter\fR as the user having the name \fIuser_name\fR or the numeric user ID \fIuser_id\fR\&. \(lqUser\(rq 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 \fBuser\fR option\&. .sp This system \fBuser\fR is defined in the configuration file under the [DEFAULT] namespace\&. For additional information, see the \fBuser\fR option\*(Aqs documentation that \fB\-\-user\fR configures\&. .sp The \fB\-\-user\fR 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 \fI\-\-user=root\fR\&. .sp This option is not available on Windows\&. .sp .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-name \fR\fB\fIrouter_name\fR\fR .TS allbox tab(:); lB l lB l lB l. T{ Command-Line Format T}:T{ --name router_name T} T{ Type T}:T{ String T} T{ Default Value T}:T{ system T} .TE .sp 1 On initial bootstrap, specifies a symbolic name for a self\-contained Router instance\&. This option is optional, and is used with \fB\-\-directory\fR\&. When creating multiple instances, the names must be unique\&. .sp .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-force\-password\-validation\fR .TS allbox tab(:); lB l lB l. T{ Command-Line Format T}:T{ --force-password-validation T} T{ Platform Specific T}:T{ Linux T} .TE .sp 1 By default, MySQL Router skips the MySQL Server\*(Aqs 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\&. .sp This option ensures that password validation (validate_password) is not skipped for generated passwords, and it is disabled by default\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-password\-retries \fR\fB\fInum_retries\fR\fR .TS allbox tab(:); lB l lB l lB l lB l lB l. T{ Command-Line Format T}:T{ --password-retries num_retries T} T{ Type T}:T{ Integer T} T{ Default Value T}:T{ 20 T} T{ Minimum Value T}:T{ 1 T} T{ Maximum Value T}:T{ 10000 T} .TE .sp 1 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\&. .sp 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 \fB\-\-force\-password\-validation\fR is set to true and/or the mysql_native_password MySQL Server plugin is disabled (this plugin allows bypassing validation)\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-force\fR .TS allbox tab(:); lB l. T{ Command-Line Format T}:T{ --force T} .TE .sp 1 Force a reconfiguration over a previously configured router instance on the host\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-ssl\-mode \fR\fB\fImode\fR\fR .TS allbox tab(:); lB l lB l lB l lB l. T{ Command-Line Format T}:T{ --ssl-mode mode T} T{ Type T}:T{ String T} T{ Default Value T}:T{ PREFERRED T} T{ Valid Values T}:T{ .PP PREFERRED .PP DISABLED .PP REQUIRED .PP VERIFY_CA .PP VERIFY_IDENTITY T} .TE .sp 1 SSL connection mode for use during bootstrap and normal operation when connecting to the metadata server\&. Analogous to \fB\-\-ssl\-mode\fR in the \fBmysql\fR client\&. .sp During bootstrap, all connections to metadata servers made by the Router will use the SSL options specified\&. If \fBssl_mode\fR 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\&. .sp When set to a value other than the default (PREFERRED), an \fBssl_mode\fR entry is inserted under the [metadata_cache] section in the generated configuration file\&. .sp Available values are DISABLED, PREFERRED, REQUIRED, VERIFY_CA, and VERIFY_IDENTITY\&. PREFERRED is the default value\&. As with the \fBmysql\fR client, this value is case\-insensitive\&. .sp The configuration file equivalent is documented separately at \fBssl_mode\fR\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-ssl\-cert \fR\fB\fIfile_path\fR\fR .TS allbox tab(:); lB l lB l lB l. T{ Command-Line Format T}:T{ --ssl-cert file_path T} T{ Type T}:T{ String T} T{ Default Value T}:T{ T} .TE .sp 1 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\*(Aqs \fB\-\-ssl\-cert\fR option\&. .sp Like \fB\-\-ssl\-key\fR, 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\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-ssl\-key \fR\fB\fIfile_path\fR\fR .TS allbox tab(:); lB l lB l. T{ Command-Line Format T}:T{ --ssl-key file_path T} T{ Type T}:T{ String T} .TE .sp 1 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\*(Aqs \fB\-\-ssl\-key\fR option\&. .sp Like \fB\-\-ssl\-cert\fR, 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\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-ssl\-cipher \fR\fB\fIciphers\fR\fR .TS allbox tab(:); lB l lB l lB l. T{ Command-Line Format T}:T{ --ssl-cipher ciphers T} T{ Type T}:T{ String T} T{ Default Value T}:T{ T} .TE .sp 1 A colon\-separated (":") list of SSL ciphers to allow, if SSL is enabled\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-tls\-version \fR\fB\fIversions\fR\fR .TS allbox tab(:); lB l lB l lB l. T{ Command-Line Format T}:T{ --tls-version versions T} T{ Type T}:T{ String T} T{ Default Value T}:T{ T} .TE .sp 1 A comma\-separated (",") list of TLS versions to request, if SSL is enabled\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-ssl\-ca \fR\fB\fIfile_path\fR\fR .TS allbox tab(:); lB l lB l lB l. T{ Command-Line Format T}:T{ --ssl-ca file_path T} T{ Type T}:T{ String T} T{ Default Value T}:T{ T} .TE .sp 1 Path to the SSL CA file to verify a server\*(Aqs certificate against\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-ssl\-capath \fR\fB\fIdir_path\fR\fR .TS allbox tab(:); lB l lB l lB l. T{ Command-Line Format T}:T{ --ssl-capath dir_path T} T{ Type T}:T{ String T} T{ Default Value T}:T{ T} .TE .sp 1 Path to directory containing the SSL CA files to verify a server\*(Aqs certificate against\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-ssl\-crl \fR\fB\fIfile_path\fR\fR .TS allbox tab(:); lB l lB l lB l. T{ Command-Line Format T}:T{ --ssl-crl file_path T} T{ Type T}:T{ String T} T{ Default Value T}:T{ T} .TE .sp 1 Path to the SSL CRL file to use when verifying a server\*(Aqs certificate\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-ssl\-crlpath \fR\fB\fIdir_path\fR\fR .TS allbox tab(:); lB l lB l lB l. T{ Command-Line Format T}:T{ --ssl-crlpath dir_path T} T{ Type T}:T{ String T} T{ Default Value T}:T{ T} .TE .sp 1 Path to the directory containing SSL CRL files to use when verifying a server\*(Aqs certificate\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-client\-ssl\-mode \fR\fB\fImode\fR\fR .TS allbox tab(:); lB l lB l lB l lB l. T{ Command-Line Format T}:T{ --client-ssl-mode T} T{ Type T}:T{ String T} T{ Default Value T}:T{ PREFERRED T} T{ Valid Values T}:T{ .PP PREFERRED .PP DISABLED .PP PASSTHROUGH .PP REQUIRED T} .TE .sp 1 SSL connection mode for use during bootstrap and normal operation when connecting between MySQL Router and client\&. .sp During bootstrap, all connections to clients made by the Router will use the SSL options specified\&. If \fBclient_ssl_mode\fR is not specified in the configuration, it defaults to PREFERRED\&. .sp The configuration file equivalent is documented separately at \fBclient_ssl_mode\fR\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-client\-ssl\-cert \fR\fB\fIfile_path\fR\fR .TS allbox tab(:); lB l lB l lB l. T{ Command-Line Format T}:T{ --client-ssl-cert file_path T} T{ Type T}:T{ String T} T{ Default Value T}:T{ T} .TE .sp 1 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\&. .sp Like \fB\-\-client\-ssl\-key\fR, 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\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fBclient\-ssl\-curves\fR .TS allbox tab(:); lB l lB l. T{ Command-Line Format T}:T{ --client-ssl-curves T} T{ Type T}:T{ String T} .TE .sp 1 Defaults to a secure list of SSL curves\&. Format this string as a colon separated list of curve names\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-client\-ssl\-key \fR\fB\fIfile_path\fR\fR .TS allbox tab(:); lB l lB l. T{ Command-Line Format T}:T{ --client-ssl-key file_path T} T{ Type T}:T{ String T} .TE .sp 1 The path name of the SSL private key file in PEM format\&. This is used to facilitate client\-side authentication during the bootstrap process\&. .sp Like \fB\-\-client\-ssl\-cert\fR, 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\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-client\-ssl\-cipher \fR\fB\fIciphers\fR\fR .TS allbox tab(:); lB l lB l. T{ Command-Line Format T}:T{ --client-ssl-cipher T} T{ Type T}:T{ String T} .TE .sp 1 A colon\-separated (":") list of SSL ciphers to allow, if SSL is enabled\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fBclient\-ssl\-dh\-params\fR .TS allbox tab(:); lB l lB l. T{ Command-Line Format T}:T{ --client-ssl-dh-params=filepath T} T{ Type T}:T{ String T} .TE .sp 1 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\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-client\-ssl\-ca \fR\fB\fIfile_path\fR\fR .TS allbox tab(:); lB l lB l lB l. T{ Command-Line Format T}:T{ --client-ssl-ca file_path T} T{ Type T}:T{ String T} T{ Default Value T}:T{ T} .TE .sp 1 Path to the SSL CA file to verify a server\*(Aqs certificate against\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-client\-ssl\-capath \fR\fB\fIdir_path\fR\fR .TS allbox tab(:); lB l lB l lB l. T{ Command-Line Format T}:T{ --client-ssl-capath dir_path T} T{ Type T}:T{ String T} T{ Default Value T}:T{ T} .TE .sp 1 Path to directory containing the SSL CA files to verify a server\*(Aqs certificate against\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-client\-ssl\-crl \fR\fB\fIfile_path\fR\fR .TS allbox tab(:); lB l lB l lB l. T{ Command-Line Format T}:T{ --client-ssl-crl file_path T} T{ Type T}:T{ String T} T{ Default Value T}:T{ T} .TE .sp 1 Path to the SSL CRL file to use when verifying a server\*(Aqs certificate\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-client\-ssl\-crlpath \fR\fB\fIdir_path\fR\fR .TS allbox tab(:); lB l lB l lB l. T{ Command-Line Format T}:T{ --client-ssl-crlpath dir_path T} T{ Type T}:T{ String T} T{ Default Value T}:T{ T} .TE .sp 1 Path to the directory containing SSL CRL files to use when verifying a server\*(Aqs certificate\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-server\-ssl\-mode \fR\fB\fImode\fR\fR .TS allbox tab(:); lB l lB l lB l lB l. T{ Command-Line Format T}:T{ --server-ssl-mode T} T{ Type T}:T{ String T} T{ Default Value T}:T{ PREFERRED T} T{ Valid Values T}:T{ .PP AS_CLIENT .PP DISABLED .PP PREFERRED .PP REQUIRED T} .TE .sp 1 SSL connection mode for use during bootstrap and normal operation when connecting between MySQL Router and server\&. .sp During bootstrap, all connections to servers made by the Router will use the SSL options specified\&. If \fBserver_ssl_mode\fR is not specified in the configuration, it defaults to PREFERRED\&. .sp The configuration file equivalent is documented separately at \fBserver_ssl_mode\fR\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-server\-ssl\-cipher \fR\fB\fIciphers\fR\fR .TS allbox tab(:); lB l lB l. T{ Command-Line Format T}:T{ --server-ssl-cipher T} T{ Type T}:T{ String T} .TE .sp 1 A colon\-separated (":") list of SSL ciphers to allow, if SSL is enabled\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-server\-ssl\-ca \fR\fB\fIfile_path\fR\fR .TS allbox tab(:); lB l lB l lB l. T{ Command-Line Format T}:T{ --server-ssl-ca file_path T} T{ Type T}:T{ String T} T{ Default Value T}:T{ T} .TE .sp 1 Path to the SSL CA file to verify a server\*(Aqs certificate against\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-server\-ssl\-capath \fR\fB\fIdir_path\fR\fR .TS allbox tab(:); lB l lB l lB l. T{ Command-Line Format T}:T{ --server-ssl-capath dir_path T} T{ Type T}:T{ String T} T{ Default Value T}:T{ T} .TE .sp 1 Path to directory containing the SSL CA files to verify a server\*(Aqs certificate against\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-server\-ssl\-crl \fR\fB\fIfile_path\fR\fR .TS allbox tab(:); lB l lB l lB l. T{ Command-Line Format T}:T{ --server-ssl-crl file_path T} T{ Type T}:T{ String T} T{ Default Value T}:T{ T} .TE .sp 1 Path to the SSL CRL file to use when verifying a server\*(Aqs certificate\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-server\-ssl\-crlpath \fR\fB\fIdir_path\fR\fR .TS allbox tab(:); lB l lB l lB l. T{ Command-Line Format T}:T{ --server-ssl-crlpath dir_path T} T{ Type T}:T{ String T} T{ Default Value T}:T{ T} .TE .sp 1 Path to the directory containing SSL CRL files to use when verifying a server\*(Aqs certificate\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fBserver\-ssl\-curves\fR .TS allbox tab(:); lB l lB l. T{ Command-Line Format T}:T{ --server-ssl-curves T} T{ Type T}:T{ String T} .TE .sp 1 Defaults to a secure list of SSL curves\&. Format this string as a colon separated list of curve names\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-server\-ssl\-verify \fR\fB\fIstring\fR\fR .TS allbox tab(:); lB l lB l lB l lB l. T{ Command-Line Format T}:T{ --server-ssl-verify T} T{ Type T}:T{ String T} T{ Default Value T}:T{ DISABLED T} T{ Valid Values T}:T{ .PP DISABLED .PP VERIFY_CA .PP VERIFY_IDENTITY T} .TE .sp 1 Verification of the SSL certificates presented to the router by the server .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} DISABLED: the connection fails if the server does not provide a certificate in the handshake\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} VERIFY_CA: the connection fails if the server\*(Aqs certificate does not match a CA trusted by MySQL Router\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} VERIFY_IDENTITY: the connection fails if the server\*(Aqs certificate does not match a CA trusted by MySQL Router, or the server certificate\*(Aqs subject does not match the hostname or IP address MySQL Router connected to\&. .RE .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-config \fR\fB\fIfile_path\fR\fR, \fB\-c \fR\fB\fIfile_path\fR\fR .TS allbox tab(:); lB l. T{ Command-Line Format T}:T{ --config file_path, -c file_path T} .TE .sp 1 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\&. .sp When used with \fB\-\-bootstrap\fR, and if the configuration file already exists, a copy of the current file is saved with a \fI\&.bak\fR extension if the generated configuration file contents is different than the original\&. Existing \fI\&.bak\fR files are overwritten\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-extra\-config \fR\fB\fIfile_path\fR\fR, \fB\-a \fR\fB\fIfile_path\fR\fR .TS allbox tab(:); lB l. T{ Command-Line Format T}:T{ --extra-config file_path, -a file_path T} .TE .sp 1 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\&. .sp 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\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-install\-service\fR .TS allbox tab(:); lB l lB l. T{ Command-Line Format T}:T{ --install-service [service_name] T} T{ Platform Specific T}:T{ Windows T} .TE .sp 1 Install Router as a Windows service that automatically starts when Windows starts\&. The service name defaults to \fIMySQLRouter\fR\&. .sp This installation process does not validate configuration files passed in via \fB\-\-config\fR\&. .sp This option is only available on Windows\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-install\-service\-manual\fR .TS allbox tab(:); lB l lB l. T{ Command-Line Format T}:T{ --install-service-manual [service_name] T} T{ Platform Specific T}:T{ Windows T} .TE .sp 1 Install MySQL Router as a Windows service that can be manually started\&. The service name defaults to \fIMySQLRouter\fR\&. .sp This option is only available on Windows\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-remove\-service\fR .TS allbox tab(:); lB l lB l. T{ Command-Line Format T}:T{ --remove-service [service_name] T} T{ Platform Specific T}:T{ Windows T} .TE .sp 1 Remove the Router Windows service; service name defaults to MySQLRouter\&. .sp This option is only available on Windows\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-service\fR .TS allbox tab(:); lB l lB l. T{ Command-Line Format T}:T{ --service T} T{ Platform Specific T}:T{ Windows T} .TE .sp 1 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\&. .sp This option is only available on Windows\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-update\-credentials\-section\fR .TS allbox tab(:); lB l lB l. T{ Command-Line Format T}:T{ --update-credentials-section section_name T} T{ Platform Specific T}:T{ Windows T} .TE .sp 1 This option is only available on Windows, and refers to its password vault\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-conf\-target\-cluster\fR .TS allbox tab(:); lB l lB l lB l. T{ Command-Line Format T}:T{ --conf-target-cluster value T} T{ Type T}:T{ String T} T{ Valid Values T}:T{ .PP current .PP primary T} .TE .sp 1 Sets the \fBtarget_cluster\fR metadata MySQL Router option\&. Accepts one of the following strings: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} current: sets \fBtarget_cluster\fR to the cluster containing the node being bootstrapped against\&. It defines it as the cluster\*(Aqs UUID value\&. .sp If this is also the Primary, it does not dynamically follow role changes like the \fBprimary\fR does; instead it remains static\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} primary: sets \fBtarget_cluster\fR to the primary cluster, including when it changes at runtime\&. .RE .sp See also \fB\-\-config\-target\-cluster\-by\-name\fR, which sets the \fBtarget_cluster\fR to a specific static cluster name\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br Bootstrapping against a \m[blue]\fBClusterSet\fR\m[]\&\s-2\u[2]\d\s+2 requires the \fBcluster_type\fR Router configuration option set to \fIgr\fR\&. .sp .5v .RE .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-conf\-set\-option\fR .TS allbox tab(:); lB l lB l. T{ Command-Line Format T}:T{ --conf-set-option section_name[:optional_section_key].option=value T} T{ Type T}:T{ String T} .TE .sp 1 Sets a value for a generated configuration option during bootstrap; this can set a value for any bootstrapped option, for example: .sp .if n \{\ .RS 4 .\} .nf $> mysqlrouter \-B 127\&.0\&.0\&.1:5000 \e \-\-directory=dir1 \e \-\-conf\-set\-option=logger\&.level=debug \e \-\-conf\-set\-option=routing:test_rw\&.max_connect_errors=0 \e \-\-conf\-set\-option=routing:test_ro\&.max_connect_errors=0 .fi .if n \{\ .RE .\} .sp Those commands alter the default values for those specific options by defining them as such: .sp .if n \{\ .RS 4 .\} .nf [logger] level=debug [routing:test_rw] \&.\&.\&. max_connect_errors=0 \&.\&.\&. [routing:test_ro] \&.\&.\&. max_connect_errors=0 \&.\&.\&. .fi .if n \{\ .RE .\} .sp \fB\-\-conf\-set\-option\fR definitions take precedence over option specific parameters to set specific value\&. For example, if both \fB\-\-connect\-timeout=X\fR and \fB\-\-conf\-set\-option=DEFAULT\&.connect_timeout=Y\fR are specified when bootstrapping, the \fBconnect_timeout\fR is set to \fIY\fR in the generated configuration file\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-conf\-target\-cluster\-by\-name\fR .TS allbox tab(:); lB l lB l. T{ Command-Line Format T}:T{ --conf-target-cluster-by-name clusterName T} T{ Type T}:T{ String T} .TE .sp 1 Sets the \fBtarget_cluster\fR metadata MySQL Router option to a specific cluster name\&. .sp Or, instead use \fB\-\-conf\-target\-cluster\fR to assign a dynamic cluster type, such as primary\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-remove\-credentials\-section \fR\fB\fIsection_name\fR\fR .TS allbox tab(:); lB l lB l. T{ Command-Line Format T}:T{ --remove-credentials-section section_name T} T{ Platform Specific T}:T{ Windows T} .TE .sp 1 Remove the credentials for a given section\&. .sp This option is only available on Windows, and refers to its password vault\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-clear\-all\-credentials\fR .TS allbox tab(:); lB l lB l. T{ Command-Line Format T}:T{ --clear-all-credentials T} T{ Platform Specific T}:T{ Windows T} .TE .sp 1 Clear the password vault by removing all credentials stored in it\&. .sp This option is only available on Windows, and refers to its password vault\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-disable\-rest\fR .TS allbox tab(:); lB l. T{ Command-Line Format T}:T{ --disable-rest T} .TE .sp 1 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\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fB\-\-https\-port\fR .TS allbox tab(:); lB l lB l lB l lB l lB l. T{ Command-Line Format T}:T{ --https-port value T} T{ Type T}:T{ Integer T} T{ Default Value T}:T{ 8443 T} T{ Minimum Value T}:T{ 1 T} T{ Maximum Value T}:T{ 65535 T} .TE .sp 1 Optionally define the HTTP server\*(Aqs \fBport\fR 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\&. .RE .SH "COPYRIGHT" .br .PP Copyright \(co 2006, 2024, Oracle and/or its affiliates. .PP 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. .PP 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. .PP 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/. .sp .SH "NOTES" .IP " 1." 4 Connecting Using URI-Like Connection Strings .RS 4 \%https://dev.mysql.com/doc/refman/8.4/en/connecting-using-uri-or-key-value-pairs.html#connecting-using-uri .RE .IP " 2." 4 ClusterSet .RS 4 \%https://dev.mysql.com/doc/mysql-shell/8.4/en/innodb-clusterset.html .RE .SH AUTHOR Oracle Corporation (http://dev.mysql.com/).