mongos
Synopsis
对于分片集群,mongos
实例提供客户端应用程序与分片群集之间的接口。mongos
实例将查询和写入操作路由到分片。从应用程序的角度来看,mongos
实例的行为与任何其他 MongoDB 实例相同。
Considerations
切勿更改
mongos
二进制文件的名称。mongos
支持对冲读,以尽量降低延迟。MongoDB 在支持 TLS 1.1+ 的系统上禁用对 TLS 1.0 加密的支持。
mongos
mongod
二进制文件无法连接到特征兼容性版本(FCV) 高于 的mongos
实例。示例,您无法将MongoDB.5 0版本mongos
60连接到FCV设立为. 6的.0 分片集群。不过,您可以将MongoDB.5 0版本mongos
6连接到.0 分片集群,并将FCV设立为. 50。mongod
包括全时诊断数据捕获机制,以协助 MongoDB 工程师对部署进行故障排除。如果该线程失败,它将终止原始进程。为了避免出现最常见的故障,请确认运行该进程的用户有权创建 FTDCdiagnostic.data
目录。对于mongod
,该目录位于storage.dbPath
内。对于mongos
,该目录与systemLog.path
并行。
选项
注意
MongoDB 弃用 SSL 选项,新增相应的 TLS 选项。
MongoDB 添加了
--tlsClusterCAFile
/net.tls.clusterCAFile
。
注意
MongoDB 5.0 删除
--serviceExecutor
命令行选项和相应的net.serviceExecutor
配置选项。
核心选项
--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
会返回错误并终止。有关扩展指令的更多信息,请参阅配置文件的自管理部署的源自外部的配置文件值。
--quiet
在尝试限制输出量的安静模式下运行
mongos
。该选项会抑制:
数据库命令输出
复制活动
连接接受事件
连接关闭事件
--port <port>
默认值:27017
mongos
实例侦听客户端连接的 TCP 端口。在版本 6.0.12 中进行了更改:
--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 地址 (
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
的值设为略高于客户端创建的最大连接数或连接池的最大大小。
--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 地址
--unixSocketPrefix <path>
默认:/tmp
UNIX 套接字的路径。
--unixSocketPrefix
仅适用于基于 Unix 的系统。如果此选项没有值,则
mongos
进程将创建一个以/tmp
作为前缀的套接字。MongoDB 创建并侦听 UNIX 套接字,除非满足以下条件之一:net.unixDomainSocket.enabled
isfalse
--nounixsocket
已设置net.bindIp
未设置net.bindIp
未指定localhost
或其相关 IP 地址
--filePermissions <path>
默认值:
0700
设置 UNIX 域套接字文件的权限。
--filePermissions
仅适用于基于 Unix 的系统。
--fork
启用后台运行
mongos
进程的守护进程模式。--fork
选项在 Windows 系统上不受支持。默认情况下,
mongos
不作为守护进程运行。您可以使用--fork
或处理守护进程的控制进程将mongos
作为守护进程运行,例如upstart
或systemd
。使用
--fork
选项需要使用以下任一选项配置mongos
的日志输出:
--transitionToAuth
允许
mongos
接受和创建与部署中其他mongod
和mongos
实例之间的经过身份验证和未经身份验证的连接。用于执行副本集或分片集群从无身份验证配置到内部身份验证的滚动过渡。需要指定内部身份验证机制,例如--keyFile
。例如,如果使用密钥文件进行内部身份验证,
mongos
会使用匹配的密钥文件与部署中的任何mongod
或mongos
创建经身份验证的连接。如果安全机制不匹配,则mongos
将改用未经身份验证的连接。使用
--transitionToAuth
运行的mongos
不会强制实施用户访问控制。用户无需任何访问控制检查即可连接到您的部署并执行读取、写入和管理操作。注意
使用内部身份验证且不使用
--transitionToAuth
运行的mongos
要求客户端使用用户访问控制进行连接。更新客户端以在重新启动mongos
之前使用适当的用户连接到mongos
,而无需--transitionToAuth
。
--networkMessageCompressors <string>
Default: snappy,zstd,zlib
指定默认压缩程序用于此
mongos
实例与以下对象之间的通信:分片集群的其他节点
支持
OP_COMPRESSED
消息格式的驱动程序。
MongoDB 支持以下压缩程序:
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
返回这些选项的解析值。警告
这可能包括之前通过外部来源进行模糊处理的任何配置的密码或密钥。
有关用法示例,请参阅:
分片集群选项
--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 文件,则会应用以下规则:
对于提供证书的客户端,
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
中指定的格式将Atlas 审核事件输出到 中指定的文件。注意
仅在 MongoDB Enterprise 和 MongoDB Atlas 中有用。
--auditEncryptionKeyUID
6.0 版本中的新功能。
指定用于审核日志加密的 Key Management Interoperability Protocol (KMIP) 密钥的唯一标识符。
--auditEncryptionKeyUID
和--auditLocalKeyFile
不能一起使用。注意
仅在 MongoDB Enterprise 中可用。MongoDB Enterprise 和 Atlas 有不同的配置要求。
--auditFormat
如果
--auditDestination
为file
,则指定用于审核的输出文件格式。--auditFormat
选项可为以下任一个值:值说明JSON
将Atlas 审核事件以JSON格式输出到
--auditPath
中指定的文件。BSON
将BSON二进制格式的Atlas 审核事件输出到
--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 <long>
默认值:10000
仅在 MongoDB Enterprise 中可用。
mongos
应等待 LDAP 服务器响应请求的时间,以毫秒为单位。如果失败的根源是连接超时,增加
--ldapTimeoutMS
的值可以防止 MongoDB 服务器和 LDAP 服务器之间的连接失败。降低--ldapTimeoutMS
的值会缩短 MongoDB 等待 LDAP 服务器响应的时间。可以在运行中的
mongos
上配置此设置,但需使用setParameter
。
--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
"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})"
对于数组中的每个文档,必须使用
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
。