mongos

核心选项

--help, -h

返回有关 mongos 的选项和使用的信息。

--version

返回 mongos 版本号。

--config <filename>, -f <filename>

指定运行时配置选项的配置文件。 配置文件是运行时配置mongos的首选方法。 这些选项相当于命令行配置选项。 有关更多信息，请参阅自管理配置文件选项。

确保配置文件使用 ASCII 编码。mongos 实例不支持非 ASCII 编码的配置文件，包括 UTF-8。

--configExpand <none|rest|exec>

默认：无

启用在配置文件中使用扩展指令。扩展指令允许您为配置文件选项设置外部来源的值。

--configExpand 支持以下扩展指令：

值	说明
none	默认。mongos 不扩展扩展指令。如果任何配置文件设置使用扩展指令，mongos 将无法启动。
rest	mongos 解析配置文件时扩展 __rest 扩展指令。
exec	mongos 解析配置文件时扩展 __exec 扩展指令。

您可以将多个扩展指令指定为以逗号分隔的列表，例如：rest, exec。如果配置文件包含未指定为 --configExpand 的扩展指令，mongos 会返回错误并终止。

有关扩展指令的更多信息，请参阅配置文件的自管理部署的源自外部的配置文件值。

--verbose, -v

增加标准输出或日志文件中返回的内部报告数量。通过多次包含该选项，可以使用 -v 形式增加详细程度，例如：-vvvvv。

--quiet

在尝试限制输出量的安静模式下运行 mongos。

该选项会抑制：

• 数据库命令输出

• 复制活动

• 连接接受事件

• 连接关闭事件

--port <port>

默认值：27017

mongos 实例侦听客户端连接的 TCP 端口。

在版本 7.0.3 中更改：--port 选项接受 0 和 65535 之间的值范围。将端口设置为 0 会将 mongos 配置为使用操作系统分配的任意端口。

--bind_ip <hostnames|ipaddresses|Unix domain socket paths>

默认值：localhost

mongos 应侦听客户端连接的主机名和/或 IP 地址和/或完整 Unix 域套接字路径。您可以将 mongos 连接到任何接口。要绑定到多个地址，输入以逗号分隔的值列表。

例子

localhost,/tmp/mongod.sock

您可以指定 IPv4 和 IPv6 解决方案，或解析为 IPv4 或 IPv6 地址的主机名。

例子

localhost, 2001:0DB8:e132:ba26:0d5c:2774:e7f9:d513

注意

如果将 IPv6 地址或解析为 IPv6 地址的主机名指定为 --bind_ip，则必须以 --ipv6 开头 mongos，才能启用 IPv6 支持。将 IPv6 地址指定为 --bind_ip 不会启用 IPv6 支持。

如果指定 链路本地 IPv6 地址 (fe80::/10 )，必须附加 区域索引 到该地址（即fe80::<address>%<adapter-name> ）。

例子

localhost,fe80::a00:27ff:fee0:1fcf%enp0s3

重要

要避免因 IP 地址变更而更新配置，请使用 DNS 主机名而非 IP 地址。在配置副本集成员或分片集群成员时，使用 DNS 主机名而非 IP 地址尤为重要。

在水平分割网络配置下，请使用主机名而非 IP 地址来配置集群。从 MongoDB 5.0 开始，仅配置了 IP 地址的节点将无法通过启动验证，因而不会启动。

警告

将实例绑定到可公开访问的 IP 地址之前，必须保护集群免遭未经授权的访问。有关安全建议的完整列表，请参阅自管理部署的安全清单。至少应考虑启用身份验证和强化网络基础设施。

有关 IP 绑定的更多信息，请参阅自托管部署中的 IP 绑定文档。

要绑定到所有 IPv4 地址，请输入 0.0.0.0。

如要绑定到所有 IPv4 和 IPv6 地址，请输入 ::,0.0.0.0 或星号 "*" （将星号括在引号中以避免文件名模式扩展）。或者您可以使用 net.bindIpAll 设置。

注意

• --bind_ip 和 --bind_ip_all 是互斥的。同时指定两个选项会导致 mongos 引发错误并终止。

• 命令行选项 --bind 覆盖配置文件设置 net.bindIp。

--bind_ip_all

如果已指定，mongos 实例将绑定到所有 IPv4 地址（即 0.0.0.0）。如果 mongos 以 --ipv6 开头，那么 --bind_ip_all 也将绑定到所有 IPv6 地址（即 ::）。

mongos 如果使用 启动，则仅支持6--ipv6 IPv 。单独指定--bind_ip_all并不能启用 IPv 6支持。

警告

将实例绑定到可公开访问的 IP 地址之前，必须保护集群免遭未经授权的访问。有关安全建议的完整列表，请参阅自管理部署的安全清单。至少应考虑启用身份验证和强化网络基础设施。

有关 IP 绑定的更多信息，请参阅自托管部署中的 IP 绑定文档。

或者，您可以将 --bind_ip 选项设置为 ::,0.0.0.0 或星号 "*"（将星号括在引号中以避免文件名模式扩展）。

注意

--bind_ip 和 --bind_ip_all 是互斥的。也就是说，您可以指定其中之一，但不能同时指定两者。

--listenBacklog <number>

默认值：目标系统 SOMAXCONN 常量

监听队列中可以存在的最大连接数。

警告

在使用此参数之前，请查阅本地系统的文档以了解限制条件和配置要求。

重要

要防止出现未定义行为，为此参数指定一个介于 1 和本地系统 SOMAXCONN 常量之间的值。

listenBacklog 参数的默认值在编译时设置为目标系统 SOMAXCONN 常量。SOMAXCONN 是为侦听系统调用的积压参数记录的最大有效值。

某些系统可能会以符号的形式解释 SOMAXCONN，而另一些系统则以数字方式解释。实践中应用的实际侦听积压可能与 SOMAXCONN 常量或 --listenBacklog 参数的任何数字解释不同，并且还可能受到 Linux 上的 net.core.somaxconn 等系统设置的限制。

根据标准的规定，为 listenBacklog 参数传递超过本地系统 SOMAXCONN 常量的值是未定义行为。较高的值可能会被默默地整数截断、可能被忽略、可能导致意外资源消耗，或者产生不利后果。

