mysqlrouter 选项总结

mysqlrouter 选项说明

--version, -V

显示应用程序的版本号及相关信息，并退出。例如：

$> mysqlrouter --version

MySQL Router v8.0.31 on Linux (64-bit) (GPL community edition)

--help, -?

显示帮助和参考信息，然后退出。

该--help选项有一个额外的好处。除了每个选项的说明外，该--help选项还显示用于查找配置文件的路径，以及几个默认路径。以下 --help输出摘录显示了 Ubuntu 16.04 机器的示例：

$> 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]
...

配置部分显示可用于读取配置文件的路径顺序。在这种情况下，只能访问第二个文件。

--bootstrap URI,-B URI

通过在提供的 URI 连接到 InnoDB Cluster 元数据服务器来执行 MySQL Router 引导程序的主要选项。MySQL Router 根据从 InnoDB Cluster 元数据服务器检索到的信息进行自我配置。如果需要，系统会提示输入密码。如果 URI 中未提供用户名，则使用默认用户名“root”。有关使用路径指定服务器实例的信息， 请参阅使用类似 URI 的连接字符串进行连接。

默认情况下，引导进程执行 MySQL Router 的系统范围配置。只能为系统范围的操作配置一个 MySQL Router 实例。MySQL Router 的系统实例有一个router_name“系统”。如果需要其他实例，请使用该 --directory选项创建独立的 MySQL 路由器安装。

URI：来自 InnoDB Cluster 的服务器实例，用于从中获取元数据信息。如果提供URI的是只读实例，MySQL Router 会自动重新连接到 InnoDB Cluster 中的读写实例，以便它可以注册 MySQL Router。

如果使用 启动 MySQL Router 时配置文件已经存在，则该文件中--bootstrap的现有router_id配置文件将被重用，并且会发生重新配置过程。配置文件从头开始重新生成，MySQL 路由器的元数据服务器帐户被重新创建，尽管名称相同。

在重新配置过程中，对现有配置文件所做的所有更改都将被丢弃。要自定义配置文件并仍然保留自动重新配置（引导）的能力，您可以使用 --extra-config命令行选项指定在主配置文件之后读取的附加配置文件。使用这些配置选项是因为这个额外的配置文件是在主配置文件之后加载的。

引导程序创建一个新的 MySQL 用户帐户，并使用随机生成的密码供该特定 MySQL Router 实例使用。当连接到元数据服务器和 InnoDB 集群以获取有关其当前状态的信息时，MySQL Router 使用此帐户。有关此用户的详细信息，包括其密码的存储方式和所需的 MySQL 权限，请参阅 MySQL user option.

生成的配置文件名为 mysqlrouter.conf，其位置取决于正在配置的实例类型、系统和包。对于系统范围的安装，生成的配置文件被添加到系统的配置目录，例如/etc或 %PROGRAMDATA%\MySQL\MySQL Router\. 执行mysqlrouter --help会显示这个位置。

--user如果使用超级用户 (uid=0) 执行引导程序，则需要 该选项。虽然不推荐，但可以通过将其名称作为参数传递来强制超级用户，例如--user=root。

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会在生成的 MySQL Router 配置文件中添加默认值，其中一些默认值取决于其他条件。下面列出了一些影响生成默认值的条件，其中default是--bootstrap通过自己传入来定义的。

--bootstrap-socket socket_name

与 结合使用 --bootstrap以使用本地 Unix 域套接字而不是 TCP/IP 进行引导。该 --bootstrap-socket值将定义中的“host:port”部分替换 --bootstrap为分配的套接字名称，用于使用 Unix 域套接字连接到 MySQL 元数据服务器。这是从中引导的 MySQL 实例，如果使用套接字，则此实例必须在同一台机器上。有关引导程序如何工作的更多详细信息，请参阅 --bootstrap。

此选项不同于 在引导程序过程 --conf-use-sockets中设置配置文件选项的命令行选项 。socket

此选项在 Windows 上不可用。

