Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MYSQLROUTER(1)			 MySQL Router			MYSQLROUTER(1)

NAME
       mysqlrouter - MySQL Router

SYNOPSIS
       mysqlrouter [options]

DESCRIPTION
       o   mysqlrouter Option Summaries

       o   mysqlrouter Option Descriptions

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

       When starting Router, you can optionally	use --config to	pass in	the
       main configuration file's location (otherwise the default location is
       used) and --extra-config	for an additional configuration	file.

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

       o   --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.21 on Linux (64-bit) (GPL community edition)

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

       o   --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 URI-Like Connection Strings[1]	for information	on using a
	   path	to specify a server instance.

	       Note
	       While --bootstrap accepts a URI for TCP/IP connections, using
	       the --bootstrap-socket option with a local Unix domain socket
	       name replaces the "host:port" part of the URI passed to the
	       --bootstrap option with the socket on the same machine.
	   By default, the bootstrap process performs a	system-wide
	   configuration of MySQL Router. Only one instance of MySQL Router
	   can be configured for system-wide operation.	The system instance of
	   MySQL Router	has a router_name of "system". If additional instances
	   are desired,	use the	--directory option to create self-contained
	   MySQL Router	installations.

	   URI:	a server instance from an InnoDB cluster to fetch metadata
	   information from. If	the provided URI is a read-only	instance,
	   MySQL Router	automatically reconnects to a read-write instance in
	   the InnoDB cluster so it can	register MySQL Router.

	   If a	configuration file already exists when you start MySQL Router
	   with	the --bootstrap, the existing router_id	in that	file is
	   reused, and a reconfiguration process occurs. The configuration
	   file	is regenerated from scratch and	the MySQL Router's metadata
	   server account is recreated,	although with the same name.

	   During the reconfiguration process, all changes made	to an existing
	   configuration file are discarded. To	customize a configuration file
	   and still retain the	ability	of automatic reconfiguration
	   (bootstrapping), you	can use	the --extra-config command line	option
	   to specify an additional configuration file that is read after the
	   main	configuration file. These configuration	options	are used
	   because this	extra configuration file is loaded after the main
	   configuration file.

	   The bootstrap process creates a new MySQL user account with a
	   randomly generated password to use by that specific MySQL Router
	   instance. This account is used by MySQL Router when connecting to
	   the metadata	server and InnoDB cluster to fetch information about
	   its current state. For detailed information about this user
	   including how its password is stored	and the	MySQL privilege	it
	   requires, see documentation for the MySQL user option.

	   The generated configuration file is named mysqlrouter.conf, and its
	   location depends on the type	of instance being configured, the
	   system, and the package. For	system-wide installations, the
	   generated configuration file	is added to the	system's configuration
	   directory such as /etc or %PROGRAMDATA%\MySQL\MySQL Router\.
	   Executing mysqlrouter --help	will display this location.

	   The --user option is	required if executing a	bootstrap with a super
	   user	(uid=0). Although not recommended, forcing the super user is
	   possible by passing its name	as an argument such as --user=root.

	       Note
	       The minimum GRANT permissions required to execute --boostrap
	       are:

		   GRANT CREATE	USER ON	*.* TO 'bootstrapuser'@'%' WITH	GRANT OPTION;
		   GRANT SELECT, INSERT, UPDATE, DELETE, EXECUTE ON mysql_innodb_cluster_metadata.* TO 'bootstrapuser'@'%';
		   GRANT SELECT	ON mysql.user TO 'bootstrapuser'@'%';
		   GRANT SELECT	ON performance_schema.replication_group_members	TO 'bootstrapuser'@'%';
		   GRANT SELECT	ON performance_schema.replication_group_member_stats TO	'bootstrapuser'@'%';
		   GRANT SELECT	ON performance_schema.global_variables TO 'bootstrapuser'@'%';
	   Using --bootstrap adds default values to the	generated MySQL	Router
	   configuration file, and some	of these default values	depend on
	   other conditions. Listed below are some of the conditions that
	   affect the generated	default	values,	where default is defined by
	   passing in --bootstrap by itself.

	   Table 4.2. Conditions that affect default --bootstrap values
	   +-------------------+----------------------------+
	   |Condition	       | Description		    |
	   +-------------------+----------------------------+
	   |--conf-base-port   |			    |
	   |		       |	    Modifies	    |
	   |		       |	    generated	    |
	   |		       |	    bind_port	    |
	   |		       |	    values for each |
	   |		       |	    connection	    |
	   |		       |	    type.	    |
	   |		       |			    |
	   |		       |	    By default,	    |
	   |		       |	    generated	    |
	   |		       |	    bind_port	    |
	   |		       |	    values are as   |
	   |		       |	    follows: For    |
	   |		       |	    the	classic	    |
	   |		       |	    protocol, Read- |
	   |		       |	    Write uses 6446 |
	   |		       |	    and	Read-Only   |
	   |		       |	    uses 6447, and  |
	   |		       |	    for	the X	    |
	   |		       |	    protocol Read-  |
	   |		       |	    Write uses	    |
	   |		       |	    64460 and Read- |
	   |		       |	    Only uses	    |
	   |		       |	    64470.	    |
	   +-------------------+----------------------------+
	   |--conf-use-sockets | Inserts socket	definitions |
	   |		       | for each connection type.  |
	   +-------------------+----------------------------+
	   |--conf-skip-tcp    | TCP/IP	connection	    |
	   |		       | definitions are not	    |
	   |		       | defined.		    |
	   +-------------------+----------------------------+
	   |--directory	       | Affects all file paths,    |
	   |		       | and also generates	    |
	   |		       | additional files.	    |
	   +-------------------+----------------------------+
	   |Other	       | This list is not	    |
	   |		       | exhaustive, other options  |
	   |		       | and conditions	also affect |
	   |		       |		 the	    |
	   |		       | generated values.	    |
	   +-------------------+----------------------------+

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

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

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

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

       o   --strict

	   +--------------------+----------+
	   |Property		| Value	   |
	   +--------------------+----------+
	   |Command-Line Format	| --strict |
	   +--------------------+----------+
	   |Introduced		| 8.0.19   |
	   +--------------------+----------+
	   |Type		| String   |
	   +--------------------+----------+
	   Enables strict mode,	which for example causes the bootstrap
	   --account user verification check to	stop the bootstrap process
	   rather than only emit a warning and continue	if the supplied	user
	   does	not pass the check.

       o   --account

	   +--------------------+--------------------+
	   |Property		| Value		     |
	   +--------------------+--------------------+
	   |Command-Line Format	| --account username |
	   +--------------------+--------------------+
	   |Introduced		| 8.0.19	     |
	   +--------------------+--------------------+
	   |Type		| String	     |
	   +--------------------+--------------------+
	   A bootstrap option to specify the MySQL user	to use,	which either
	   reuses an existing MySQL user account or creates one; behavior
	   controlled by the related --account-create option.

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

	   Setting this	option triggers	a password prompt for this account
	   regardless of whether the password is available in the keyring.

	   Bootstrapping without passing in --account does not recreate	an
	   existing MySQL server account. Prior	to MySQL Router	8.0.18,
	   bootstrapping would DROP the	existing user and reCREATE it.

	   Using this option assumes the user has sufficient access rights for
	   Router because the bootstrap	process	does not attempt to add
	   missing grants to existing accounts.	The bootstrap process does
	   verify the permissions and outputs information to the console of
	   the failed check. The bootstrap process continues despite these
	   failed checks unless	the optional --strict option is	also used.
	   Example required permissions:

	       GRANT SELECT ON mysql_innodb_cluster_metadata.* TO `theuser`
	       GRANT SELECT ON performance_schema.replication_group_members TO `theuser`
	       GRANT SELECT ON performance_schema.replication_group_member_stats TO `theuser`

	   A password is not accepted from the command-line. For example,
	   passing in "foo:bar"	assumes	"foo:bar" is the desired username
	   rather than user foo	with the password bar.

       o   --account-create

	   +--------------------+---------------------------+
	   |Property		| Value			    |
	   +--------------------+---------------------------+
	   |Command-Line Format	| --account-create behavior |
	   +--------------------+---------------------------+
	   |Introduced		| 8.0.19		    |
	   +--------------------+---------------------------+
	   |Type		| String		    |
	   +--------------------+---------------------------+
	   |Default Value	| if-not-exists		    |
	   +--------------------+---------------------------+
	   |Valid Values	|			    |
	   |			|	     if-not-exists  |
	   |			|			    |
	   |			|	     always	    |
	   |			|			    |
	   |			|	     never	    |
	   +--------------------+---------------------------+
	   Specify the account creation	policy to help guard against
	   accidentally	bootstrapping with the wrong user account. Potential
	   values are:

	   o   if-not-exists (default):	Bootstrap either way; reuse the
	       account if it exists, otherwise create it.

	   o   always: Only bootstrap if the account does not already exist;
	       and create it.

	   o   never: Only bootstrap if	the account already exists; and	reuse
	       it.

	   This	option requires	that the --account option is also used,	and
	   that	--account-host is not used.

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

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

       o   --conf-use-gr-notifications

	   +--------------------+----------------+
	   |Property		| Value		 |
	   +--------------------+----------------+
	   |Command-Line Format	| --conf-use-gr- |
	   |			| notifications	 |
	   +--------------------+----------------+
	   |Introduced		| 8.0.17	 |
	   +--------------------+----------------+
	   Enables the use_gr_notifications [metadata_cache] option during
	   bootstrap. When enabled, Router is asynchronously notified about
	   most	cluster	changes. See use_gr_notifications for more
	   information.

       o   --pid-file path

	   +--------------------+-----------------+
	   |Property		| Value		  |
	   +--------------------+-----------------+
	   |Command-Line Format	| --pid-file path |
	   +--------------------+-----------------+
	   |Introduced		| 8.0.20	  |
	   +--------------------+-----------------+
	   |Type		| String	  |
	   +--------------------+-----------------+
	   Sets	location of the	PID file. This can be set in three different
	   ways	(in order of precedence): this --pid-file command-line option,
	   setting pid_file in Router's	configuration file, or defining	the
	   ROUTER_PID environment variable.

	   If --bootstrap is specified,	then setting --pid-file	causes Router
	   to fail. This is unlike ROUTER_PID and the pid_file configuration
	   option, which are ignored if	--bootstrap is specified.

	   If --bootstrap is not specified, then the following cause Router to
	   fail: the --pid-file	already	exists,	pid_file or ROUTER_PID are set
	   but empty, or if Router can't write the PID file.

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

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

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

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

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

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

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

       o   --name router_name

	   +--------------------+--------------------+
	   |Property		| Value		     |
	   +--------------------+--------------------+
	   |Command-Line Format	| --name router_name |
	   +--------------------+--------------------+
	   |Type		| String	     |
	   +--------------------+--------------------+
	   |Default Value	| system	     |
	   +--------------------+--------------------+
	   On initial bootstrap, specifies a symbolic name for a
	   self-contained Router instance. This	option is optional, and	is
	   used	with --directory. When creating	multiple instances, the	names
	   must	be unique.

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

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

       o   --force

	   +--------------------+---------+
	   |Property		| Value	  |
	   +--------------------+---------+
	   |Command-Line Format	| --force |
	   +--------------------+---------+
	   Force a reconfiguration over	a previously configured	router
	   instance on the host.

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

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

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

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

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

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

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

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

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

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

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

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

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

       o   --remove-service

	   +--------------------+------------------+
	   |Property		| Value		   |
	   +--------------------+------------------+
	   |Command-Line Format	| --remove-service |
	   +--------------------+------------------+
	   |Platform Specific	| Windows	   |
	   +--------------------+------------------+
	   Remove the Router Windows service.

	   This	option is only available on Windows.

       o   --service

	   +--------------------+-----------+
	   |Property		| Value	    |
	   +--------------------+-----------+
	   |Command-Line Format	| --service |
	   +--------------------+-----------+
	   |Platform Specific	| Windows   |
	   +--------------------+-----------+
	   Start Router	as a Windows service.

	   This	option is only available on Windows.

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

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

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

COPYRIGHT
       Copyright (C) 2006, 2020, Oracle	and/or its affiliates.

       This documentation is free software; you	can redistribute it and/or
       modify it only under the	terms of the GNU General Public	License	as
       published by the	Free Software Foundation; version 2 of the License.

       This documentation is distributed in the	hope that it will be useful,
       but WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A	PARTICULAR PURPOSE. See	the GNU
       General Public License for more details.

       You should have received	a copy of the GNU General Public License along
       with the	program; if not, write to the Free Software Foundation,	Inc.,
       51 Franklin Street, Fifth Floor,	Boston,	MA 02110-1301 USA or see
       http://www.gnu.org/licenses/.

NOTES
	1. Connecting Using URI-Like Connection	Strings
	   https://dev.mysql.com/doc/refman/8.0/en/connecting-using-uri-or-key-value-pairs.html#connecting-using-uri

AUTHOR
       Oracle Corporation (http://dev.mysql.com/).

MySQL 8.0			  05/30/2020			MYSQLROUTER(1)

NAME | SYNOPSIS | DESCRIPTION | COPYRIGHT | NOTES | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=mysqlrouter&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help