在工作负载出现连接峰值的系统上，经验证本地系统能够支持比 SOMAXCONN 常量更高的积压参数值，通过减少被迫进入回退状态的连接次数，将 listenBacklog 参数设置为更高的值可能会减少客户端观察到的操作延迟。

--maxConns <number>

mongos 接受的最大并行连接数。如果该设置高于操作系统配置的最大连接跟踪阈值，则该设置无效。

不要为此选项分配过低的值，否则会在正常的应用程序操作期间遇到错误。

如果您的客户端创建了多个连接，并且允许这些连接超时而不是将其关闭，那么这对于 mongos 特别有用。

在此情况下，请将 maxIncomingConnections 的值设为略高于客户端创建的最大连接数或连接池的最大大小。

此设置可防止 mongos 在各分片上造成连接峰值。此类峰值可能会扰乱分片集群的操作和内存分配。

--logpath <path>

将所有诊断日志记录信息发送到日志文件中，而不是标准输出或主机的系统日志系统。MongoDB 在您指定的路径创建日志文件。

默认情况下，MongoDB 会移动而非覆盖现有日志文件。要改为追加到日志文件，请设置 --logappend 选项。

--syslog

将所有日志记录输出发送到主机的 syslog 系统，而不是发送到标准输出或日志文件 (--logpath)。

--syslog 选项在 Windows 上不受支持。

警告

syslog 守护进程在记录消息时生成时间戳，而不是在 MongoDB 发出消息时生成时间戳。这可能会导致日志条目的时间戳产生误导，尤其是当系统负载较重时。我们建议对生产系统使用 --logpath 选项，以确保时间戳的准确性。

MongoDB 将该组件包含在其发往 syslog 的日志消息中。

...  ACCESS   [repl writer worker 5] Unsupported modification to roles collection ...

--syslogFacility <string>

默认：用户

指定将消息记录到系统日志时使用的设施级别。您指定的值必须受操作系统的系统日志实现支持。要使用该选项，必须启用 --syslog 选项。

--logappend

当 mongos 实例重新启动时，将新条目附加到现有日志文件的末尾。如果没有该选项，mongod 将会备份现有日志并创建新文件。

--logRotate <string>

默认：重命名

确定轮换服务器日志和/或审核日志时 logRotate 命令的行为。指定 rename 或 reopen：

• rename 对日志文件进行重命名。

• reopen 按照典型的 Linux/Unix 日志轮换行为关闭并重新打开日志文件。使用 Linux/Unix logrotate 实用程序时使用 reopen 避免日志丢失。

  如果指定 reopen，那么您还必须使用 --logappend。

--redactClientLogData

仅在 MongoDB Enterprise 中可用。

使用 --redactClientLogData 运行的 mongos 会在登录之前编辑与给定日志事件相关的任何消息。这可以防止 mongos 将数据库中存储的潜在敏感数据写入诊断日志。错误或操作代码、行号和源文件名等元数据在日志中仍然可见。

将 --redactClientLogData 与静态加密和 TLS/SSL（传输加密）结合使用，以帮助符合监管要求。

例如，MongoDB 部署可能会将个人身份信息 (PII) 存储在一个或多个集合中。mongos 日志事件，例如与增删改查操作、分片元数据等。mongos 可能会公开 PII 作为这些日志记录操作的一部分。通过 --redactClientLogData 运行的 mongos 会在输出到日志之前删除与这些事件相关的任何消息，从而有效地删除了 PII。

由于缺少与日志事件相关的数据，对使用 --redactClientLogData 运行的 mongos 进行诊断可能会更加困难。有关 --redactClientLogData 对日志输出影响的示例，请参阅进程日志记录手册页面。

在运行中的 mongos 上，使用 setParameter 与 redactClientLogData 参数配置此设置。

--timeStampFormat <string>

Default: iso8601-local

日志消息中时间戳的时间格式。指定以下值之一：

值	说明
iso8601-utc	以 ISO-8601 格式显示协调通用时间 (UTC) 的时间戳。例如，对于纪元开始时的纽约： 1970-01-01T00:00:00.000Z
iso8601-local	以 ISO-8601 格式显示当地时间的时间戳。例如，对于纪元开始时的纽约： 1969-12-31T19:00:00.000-05:00

注意

--timeStampFormat 不再支持 ctime。ctime 格式日期的示例为：Wed Dec 31 18:17:54.811。

--pidfilepath <path>

指定文件位置以存储 mongos 进程的进程 ID (PID)。运行 mongod 或 mongos 进程的用户必须能够写入此路径。如果未指定 --pidfilepath 选项，进程不会创建 PID 文件。该选项通常只能与 --fork 选项结合使用。

注意

Linux

在 Linux 上，PID 文件管理通常由发行版的初始化系统负责：一般是 /etc/init.d 目录中的服务文件，或者是使用 systemctl 注册的 systemd 单元文件。仅当您未使用这些初始化系统时，才使用 --pidfilepath 选项。有关更多信息，请参阅操作系统的相关安装指南。

注意

macOS

在 macOS 上，PID 文件管理通常由 brew 处理。仅当在 macOS 系统上未使用 brew 时，才使用 --pidfilepath 选项。有关更多信息，请参阅适用于您操作系统的相应《安装指南》。

--keyFile <file>

指定密钥文件的路径，该文件存储MongoDB实例用于在分片分片集群或副本集相互验证的共享密钥。 --keyFile意味着client authorization 。 有关更多信息，请参阅自管理内部/成员身份验证。

用于内部成员身份验证的密钥文件使用 YAML 格式，允许在密钥文件中包含多个密钥。YAML 格式接受以下任一形式：

• 单个密钥字符串（与早期版本相同）

• 键字符串序列

YAML 格式与使用文本文件格式的现有单密钥文件兼容。

--setParameter <options>

指定用于自托管部署的MongoDB Server参数 中描述的MongoDB参数之一。 您可以指定多个setParameter字段。

--noscripting

禁用脚本引擎。禁用后，您便无法使用可在服务器端执行 JavaScript 代码的操作，如 $where 查询运算符、mapReduce 命令、$accumulator 和 $function。

如果不使用这些操作，请禁用服务器端脚本。

--nounixsocket

禁用 UNIX 域套接字上的侦听。--nounixsocket 仅适用于基于 Unix 的系统。

mongos 进程始终侦听 UNIX 套接字，除非满足以下任一条件：