--directory dir_path,-d dir_path

指定将在定义的目录中创建独立的 MySQL 路由器安装，而不是配置系统范围的路由器实例。这也允许在同一系统上创建多个路由器实例。

Router 的独立目录结构是：

$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

如果指定了此选项，则密钥环文件存储在该实例的运行时状态目录下， run/在指定目录下，而不是系统范围的运行时状态目录。

如果--conf-use-sockets也启用，则生成的套接字文件也将添加到此目录。

--master-key-writer

这个可选的引导程序选项接受一个脚本，该脚本从STDIN 读取主密钥。它还使用 MySQL Router 在调用脚本 之前设置的ROUTER_ID环境变量。master-key-writer

master-key-writer和 master-key-reader选项必须一起使用，使用它们意味着 master_key_file不能定义 该选项，mysqlrouter.conf因为主密钥没有写入mysqlrouter.key主密钥文件。

master-key-writer这也作为[DEFAULT] 选项 写入生成的 MySQL Router 配置文件。

我们示例中使用的名为 bash 脚本的示例内容 writer.sh：

#!/bin/bash

KID_=$(keyctl padd user ${ROUTER_ID} @us <&0)

用法示例：

$> mysqlrouter --bootstrap=127.0.0.1:3310 --master-key-reader=./reader.sh --master-key-writer=./writer.sh

这也会影响生成 mysqlrouter.conf的，例如：

[DEFAULT]
...
master-key-reader=reader.sh
master-key-writer=writer.sh

--master-key-reader

这个可选的引导程序选项接受将主密钥写入STDOUT的脚本。它还使用MySQL Router 在调用脚本 之前设置的ROUTER_ID环境变量。master-key-reader

master-key-reader和 master-key-writer选项必须一起使用，使用它们意味着 master_key_file不能在主密钥文件中定义 该选项，mysqlrouter.conf因为主密钥不会写入mysqlrouter.key主密钥文件，而是使用该选项的脚本提供的值。

master-key-reader这也作为[DEFAULT] 选项 写入生成的 MySQL Router 配置文件。

我们示例中使用的名为 bash 脚本的示例内容 reader.sh：

#!/bin/bash

KID_=$(keyctl search @us user ${ROUTER_ID} 2>/dev/null)
if [ ! -z $KID_ ]; then
  keyctl pipe $KID_
fi

用法示例：

$> mysqlrouter --bootstrap=127.0.0.1:3310 --master-key-reader=./reader.sh --master-key-writer=./writer.sh

这也会影响生成 mysqlrouter.conf的，例如：

[DEFAULT]
...
master-key-reader=reader.sh
master-key-writer=writer.sh

--strict

启用严格模式，例如，这会导致引导程序 --account用户验证检查停止引导程序进程，而不是仅在提供的用户未通过检查时发出警告并继续。

--account

用于指定要使用的 MySQL 用户的引导选项，它可以重用现有的 MySQL 用户帐户或创建一个；由相关 --account-create选项控制的行为。

与--account相比，使用更倾向于易于管理而不是易于部署，因为多个路由器可能共享同一个帐户，并且用户名和密码是手动定义的而不是自动生成的。

设置此选项会触发此帐户的密码提示，而不管密码是否在密钥环中可用。

不传入的引导--account 不会重新创建现有的 MySQL 服务器帐户。在 MySQL Router 8.0.18 之前，引导会删除现有用户并重新创建它。

