diff options
Diffstat (limited to 'debian/mongos.1')
| -rw-r--r-- | debian/mongos.1 | 1298 |
1 files changed, 1106 insertions, 192 deletions
diff --git a/debian/mongos.1 b/debian/mongos.1 index 72fb11495e8..f1a5c14f9b6 100644 --- a/debian/mongos.1 +++ b/debian/mongos.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "MONGOS" "1" "Jun 21, 2018" "4.0" "mongodb-manual" +.TH "MONGOS" "1" "Jul 25, 2019" "4.2" "mongodb-manual" .SH NAME mongos \- MongoDB Sharded Cluster Query Router . @@ -41,26 +41,52 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .UNINDENT .SH SYNOPSIS .sp -\fI\%mongos\fP for “MongoDB Shard,” is a routing service for -MongoDB shard configurations that processes queries from the -application layer, and determines the location of this data in the -sharded cluster, in order to complete these operations. -From the perspective of the application, a -\fI\%mongos\fP instance behaves identically to any other MongoDB -instance. -.sp -\fBNOTE:\fP +For a sharded cluster, the \fI\%mongos\fP +instances provide the interface between the client applications and the +sharded cluster. The \fI\%mongos\fP instances route queries and +write operations to the shards. From the perspective of the +application, a \fI\%mongos\fP instance behaves identically to +any other MongoDB instance. +.SH CONSIDERATIONS .INDENT 0.0 -.INDENT 3.5 +.IP \(bu 2 +Never change the name of the \fI\%mongos\fP binary. +.IP \(bu 2 Starting in version 4.0, MongoDB disables support for TLS 1.0 encryption on systems where TLS 1.1+ is available. For more details, see 4.0\-disable\-tls\&. +.IP \(bu 2 +Starting in MongoDB 4.0, the \fI\%mongos\fP binary will crash when +attempting to connect to \fBmongod\fP instances whose +feature compatibility version (fCV) is greater than +that of the \fI\%mongos\fP\&. For example, you cannot connect +a MongoDB 4.0 version \fI\%mongos\fP to a 4.2 +sharded cluster with fCV set to 4.2\&. You +can, however, connect a MongoDB 4.0 version +\fI\%mongos\fP to a 4.2 sharded cluster with fCV set to 4.0\&. .UNINDENT -.UNINDENT -.SH CONSIDERATIONS -.sp -Never change the name of the \fI\%mongos\fP binary. .SH OPTIONS +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +conf\-file\-command\-line\-mapping +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.IP "Starting in version 4.2" +.INDENT 0.0 +.IP \(bu 2 +MongoDB deprecates the SSL options and insteads adds new +corresponding TLS options. +.IP \(bu 2 +MongoDB adds +\fI\%\-\-tlsClusterCAFile\fP/\fBnet.tls.clusterCAFile\fP\&. (Also availalbe +in 3.4.18+, 3.6.9+, 4.0.3+) +.UNINDENT +.UNINDENT +.UNINDENT .SS Core Options .INDENT 0.0 .TP @@ -87,6 +113,61 @@ including UTF\-8. .UNINDENT .INDENT 0.0 .TP +.B \-\-configExpand <none|rest|exec> +\fIDefault\fP: none +.sp +New in version 4.2. + +.sp +Enables using Expansion Directives +in configuration files. Expansion directives allow you to set +externally sourced values for configuration file options. +.sp +\fI\%\-\-configExpand\fP supports the following expansion directives: +.TS +center; +|l|l|. +_ +T{ +Value +T} T{ +Description +T} +_ +T{ +\fBnone\fP +T} T{ +Default. \fBmongos\fP does not expand expansion directives. +\fBmongos\fP fails to start if any configuration file settings +use expansion directives. +T} +_ +T{ +\fBrest\fP +T} T{ +\fBmongos\fP expands \fB__rest\fP expansion directives when +parsing the configuration file. +T} +_ +T{ +\fBexec\fP +T} T{ +\fBmongos\fP expands \fB__exec\fP expansion directives when +parsing the configuration file. +T} +_ +.TE +.sp +You can specify multiple expansion directives as a comma\-separated +list, e.g. \fBrest, exec\fP\&. If the configuration file contains +expansion directives not specified to \fI\%\-\-configExpand\fP, the \fBmongos\fP +returns an error and terminates. +.sp +See externally\-sourced\-values for configuration files +for more information on expansion directives. +.UNINDENT +.INDENT 0.0 +.TP .B \-\-verbose, \-v Increases the amount of internal reporting returned on standard output or in log files. Increase the verbosity with the \fB\-v\fP form by @@ -115,26 +196,26 @@ connection closed events .B \-\-port <port> \fIDefault\fP: 27017 .sp -Specifies the TCP port on which the MongoDB instance listens for +The TCP port on which the \fI\%mongos\fP instance listens for client connections. .UNINDENT .INDENT 0.0 .TP -.B \-\-bind_ip <ip address> +.B \-\-bind_ip <hostnames|ipaddresses|Unix domain socket paths> \fIDefault\fP: localhost .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Starting in MongoDB 3.6, \fBmongos\fP bind to localhost -(\fB127.0.0.1\fP) by default. See 3.6\-bind\-to\-localhost\&. +by default. See 3.6\-bind\-to\-localhost\&. .UNINDENT .UNINDENT .sp -The IP addresses and/or full Unix domain socket paths on which -\fBmongos\fP should listen for client connections. You may attach -\fBmongos\fP to any interface. To bind to multiple addresses, enter a -list of comma\-separated values. +The hostnames and/or IP addresses and/or full Unix domain socket +paths on which \fBmongos\fP should listen for client connections. You +may attach \fBmongos\fP to any interface. To bind to multiple +addresses, enter a list of comma\-separated values. .INDENT 7.0 .INDENT 3.5 .SS Example @@ -143,26 +224,83 @@ list of comma\-separated values. .UNINDENT .UNINDENT .sp +You can specify both IPv4 and IPv6 addresses, or hostnames that +resolve to an IPv4 or IPv6 address. +.INDENT 7.0 +.INDENT 3.5 +.SS Example +.sp +\fBlocalhost, 2001:0DB8:e132:ba26:0d5c:2774:e7f9:d513\fP +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +If specifying an IPv6 address \fIor\fP a hostname that resolves to an +IPv6 address to \fI\%\-\-bind_ip\fP, you must start \fBmongos\fP with +\fI\%\-\-ipv6\fP to enable IPv6 support. Specifying an IPv6 address +to \fI\%\-\-bind_ip\fP does not enable IPv6 support. +.UNINDENT +.UNINDENT +.sp +If specifying a +\fI\%link\-local IPv6 address\fP +(\fBfe80::/10\fP), you must append the +\fI\%zone index\fP +to that address (i.e. \fBfe80::<address>%<adapter\-name>\fP). +.INDENT 7.0 +.INDENT 3.5 +.SS Example +.sp +\fBlocalhost,fe80::a00:27ff:fee0:1fcf%enp0s3\fP +.UNINDENT +.UNINDENT +.INDENT 7.0 +.INDENT 3.5 +.SS Tip +.sp +When possible, use a logical DNS hostname instead of an ip address, +particularly when configuring replica set members or sharded cluster +members. The use of logical DNS hostnames avoids configuration +changes due to ip address changes. +.UNINDENT +.UNINDENT +.sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 -Before you bind to other ip addresses, consider enabling -access control and other security measures listed -in /administration/security\-checklist to prevent unauthorized -access. +Before binding to a non\-localhost (e.g. publicly accessible) +IP address, ensure you have secured your cluster from unauthorized +access. For a complete list of security recommendations, see +/administration/security\-checklist\&. At minimum, consider +enabling authentication and +hardening network infrastructure\&. .UNINDENT .UNINDENT .sp +For more information about IP Binding, refer to the +/core/security\-mongodb\-configuration documentation. +.sp To bind to all IPv4 addresses, enter \fB0.0.0.0\fP\&. .sp -To bind to all IPv4 and IPv6 addresses, enter \fB0.0.0.0,::\fP -or alternatively, use the \fBnet.bindIpAll\fP setting. +To bind to all IPv4 and IPv6 addresses, enter \fB::,0.0.0.0\fP or +starting in MongoDB 4.2, an asterisk \fB"*"\fP (enclose the asterisk in +quotes to avoid filename pattern expansion). Alternatively, use the +\fBnet.bindIpAll\fP setting. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 -\fB\-\-bind_ip\fP and \fB\-\-bind_ip_all\fP are mutually exclusive. That -is, you can specify one or the other, but not both. +.INDENT 0.0 +.IP \(bu 2 +\fB\-\-bind_ip\fP and \fB\-\-bind_ip_all\fP are mutually exclusive. +Specifying both options causes \fBmongos\fP to throw an error and +terminate. +.IP \(bu 2 +The command\-line option \fB\-\-bind\fP overrides the configuration +file setting \fBnet.bindIp\fP\&. +.UNINDENT .UNINDENT .UNINDENT .UNINDENT @@ -172,23 +310,32 @@ is, you can specify one or the other, but not both. New in version 3.6. .sp -If specified, the \fBmongos\fP instance binds to all ip addresses. When -attaching \fBmongos\fP to a publicly accessible interface, ensure -that you have implemented proper authentication and firewall -restrictions to protect the integrity of your database. +If specified, the \fBmongos\fP instance binds to all IPv4 +addresses (i.e. \fB0.0.0.0\fP). If \fBmongos\fP starts with +\fI\%\-\-ipv6\fP, \fI\%\-\-bind_ip_all\fP also binds to all IPv6 addresses +(i.e. \fB::\fP). +.sp +\fBmongos\fP only supports IPv6 if started with \fI\%\-\-ipv6\fP\&. Specifying +\fI\%\-\-bind_ip_all\fP alone does not enable IPv6 support. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 -Before you bind to other ip addresses, consider enabling -access control and other security measures listed -in /administration/security\-checklist to prevent unauthorized -access. +Before binding to a non\-localhost (e.g. publicly accessible) +IP address, ensure you have secured your cluster from unauthorized +access. For a complete list of security recommendations, see +/administration/security\-checklist\&. At minimum, consider +enabling authentication and +hardening network infrastructure\&. .UNINDENT .UNINDENT .sp -Alternatively, you can set the \fB\-\-bind_ip\fP option to -\fB0.0.0.0,::\fP to bind to all IP addresses. +For more information about IP Binding, refer to the +/core/security\-mongodb\-configuration documentation. +.sp +Alternatively, you can set the \fB\-\-bind_ip\fP option to \fB::,0.0.0.0\fP +or, starting in MongoDB 4.2, to an asterisk \fB"*"\fP (enclose the +asterisk in quotes to avoid filename pattern expansion). .sp \fBNOTE:\fP .INDENT 7.0 @@ -203,7 +350,7 @@ is, you can specify one or the other, but not both. .B \-\-maxConns <number> The maximum number of simultaneous connections that \fBmongos\fP will accept. This setting has no effect if it is higher than your operating -system’s configured maximum connection tracking threshold. +system\(aqs configured maximum connection tracking threshold. .sp Do not assign too low of a value to this option, or you will encounter errors during normal application operation. @@ -232,8 +379,8 @@ setting. .INDENT 0.0 .TP .B \-\-syslog -Sends all logging output to the host’s syslog system rather -than to standard output or to a log file. , as with \fI\%\-\-logpath\fP\&. +Sends all logging output to the host\(aqs syslog system rather +than to standard output or to a log file (\fI\%\-\-logpath\fP). .sp The \fI\%\-\-syslog\fP option is not supported on Windows. .sp @@ -247,6 +394,18 @@ recommend using the \fI\%\-\-logpath\fP option for production systems to ensure accurate timestamps. .UNINDENT .UNINDENT +.sp +Starting in version 4.2, MongoDB includes the component in its log messages to \fBsyslog\fP\&. +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +\&... ACCESS [repl writer worker 5] Unsupported modification to roles collection ... +.ft P +.fi +.UNINDENT +.UNINDENT .UNINDENT .INDENT 0.0 .TP @@ -255,14 +414,14 @@ ensure accurate timestamps. .sp Specifies the facility level used when logging messages to syslog. The value you specify must be supported by your -operating system’s implementation of syslog. To use this option, you +operating system\(aqs implementation of syslog. To use this option, you must enable the \fI\%\-\-syslog\fP option. .UNINDENT .INDENT 0.0 .TP .B \-\-logpath <path> Sends all diagnostic logging information to a log file instead of to -standard output or to the host’s syslog system. MongoDB creates +standard output or to the host\(aqs syslog system. MongoDB creates the log file at the path you specify. .sp By default, MongoDB will move any existing log file rather than overwrite @@ -287,8 +446,10 @@ potentially sensitive data stored on the database to the diagnostic log. Metadata such as error or operation codes, line numbers, and source file names are still visible in the logs. .sp -Use \fI\%\-\-redactClientLogData\fP in conjunction with encryption to assist compliance with regulatory -requirements. +Use \fI\%\-\-redactClientLogData\fP in conjunction with +/core/security\-encryption\-at\-rest and +/core/security\-transport\-encryption to assist compliance with +regulatory requirements. .sp For example, a MongoDB deployment might store Personally Identifiable Information (PII) in one or more collections. The \fBmongos\fP logs events @@ -377,6 +538,21 @@ that MongoDB instances use to authenticate to each other in a sharded cluster or replica set\&. \fI\%\-\-keyFile\fP implies \fBclient authorization\fP\&. See inter\-process\-auth for more information. +.sp +Starting in MongoDB 4.2, keyfiles for internal membership +authentication use YAML format to allow for +multiple keys in a keyfile. The YAML format accepts content of: +.INDENT 7.0 +.IP \(bu 2 +a single key string (same as in earlier versions), +.IP \(bu 2 +multiple key strings (each string must be enclosed in quotes), or +.IP \(bu 2 +sequence of key strings. +.UNINDENT +.sp +The YAML format is compatible with the existing single\-key +keyfiles that use the text file format. .UNINDENT .INDENT 0.0 .TP @@ -399,7 +575,7 @@ always listens on the UNIX socket unless one of the following is true: .IP \(bu 2 \fBnet.bindIp\fP is not set .IP \(bu 2 -\fBnet.bindIp\fP does not specify \fB127.0.0.1\fP +\fBnet.bindIp\fP does not specify \fBlocalhost\fP or its associated IP address .UNINDENT .sp New in version 2.6: \fBmongos\fP installed from official \&.deb and \&.rpm packages @@ -426,7 +602,7 @@ creates and listens on a UNIX socket unless one of the following is true: .IP \(bu 2 \fBnet.bindIp\fP is not set .IP \(bu 2 -\fBnet.bindIp\fP does not specify \fB127.0.0.1\fP +\fBnet.bindIp\fP does not specify \fBlocalhost\fP or its associated IP address .UNINDENT .UNINDENT .INDENT 0.0 @@ -482,21 +658,42 @@ prior to restarting \fBmongos\fP without \fI\%\-\-transitionToAuth\fP\&. .INDENT 0.0 .TP .B \-\-networkMessageCompressors <string> -New in version 3.4. - +\fIDefault\fP: snappy,zstd,zlib .sp -Changed in version 3.6: Add support for zlib compressor. +New in version 3.4. .sp -Enables network compression for communication between this -\fBmongos\fP instance and: +Specifies the default compressor(s) to use for +communication between this \fBmongos\fP instance and: .INDENT 7.0 .IP \(bu 2 other members of the sharded cluster .IP \(bu 2 -a \fBmongo\fP shell. +a \fBmongo\fP shell +.IP \(bu 2 +drivers that support the \fBOP_COMPRESSED\fP message format. .UNINDENT .sp +MongoDB supports the following compressors: +.INDENT 7.0 +.IP \(bu 2 +snappy +.IP \(bu 2 +zlib (Available starting in MongoDB 3.6) +.IP \(bu 2 +zstd (Available starting in MongoDB 4.2) +.UNINDENT +.sp +\fBIn versions 3.6 and 4.0\fP, \fBmongod\fP and +\fI\%mongos\fP enable network compression by default with +\fBsnappy\fP as the compressor. +.sp +\fBStarting in version 4.2\fP, \fBmongod\fP and +\fI\%mongos\fP instances default to both \fBsnappy,zstd,zlib\fP +compressors, in that order. +.sp +To disable network compression, set the value to \fBdisabled\fP\&. +.sp \fBIMPORTANT:\fP .INDENT 7.0 .INDENT 3.5 @@ -506,14 +703,6 @@ uncompressed. .UNINDENT .UNINDENT .sp -You can specify the following compressors: -.INDENT 7.0 -.IP \(bu 2 -snappy (Default) -.IP \(bu 2 -zlib -.UNINDENT -.sp If you specify multiple compressors, then the order in which you list the compressors matter as well as the communication initiator. For example, if a \fBmongo\fP shell specifies the following network @@ -596,6 +785,19 @@ mongos \-\-timeZoneInfo timezonedb\-2017b/ .UNINDENT .UNINDENT .UNINDENT +.INDENT 0.0 +.TP +.B \-\-outputConfig +New in version 4.2. + +.sp +Outputs the resolved YAML configuration document for the \fBmongos\fP +to \fBstdout\fP and halts the \fBmongos\fP instance. For configuration +options using externally\-sourced\-values, \fI\%\-\-outputConfig\fP returns the +resolved value for those options. This may include any configured +passwords or secrets previously obfuscated through the external +source. +.UNINDENT .SS Sharded Cluster Options .INDENT 0.0 .TP @@ -619,7 +821,7 @@ at least one of the members of the config server replica set. .nf .ft C sharding: - configDB: <configReplSetName>/cfg1.example.net:27017, cfg2.example.net:27017,... + configDB: <configReplSetName>/cfg1.example.net:27019, cfg2.example.net:27019,... .ft P .fi .UNINDENT @@ -637,7 +839,7 @@ port of different members of the replica set. Specifies the ping time, in milliseconds, that \fI\%mongos\fP uses to determine which secondary replica set members to pass read operations from clients. The default value of \fB15\fP corresponds to -the default value in all of the client drivers\&. +the default value in all of the client \fI\%drivers\fP\&. .sp When \fI\%mongos\fP receives a request that permits reads to secondary members, the \fI\%mongos\fP will: @@ -664,40 +866,23 @@ See the replica\-set\-read\-preference\-behavior\-member\-selection section of the read preference documentation for more information. .UNINDENT -.SS TLS/SSL Options +.SS TLS Options .INDENT 0.0 .INDENT 3.5 .SS See .sp /tutorial/configure\-ssl for full -documentation of MongoDB’s support. -.UNINDENT +documentation of MongoDB\(aqs support. .UNINDENT -.INDENT 0.0 -.TP -.B \-\-sslOnNormalPorts -Deprecated since version 2.6: Use \fI\%\-\-sslMode requireSSL\fP instead. - -.sp -Enables TLS/SSL for \fBmongos\fP\&. -.sp -With \fI\%\-\-sslOnNormalPorts\fP, a \fBmongos\fP requires TLS/SSL encryption for all -connections on the default MongoDB port, or the port specified by -\fI\%\-\-port\fP\&. By default, \fI\%\-\-sslOnNormalPorts\fP is -disabled. -.sp -For more information about TLS/SSL and MongoDB, see -/tutorial/configure\-ssl and -/tutorial/configure\-ssl\-clients . .UNINDENT .INDENT 0.0 .TP -.B \-\-sslMode <mode> -New in version 2.6. +.B \-\-tlsMode <mode> +New in version 4.2. .sp -Enables TLS/SSL or mixed TLS/SSL used for all network connections. The -argument to the \fI\%\-\-sslMode\fP option can be one of the following: +Enables TLS used for all network connections. The +argument to the \fI\%\-\-tlsMode\fP option can be one of the following: .TS center; |l|l|. @@ -711,70 +896,98 @@ _ T{ \fBdisabled\fP T} T{ -The server does not use TLS/SSL. +The server does not use TLS. T} _ T{ -\fBallowSSL\fP +\fBallowTLS\fP T} T{ -Connections between servers do not use TLS/SSL. For incoming -connections, the server accepts both TLS/SSL and non\-TLS/non\-SSL. +Connections between servers do not use TLS. For incoming +connections, the server accepts both TLS and non\-TLS. T} _ T{ -\fBpreferSSL\fP +\fBpreferTLS\fP T} T{ -Connections between servers use TLS/SSL. For incoming -connections, the server accepts both TLS/SSL and non\-TLS/non\-SSL. +Connections between servers use TLS. For incoming +connections, the server accepts both TLS and non\-TLS. T} _ T{ -\fBrequireSSL\fP +\fBrequireTLS\fP T} T{ -The server uses and accepts only TLS/SSL encrypted connections. +The server uses and accepts only TLS encrypted connections. T} _ .TE .sp -Starting in version 3.4, if \fB\-\-sslCAFile\fP or \fBssl.CAFile\fP is not +If \fB\-\-tlsCAFile\fP or \fBtls.CAFile\fP is not specified and you are not using x.509 authentication, the system\-wide CA certificate store will be used when connecting to an -TLS/SSL\-enabled server. +TLS\-enabled server. .sp -If using x.509 authentication, \fB\-\-sslCAFile\fP or \fBssl.CAFile\fP -must be specified. +If using x.509 authentication, \fB\-\-tlsCAFile\fP or \fBtls.CAFile\fP +must be specified unless using \fB\-\-tlsCertificateSelector\fP\&. .sp -For more information about TLS/SSL and MongoDB, see +For more information about TLS and MongoDB, see /tutorial/configure\-ssl and /tutorial/configure\-ssl\-clients . .UNINDENT .INDENT 0.0 .TP -.B \-\-sslPEMKeyFile <filename> -Specifies the \fB\&.pem\fP file that contains both the TLS/SSL certificate -and key. Specify the file name of the \fB\&.pem\fP file using relative -or absolute paths. +.B \-\-tlsCertificateKeyFile <filename> +New in version 4.2. + .sp -You must specify \fI\%\-\-sslPEMKeyFile\fP when TLS/SSL is enabled. +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Starting in 4.0, on macOS or Windows, you can use a certificate from +the operating system\(aqs secure store instead of specifying a PEM file. See +\fI\%\-\-tlsCertificateSelector\fP\&. +.UNINDENT +.UNINDENT .sp -For more information about TLS/SSL and MongoDB, see +Specifies the \fB\&.pem\fP file that contains both the TLS certificate +and key. +.INDENT 7.0 +.IP \(bu 2 +On Linux/BSD, you must specify \fI\%\-\-tlsCertificateKeyFile\fP when TLS is enabled. +.IP \(bu 2 +On Windows or macOS, you must specify either \fI\%\-\-tlsCertificateKeyFile\fP or +\fI\%\-\-tlsCertificateSelector\fP when TLS is enabled. +.UNINDENT +.sp +For more information about TLS and MongoDB, see /tutorial/configure\-ssl and /tutorial/configure\-ssl\-clients . .UNINDENT .INDENT 0.0 .TP -.B \-\-sslPEMKeyPassword <value> +.B \-\-tlsCertificateKeyFilePassword <value> +New in version 4.2. + +.sp Specifies the password to de\-crypt the certificate\-key file (i.e. -\fI\%\-\-sslPEMKeyFile\fP). Use the \fI\%\-\-sslPEMKeyPassword\fP option only if the +\fI\%\-\-tlsCertificateKeyFile\fP). Use the \fI\%\-\-tlsCertificateKeyFilePassword\fP option only if the certificate\-key file is encrypted. In all cases, the \fBmongos\fP will redact the password from all logging and reporting output. .sp -Changed in version 2.6: If the private key in the PEM file is encrypted and you do not -specify the \fI\%\-\-sslPEMKeyPassword\fP option, the \fBmongos\fP will prompt for a +Starting in MongoDB 4.0: +.INDENT 7.0 +.IP \(bu 2 +On Linux/BSD, if the private key in the PEM file is encrypted and +you do not specify the \fI\%\-\-tlsCertificateKeyFilePassword\fP option, MongoDB will prompt for a passphrase. See ssl\-certificate\-password\&. - +.IP \(bu 2 +On macOS or Windows, if the private key in the PEM file is +encrypted, you must explicitly specify the \fI\%\-\-tlsCertificateKeyFilePassword\fP option. +Alternatively, you can use a certificate from the secure system +store (see \fI\%\-\-tlsCertificateSelector\fP) instead of a PEM file or use an +unencrypted PEM file. +.UNINDENT .sp -For more information about TLS/SSL and MongoDB, see +For more information about TLS and MongoDB, see /tutorial/configure\-ssl and /tutorial/configure\-ssl\-clients . .UNINDENT @@ -831,13 +1044,406 @@ T} _ .TE .sp -Starting in version 3.4, if \fB\-\-sslCAFile\fP or \fBssl.CAFile\fP is not +If \fB\-\-tlsCAFile\fP or \fBtls.CAFile\fP is not specified and you are not using x.509 authentication, the system\-wide CA certificate store will be used when connecting to an -TLS/SSL\-enabled server. +TLS\-enabled server. +.sp +If using x.509 authentication, \fB\-\-tlsCAFile\fP or \fBtls.CAFile\fP +must be specified unless using \fB\-\-tlsCertificateSelector\fP\&. +.sp +For more information about TLS and MongoDB, see +/tutorial/configure\-ssl and +/tutorial/configure\-ssl\-clients . +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tlsClusterFile <filename> +New in version 4.2. + +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Starting in 4.0, on macOS or Windows, you can use a certificate +from the operating system\(aqs secure store instead of a PEM +file. See \fI\%\-\-tlsClusterCertificateSelector\fP\&. +.UNINDENT +.UNINDENT +.sp +Specifies the \fB\&.pem\fP file that contains the x.509 certificate\-key +file for membership authentication +for the cluster or replica set. +.sp +If \fI\%\-\-tlsClusterFile\fP does not specify the \fB\&.pem\fP file for internal cluster +authentication or the alternative +\fI\%\-\-tlsClusterCertificateSelector\fP, the cluster uses the +\fB\&.pem\fP file specified in the \fI\%\-\-tlsCertificateKeyFile\fP option or +the certificate returned by the \fI\%\-\-tlsCertificateSelector\fP\&. +.sp +If using x.509 authentication, \fB\-\-tlsCAFile\fP or \fBtls.CAFile\fP +must be specified unless using \fB\-\-tlsCertificateSelector\fP\&. +.sp +For more information about TLS and MongoDB, see +/tutorial/configure\-ssl and +/tutorial/configure\-ssl\-clients . +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tlsClusterPassword <value> +New in version 4.2. + +.sp +Specifies the password to de\-crypt the x.509 certificate\-key file +specified with \fB\-\-tlsClusterFile\fP\&. Use the \fI\%\-\-tlsClusterPassword\fP option only +if the certificate\-key file is encrypted. In all cases, the \fBmongos\fP +will redact the password from all logging and reporting output. +.sp +Starting in MongoDB 4.0: +.INDENT 7.0 +.IP \(bu 2 +On Linux/BSD, if the private key in the x.509 file is encrypted and +you do not specify the \fI\%\-\-tlsClusterPassword\fP option, MongoDB will prompt for a +passphrase. See ssl\-certificate\-password\&. +.IP \(bu 2 +On macOS or Windows, if the private key in the x.509 file is +encrypted, you must explicitly specify the \fI\%\-\-tlsClusterPassword\fP option. +Alternatively, you can either use a certificate from the secure +system store (see \fI\%\-\-tlsClusterCertificateSelector\fP) instead of a cluster PEM file or +use an unencrypted PEM file. +.UNINDENT +.sp +For more information about TLS and MongoDB, see +/tutorial/configure\-ssl and +/tutorial/configure\-ssl\-clients . +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tlsCAFile <filename> +New in version 4.2. + +.sp +Specifies the \fB\&.pem\fP file that contains the root certificate chain +from the Certificate Authority. Specify the file name of the +\fB\&.pem\fP file using relative or absolute paths. +.sp +Starting in 4.0, on macOS or Windows, you can use a certificate from +the operating system\(aqs secure store instead of a PEM key file. See +\fI\%\-\-tlsCertificateSelector\fP\&. When using the secure store, you +do not need to, but can, also specify the \fI\%\-\-tlsCAFile\fP\&. +.sp +For more information about TLS and MongoDB, see +/tutorial/configure\-ssl and +/tutorial/configure\-ssl\-clients . +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tlsClusterCAFile <filename> +New in version 4.2. + +.sp +Specifies the \fB\&.pem\fP file that contains the root certificate chain +from the Certificate Authority used to validate the certificate +presented by a client establishing a connection. Specify the file +name of the \fB\&.pem\fP file using relative or absolute paths. +.sp +If \fI\%\-\-tlsClusterCAFile\fP does not specify the \fB\&.pem\fP file for validating the +certificate from a client establishing a connection, the cluster uses +the \fB\&.pem\fP file specified in the \fI\%\-\-tlsCAFile\fP option. +.sp +\fI\%\-\-tlsClusterCAFile\fP lets you use separate Certificate Authorities to verify the +client to server and server to client portions of the TLS handshake. +.sp +Starting in 4.0, on macOS or Windows, you can use a certificate from +the operating system\(aqs secure store instead of a PEM key file. See +\fI\%\-\-tlsClusterCertificateSelector\fP\&. When using the secure store, you +do not need to, but can, also specify the \fI\%\-\-tlsClusterCAFile\fP\&. +.sp +Requires that \fI\%\-\-tlsCAFile\fP is set. +.sp +For more information about TLS and MongoDB, see +/tutorial/configure\-ssl and +/tutorial/configure\-ssl\-clients . +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tlsCertificateSelector <parameter>=<value> +New in version 4.2: Available on Windows and macOS as an alternative to \fI\%\-\-tlsCertificateKeyFile\fP\&. +.sp +The \fI\%\-\-tlsCertificateKeyFile\fP and \fI\%\-\-tlsCertificateSelector\fP options are mutually exclusive. You can only +specify one. + +.sp +Specifies a certificate property in order to select a matching +certificate from the operating system\(aqs certificate store. +.sp +\fI\%\-\-tlsCertificateSelector\fP accepts an argument of the format \fB<property>=<value>\fP +where the property can be one of the following: +.TS +center; +|l|l|l|. +_ +T{ +Property +T} T{ +Value type +T} T{ +Description +T} +_ +T{ +\fBsubject\fP +T} T{ +ASCII string +T} T{ +Subject name or common name on certificate +T} +_ +T{ +\fBthumbprint\fP +T} T{ +hex string +T} T{ +A sequence of bytes, expressed as hexadecimal, used to +identify a public key by its SHA\-1 digest. +.sp +The \fBthumbprint\fP is sometimes referred to as a +\fBfingerprint\fP\&. +T} +_ +.TE +.sp +When using the system SSL certificate store, OCSP (Online +Certificate Status Protocol) is used to validate the revocation +status of certificates. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tlsClusterCertificateSelector <parameter>=<value> +New in version 4.2: Available on Windows and macOS as an alternative to +\fI\%\-\-tlsClusterFile\fP\&. +.sp +\fI\%\-\-tlsClusterFile\fP and \fI\%\-\-tlsClusterCertificateSelector\fP options are mutually exclusive. You can only +specify one. + +.sp +Specifies a certificate property in order to select a matching +certificate from the operating system\(aqs certificate store to use for +internal authentication. +.sp +\fI\%\-\-tlsClusterCertificateSelector\fP accepts an argument of the format \fB<property>=<value>\fP +where the property can be one of the following: +.TS +center; +|l|l|l|. +_ +T{ +Property +T} T{ +Value type +T} T{ +Description +T} +_ +T{ +\fBsubject\fP +T} T{ +ASCII string +T} T{ +Subject name or common name on certificate +T} +_ +T{ +\fBthumbprint\fP +T} T{ +hex string +T} T{ +A sequence of bytes, expressed as hexadecimal, used to +identify a public key by its SHA\-1 digest. +.sp +The \fBthumbprint\fP is sometimes referred to as a +\fBfingerprint\fP\&. +T} +_ +.TE +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tlsCRLFile <filename> +New in version 4.2. + +.sp +Specifies the the \fB\&.pem\fP file that contains the Certificate Revocation +List. Specify the file name of the \fB\&.pem\fP file using relative or +absolute paths. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Starting in MongoDB 4.0, you cannot specify \fI\%\-\-tlsCRLFile\fP on macOS. Use \fI\%\-\-tlsCertificateSelector\fP instead. +.UNINDENT +.UNINDENT +.sp +For more information about TLS and MongoDB, see +/tutorial/configure\-ssl and +/tutorial/configure\-ssl\-clients . +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tlsAllowConnectionsWithoutCertificates +New in version 4.2. + +.sp +For clients that do not present certificates, \fBmongos\fP bypasses +TLS/SSL certificate validation when establishing the connection. +.sp +For clients that present a certificate, however, \fBmongos\fP performs +certificate validation using the root certificate chain specified by +\fB\-\-tlsCAFile\fP and reject clients with invalid certificates. +.sp +Use the \fI\%\-\-tlsAllowConnectionsWithoutCertificates\fP option if you have a mixed deployment that includes +clients that do not or cannot present certificates to the \fBmongos\fP\&. +.sp +For more information about TLS and MongoDB, see +/tutorial/configure\-ssl and +/tutorial/configure\-ssl\-clients . +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tlsAllowInvalidCertificates +New in version 4.2. + +.sp +Bypasses the validation checks for TLS certificates on other +servers in the cluster and allows the use of invalid certificates to +connect. .sp -If using x.509 authentication, \fB\-\-sslCAFile\fP or \fBssl.CAFile\fP -must be specified. +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +If you specify +\fB\-\-tlsAllowInvalidCertificates\fP or \fBtls.allowInvalidCertificates: +true\fP when using x.509 authentication, an invalid certificate is +only sufficient to establish a TLS connection but is +\fIinsufficient\fP for authentication. +.UNINDENT +.UNINDENT +.sp +When using +the \fI\%\-\-tlsAllowInvalidCertificates\fP setting, MongoDB +logs a warning regarding the use of the invalid certificate. +.sp +For more information about TLS and MongoDB, see +/tutorial/configure\-ssl and +/tutorial/configure\-ssl\-clients . +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tlsAllowInvalidHostnames +New in version 4.2. + +.sp +Disables the validation of the hostnames in TLS certificates, +when connecting to other members of the replica set or sharded cluster +for inter\-process authentication. This allows \fBmongos\fP to connect +to other members if the hostnames in their certificates do not match +their configured hostname. +.sp +For more information about TLS and MongoDB, see +/tutorial/configure\-ssl and +/tutorial/configure\-ssl\-clients . +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tlsDisabledProtocols <protocol(s)> +New in version 4.2. + +.sp +Prevents a MongoDB server running with TLS from accepting +incoming connections that use a specific protocol or protocols. To +specify multiple protocols, use a comma separated list of protocols. +.sp +\fI\%\-\-tlsDisabledProtocols\fP recognizes the following protocols: \fBTLS1_0\fP, \fBTLS1_1\fP, +\fBTLS1_2\fP, and starting in version 4.0.4 (and 3.6.9), \fBTLS1_3\fP\&. +.INDENT 7.0 +.IP \(bu 2 +On macOS, you cannot disable \fBTLS1_1\fP and leave both \fBTLS1_0\fP and +\fBTLS1_2\fP enabled. You must disable at least one of the other +two, for example, \fBTLS1_0,TLS1_1\fP\&. +.IP \(bu 2 +To list multiple protocols, specify as a comma separated list of +protocols. For example \fBTLS1_0,TLS1_1\fP\&. +.IP \(bu 2 +Specifying an unrecognized protocol will prevent the server from +starting. +.IP \(bu 2 +The specified disabled protocols overrides any default disabled +protocols. +.UNINDENT +.sp +Starting in version 4.0, MongoDB disables the use of TLS 1.0 if TLS +1.1+ is available on the system. To enable the disabled TLS 1.0, +specify \fBnone\fP to \fI\%\-\-tlsDisabledProtocols\fP\&. See 4.0\-disable\-tls\&. +.sp +Members of replica sets and sharded clusters must speak at least one +protocol in common. +.sp +\fBSEE ALSO:\fP +.INDENT 7.0 +.INDENT 3.5 +ssl\-disallow\-protocols +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tlsFIPSMode +New in version 4.2. + +.sp +Directs the \fBmongos\fP to use the FIPS mode of the TLS +library. Your system must have a FIPS +compliant library to use the \fI\%\-\-tlsFIPSMode\fP option. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +FIPS\-compatible TLS/SSL is +available only in \fI\%MongoDB Enterprise\fP\&. See +/tutorial/configure\-fips for more information. +.UNINDENT +.UNINDENT +.UNINDENT +.SS SSL Options (Deprecated) +.sp +\fBIMPORTANT:\fP +.INDENT 0.0 +.INDENT 3.5 +All SSL options are deprecated since 4.2. Use the TLS counterparts +instead, as they have identical functionality to the SSL options. The SSL +protocol is deprecated and MongoDB supports TLS 1.0 and later. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.SS See +.sp +/tutorial/configure\-ssl for full +documentation of MongoDB\(aqs support. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-sslOnNormalPorts +Deprecated since version 2.6: Use \fI\%\-\-tlsMode requireTLS\fP instead. + +.sp +Enables TLS/SSL for \fBmongos\fP\&. +.sp +With \fI\%\-\-sslOnNormalPorts\fP, a \fBmongos\fP requires TLS/SSL encryption for all +connections on the default MongoDB port, or the port specified by +\fI\%\-\-port\fP\&. By default, \fI\%\-\-sslOnNormalPorts\fP is +disabled. .sp For more information about TLS/SSL and MongoDB, see /tutorial/configure\-ssl and @@ -845,20 +1451,157 @@ For more information about TLS/SSL and MongoDB, see .UNINDENT .INDENT 0.0 .TP -.B \-\-sslClusterFile <filename> +.B \-\-sslMode <mode> +Deprecated since version 4.2: Use \fI\%\-\-tlsMode\fP instead. + +.sp New in version 2.6. .sp +Enables TLS/SSL or mixed TLS/SSL used for all network connections. The +argument to the \fI\%\-\-sslMode\fP option can be one of the following: +.TS +center; +|l|l|. +_ +T{ +Value +T} T{ +Description +T} +_ +T{ +\fBdisabled\fP +T} T{ +The server does not use TLS/SSL. +T} +_ +T{ +\fBallowSSL\fP +T} T{ +Connections between servers do not use TLS/SSL. For incoming +connections, the server accepts both TLS/SSL and non\-TLS/non\-SSL. +T} +_ +T{ +\fBpreferSSL\fP +T} T{ +Connections between servers use TLS/SSL. For incoming +connections, the server accepts both TLS/SSL and non\-TLS/non\-SSL. +T} +_ +T{ +\fBrequireSSL\fP +T} T{ +The server uses and accepts only TLS/SSL encrypted connections. +T} +_ +.TE +.sp +Starting in version 3.4, if \fB\-\-tlsCAFile\fP/\fBnet.tls.CAFile\fP (or +their aliases \fB\-\-sslCAFile\fP/\fBnet.ssl.CAFile\fP) is not specified +and you are not using x.509 authentication, the system\-wide CA +certificate store will be used when connecting to an TLS/SSL\-enabled +server. +.sp +To use x.509 authentication, \fB\-\-tlsCAFile\fP or \fBnet.tls.CAFile\fP +must be specified unless using \fB\-\-tlsCertificateSelector\fP or +\fB\-\-net.tls.certificateSelector\fP\&. Or if using the \fBssl\fP aliases, +\fB\-\-sslCAFile\fP or \fBnet.ssl.CAFile\fP must be specified unless using +\fB\-\-sslCertificateSelector\fP or \fBnet.ssl.certificateSelector\fP\&. +.sp +For more information about TLS/SSL and MongoDB, see +/tutorial/configure\-ssl and +/tutorial/configure\-ssl\-clients . +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-sslPEMKeyFile <filename> +Deprecated since version 4.2: Use \fI\%\-\-tlsPEMKeyFile\fP instead. + +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Starting in 4.0, on macOS or Windows, you can use a certificate from +the operating system\(aqs secure store instead of a PEM file. See +\fI\%\-\-sslCertificateSelector\fP\&. +.UNINDENT +.UNINDENT +.sp +Specifies the \fB\&.pem\fP file that contains both the TLS/SSL certificate +and key. +.INDENT 7.0 +.IP \(bu 2 +On Linux/BSD, you must specify \fI\%\-\-sslPEMKeyFile\fP when TLS/SSL is enabled. +.IP \(bu 2 +On Windows or macOS, you must specify either \fI\%\-\-sslPEMKeyFile\fP or +\fI\%\-\-sslCertificateSelector\fP when TLS/SSL is enabled. +.UNINDENT +.sp +For more information about TLS/SSL and MongoDB, see +/tutorial/configure\-ssl and +/tutorial/configure\-ssl\-clients . +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-sslPEMKeyPassword <value> +Deprecated since version 4.2: Use \fI\%\-\-tlsPEMKeyPassword\fP instead. + +.sp +Specifies the password to de\-crypt the certificate\-key file (i.e. +\fI\%\-\-sslPEMKeyFile\fP). Use the \fI\%\-\-sslPEMKeyPassword\fP option only if the +certificate\-key file is encrypted. In all cases, the \fBmongos\fP will +redact the password from all logging and reporting output. +.sp +Starting in MongoDB 4.0: +.INDENT 7.0 +.IP \(bu 2 +On Linux/BSD, if the private key in the PEM file is encrypted and +you do not specify the \fI\%\-\-sslPEMKeyPassword\fP option, MongoDB will prompt for a +passphrase. See ssl\-certificate\-password\&. +.IP \(bu 2 +On macOS or Windows, if the private key in the PEM file is +encrypted, you must explicitly specify the \fI\%\-\-sslPEMKeyPassword\fP option. +Alternatively, you can use a certificate from the secure system +store (see \fI\%\-\-sslCertificateSelector\fP) instead of a PEM key file or use an +unencrypted PEM file. +.UNINDENT +.sp +For more information about TLS/SSL and MongoDB, see +/tutorial/configure\-ssl and +/tutorial/configure\-ssl\-clients . +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-sslClusterFile <filename> +Deprecated since version 4.2: Use \fI\%\-\-tlsClusterFile\fP instead. + +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Starting in 4.0, on macOS or Windows, you can use a certificate +from the operating system\(aqs secure store instead of a PEM key +file. See \fI\%\-\-sslClusterCertificateSelector\fP\&. +.UNINDENT +.UNINDENT +.sp Specifies the \fB\&.pem\fP file that contains the x.509 certificate\-key file for membership authentication for the cluster or replica set. .sp If \fI\%\-\-sslClusterFile\fP does not specify the \fB\&.pem\fP file for internal cluster -authentication, the cluster uses the \fB\&.pem\fP file specified in the -\fI\%\-\-sslPEMKeyFile\fP option. +authentication or the alternative +\fI\%\-\-sslClusterCertificateSelector\fP, the cluster uses the +\fB\&.pem\fP file specified in the \fI\%\-\-sslPEMKeyFile\fP option or +the certificate returned by the \fI\%\-\-sslCertificateSelector\fP\&. .sp -If using x.509 authentication, \fB\-\-sslCAFile\fP or \fBssl.CAFile\fP -must be specified. +To use x.509 authentication, \fB\-\-tlsCAFile\fP or \fBnet.tls.CAFile\fP +must be specified unless using \fB\-\-tlsCertificateSelector\fP or +\fB\-\-net.tls.certificateSelector\fP\&. Or if using the \fBssl\fP aliases, +\fB\-\-sslCAFile\fP or \fBnet.ssl.CAFile\fP must be specified unless using +\fB\-\-sslCertificateSelector\fP or \fBnet.ssl.certificateSelector\fP\&. .sp For more information about TLS/SSL and MongoDB, see /tutorial/configure\-ssl and @@ -867,6 +1610,9 @@ For more information about TLS/SSL and MongoDB, see .INDENT 0.0 .TP .B \-\-sslClusterPassword <value> +Deprecated since version 4.2: Use \fI\%\-\-tlsClusterPassword\fP instead. + +.sp New in version 2.6. .sp @@ -875,9 +1621,19 @@ specified with \fB\-\-sslClusterFile\fP\&. Use the \fI\%\-\-sslClusterPassword\f if the certificate\-key file is encrypted. In all cases, the \fBmongos\fP will redact the password from all logging and reporting output. .sp -If the x.509 key file is encrypted and you do not specify the -\fI\%\-\-sslClusterPassword\fP option, the \fBmongos\fP will prompt for a passphrase. See -ssl\-certificate\-password\&. +Starting in MongoDB 4.0: +.INDENT 7.0 +.IP \(bu 2 +On Linux/BSD, if the private key in the x.509 file is encrypted and +you do not specify the \fI\%\-\-sslClusterPassword\fP option, MongoDB will prompt for a +passphrase. See ssl\-certificate\-password\&. +.IP \(bu 2 +On macOS or Windows, if the private key in the x.509 file is +encrypted, you must explicitly specify the \fI\%\-\-sslClusterPassword\fP option. +Alternatively, you can either use a certificate from the secure +system store (see \fI\%\-\-sslClusterCertificateSelector\fP) instead of a cluster PEM file or +use an unencrypted PEM file. +.UNINDENT .sp For more information about TLS/SSL and MongoDB, see /tutorial/configure\-ssl and @@ -886,17 +1642,46 @@ For more information about TLS/SSL and MongoDB, see .INDENT 0.0 .TP .B \-\-sslCAFile <filename> +Deprecated since version 4.2: Use \fI\%\-\-tlsCAFile\fP instead. + +.sp Specifies the \fB\&.pem\fP file that contains the root certificate chain from the Certificate Authority. Specify the file name of the \fB\&.pem\fP file using relative or absolute paths. .sp -Starting in version 3.4, if \fB\-\-sslCAFile\fP or \fBssl.CAFile\fP is not -specified and you are not using x.509 authentication, the -system\-wide CA certificate store will be used when connecting to an -TLS/SSL\-enabled server. +Starting in 4.0, on macOS or Windows, you can use a certificate from +the operating system\(aqs secure store instead of a PEM key file. See +\fI\%\-\-sslCertificateSelector\fP\&. When using the secure store, you +do not need to, but can, also specify the \fI\%\-\-sslCAFile\fP\&. +.sp +For more information about TLS/SSL and MongoDB, see +/tutorial/configure\-ssl and +/tutorial/configure\-ssl\-clients . +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-sslClusterCAFile <filename> +Deprecated since version 4.2: Use \fI\%\-\-tlsClusterCAFile\fP instead. + +.sp +Specifies the \fB\&.pem\fP file that contains the root certificate chain +from the Certificate Authority used to validate the certificate +presented by a client establishing a connection. Specify the file +name of the \fB\&.pem\fP file using relative or absolute paths. +.sp +If \fI\%\-\-sslClusterCAFile\fP does not specify the \fB\&.pem\fP file for validating the +certificate from a client establishing a connection, the cluster uses +the \fB\&.pem\fP file specified in the \fI\%\-\-sslCAFile\fP option. +.sp +\fI\%\-\-sslClusterCAFile\fP lets you use separate Certificate Authorities to verify the +client to server and server to client portions of the TLS handshake. .sp -If using x.509 authentication, \fB\-\-sslCAFile\fP or \fBssl.CAFile\fP -must be specified. +Starting in 4.0, on macOS or Windows, you can use a certificate from +the operating system\(aqs secure store instead of a PEM key file. See +\fI\%\-\-sslClusterCertificateSelector\fP\&. When using the secure store, you +do not need to, but can, also specify the \fI\%\-\-sslClusterCAFile\fP\&. +.sp +Requires that \fI\%\-\-sslCAFile\fP is set. .sp For more information about TLS/SSL and MongoDB, see /tutorial/configure\-ssl and @@ -904,11 +1689,129 @@ For more information about TLS/SSL and MongoDB, see .UNINDENT .INDENT 0.0 .TP +.B \-\-sslCertificateSelector <parameter>=<value> +Deprecated since version 4.2: Use \fI\%\-\-tlsCertificateSelector\fP instead. + +.sp +New in version 4.0: Available on Windows and macOS as an alternative to \fI\%\-\-tlsCertificateKeyFile\fP\&. +.sp +\fI\%\-\-tlsCertificateKeyFile\fP and \fI\%\-\-sslCertificateSelector\fP options are mutually exclusive. You can only +specify one. + +.sp +Specifies a certificate property in order to select a matching +certificate from the operating system\(aqs certificate store. +.sp +\fI\%\-\-sslCertificateSelector\fP accepts an argument of the format \fB<property>=<value>\fP +where the property can be one of the following: +.TS +center; +|l|l|l|. +_ +T{ +Property +T} T{ +Value type +T} T{ +Description +T} +_ +T{ +\fBsubject\fP +T} T{ +ASCII string +T} T{ +Subject name or common name on certificate +T} +_ +T{ +\fBthumbprint\fP +T} T{ +hex string +T} T{ +A sequence of bytes, expressed as hexadecimal, used to +identify a public key by its SHA\-1 digest. +.sp +The \fBthumbprint\fP is sometimes referred to as a +\fBfingerprint\fP\&. +T} +_ +.TE +.sp +When using the system SSL certificate store, OCSP (Online +Certificate Status Protocol) is used to validate the revocation +status of certificates. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-sslClusterCertificateSelector <parameter>=<value> +Deprecated since version 4.2: Use \fI\%\-\-tlsClusterCertificateSelector\fP instead. + +.sp +New in version 4.0: Available on Windows and macOS as an alternative to +\fI\%\-\-sslClusterFile\fP\&. +.sp +\fI\%\-\-sslClusterFile\fP and \fI\%\-\-sslClusterCertificateSelector\fP options are mutually exclusive. You can only +specify one. + +.sp +Specifies a certificate property in order to select a matching +certificate from the operating system\(aqs certificate store to use for +internal authentication. +.sp +\fI\%\-\-sslClusterCertificateSelector\fP accepts an argument of the format \fB<property>=<value>\fP +where the property can be one of the following: +.TS +center; +|l|l|l|. +_ +T{ +Property +T} T{ +Value type +T} T{ +Description +T} +_ +T{ +\fBsubject\fP +T} T{ +ASCII string +T} T{ +Subject name or common name on certificate +T} +_ +T{ +\fBthumbprint\fP +T} T{ +hex string +T} T{ +A sequence of bytes, expressed as hexadecimal, used to +identify a public key by its SHA\-1 digest. +.sp +The \fBthumbprint\fP is sometimes referred to as a +\fBfingerprint\fP\&. +T} +_ +.TE +.UNINDENT +.INDENT 0.0 +.TP .B \-\-sslCRLFile <filename> +Deprecated since version 4.2: Use \fI\%\-\-tlsCRLFile\fP instead. + +.sp Specifies the the \fB\&.pem\fP file that contains the Certificate Revocation List. Specify the file name of the \fB\&.pem\fP file using relative or absolute paths. .sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Starting in MongoDB 4.0, you cannot specify \fI\%\-\-sslCRLFile\fP on macOS. Use \fI\%\-\-sslCertificateSelector\fP instead. +.UNINDENT +.UNINDENT +.sp For more information about TLS/SSL and MongoDB, see /tutorial/configure\-ssl and /tutorial/configure\-ssl\-clients . @@ -916,15 +1819,15 @@ For more information about TLS/SSL and MongoDB, see .INDENT 0.0 .TP .B \-\-sslAllowConnectionsWithoutCertificates -Disables the requirement for TLS/SSL certificate validation that -\fB\-\-sslCAFile\fP enables. With the \fI\%\-\-sslAllowConnectionsWithoutCertificates\fP option, the \fBmongos\fP -will accept connections when the client does not present a certificate -when establishing the connection. +Deprecated since version 4.2: Use \fI\%\-\-tlsAllowConnectionsWithoutCertificates\fP instead. + .sp -If the client presents a certificate and the \fBmongos\fP has \fI\%\-\-sslAllowConnectionsWithoutCertificates\fP -enabled, the \fBmongos\fP will validate the certificate using the root -certificate chain specified by \fB\-\-sslCAFile\fP and reject clients -with invalid certificates. +For clients that do not present certificates, \fBmongos\fP bypasses +TLS/SSL certificate validation when establishing the connection. +.sp +For clients that present a certificate, however, \fBmongos\fP performs +certificate validation using the root certificate chain specified by +\fB\-\-sslCAFile\fP and reject clients with invalid certificates. .sp Use the \fI\%\-\-sslAllowConnectionsWithoutCertificates\fP option if you have a mixed deployment that includes clients that do not or cannot present certificates to the \fBmongos\fP\&. @@ -936,6 +1839,9 @@ For more information about TLS/SSL and MongoDB, see .INDENT 0.0 .TP .B \-\-sslAllowInvalidCertificates +Deprecated since version 4.2: Use \fI\%\-\-tlsAllowInvalidCertificates\fP instead. + +.sp Bypasses the validation checks for TLS/SSL certificates on other servers in the cluster and allows the use of invalid certificates to connect. @@ -944,10 +1850,13 @@ connect. .INDENT 7.0 .INDENT 3.5 Starting in MongoDB 4.0, if you specify -\fB\-\-sslAllowInvalidCertificates\fP or \fBssl.allowInvalidCertificates: -true\fP when using x.509 authentication, an invalid certificate is -only sufficient to establish a TLS/SSL connection but is -\fIinsufficient\fP for authentication. +\fB\-\-sslAllowInvalidCertificates\fP or +\fBnet.ssl.allowInvalidCertificates: true\fP (or in MongoDB 4.2, the +alias \fB\-\-tlsAllowInvalidateCertificates\fP or +\fBnet.tls.allowInvalidCertificates: true\fP) when using x.509 +authentication, an invalid certificate is only sufficient to +establish a TLS/SSL connection but is \fIinsufficient\fP for +authentication. .UNINDENT .UNINDENT .sp @@ -962,6 +1871,9 @@ For more information about TLS/SSL and MongoDB, see .INDENT 0.0 .TP .B \-\-sslAllowInvalidHostnames +Deprecated since version 4.2: Use \fI\%\-\-tlsAllowInvalidHostnames\fP instead. + +.sp New in version 3.0. .sp @@ -978,6 +1890,9 @@ For more information about TLS/SSL and MongoDB, see .INDENT 0.0 .TP .B \-\-sslDisabledProtocols <protocol(s)> +Deprecated since version 4.2: Use \fI\%\-\-tlsDisabledProtocols\fP instead. + +.sp New in version 3.0.7. .sp @@ -986,7 +1901,7 @@ incoming connections that use a specific protocol or protocols. To specify multiple protocols, use a comma separated list of protocols. .sp \fI\%\-\-sslDisabledProtocols\fP recognizes the following protocols: \fBTLS1_0\fP, \fBTLS1_1\fP, -and \fBTLS1_2\fP\&. +\fBTLS1_2\fP, and starting in version 4.0.4 (and 3.6.9), \fBTLS1_3\fP\&. .INDENT 7.0 .IP \(bu 2 On macOS, you cannot disable \fBTLS1_1\fP and leave both \fBTLS1_0\fP and @@ -1005,7 +1920,7 @@ protocols. .sp Starting in version 4.0, MongoDB disables the use of TLS 1.0 if TLS 1.1+ is available on the system. To enable the disabled TLS 1.0, -specify \fBnone\fP to \fI\%\-\-sslDisabledProtocols\fP\&. 4.0\-disable\-tls +specify \fBnone\fP to \fI\%\-\-sslDisabledProtocols\fP\&. See 4.0\-disable\-tls\&. .sp Members of replica sets and sharded clusters must speak at least one protocol in common. @@ -1020,9 +1935,12 @@ ssl\-disallow\-protocols .INDENT 0.0 .TP .B \-\-sslFIPSMode -Directs the \fBmongos\fP to use the FIPS mode of the installed OpenSSL +Deprecated since version 4.2: Use \fI\%\-\-tlsFIPSMode\fP instead. + +.sp +Directs the \fBmongos\fP to use the FIPS mode of the TLS/SSL library. Your system must have a FIPS -compliant OpenSSL library to use the \fI\%\-\-sslFIPSMode\fP option. +compliant library to use the \fI\%\-\-sslFIPSMode\fP option. .sp \fBNOTE:\fP .INDENT 7.0 @@ -1082,7 +2000,8 @@ _ \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 -Available only in \fI\%MongoDB Enterprise\fP\&. +Available only in \fI\%MongoDB Enterprise\fP +and \fI\%MongoDB Atlas\fP\&. .UNINDENT .UNINDENT .UNINDENT @@ -1126,7 +2045,8 @@ performance more than printing to a file in BSON format. \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 -Available only in \fI\%MongoDB Enterprise\fP\&. +Available only in \fI\%MongoDB Enterprise\fP +and \fI\%MongoDB Atlas\fP\&. .UNINDENT .UNINDENT .UNINDENT @@ -1143,7 +2063,8 @@ option can take either a full path name or a relative path name. \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 -Available only in \fI\%MongoDB Enterprise\fP\&. +Available only in \fI\%MongoDB Enterprise\fP +and \fI\%MongoDB Atlas\fP\&. .UNINDENT .UNINDENT .UNINDENT @@ -1179,7 +2100,8 @@ the configuration file. \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 -Available only in \fI\%MongoDB Enterprise\fP\&. +Available only in \fI\%MongoDB Enterprise\fP +and \fI\%MongoDB Atlas\fP\&. .UNINDENT .UNINDENT .UNINDENT @@ -1195,11 +2117,12 @@ New in version 4.0. The \fIslow\fP operation time threshold, in milliseconds. Operations that run for longer than this threshold are considered \fIslow\fP\&. .sp -When \fBlogLevel\fP is set to \fB0\fP, MongoDB -records \fIslow\fP operations to the diagnostic log at a rate determined by -\fBslowOpSampleRate\fP\&. At higher -\fBlogLevel\fP settings, all operations appear in the diagnostic -log regardless of their latency. +When \fBlogLevel\fP is set to \fB0\fP, MongoDB records \fIslow\fP +operations to the diagnostic log at a rate determined by +\fBslowOpSampleRate\fP\&. +.sp +At higher \fBlogLevel\fP settings, all operations appear +in the diagnostic log regardless of their latency. .sp For \fI\%mongos\fP instances, affects the diagnostic log only and not the profiler since profiling is not available on @@ -1223,24 +2146,6 @@ only and not the profiler since profiling is not available on New in version 4.0. .UNINDENT -.SS Text Search Options -.INDENT 0.0 -.TP -.B \-\-basisTechRootDirectory <path> -New in version 3.2. - -.sp -Specify the root directory of the Basis Technology Rosette -Linguistics Platform installation to support additional languages for -text search operations. -.INDENT 7.0 -.INDENT 3.5 -.IP "Enterprise Feature" -.sp -Available in MongoDB Enterprise only. -.UNINDENT -.UNINDENT -.UNINDENT .SS LDAP Authentication and Authorization Options .INDENT 0.0 .TP @@ -1258,7 +2163,7 @@ If your LDAP infrastrucure partitions the LDAP directory over multiple LDAP servers, specify \fIone\fP LDAP server any of its replicated instances to \fI\%\-\-ldapServers\fP\&. MongoDB supports following LDAP referrals as defined in \fI\%RFC 4511 4.1.10\fP\&. Do not use \fI\%\-\-ldapServers\fP -for listing every LDAP server in your infrastucture. +for listing every LDAP server in your infrastructure. .sp This setting can be configured on a running \fBmongos\fP using \fBsetParameter\fP\&. @@ -1459,7 +2364,7 @@ By default, \fBmongos\fP creates a TLS/SSL secured connection to the LDAP server. .sp For Linux deployments, you must configure the appropriate TLS Options in -\fB/etc/openldap/ldap.conf\fP file. Your operating system’s package manager +\fB/etc/openldap/ldap.conf\fP file. Your operating system\(aqs package manager creates this file as part of the MongoDB Enterprise installation, via the \fBlibldap\fP dependency. See the documentation for \fBTLS Options\fP in the \fI\%ldap.conf OpenLDAP documentation\fP @@ -1572,6 +2477,8 @@ authentication name matched by the \fBmatch\fP regex into a LDAP DN. Each curly bracket\-enclosed numeric value is replaced by the corresponding \fI\%regex capture group\fP extracted from the authentication username via the \fBmatch\fP regex. +.sp +The result of the substitution must be an \fI\%RFC4514\fP escaped string. T} T{ \fB"cn={0},ou=engineering, dc=example,dc=com"\fP @@ -1596,6 +2503,17 @@ T} _ .TE .sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +An explanation of \fI\%RFC4514\fP, +\fI\%RFC4515\fP, +\fI\%RFC4516\fP, or LDAP queries is out +of scope for the MongoDB Documentation. Please review the RFC directly or +use your preferred LDAP resource. +.UNINDENT +.UNINDENT +.sp For each document in the array, you must use either \fBsubstitution\fP or \fBldapQuery\fP\&. You \fIcannot\fP specify both in the same document. .sp @@ -1667,31 +2585,27 @@ when attempting to authenticate or authorize a user against the LDAP server. .sp This setting can be configured on a running \fBmongos\fP using the \fBsetParameter\fP database command. -.sp -\fBNOTE:\fP -.INDENT 7.0 -.INDENT 3.5 -An explanation of \fI\%RFC4515\fP, -\fI\%RFC4516\fP or LDAP queries is out -of scope for the MongoDB Documentation. Please review the RFC directly or -use your preferred LDAP resource. -.UNINDENT -.UNINDENT .UNINDENT .SS Additional Options .INDENT 0.0 .TP .B \-\-ipv6 Enables IPv6 support. \fBmongos\fP disables IPv6 support by default. +.sp +Setting \fI\%\-\-ipv6\fP does \fInot\fP direct the \fBmongos\fP to listen on any +local IPv6 addresses or interfaces. To configure the \fBmongos\fP to +listen on an IPv6 interface, you must either: +.INDENT 7.0 +.IP \(bu 2 +Configure \fI\%\-\-bind_ip\fP with one or more IPv6 addresses or +hostnames that resolve to IPv6 addresses, \fBor\fP +.IP \(bu 2 +Set \fI\%\-\-bind_ip_all\fP to \fBtrue\fP\&. .UNINDENT -.INDENT 0.0 -.TP -.B \-\-noscripting -Disables the scripting engine. .UNINDENT .SH AUTHOR MongoDB Documentation Project .SH COPYRIGHT -2008-2018 +2008-2019 .\" Generated by docutils manpage writer. . |