• --nounixsocket 已设置

• net.bindIp 未设置

• net.bindIp 未指定 localhost 或其相关 IP 地址

mongos 通过官方 .deb 和 .rpm 软件包默认将 bind_ip 配置设置为 127.0.0.1。

--unixSocketPrefix <path>

默认：/tmp

UNIX 套接字的路径。--unixSocketPrefix 仅适用于基于 Unix 的系统。

如果此选项没有值，则 mongos 进程将创建一个以 /tmp 作为前缀的套接字。MongoDB 创建并侦听 UNIX 套接字，除非满足以下条件之一：

• net.unixDomainSocket.enabled is false

• --nounixsocket 已设置

• net.bindIp 未设置

• net.bindIp 未指定 localhost 或其相关 IP 地址

--filePermissions <path>

默认值：0700

设置 UNIX 域套接字文件的权限。

--filePermissions 仅适用于基于 Unix 的系统。

--fork

启用后台运行 mongos 进程的守护进程模式。--fork 选项在 Windows 系统上不受支持。

默认情况下，mongos 不作为守护进程运行。您可以使用 --fork 或处理守护进程的控制进程将 mongos 作为守护进程运行，例如 upstart 或 systemd。

使用 --fork 选项需要使用以下任一选项配置 mongos 的日志输出：

• --logpath

• --syslog

--transitionToAuth

允许 mongos 接受和创建与部署中其他 mongod 和 mongos 实例之间的经过身份验证和未经身份验证的连接。用于执行副本集或分片集群从无身份验证配置到内部身份验证的滚动过渡。需要指定内部身份验证机制，例如 --keyFile。

例如，如果使用密钥文件进行内部身份验证，mongos 会使用匹配的密钥文件与部署中的任何 mongod 或 mongos 创建经身份验证的连接。如果安全机制不匹配，则 mongos 将改用未经身份验证的连接。

使用 --transitionToAuth 运行的 mongos 不会强制实施用户访问控制。用户无需任何访问控制检查即可连接到您的部署并执行读取、写入和管理操作。

注意

使用内部身份验证且不使用 --transitionToAuth 运行的 mongos 要求客户端使用用户访问控制进行连接。更新客户端以在重新启动 mongos 之前使用适当的用户连接到 mongos，而无需 --transitionToAuth。

--networkMessageCompressors <string>

Default: snappy,zstd,zlib

指定默认压缩程序用于此 mongos 实例与以下对象之间的通信：

• 分片集群的其他节点

• mongosh

• 支持 OP_COMPRESSED 消息格式的驱动程序。

MongoDB 支持以下压缩程序：

• snappy

• zlib

• zstd

mongod 和 mongos 实例按该顺序均默认为 snappy,zstd,zlib 压缩器。

要禁用网络压缩，请将值设置为 disabled。

重要

当双方都启用网络压缩时，消息就会被压缩。否则，各方之间的消息不会被压缩。

如果指定多个压缩程序，则列出压缩程序的顺序与通信发起者都很重要。例如，如果 mongosh 指定以下网络压缩程序 zlib,snappy 且 mongod 指定 snappy,zlib，则在 mongosh 和 mongod 之间的消息使用 zlib。

如果各方未分享至少一个通用压缩程序，则各方之间的消息将不会被压缩。例如，如果 mongosh 指定网络压缩程序 zlib 且 mongod 指定 snappy，则 mongosh 与 mongod 之间的消息将不会被压缩。

--timeZoneInfo <path>

加载时区数据库的完整路径。如果未提供此选项，则 MongoDB 将使用内置的时区数据库。

Linux 和 macOS 软件包中包含的配置文件默认将时区数据库设置为 /usr/share/zoneinfo 。

内置时区数据库是 OLSON/IANA 时区数据库的副本。它随着 MongoDB 的发布而更新，但时区数据库的发布周期与 MongoDB 的发布周期不同。时区数据库的最新版本可在我们的下载网站上找到。

wget https://downloads.mongodb.org/olson_tz_db/timezonedb-latest.zip
unzip timezonedb-latest.zip
mongos --timeZoneInfo timezonedb-2017b/

警告

MongoDB 使用第三方 timelib 库提供时区之间的准确转换。由于最近的更新，timelib 可能会在旧版本的 MongoDB 中创建不准确的时区转换。

要在 5.0 之前的 MongoDB 版本中显式链接到时区数据库，请下载时区数据库。并使用 timeZoneInfo 参数。

--outputConfig

将mongos实例的配置选项（采用 YAML 格式）输出到stdout并退出mongos实例。 对于使用来自外部的配置文件值进行自我管理的部署的配置选项， --outputConfig返回这些选项的解析值。

警告

这可能包括之前通过外部来源进行模糊处理的任何配置的密码或密钥。

有关用法示例，请参阅：

• 输出具有已解析扩展指令值的配置文件

• 将自管理命令行选项转换为 YAML

分片集群选项

--configdb <replicasetName>/<config1>,<config2>...

指定该分片集群的配置服务器。

分片集群的配置服务器将部署为副本集。副本集配置服务器必须运行 WiredTiger 存储引擎。

指定配置服务器副本集名称以及至少一个配置服务器副本集成员的主机名和端口。

sharding:
  configDB: <configReplSetName>/cfg1.example.net:27019, cfg2.example.net:27019,...

该分片集群的 mongos 实例必须指定相同的配置服务器副本集名称，但可指定副本集不同节点的主机名和端口。

--localThreshold

默认：15

指定 ping 时间（以毫秒为单位），mongos 将根据该 ping 时间来确定哪些从节点副本集节点传递来自客户端的读取操作。15 的默认值对应于所有客户端驱动程序中的默认值。

当 mongos 收到允许从节点读取的请求时，将：

• 找到该副本集中 ping 时间最短的节点。

• 构造一个副本集节点列表，保持与该副本集中最近的合适节点的 ping 时间在 15 毫秒之内。

  如果为 --localThreshold 选项指定一个值，mongos 将构造一个在该值允许的延迟范围内的副本集节点列表。

• 从该列表中随机选择要读取的节点。

按 --localThreshold 设置进行比较的节点所用的网络探测（ping）时间是最近网络探测（ping）时间的移动平均值，且最多每 10 秒计算一次。因此，在 mongos 重新计算平均值之前，一些查询查找到的节点可能会超过阈值。