使用此选项假定用户对 Router 具有足够的访问权限，因为引导过程不会尝试向现有帐户添加缺少的授权。引导程序确实会验证权限并将信息输出到失败检查的控制台。尽管这些检查失败，引导过程仍会继续，除非--strict还使用了可选选项。所需权限示例：

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`@`%`

命令行不接受密码。例如，传入 "foo:bar" 假定 "foo:bar" 是所需的用户名，而不是密码为 bar的用户foo。

--account-create

指定帐户创建策略以帮助防止使用错误的用户帐户意外引导。潜在的价值是：

该选项要求该--account 选项也被使用，那个--account-host 不被使用。

--account-host

用于 MySQL Router 在引导过程中创建的帐户的主机模式。这是可选的，默认为“%”。

多次传入此选项以定义多个模式，在这种情况下生成的 MySQL 帐户使用相同的密码。

例子：

# 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

--conf-use-sockets

启用本地 Unix 域套接字。

引导时使用此选项，启用它会将socket选项添加到生成的配置文件中。

生成的套接字文件的名称取决于 mode和protocol选项。启用经典协议后，文件以 mysql.sock读写模式命名，并 mysqlro.sock以只读模式命名。启用 X 协议后，文件以 mysqlx.sock读写模式和 mysqlxro.sock只读模式命名。

此选项在 Windows 上不可用。

--conf-use-gr-notifications

在引导过程中启用 use_gr_notifications [metadata_cache] 选项。启用后，路由器会异步收到有关大多数集群更改的通知。有关 use_gr_notifications详细信息，请参阅。此外，使用此选项设置 ttl=60 和 auth_cache_refresh_interval=60。

--pid-file path

设置 PID 文件的位置。这可以通过三种不同的方式设置（按优先顺序）：此 --pid-file命令行选项、 pid_file在路由器的配置文件中设置或定义 ROUTER_PID环境变量。

如果--bootstrap指定，则设置 --pid-file 会导致路由器失败。这与 ROUTER_PID 和 pid_file 配置选项不同，如果指定了 --bootstrap，它们将被忽略。

如果--bootstrap未指定，则以下原因会导致 Router 失败：--pid-file 已存在，pid_file 或 ROUTER_PID 已设置但为空，或者 Router 无法写入 PID 文件。

--report-host

可选地定义路由器的主机名，而不是依靠自动检测来确定在引导过程中注册到元数据的外部可见主机名。

路由器不检查或确认提供的主机名是否可达，但使用 RFC 1123 验证主机名，并使用 RFC 2181 验证地址。

提供的主机名被写入 MySQL InnoDB 集群元数据存储中的 mysql_innodb_cluster_metadata.hosts 表的 host_name 字段。

--conf-skip-tcp

跳过用于侦听传入连接的 TCP 端口配置。另见 --conf-use-sockets。

此选项在 Windows 上不可用。

--conf-base-port port_num

bind_port通过为每个引导路由 设置，用于侦听 TCP 端口的基本（第一个）值 。

该值用于经典的读写路由，每个额外分配的端口都递增一个值。设置的端口顺序是经典的读写/只读，然后是x读写/只读。

从路由器 8.0.24 开始：设置--conf-base-port 为 0 会将默认bind_port值更改为以前（8.0.24 之前）的默认值，如下所示：对于经典协议，读写使用 6446，只读使用 6447，对于 X协议 Read-Write 使用 64460，Read-Only 使用 64470。

用法示例：

# Example without --conf-base-port
$> 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:6448
- Read/Only Connections: localhost:6449

# Example demonstrating --conf-base-port set to 0
$> mysqlrouter --bootstrap root@localhost:3310 --conf-base-port 0
...
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

--conf-bind-address address

修改 生成的路由器配置文件中bind_address 设置的值。--bootstrap默认情况下，bootstrappingbind_address=0.0.0.0会为每个路由设置，此选项会更改该值。

--read-timeout num_seconds

对元数据服务器的读取操作被视为超时之前的秒数。

这会影响引导过程中的读取操作，并且还会通过 read_timeout 在生成的mysqlrouter.conf.

该选项设置在[DEFAULT] 命名空间下。

--connect-timeout num_seconds

连接到元数据服务器的尝试被视为超时之前的秒数。

这会影响引导过程中的连接，并且还会通过 connect_timeout 在生成的mysqlrouter.conf.

有两种connect_timeout变体。元数据服务器变体在命名空间下定义 [DEFAULT]，而 MySQL 服务器变体在命名空间下定义[routing] 。

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

以具有名称 或数字用户 ID 的用户身份 运行mysqlrouter。“用户”在此上下文中是指系统登录帐户，而不是授权表中列出的 MySQL 用户。引导时，所有生成的文件都归该用户所有，这也设置了相关选项。 user_nameuser_iduser

这个系统 user 定义在 [DEFAULT]命名空间下的配置文件中。有关其他信息，请参阅 user 选项的--user 配置文档。

--user如果以超级用户 (uid=0) 身份执行引导程序，则需要 该选项。虽然不推荐，但可以通过将其名称作为参数传递来强制超级用户，例如--user=root。

此选项在 Windows 上不可用。

--name router_name

在初始引导时，为独立的 Router 实例指定一个符号名称。此选项是可选的，与 一起使用--directory。创建多个实例时，名称必须是唯一的。

--force-password-validation

默认情况下，MySQL Router 会跳过 MySQL Server 的 validate_password 机制，而是 Router 根据已知的 validate_password 默认设置生成并使用一个 STRONG 密码。这是因为 validate_password 可以由用户配置，而 Router 无法考虑异常的自定义设置。

此选项确保不会为生成的密码跳过密码验证 (validate_password)，默认情况下禁用。

--password-retries num_retries

指定在使用密码验证规则创建用户帐户时 MySQL Router 应尝试生成密码的次数。默认值为 20。有效范围为 1 到 10000。

失败的最可能原因是自定义 validate_password 设置具有异常要求（例如最少 50 个字符）。在那种失败的情况下，要么 --force-password-validation 设置为 true 和/或 mysql_native_password禁用 MySQL 服务器插件（该插件允许绕过验证）。

--force

强制对主机上先前配置的路由器实例进行重新配置。

--ssl-mode mode

连接到元数据服务器时在引导和正常操作期间使用的 SSL 连接模式。类似于 --ssl-mode在 mysql客户端中。

在引导期间，路由器与元数据服务器建立的所有连接都将使用指定的 SSL 选项。如果 ssl_mode未在配置中指定，则默认为 PREFERRED。在正常操作期间，路由器启动后，其元数据缓存插件将读取并遵守所有已配置的 SSL 设置。

当设置为默认值 (PREFERRED) 以外的值时，将 在生成的配置文件 ssl_mode的部分下插入一个条目 。[metadata_cache]

可用值为 DISABLED、PREFERRED、REQUIRED、VERIFY_CA 和 VERIFY_IDENTITY。PREFERRED 是默认值。对于mysql客户端，此值不区分大小写。

等效的配置文件单独记录在 ssl_mode。

--ssl-cert file_path

PEM 格式的 SSL 公钥证书文件的路径名。这用于在引导过程中促进客户端身份验证。这直接匹配并使用 MySQL 客户端 --ssl-cert选项的功能。

与 一样--ssl-key，此选项仅在使用 root 帐户的引导程序期间使用。当使用 REQUIRE X509 创建 root 帐户时它很有用，因此以 root 身份登录需要客户端对自己进行身份验证。

--ssl-key file_path

PEM 格式的 SSL 私钥文件的路径名。这用于在引导过程中促进客户端身份验证。这直接匹配并使用 MySQL 客户端 --ssl-key选项的功能。

与 一样--ssl-cert，此选项仅在使用 root 帐户的引导过程中使用。当使用 REQUIRE X509 创建 root 帐户时它很有用，因此以 root 身份登录需要客户端对自己进行身份验证。

--ssl-cipher ciphers

如果启用了 SSL，则允许的 SSL 密码的冒号分隔（“:”）列表。

--tls-version versions

如果启用了 SSL，则要请求的 TLS 版本的逗号分隔 (",") 列表。

--ssl-ca file_path

用于验证服务器证书的 SSL CA 文件的路径。

--ssl-capath dir_path

包含用于验证服务器证书的 SSL CA 文件的目录路径。

--ssl-crl file_path

验证服务器证书时要使用的 SSL CRL 文件的路径。

--ssl-crlpath dir_path

验证服务器证书时要使用的包含 SSL CRL 文件的目录的路径。

--config file_path,-c file_path

用于为要使用的配置文件提供路径和文件名。如果要使用位于默认位置以外的文件夹中的配置文件，请使用此选项。

与 一起使用时 ，如果配置文件已经存在，如果生成的配置文件内容与原始文件不同--bootstrap，则当前文件的副本将以.bak扩展名保存。现有的.bak文件被覆盖。

--extra-config file_path,-a file_path

用于提供可选的附加配置文件以供使用。如果要将配置文件拆分为两部分进行测试、应用程序的多个实例在同一台机器上运行等，请使用此选项。

该配置文件在主配置文件之后读取。如果存在冲突（在多个配置文件中设置了一个选项），则使用最后加载的文件中的值。

--install-service

将路由器安装为 Windows 启动时自动启动的 Windows 服务。服务名称默认为 MySQLRouter。

此安装过程不会验证通过 --config.

此选项仅在 Windows 上可用。

--install-service-manual

将 MySQL Router 安装为可以手动启动的 Windows 服务。服务名称默认为 MySQLRouter。

此选项仅在 Windows 上可用。从 MySQL Router 8.0.28 开始可用的可选服务名称参数。

--remove-service

移除 Router Windows 服务；服务名称默认为 MySQLRouter。

此选项仅在 Windows 上可用。从 MySQL Router 8.0.28 开始可用的可选服务名称参数。

--service

将 Router 作为 Windows 服务启动。这是一个私有选项，意味着它仅供 Windows 服务在将路由器作为服务启动时使用。

此选项仅在 Windows 上可用。从 MySQL Router 8.0.28 开始可用的可选服务名称参数。

--update-credentials-section

此选项仅在 Windows 上可用，并且指的是其密码库。

--conf-target-cluster

设置target_cluster元数据 MySQL 路由器选项。接受以下字符串之一：

另请参阅--config-target-cluster-by-name，它将 设置target_cluster为特定的静态集群名称。

--conf-set-option

在引导过程中为生成的配置选项设置一个值；这可以为任何引导选项设置一个值，例如：

$> mysqlrouter -B 127.0.0.1:5000 \
               --directory=dir1  \
               --conf-set-option=logger.level=debug \
               --conf-set-option=routing:test_rw.max_connect_errors=0 \
               --conf-set-option=routing:test_ro.max_connect_errors=0

这些命令通过如下定义来更改这些特定选项的默认值：

[logger]
level=debug

[routing:test_rw]
...
max_connect_errors=0
...

[routing:test_ro]
...
max_connect_errors=0
...

--conf-set-option定义优先于选项特定参数来设置特定值。例如，如果 在引导时指定 了--connect-timeout=X和 ，则在生成的配置文件中将 设置为 Y。--conf-set-option=DEFAULT.connect_timeout=Yconnect_timeout

--conf-target-cluster-by-name

将target_cluster元数据 MySQL Router 选项设置为特定的集群名称。

或者，改为使用--conf-target-cluster分配动态集群类型，例如主集群。

--remove-credentials-section section_name

删除给定部分的凭据。

此选项仅在 Windows 上可用，并且指的是其密码库。

--clear-all-credentials

通过删除存储在其中的所有凭据来清除密码库。

此选项仅在 Windows 上可用，并且指的是其密码库。

--disable-rest

默认情况下， MySQL Router REST APImysqlrouter.conf Web 服务功能的配置详细信息会在引导 时添加到生成的 文件中；并且此参数表示不添加这些详细信息。这不会禁用 REST API 功能，因为稍后可以手动配置（启用）REST API 功能。

--https-port

port可以选择在引导程序生成的 [http_server] 部分下为 MySQL Router REST API 定义 HTTP 服务器mysqlrouter.conf。它默认为 8443。不检查端口的可用性。