请参阅读取偏好文档的副本集的读取偏好部分，了解更多信息。

TLS 选项

--tlsMode <mode>

对所有网络连接启用 TLS 模式。--tlsMode 选项的参数可以是以下之一：

值	说明
disabled	该服务器不使用 TLS。
allowTLS	服务器之间的连接不使用 TLS。对于传入连接，服务器既接受 TLS，也接受非 TLS。
preferTLS	服务器之间的连接使用 TLS。对于传入连接，服务器既接受 TLS，也接受 TLS。
requireTLS	服务器仅使用并接受 TLS 加密连接。

如果未指定 --tlsCAFile 或 tls.CAFile 且您未使用 x.509 身份验证，则必须将 tlsUseSystemCA 参数设置为 true。这使得 MongoDB 在连接到启用 TLS 的服务器时使用系统范围的 CA 证书存储。

如果使用 x.509 身份验证，则必须指定 --tlsCAFile 或 tls.CAFile，除非使用 --tlsCertificateSelector。

有关 TLS 和 MongoDB 的详细信息，请参阅为 TLS/SSL 配置 mongod 和 mongos 以及客户端的 TLS/SSL 配置。

--tlsCertificateKeyFile <filename>

注意

在 macOS 或 Windows 上，您可以使用操作系统安全存储库中的证书，而非指定 PEM 文件。请参阅 --tlsCertificateSelector。

指定同时包含 TLS/SSL 证书和密钥的 .pem 文件。

• 在 Linux/BSD 上，当启用 TLS 时，您必须指定 --tlsCertificateKeyFile。

• 在 Windows 或 macOS 上，当启用 TLS 时，您必须指定 --tlsCertificateKeyFile 或 --tlsCertificateSelector。

有关 TLS 和 MongoDB 的详细信息，请参阅为 TLS/SSL 配置 mongod 和 mongos 以及客户端的 TLS/SSL 配置。

--tlsCertificateKeyFilePassword <value>

指定解密证书密钥文件的密码（即--tlsCertificateKeyFile）。仅在证书密钥文件已加密的情况下使用 --tlsCertificateKeyFilePassword 选项。在所有情况下，mongos 都会对所有日志记录和报告输出中的密码进行脱敏。

• 在 Linux/BSD 上，如果 PEM 文件中的私钥已加密且您未指定 --tlsCertificateKeyFilePassword 选项，则 MongoDB 会提示您输入密码。请参阅 TLS/SSL 证书密码。

• 在 macOS 或 Windows 上，如果 PEM 文件中的私钥已加密，则必须显式指定 --tlsCertificateKeyFilePassword 选项。或者，您可以使用安全系统存储中的证书（请参阅 --tlsCertificateSelector）而不是 PEM 文件，或者使用未加密的 PEM 文件。

有关 TLS 和 MongoDB 的详细信息，请参阅为 TLS/SSL 配置 mongod 和 mongos 以及客户端的 TLS/SSL 配置。

--clusterAuthMode <option>

默认：keyFile

集群身份验证时使用的身份验证方式。如果使用内部 x.509 身份验证，请在此处指定。此选项可为以下值之一：

值	说明
keyFile	使用密钥文件进行身份验证。仅接受密钥文件。
sendKeyFile	用于滚动升级目的。发送密钥文件进行 身份验证，但可以接受密钥文件和 x.509 证书。
sendX509	用于滚动升级目的。发送 x.509 证书进行身份验证，但可以同时接受密钥文件和 x.509 证书。
x509	推荐。发送 x.509 证书进行身份验证，仅接受 x.509 证书。

如果未指定 --tlsCAFile 或 tls.CAFile 且您未使用 x.509 身份验证，则必须将 tlsUseSystemCA 参数设置为 true。这使得 MongoDB 在连接到启用 TLS 的服务器时使用系统范围的 CA 证书存储。

如果使用 x.509 身份验证，则必须指定 --tlsCAFile 或 tls.CAFile，除非使用 --tlsCertificateSelector。

有关 TLS 和 MongoDB 的详细信息，请参阅为 TLS/SSL 配置 mongod 和 mongos 以及客户端的 TLS/SSL 配置。

--tlsClusterFile <filename>

注意

在 macOS 或 Windows 上，您可以使用操作系统安全存储区中的证书而不是 PEM 密钥文件。请参阅 --tlsClusterCertificateSelector。

指定包含 x.509 证书密钥文件的 .pem 文件，用于群集或副本集的成员身份验证。

如果 --tlsClusterFile 没有为内部集群身份验证指定 .pem 文件，或者未指定备选 --tlsClusterCertificateSelector，则集群使用在 --tlsCertificateKeyFile 选项中指定的 .pem 文件，或使用由 --tlsCertificateSelector 返回的证书。

如果使用 x.509 身份验证，则必须指定 --tlsCAFile 或 tls.CAFile，除非使用 --tlsCertificateSelector。

如果显示的 x.509 证书在 mongod/mongos 主机系统时间后的 30 天内过期，则 mongod / mongos 会在连接时记录警告。

有关 TLS 和 MongoDB 的详细信息，请参阅为 TLS/SSL 配置 mongod 和 mongos 以及客户端的 TLS/SSL 配置。

--tlsClusterPassword <value>

指定用于解密 x.509 证书密钥文件（由 --tlsClusterFile 指定）的密码。仅当证书密钥文件已加密时才能使用 --tlsClusterPassword 选项。在所有情况下，mongos 都会对所有日志记录和报告输出中的密码进行脱敏。

• 在 Linux/BSD 上，如果 x.509 文件中的私钥已加密且未指定 --tlsClusterPassword 选项，MongoDB 则会提示输入密码。请参阅 TLS/SSL 证书密码。

• 在 macOS 或 Windows 上，如果 x.509 文件中的私钥已加密，则必须显式指定 --tlsClusterPassword 选项。另外，也可以使用安全系统存储区中的证书（请参阅 --tlsClusterCertificateSelector）而不是集群 PEM 文件，或者使用未加密的 PEM 文件。

有关 TLS 和 MongoDB 的详细信息，请参阅为 TLS/SSL 配置 mongod 和 mongos 以及客户端的 TLS/SSL 配置。

--tlsCAFile <filename>

指定包含来自证书颁发机构的根证书链的 .pem 文件。使用相对或绝对路径指定 .pem 文件的文件名。

在 macOS 或 Windows 上，您可以使用操作系统安全存储区中的证书而不是 PEM 密钥文件。请参阅 --tlsCertificateSelector。使用安全存储区时，您不需要（但也可以）指定 --tlsCAFile。

有关 TLS 和 MongoDB 的详细信息，请参阅为 TLS/SSL 配置 mongod 和 mongos 以及客户端的 TLS/SSL 配置。

--tlsClusterCAFile <filename>

指定包含来自证书授权机构的根证书链的 .pem 文件，用于验证建立连接的客户端提供的证书。使用相对或绝对路径指定 .pem 文件的文件名。

如果 --tlsClusterCAFile 未指定 .pem 文件来验证建立连接的客户端的证书，集群就会使用 --tlsCAFile 选项中指定的 .pem 文件。

--tlsClusterCAFile 允许您使用单独的证书颁发机构来验证 TLS 握手的客户端到服务器和服务器到客户端部分。

在 macOS 或 Windows 上，您可以使用操作系统安全存储区中的证书而不是 PEM 密钥文件。请参阅 --tlsClusterCertificateSelector。使用安全存储区时，您不需要（但也可以）指定 --tlsClusterCAFile。

需要设置 --tlsCAFile。

有关 TLS 和 MongoDB 的详细信息，请参阅为 TLS/SSL 配置 mongod 和 mongos 以及客户端的 TLS/SSL 配置。

--tlsCertificateSelector <parameter>=<value>

注意

可在 Windows 和 macOS 上用作 --tlsCertificateKeyFile 的替代方案。

--tlsCertificateKeyFile 和 --tlsCertificateSelector 选项是互斥的。您只能指定一个。

指定证书属性，以便从操作系统的证书存储中选择匹配的证书。

--tlsCertificateSelector 接受格式为 <property>=<value> 的参数，其中属性可以是以下之一：

属性	值类型	说明
subject	ASCII 字符串	证书上的主题名称或公用名
thumbprint	十六进制字符串	以十六进制表示的字节序列，用于通过 SHA-1 摘要识别公钥。 thumbprint 有时称为 fingerprint。

在使用系统 SSL 证书存储区时，会用 OCSP（在线证书状态协议）来验证证书的吊销状态。

注意

当使用 net.tls.certificateSelector 或将 --tlsCertificateSelector 设为 thumbprint 时，您无法使用 rotateCertificates 命令或 db.rotateCertificates() Shell 方法

--tlsClusterCertificateSelector <parameter>=<value>

注意

可在 Windows 和 macOS 上用作 --tlsClusterFile 的替代方案。

--tlsClusterFile 和 --tlsClusterCertificateSelector 选项是互斥的。您只能指定一个。

指定证书属性，以便从操作系统的证书存储区中选择匹配的证书用于内部 x.509 成员身份验证。

--tlsClusterCertificateSelector 接受格式为 <property>=<value> 的参数，其中属性可以是以下之一：

属性	值类型	说明
subject	ASCII 字符串	证书上的主题名称或公用名
thumbprint	十六进制字符串	以十六进制表示的字节序列，用于通过 SHA-1 摘要识别公钥。 thumbprint 有时称为 fingerprint。

如果显示的 x.509 证书在 mongod/mongos 主机系统时间后的 30 天内过期，则 mongod / mongos 会在连接时记录警告。

--tlsCRLFile <filename>

指定包含证书吊销列表的 .pem 文件。使用相对或绝对路径指定 .pem 文件的文件名。

注意

• macOS 上无法指定 CRL 文件。相反，您可以使用系统 SSL 证书存储，它使用 OCSP（在线证书状态协议）来验证证书的吊销状态。要使用系统 SSL 证书存储，请参阅 --tlsCertificateSelector。

• 为了检查证书吊销状况，MongoDB 默认enables OCSP（在线证书状态协议）作为指定 CRL 文件或使用系统 SSL 证书存储区的替代方法。

有关 TLS 和 MongoDB 的详细信息，请参阅为 TLS/SSL 配置 mongod 和 mongos 以及客户端的 TLS/SSL 配置。

--tlsAllowConnectionsWithoutCertificates

默认情况下，服务器会绕过客户端证书验证，除非将服务器配置为使用 CA 文件。如果提供了 CA 文件，则会应用以下规则：

• 对于不提供证书的客户端，mongod 或 mongos 会对 TLS/SSL 连接进行加密（假定已成功建立连接）。

• 对于提供证书的客户端，mongos 会使用 --tlsCAFile 指定的根证书链来执行证书验证，并拒绝证书无效的客户端。

如果您的混合部署包含不向或不能向 mongos 提供证书的客户端，请使用 --tlsAllowConnectionsWithoutCertificates 选项。

有关 TLS 和 MongoDB 的详细信息，请参阅为 TLS/SSL 配置 mongod 和 mongos 以及客户端的 TLS/SSL 配置。

--tlsAllowInvalidCertificates

绕过对集群中其他服务器上的 TLS 证书进行验证检查，并允许使用无效证书进行连接。

注意

如果您在使用 x.509 身份验证时指定 --tlsAllowInvalidCertificates 或 tls.allowInvalidCertificates: true，则无效证书仅足以建立 TLS 连接，但不足以进行身份验证。

使用 --tlsAllowInvalidCertificates 设置时，MongoDB 会记录有关使用无效证书的警告。

有关 TLS 和 MongoDB 的详细信息，请参阅为 TLS/SSL 配置 mongod 和 mongos 以及客户端的 TLS/SSL 配置。

--tlsAllowInvalidHostnames

连接副本集或分片集群的其他成员以进行进程间身份验证时，禁用 TLS 证书中的主机名验证。这样即便其他成员的证书中的主机名与配置的主机名不匹配，mongos 也能与这些成员连接。

有关 TLS 和 MongoDB 的详细信息，请参阅为 TLS/SSL 配置 mongod 和 mongos 以及客户端的 TLS/SSL 配置。

--tlsDisabledProtocols <protocol(s)>

防止使用 TLS 运行的 MongoDB Server 接受使用特定协议的传入连接。要指定多个协议，请使用逗号分隔的协议列表。

--tlsDisabledProtocols 可识别以下协议：TLS1_0、TLS1_1、TLS1_2 和 TLS1_3。

• 在 macOS 上，您无法在禁用 TLS1_1 的情况下，让 TLS1_0 和 TLS1_2 同时启用。您必须至少禁用后两者中的一个，比如 TLS1_0,TLS1_1。

• 若要列出多个协议，请指定为逗号分隔的协议列表，例如 TLS1_0,TLS1_1。

• 指定无法识别的协议会阻止服务器启动。

• 指定的禁用协议将覆盖任何默认禁用的协议。

如果系统支持 TLS 1.1+，MongoDB 将禁用 TLS 1.0。要启用已禁用的 TLS 1.0，请将 none 指定为 --tlsDisabledProtocols。

副本集和分片集群的成员必须至少使用一个共同协议。

提示

另请参阅：

禁用协议

--tlsFIPSMode

指示 mongos 使用 TLS 库的 FIPS 模式。系统必须有符合 FIPS 标准的库，才能使用 --tlsFIPSMode 选项。

注意

只有 MongoDB Enterprise 支持与 FIPS 兼容的 TLS/SSL。有关更多信息，请参阅为 FIPS 配置 MongoDB 。

审核选项

--auditCompressionMode

5.3 版本中的新增功能。

指定压缩模式以进行审核日志加密。您还须使用 --auditEncryptionKeyUID 或 --auditLocalKeyFile 启用审核日志加密。

--auditCompressionMode 可以设置为以下值之一：

值	说明
zstd	使用 zstd 算法压缩审核日志。
none （默认）	请勿压缩审核日志。

注意

仅在 MongoDB Enterprise 中可用。MongoDB Enterprise 和 Atlas 有不同的配置要求。

--auditDestination

启用审核并指定 mongos 发送所有审核事件的位置。

--auditDestination 可能的值：

值	说明
syslog	将审核事件以 JSON 格式输出到系统日志中。在 Windows 上不可用。审核消息的系统日志严重性级别为 info，设施级别为 info。 系统日志消息限制可能会导致审核消息被截断。审核系统既不会检测此类截断，也不会在其出现时报错。
console	将审核事件以 JSON 格式输出到 stdout。
file	以 --auditFormat 中指定的格式将审核事件输出到 --auditPath 中指定的文件。

注意

仅在 MongoDB Enterprise 和 MongoDB Atlas 中有用。

--auditEncryptionKeyUID

6.0 版本中的新功能。

指定用于审核日志加密的 Key Management Interoperability Protocol (KMIP) 密钥的唯一标识符。

--auditEncryptionKeyUID 和 --auditLocalKeyFile 不能一起使用。

注意

仅在 MongoDB Enterprise 中可用。MongoDB Enterprise 和 Atlas 有不同的配置要求。

--auditFormat

如果 --auditDestination为 file，则指定用于审核的输出文件格式。--auditFormat 选项可为以下任一个值：

值	说明
JSON	将 JSON 格式的审核事件输出到 --auditPath 中指定的文件。
BSON	以 BSON 二进制格式将审核事件输出到 --auditPath 中指定的文件。

与以 BSON 格式打印相比，将 Atlas 审核事件以 JSON 格式打印到文件更可能导致服务器性能下降。

注意

仅在 MongoDB Enterprise 和 MongoDB Atlas 中有用。

--auditLocalKeyFile

5.3 版本中的新增功能。

指定本地审核密钥文件的路径和文件名，用于审核日志加密。

注意

由于该密钥不安全，仅使用 --auditLocalKeyFile 进行测试。要保护密钥的安全，请使用 --auditEncryptionKeyUID 和外部 Key Management Interoperability Protocol (KMIP) 服务器。

--auditLocalKeyFile 和 --auditEncryptionKeyUID 不能一起使用。

注意

仅在 MongoDB Enterprise 中可用。MongoDB Enterprise 和 Atlas 有不同的配置要求。

--auditPath

如果 --auditDestination 的值为 file，则指定用于审核的输出文件。该 --auditPath 选项可以使用完整路径名或相对路径名。

注意

仅在 MongoDB Enterprise 和 MongoDB Atlas 中有用。

--auditFilter

指定用于限制审核系统记录的操作类型的筛选器。该选项采用以下形式的查询文档的字符串表示形式：

{ <field1>: <expression1>, ... }

<field> 可以是审核消息中的任意字段，包括参数文档中返回的字段。<expression> 是查询条件表达式。

要指定 Atlas 审核过滤器，请将过滤器文档括在单引号 中，以将文档作为字符串传递。

要在配置文件中指定审核筛选器，必须使用配置文件的 YAML 格式。

注意

仅在 MongoDB Enterprise 和 MongoDB Atlas 中有用。

分析器选项

--slowms <integer>

默认值：100

慢速操作时长阈值（以毫秒为单位）。运行时长超过此阈值的操作被视为慢速操作。

当 logLevel 设置为 0 时，MongoDB 会将慢速操作记录到诊断日志中，记录速度由 slowOpSampleRate 确定。

在较高的 logLevel 设置下，所有操作无论延迟如何，都会显示在诊断日志中。

对于 mongos 实例，仅影响诊断日志而不影响分析器，因为 mongos 无法使用分析。

--slowOpSampleRate <double>

默认值：1.0

应记录的慢操作比例。--slowOpSampleRate 接受 0 到 1（含）之间的值。

对于 mongos 实例，--slowOpSampleRate 仅影响诊断日志而不影响分析器，因为 mongos 无法使用分析。

LDAP 身份验证和授权选项

--ldapServers <host1>:<port>,<host2>:<port>,...,<hostN>:<port>

仅在 MongoDB Enterprise 中可用。

特定 LDAP 服务器，mongos 在该服务器上对用户进行身份验证或决定授权用户可对给定数据库执行哪些操作。如果指定的 LDAP 服务器有任何复制的实例，则可以在逗号分隔的列表中指定每个复制的服务器的主机和端口。

如果您的 LDAP 基础架构将 LDAP 目录分区到多个 LDAP 服务器，请将一个LDAP 服务器或其任何复制实例指定为--ldapServers 。 MongoDB 支持 RFC45114.1 中定义的以下 LDAP10 引用。 。请勿使用--ldapServers列出基础架构中的每台 LDAP 服务器。

可以在运行中的 mongos 上配置此设置，但需使用 setParameter。

如果未设置，mongos 无法使用 LDAP 身份验证或授权。

--ldapValidateLDAPServerConfig <boolean>

在 MongoDB Enterprise 中可用

一个标记，其确定 mongos 实例是否在启动时检查 LDAP server(s) 的可用性：

• 如果为 true，则 mongos 实例执行可用性检查，并且仅在 LDAP 服务器可用时才继续启动。

• 如果为 false，则 mongos 实例将跳过可用性检查；也就是说，即使 LDAP 服务器不可用，实例也会启动。

--ldapQueryUser <string>

仅在 MongoDB Enterprise 中可用。

mongos 连接到 LDAP 服务器或在该服务器上执行查询时所绑定的身份。

仅当满足以下任一条件时才需要：

• 使用 LDAP 授权。

• 将 LDAP 查询用于 username transformation

• LDAP 服务器不允许匿名绑定

您必须使用 --ldapQueryUser 和 --ldapQueryPassword。

如果未设置，则 mongos 不会尝试绑定到 LDAP 服务器。

可以在运行中的 mongos 上配置此设置，但需使用 setParameter。

注意

Windows MongoDB 部署可以使用 --ldapBindWithOSDefaults 而不是 --ldapQueryUser 和 --ldapQueryPassword。不能同时指定 --ldapQueryUser 和 --ldapBindWithOSDefaults。

--ldapQueryPassword <string>

仅在 MongoDB Enterprise 中可用。

使用 --ldapQueryUser 时用于绑定到 LDAP 服务器的密码。您必须使用 --ldapQueryPassword 与 --ldapQueryUser。

如果未设置，则 mongos 不会尝试绑定到 LDAP 服务器。

可以在运行中的 mongos 上配置此设置，但需使用 setParameter。

注意

Windows MongoDB 部署可以使用 --ldapBindWithOSDefaults 而不是 --ldapQueryPassword 和 --ldapQueryPassword。不能同时指定 --ldapQueryPassword 和 --ldapBindWithOSDefaults。

--ldapBindWithOSDefaults <bool>

默认：false

仅在 Windows 平台上的 MongoDB Enterprise 中可用。

在连接 LDAP 服务器时，允许 mongos 使用您的 Windows 登录档案进行身份验证或绑定。

仅在以下情况下才需要：

• 使用 LDAP 授权。

• 将 LDAP 查询用于 username transformation

• LDAP 服务器不允许匿名绑定

使用 --ldapBindWithOSDefaults 替换 --ldapQueryUser 和 --ldapQueryPassword。

--ldapBindMethod <string>

默认值：简单

仅在 MongoDB Enterprise 中可用。

mongos 用于对 LDAP 服务器进行身份验证的方法。与 --ldapQueryUser 和 --ldapQueryPassword 一起使用以连接到 LDAP 服务器。

--ldapBindMethod 支持以下值：

• simple - mongos 使用简单身份验证。

• sasl mongos 使用 SASL 协议进行身份验证

如果指定 sasl，则可以使用 --ldapBindSaslMechanisms 配置可用的 SASL 机制。mongos 默认使用 DIGEST-MD5 机制。

--ldapBindSaslMechanisms <string>

默认值：DIGEST-MD5

仅在 MongoDB Enterprise 中可用。

以逗号分隔的 SASL 机制列表，mongos 可使用此列表向 LDAP 服务器进行身份验证。mongos 和 LDAP 服务器必须就至少一种机制达成一致。mongos 可在运行时动态加载主机上安装的任何 SASL 机制库。

可在 mongos 主机以及远程 LDAP 服务器主机上安装和配置所选 SASL 机制的相应库。默认情况下，操作系统可能包含某些 SASL 库。请遵循与每个 SASL 机制相关的文档来获取有关安装和配置的指南。

如果将GSSAPI SASL 机制与自托管部署上的Kerberos身份验证结合使用，请验证mongos托管的以下内容：

Linux

• KRB5_CLIENT_KTNAME 环境变量会解析为主机客户端 Linux Keytab 文件的名称。有关 Kerberos 环境变量的更多信息，请参阅 Kerberos 文档。

• 客户端密钥表包含供 mongos 连接到 LDAP 服务器并执行 LDAP 查询时使用的用户主体。

Windows

如果连接到 Active Directory 服务器，Windows Kerberos 配置会在用户登录系统时自动生成 Ticket-Granting-Ticket。将 --ldapBindWithOSDefaults 设置为 true 以允许 mongos 在连接到 Active Directory 服务器时使用生成的凭证并执行查询。

将 --ldapBindMethod 设置为 sasl 以使用此选项。

注意

有关 SASL 机制的完整列表，请参阅 IANA 列表。请参阅 LDAP 或 Active Directory 服务的文档来识别与该服务兼容的 SASL 机制。

MongoDB 不是 SASL 机制库的来源，MongoDB 文档也不是安装或配置任何给定 SASL 机制的权威来源。如需获得文档和支持，请咨询 SASL 机制库供应商或所有者。

有关 SASL 的更多信息，请参阅以下资源：

• 对于 Linux，请参阅 Cyrus SASL 文档。

• 对于 Windows，请参阅 Windows SASL 文档。

--ldapTransportSecurity <string>

默认值：tls

仅在 MongoDB Enterprise 中可用。

默认情况下， mongos 会创建与 LDAP 服务器的 TLS/SSL 安全连接。

对于 Linux 部署，必须在 /etc/openldap/ldap.conf 文件中配置相应的 TLS 选项。操作系统的程序包管理器通过 libldap 依赖项创建此文件作为 MongoDB Enterprise 安装的一部分。有关更完整的说明，请参阅 ldap.conf OpenLDAP 文档中的 TLS Options。

在 Windows 上部署时，必须将 LDAP 服务器 CA 证书添加到 Windows 证书管理工具中。该工具的确切名称和功能可能会因操作系统版本而异。有关证书管理的更多信息，请参阅您的 Windows 版本对应的文档。

将 --ldapTransportSecurity 设置为 none，可在 mongos 与 LDAP 服务器之间禁用 TLS/SSL。

警告

将--ldapTransportSecurity设置为none可在mongos和 LDAP 服务器之间传输纯文本信息，可能还传输凭证。

--ldapTimeoutMS <int>

默认值：10000

仅在 MongoDB Enterprise 中可用。

mongos 应等待 LDAP 服务器响应请求的时间，以毫秒为单位。

如果失败的根源是连接超时，增加 --ldapTimeoutMS 的值可以防止 MongoDB 服务器和 LDAP 服务器之间的连接失败。降低 --ldapTimeoutMS 的值会缩短 MongoDB 等待 LDAP 服务器响应的时间。

可以在运行中的 mongos 上配置此设置，但需使用 setParameter。

--ldapRetryCount <int>

6.1 版本新增内容。

默认值：0

仅在 MongoDB Enterprise 中可用。

在出现网络错误后服务器 LDAP 管理器重试的操作数。

--ldapUserToDNMapping <string>

仅在 MongoDB Enterprise 中可用。

将提供给 mongos 进行身份验证的用户名映射到 LDAP 标识名 (DN)。以下情况下，可能需要使用 --ldapUserToDNMapping 将用户名转换为 LDAP DN：

• 通过 LDAP 简单绑定进行 LDAP 身份验证，其中用户使用非完整 LDAP DN 的用户名向 MongoDB 进行身份验证。

• 使用需要 DN 的 LDAP authorization query template。

• 使用不同的身份验证机制（如 x.509、kerberos）将向 Mongo DB 进行身份验证的客户端的用户名转换为完整的 LDAP DN，以进行授权。

--ldapUserToDNMapping 需要一个用引号括住的 JSON 字符串，代表一个有序的文档数组。每个文档都包含正则表达式 match 以及用于转换传入用户名的 substitution 或 ldapQuery 模板。

数组中的每个文档均采用以下形式：

{
  match: "<regex>"
  substitution: "<LDAP DN>" | ldapQuery: "<LDAP Query>"
}

字段	说明	例子
match	ECMAScript 格式的正则表达式 (regex)，用于与提供的用户名进行匹配。每个括号括起来的部分表示 substitution 或 ldapQuery 使用的正则表达式捕获组。	"(.+)ENGINEERING" "(.+)DBA"
substitution	LDAP 标识名 (DN) 格式模板，该模板将 match 正则表达式匹配的身份验证名称转换为 LDAP DN。每个大括号内的数值都替换为相应的正则表达式捕获组，这些捕获组是通过 match 正则表达式从身份验证用户名中提取而来的。 替换的结果必须是 RFC4514 转义字符串。	"cn={0},ou=engineering, dc=example,dc=com"
ldapQuery	LDAP 查询格式模板，该模板将匹配 match 正则表达式的身份验证名称插入到按照 RFC4515 和 RFC4516 编码的 LDAP 查询 URI 中。每个大括号内的数值都替换为相应的正则表达式捕获组，这些捕获组是通过 match 表达式从身份验证用户名中提取而来的。mongos 针对 LDAP 服务器执行查询，以检索经身份验证用户的 LDAP DN。mongos 要求只有一个返回结果才能转换成功，也可以通过 mongos 跳过此转换。	"ou=engineering,dc=example, dc=com??one?(user={0})"

注意

对 RFC4514、 RFC4515、RFC4516 或 LDAP 查询的解释超出了 MongoDB 文档的范围。请直接查看 RFC 或使用您首选的 LDAP 资源。

对于数组中的每个文档，必须使用 substitution 或 ldapQuery。不能在同一文档中同时指定两者。

执行身份验证或授权时，mongos 按给定顺序遍历数组中的每个文档，对照 match 筛选器检查身份验证用户名。如果发现匹配，mongos 就会进行转换，并使用输出结果对用户进行身份验证。mongos 不会检查数组中的其余文档。

如果给定文档与提供的身份验证名称不匹配，mongos 会继续浏览文档列表以查找其他匹配项。如果在任何文档中均未找到匹配项，或者文档描述的转换失败，mongos 将返回错误信息。

mongos 也会返回错误（如果由于 LDAP 服务器网络或身份验证失败而无法评估某项转换）。mongos 会拒绝连接请求，不检查数组中的其余文档。

从 MongoDB 5.0 开始，--ldapUserToDNMapping 接受空字符串 "" 或空数组 [ ] 来代替映射文档。如果向 --ldapUserToDNMapping 提供空字符串或空数组，则 MongoDB 会将已经过身份验证的用户名映射为 LDAP DN。以前，提供空映射文档会导致映射失败。

例子

下面展示了两个转换文档。第一个文档匹配以 @ENGINEERING 结尾的任何字符串，将后缀前面的所有内容放入正则表达式捕获组中。第二个文档匹配以 @DBA 结尾的任何字符串，将后缀前面的所有内容放入正则表达式捕获组中。

重要

必须将数组作为字符串传递给 --ldapUserToDNMapping。

"[
   {
      match: "(.+)@ENGINEERING.EXAMPLE.COM",
      substitution: "cn={0},ou=engineering,dc=example,dc=com"
   },
   {
      match: "(.+)@DBA.EXAMPLE.COM",
      ldapQuery: "ou=dba,dc=example,dc=com??one?(user={0})"
   }
]"

用户名为 alice@ENGINEERING.EXAMPLE.COM 的用户匹配第一个文档。正则表达式捕获群组 {0} 对应于字符串 alice。生成的输出是 DN "cn=alice,ou=engineering,dc=example,dc=com"。

用户名为 bob@DBA.EXAMPLE.COM 的用户匹配第二个文档。正则表达式捕获群组 {0} 对应于字符串 bob。生成的输出是 LDAP 查询 "ou=dba,dc=example,dc=com??one?(user=bob)"。mongos 针对 LDAP 服务器执行此查询，并返回结果 "cn=bob,ou=dba,dc=example,dc=com"。

如果未设置 --ldapUserToDNMapping，则 mongos 在尝试通过 LDAP 服务器对用户进行身份验证或授权时，不会对用户名进行转换。

可以在运行中的 mongos 上配置此设置，但需使用 setParameter 数据库命令。

其他选项

--ipv6

启用 IPv6 支持。默认情况下，mongos 禁用 IPv6 支持。

设置 --ipv6 不会指示 mongos 侦听任何本地 IPv6 地址或接口。要将 mongos 配置为侦听 IPv6 接口，您必须：

• 使用一个或多个 IPv6 地址或解析为 IPv6 地址的主机名配置 --bind_ip，或

• 将 --bind_ip_all 设为 true。