From 22b6ecf9992e1220f16f477157b20e684b6b2855 Mon Sep 17 00:00:00 2001 From: Britt Snyman <106108223+bsnyman@users.noreply.github.com> Date: Mon, 22 Jul 2024 12:28:42 -0400 Subject: [PATCH] SERVER-87888 Update man pages for 8.0 (#25054) GitOrigin-RevId: cc850514aeed8853f1f2c877f5f3899a0f33fd13 --- debian/mongod.1 | 1396 ++++++------------ debian/mongodb-parameters.5 | 2713 ++++++++++++++++++++++++++++------- debian/mongokerberos.1 | 7 +- debian/mongoldap.1 | 27 +- debian/mongos.1 | 904 +++--------- 5 files changed, 2855 insertions(+), 2192 deletions(-) diff --git a/debian/mongod.1 b/debian/mongod.1 index 3fb4cb658ad..c854769102d 100644 --- a/debian/mongod.1 +++ b/debian/mongod.1 @@ -1,12 +1,12 @@ .TH mongod 1 .SH MONGOD .SH SYNOPSIS -\fBmongod\f1\f1 is the primary daemon process for the MongoDB +\fBmongod\f1 is the primary daemon process for the MongoDB system. It handles data requests, manages data access, and performs background management operations. .PP This document provides a complete overview of all command line options -for \fBmongod\f1\f1\&. These command line options are primarily useful +for \fBmongod\f1\&. These command line options are primarily useful for testing: In common operation, use the \fBconfiguration file options\f1 to control the behavior of your database. @@ -14,8 +14,35 @@ your database. \fBConfiguration File Settings and Command\-Line Options Mapping\f1 .PP MongoDB disables support for TLS 1.0 -encryption on systems where TLS 1.1+ is available. For -more details, see \fBDisable TLS 1.0\f1\&. +encryption on systems where TLS 1.1+ is available. +.SH COMPATIBILITY +.PP +Deployments hosted in the following environments use \fBmongod\f1: +.RS +.IP \(bu 2 +MongoDB Atlas (https://www.mongodb.com/docs/atlas?tck=docs_server): The fully +managed service for MongoDB deployments in the cloud +.RE +.PP +MongoDB Atlas manages the \fBmongod\f1 for all MongoDB Atlas deployments. +.RS +.IP \(bu 2 +\fBMongoDB Enterprise\f1: The +subscription\-based, self\-managed version of MongoDB +.IP \(bu 2 +\fBMongoDB Community\f1: The +source\-available, free\-to\-use, and self\-managed version of MongoDB +.RE +.SH CONSIDERATIONS +.RS +.IP \(bu 2 +\fBmongod\f1\f1 includes a \fBFull Time Diagnostic Data Capture\f1 mechanism to assist MongoDB engineers with troubleshooting +deployments. If this thread fails, it terminates the originating process. +To avoid the most common failures, confirm that the user running the +process has permissions to create the FTDC \fBdiagnostic.data\f1 +directory. For \fBmongod\f1 the directory is within +\fBstorage.dbPath\f1\f1\&. For \fBmongos\f1 it is parallel to \fBsystemLog.path\f1\f1\&. +.RE .SH OPTIONS .RS .IP \(bu 2 @@ -32,31 +59,18 @@ MongoDB removes the \fB\-\-cpu\f1 command\-line option. MongoDB removes the \fB\-\-serviceExecutor\f1 command\-line option and the corresponding \fBnet.serviceExecutor\f1 configuration option. .RE -.RS -.IP \(bu 2 -MongoDB removes the \fB\-\-noIndexBuildRetry\f1 command\-line option -and the corresponding \fBstorage.indexBuildRetry\f1 option. -.RE -.RS -.IP \(bu 2 -MongoDB deprecates the SSL options and instead adds new -corresponding TLS options. -.IP \(bu 2 -MongoDB adds -\fB\-\-tlsClusterCAFile\f1\f1/\fBnet.tls.clusterCAFile\f1\f1\&. -.RE .SS CORE OPTIONS .PP \fBmongod \-\-help\f1, \fBmongod \-h\f1 .RS .PP -Returns information on the options and use of \fBmongod\f1\f1\&. +Returns information on the options and use of \fBmongod\f1\&. .RE .PP \fBmongod \-\-version\f1 .RS .PP -Returns the \fBmongod\f1\f1 release number. +Returns the \fBmongod\f1 release number. .RE .PP \fBmongod \-\-config\f1, \fBmongod \-f\f1 @@ -64,11 +78,11 @@ Returns the \fBmongod\f1\f1 release number. .PP Specifies a configuration file for runtime configuration options. The configuration file is the preferred method for runtime configuration of -\fBmongod\f1\f1\&. The options are equivalent to the command\-line +\fBmongod\f1\&. The options are equivalent to the command\-line configuration options. See \fBConfiguration File Options\f1 for more information. .PP -Ensure the configuration file uses ASCII encoding. The \fBmongod\f1\f1 +Ensure the configuration file uses ASCII encoding. The \fBmongod\f1 instance does not support configuration files with non\-ASCII encoding, including UTF\-8. .RE @@ -96,8 +110,8 @@ Description .IP \(bu 4 \fBnone\f1 .IP \(bu 4 -Default. \fBmongod\f1\f1 does not expand expansion directives. -\fBmongod\f1\f1 fails to start if any configuration file settings +Default. \fBmongod\f1 does not expand expansion directives. +\fBmongod\f1 fails to start if any configuration file settings use expansion directives. .RE .IP \(bu 2 @@ -105,7 +119,7 @@ use expansion directives. .IP \(bu 4 \fBrest\f1 .IP \(bu 4 -\fBmongod\f1\f1 expands \fB__rest\f1 expansion directives when +\fBmongod\f1 expands \fB__rest\f1 expansion directives when parsing the configuration file. .RE .IP \(bu 2 @@ -113,14 +127,14 @@ parsing the configuration file. .IP \(bu 4 \fBexec\f1 .IP \(bu 4 -\fBmongod\f1\f1 expands \fB__exec\f1 expansion directives when +\fBmongod\f1 expands \fB__exec\f1 expansion directives when parsing the configuration file. .RE .RE .PP You can specify multiple expansion directives as a comma\-separated -list, e.g. \fBrest, exec\f1\&. If the configuration file contains -expansion directives not specified to \fB\-\-configExpand\f1\f1, the \fBmongod\f1\f1 +list, for example: \fBrest, exec\f1\&. If the configuration file contains +expansion directives not specified to \fB\-\-configExpand\f1\f1, the \fBmongod\f1 returns an error and terminates. .PP See \fBExternally Sourced Configuration File Values\f1 for configuration files @@ -132,7 +146,7 @@ for more information on expansion directives. .PP Increases the amount of internal reporting returned on standard output or in log files. Increase the verbosity with the \fB\-v\f1 form by -including the option multiple times, (e.g. \fB\-vvvvv\f1\&.) +including the option multiple times, for example: \fB\-vvvvv\f1\&. .PP Starting in version 4.2, MongoDB includes the Debug verbosity level (1\-5) in the \fBlog messages\f1\&. For example, @@ -143,7 +157,7 @@ versions, MongoDB log messages only specified \fBD\f1 for Debug level. \fBmongod \-\-quiet\f1 .RS .PP -Runs \fBmongod\f1\f1 in a quiet mode that attempts to limit the amount +Runs \fBmongod\f1 in a quiet mode that attempts to limit the amount of output. .PP This option suppresses: @@ -165,15 +179,19 @@ connection closed events \fIDefault\f1: .RS .IP \(bu 2 -27017 if \fBmongod\f1\f1 is not a shard member or a config server member +27017 if \fBmongod\f1 is not a shard member or a config server member .IP \(bu 2 -27018 if \fBmongod\f1\f1 is a \fBshard member\f1\f1 +27018 if \fBmongod\f1 is a \fBshard member\f1\f1 .IP \(bu 2 -27019 if \fBmongod\f1\f1 is a \fBconfig server member\f1\f1 +27019 if \fBmongod\f1 is a \fBconfig server member\f1\f1 .RE .PP The TCP port on which the MongoDB instance listens for client connections. +.PP +The \fB\-\-port\f1 option accepts a range of values between \fB0\f1 and \fB65535\f1\&. +Setting the port to \fB0\f1 configures \fBmongod\f1 to use an arbitrary port +assigned by the operating system. .RE .PP \fBmongod \-\-bind_ip\f1 @@ -182,15 +200,15 @@ client connections. \fIDefault\f1: localhost .PP The hostnames and/or IP addresses and/or full Unix domain socket -paths on which \fBmongod\f1\f1 should listen for client connections. You -may attach \fBmongod\f1\f1 to any interface. To bind to multiple +paths on which \fBmongod\f1 should listen for client connections. You +may attach \fBmongod\f1 to any interface. To bind to multiple addresses, enter a list of comma\-separated values. .PP You can specify both IPv4 and IPv6 addresses, or hostnames that resolve to an IPv4 or IPv6 address. .PP If specifying an IPv6 address \fIor\f1 a hostname that resolves to an -IPv6 address to \fB\-\-bind_ip\f1\f1, you must start \fBmongod\f1\f1 with +IPv6 address to \fB\-\-bind_ip\f1\f1, you must start \fBmongod\f1 with \fB\-\-ipv6\f1\f1 to enable IPv6 support. Specifying an IPv6 address to \fB\-\-bind_ip\f1\f1 does not enable IPv6 support. .PP @@ -207,8 +225,7 @@ set members or sharded cluster members. .PP Use hostnames instead of IP addresses to configure clusters across a split network horizon. Starting in MongoDB 5.0, nodes that are only -configured with an IP address will fail startup validation and will -not start. +configured with an IP address fail startup validation and do not start. .PP Before you bind your instance to a publicly\-accessible IP address, you must secure your cluster from unauthorized access. For a complete @@ -223,13 +240,12 @@ For more information about IP Binding, refer to the To bind to all IPv4 addresses, enter \fB0.0.0.0\f1\&. .PP To bind to all IPv4 and IPv6 addresses, enter \fB::,0.0.0.0\f1 or -starting in MongoDB 4.2, an asterisk \fB"*"\f1 (enclose the asterisk in -quotes to avoid filename pattern expansion). Alternatively, use the -\fBnet.bindIpAll\f1\f1 setting. +an asterisk \fB"*"\f1 (enclose the asterisk in quotes to avoid filename +pattern expansion). Alternatively, use the \fBnet.bindIpAll\f1\f1 setting. .RS .IP \(bu 2 \fB\-\-bind_ip\f1 and \fB\-\-bind_ip_all\f1 are mutually exclusive. -Specifying both options causes \fBmongod\f1\f1 to throw an error and +Specifying both options causes \fBmongod\f1 to throw an error and terminate. .IP \(bu 2 The command\-line option \fB\-\-bind\f1 overrides the configuration @@ -240,12 +256,12 @@ file setting \fBnet.bindIp\f1\f1\&. \fBmongod \-\-bind_ip_all\f1 .RS .PP -If specified, the \fBmongod\f1\f1 instance binds to all IPv4 -addresses (i.e. \fB0.0.0.0\f1). If \fBmongod\f1\f1 starts with +If specified, the \fBmongod\f1 instance binds to all IPv4 +addresses (i.e. \fB0.0.0.0\f1). If \fBmongod\f1 starts with \fB\-\-ipv6\f1\f1, \fB\-\-bind_ip_all\f1\f1 also binds to all IPv6 addresses (i.e. \fB::\f1). .PP -\fBmongod\f1\f1 only supports IPv6 if started with \fB\-\-ipv6\f1\f1\&. Specifying +\fBmongod\f1 only supports IPv6 if started with \fB\-\-ipv6\f1\f1\&. Specifying \fB\-\-bind_ip_all\f1\f1 alone does not enable IPv6 support. .PP Before you bind your instance to a publicly\-accessible IP address, @@ -259,8 +275,8 @@ For more information about IP Binding, refer to the \fBIP Binding\f1 documentation. .PP Alternatively, you can set the \fB\-\-bind_ip\f1 option to \fB::,0.0.0.0\f1 -or, starting in MongoDB 4.2, to an asterisk \fB"*"\f1 (enclose the -asterisk in quotes to avoid filename pattern expansion). +or to an asterisk \fB"*"\f1 (enclose the asterisk in quotes to avoid filename +pattern expansion). .PP \fB\-\-bind_ip\f1 and \fB\-\-bind_ip_all\f1 are mutually exclusive. That is, you can specify one or the other, but not both. @@ -270,14 +286,14 @@ is, you can specify one or the other, but not both. .RS .PP A list of IP addresses/CIDR (Classless Inter\-Domain Routing (https://tools.ietf.org/html/rfc4632)) ranges against which the -\fBmongod\f1\f1 validates authentication requests from other members of +\fBmongod\f1 validates authentication requests from other members of the replica set and, if part of a sharded cluster, the \fBmongos\f1\f1 -instances. The \fBmongod\f1\f1 verifies that the originating IP is +instances. The \fBmongod\f1 verifies that the originating IP is either explicitly in the list or belongs to a CIDR range in the list. If the IP address is not present, the server does not authenticate the -\fBmongod\f1\f1 or \fBmongos\f1\f1\&. +\fBmongod\f1 or \fBmongos\f1\f1\&. .PP -\fB\-\-clusterIpSourceAllowlist\f1\f1 has no effect on a \fBmongod\f1\f1 started without +\fB\-\-clusterIpSourceAllowlist\f1\f1 has no effect on a \fBmongod\f1 started without \fBauthentication\f1\&. .PP \fB\-\-clusterIpSourceAllowlist\f1\f1 accepts multiple comma\-separated IPv4/6 addresses or Classless @@ -299,14 +315,14 @@ deployment to ensure healthy communication between cluster components. Use \fB\-\-clusterIpSourceAllowlist\f1\f1 instead. .PP A list of IP addresses/CIDR (Classless Inter\-Domain Routing (https://tools.ietf.org/html/rfc4632)) ranges against which the -\fBmongod\f1\f1 validates authentication requests from other members of +\fBmongod\f1 validates authentication requests from other members of the replica set and, if part of a sharded cluster, the \fBmongos\f1\f1 -instances. The \fBmongod\f1\f1 verifies that the originating IP is +instances. The \fBmongod\f1 verifies that the originating IP is either explicitly in the list or belongs to a CIDR range in the list. If the IP address is not present, the server does not authenticate the -\fBmongod\f1\f1 or \fBmongos\f1\f1\&. +\fBmongod\f1 or \fBmongos\f1\f1\&. .PP -\fB\-\-clusterIpSourceWhitelist\f1\f1 has no effect on a \fBmongod\f1\f1 started without +\fB\-\-clusterIpSourceWhitelist\f1\f1 has no effect on a \fBmongod\f1 started without \fBauthentication\f1\&. .PP \fB\-\-clusterIpSourceWhitelist\f1\f1 accepts multiple comma\-separated IPv4/6 addresses or Classless @@ -324,10 +340,10 @@ deployment to ensure healthy communication between cluster components. \fBmongod \-\-ipv6\f1 .RS .PP -Enables IPv6 support. \fBmongod\f1\f1 disables IPv6 support by default. +Enables IPv6 support. \fBmongod\f1 disables IPv6 support by default. .PP -Setting \fB\-\-ipv6\f1\f1 does \fInot\f1 direct the \fBmongod\f1\f1 to listen on any -local IPv6 addresses or interfaces. To configure the \fBmongod\f1\f1 to +Setting \fB\-\-ipv6\f1\f1 does \fInot\f1 direct the \fBmongod\f1 to listen on any +local IPv6 addresses or interfaces. To configure the \fBmongod\f1 to listen on an IPv6 interface, you must either: .RS .IP \(bu 2 @@ -382,8 +398,8 @@ of connections which are forced into a backoff state. \fBmongod \-\-maxConns\f1 .RS .PP -The maximum number of simultaneous connections that \fBmongod\f1\f1 will -accept. This setting has no effect if it is higher than your operating +The maximum number of simultaneous connections that \fBmongod\f1 +accepts. This setting has no effect if it is higher than your operating system\(aqs configured maximum connection tracking threshold. .PP Do not assign too low of a value to this option, or you will @@ -397,7 +413,7 @@ Sends all diagnostic logging information to a log file instead of to standard output or to the host\(aqs \fBsyslog\f1 system. MongoDB creates the log file at the path you specify. .PP -By default, MongoDB will move any existing log file rather than overwrite +By default, MongoDB moves any existing log file rather than overwriting it. To instead append to the log file, set the \fB\-\-logappend\f1\f1 option. .RE .PP @@ -415,7 +431,8 @@ for log entries, especially when the system is under heavy load. We recommend using the \fB\-\-logpath\f1\f1 option for production systems to ensure accurate timestamps. .PP -Starting in version 4.2, MongoDB includes the \fBcomponent\f1 in its log messages to \fBsyslog\f1\&. +MongoDB includes the \fBcomponent\f1 in its log +messages to \fBsyslog\f1\&. .PP .EX ... ACCESS [repl writer worker 5] Unsupported modification to roles collection ... @@ -436,8 +453,8 @@ must enable the \fB\-\-syslog\f1\f1 option. \fBmongod \-\-logappend\f1 .RS .PP -Appends new entries to the end of the existing log file when the \fBmongod\f1\f1 -instance restarts. Without this option, \fBmongod\f1\f1 will back up the +Appends new entries to the end of the existing log file when the \fBmongod\f1 +instance restarts. Without this option, \fBmongod\f1 backs up the existing log and create a new file. .RE .PP @@ -496,9 +513,8 @@ format. For example, for New York at the start of the Epoch: .RE .RE .PP -Starting in MongoDB 4.4, \fB\-\-timeStampFormat\f1\f1 no longer supports \fBctime\f1\&. -An example of \fBctime\f1 formatted date is: \fBWed Dec 31 -18:17:54.811\f1\&. +\fB\-\-timeStampFormat\f1\f1 no longer supports \fBctime\f1\&. An example of \fBctime\f1 +formatted date is: \fBWed Dec 31 18:17:54.811\f1\&. .RE .PP \fBmongod \-\-traceExceptions\f1 @@ -510,7 +526,7 @@ For internal diagnostic use only. \fBmongod \-\-pidfilepath\f1 .RS .PP -Specifies a file location to store the process ID (PID) of the \fBmongod\f1\f1 +Specifies a file location to store the process ID (PID) of the \fBmongod\f1 process. The user running the \fBmongod\f1 or \fBmongos\f1 process must be able to write to this path. If the \fB\-\-pidfilepath\f1\f1 option is not specified, the process does not create a PID file. This option is generally @@ -538,9 +554,8 @@ that MongoDB instances use to authenticate to each other in a \fB\-\-auth\f1\f1\&. See \fBInternal/Membership Authentication\f1 for more information. .PP -Starting in MongoDB 4.2, \fBkeyfiles for internal membership -authentication\f1 use YAML format to allow for -multiple keys in a keyfile. The YAML format accepts either: +\fBKeyfiles for internal membership authentication\f1 use YAML format to allow for multiple keys in a +keyfile. The YAML format accepts either: .RS .IP \(bu 2 A single key string (same as in earlier versions) @@ -566,7 +581,7 @@ fields. Disables listening on the UNIX domain socket. \fB\-\-nounixsocket\f1\f1 applies only to Unix\-based systems. .PP -The \fBmongod\f1\f1 process +The \fBmongod\f1 process always listens on the UNIX socket unless one of the following is true: .RS .IP \(bu 2 @@ -577,7 +592,7 @@ always listens on the UNIX socket unless one of the following is true: \fBnet.bindIp\f1\f1 does not specify \fBlocalhost\f1 or its associated IP address .RE .PP -\fBmongod\f1\f1 installed from official \fB\&.deb\f1 and \fB\&.rpm\f1 packages +\fBmongod\f1 installed from official \fB\&.deb\f1 and \fB\&.rpm\f1 packages have the \fBbind_ip\f1 configuration set to \fB127.0.0.1\f1 by default. .RE @@ -591,7 +606,7 @@ The path for the UNIX socket. \fB\-\-unixSocketPrefix\f1\f1 applies only to Unix\-based systems. .PP If this option has no value, the -\fBmongod\f1\f1 process creates a socket with \fB/tmp\f1 as a prefix. MongoDB +\fBmongod\f1 process creates a socket with \fB/tmp\f1 as a prefix. MongoDB creates and listens on a UNIX socket unless one of the following is true: .RS .IP \(bu 2 @@ -618,22 +633,20 @@ Sets the permission for the UNIX domain socket file. \fBmongod \-\-fork\f1 .RS .PP -Enables a \fBdaemon\f1 mode that runs the \fBmongod\f1\f1 process in the -background. By default \fBmongod\f1\f1 does not run as a daemon: -typically you will run \fBmongod\f1\f1 as a daemon, either by using -\fB\-\-fork\f1\f1 or by using a controlling process that handles the -daemonization process (e.g. as with \fBupstart\f1 and \fBsystemd\f1). +Enables a \fBdaemon\f1 mode that runs the \fBmongod\f1 process in the +background. The \fB\-\-fork\f1\f1 option is not supported on Windows. .PP -Using the \fB\-\-fork\f1\f1 option requires that you configure log -output for the \fBmongod\f1\f1 with one of the following: +By default \fBmongod\f1 does not run as a daemon. You run \fBmongod\f1 as +a daemon by using either \fB\-\-fork\f1\f1 or a controlling process +that handles daemonization, such as \fBupstart\f1 or \fBsystemd\f1\&. +.PP +To use \fB\-\-fork\f1\f1, configure log output for the \fBmongod\f1 with one of the following: .RS .IP \(bu 2 \fB\-\-logpath\f1\f1 .IP \(bu 2 \fB\-\-syslog\f1\f1 .RE -.PP -The \fB\-\-fork\f1\f1 option is not supported on Windows. .RE .PP \fBmongod \-\-auth\f1 @@ -645,11 +658,10 @@ clients to authenticate themselves first in order to determine the access for the client. .PP To configure users, use the \fBmongosh\f1\f1 client. If no users -exist, the localhost interface will continue to have access to the +exist, the localhost interface has access to the database until you create the first user. .PP -See \fBSecurity\f1 -for more information. +See \fBSecurity\f1 for more information. .RE .PP \fBmongod \-\-noauth\f1 @@ -662,8 +674,8 @@ compatibility and clarity. \fBmongod \-\-transitionToAuth\f1 .RS .PP -Allows the \fBmongod\f1\f1 to accept and create authenticated and -non\-authenticated connections to and from other \fBmongod\f1\f1 +Allows the \fBmongod\f1 to accept and create authenticated and +non\-authenticated connections to and from other \fBmongod\f1 and \fBmongos\f1\f1 instances in the deployment. Used for performing rolling transition of replica sets or sharded clusters from a no\-auth configuration to \fBinternal authentication\f1\&. Requires specifying a \fBinternal @@ -671,19 +683,19 @@ authentication\f1 mechanism such as \fB\-\-keyFile\f1\f1\&. .PP For example, if using \fBkeyfiles\f1 for -\fBinternal authentication\f1, the \fBmongod\f1\f1 creates -an authenticated connection with any \fBmongod\f1\f1 or \fBmongos\f1\f1 +\fBinternal authentication\f1, the \fBmongod\f1 creates +an authenticated connection with any \fBmongod\f1 or \fBmongos\f1\f1 in the deployment using a matching keyfile. If the security mechanisms do -not match, the \fBmongod\f1\f1 utilizes a non\-authenticated connection instead. +not match, the \fBmongod\f1 utilizes a non\-authenticated connection instead. .PP -A \fBmongod\f1\f1 running with \fB\-\-transitionToAuth\f1\f1 does not enforce \fBuser access +A \fBmongod\f1 running with \fB\-\-transitionToAuth\f1\f1 does not enforce \fBuser access controls\f1\&. Users may connect to your deployment without any access control checks and perform read, write, and administrative operations. .PP -A \fBmongod\f1\f1 running with \fBinternal authentication\f1 and \fIwithout\f1 \fB\-\-transitionToAuth\f1\f1 requires clients to connect +A \fBmongod\f1 running with \fBinternal authentication\f1 and \fIwithout\f1 \fB\-\-transitionToAuth\f1\f1 requires clients to connect using \fBuser access controls\f1\&. Update clients to -connect to the \fBmongod\f1\f1 using the appropriate \fBuser\f1 -prior to restarting \fBmongod\f1\f1 without \fB\-\-transitionToAuth\f1\f1\&. +connect to the \fBmongod\f1 using the appropriate \fBuser\f1 +prior to restarting \fBmongod\f1 without \fB\-\-transitionToAuth\f1\f1\&. .RE .PP \fBmongod \-\-sysinfo\f1 @@ -709,8 +721,8 @@ Forbids operations that require a collection scan. See \fBnotablescan\f1\f1 for \fBmongod \-\-shutdown\f1 .RS .PP -The \fB\-\-shutdown\f1\f1 option cleanly and safely terminates the \fBmongod\f1\f1 -process. When invoking \fBmongod\f1\f1 with this option you must set the +The \fB\-\-shutdown\f1\f1 option cleanly and safely terminates the \fBmongod\f1 +process. When invoking \fBmongod\f1 with this option you must set the \fB\-\-dbpath\f1\f1 option either directly or by way of the \fBconfiguration file\f1 and the \fB\-\-config\f1\f1 option. @@ -725,8 +737,8 @@ For additional ways to shut down, see also \fBStop mongod\f1 Processes\f1\&. .PP \fIAvailable in MongoDB Enterprise only.\f1 .PP -A \fBmongod\f1\f1 running with \fB\-\-redactClientLogData\f1\f1 redacts any message accompanying a given -log event before logging. This prevents the \fBmongod\f1\f1 from writing +A \fBmongod\f1 running with \fB\-\-redactClientLogData\f1\f1 redacts any message accompanying a given +log event before logging. This prevents the \fBmongod\f1 from writing 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. @@ -737,19 +749,19 @@ Use \fB\-\-redactClientLogData\f1\f1 in conjunction with regulatory requirements. .PP For example, a MongoDB deployment might store Personally Identifiable -Information (PII) in one or more collections. The \fBmongod\f1\f1 logs events +Information (PII) in one or more collections. The \fBmongod\f1 logs events such as those related to CRUD operations, sharding metadata, etc. It is -possible that the \fBmongod\f1\f1 may expose PII as a part of these logging -operations. A \fBmongod\f1\f1 running with \fB\-\-redactClientLogData\f1\f1 removes any message +possible that the \fBmongod\f1 may expose PII as a part of these logging +operations. A \fBmongod\f1 running with \fB\-\-redactClientLogData\f1\f1 removes any message accompanying these events before being output to the log, effectively removing the PII. .PP -Diagnostics on a \fBmongod\f1\f1 running with \fB\-\-redactClientLogData\f1\f1 may be more difficult +Diagnostics on a \fBmongod\f1 running with \fB\-\-redactClientLogData\f1\f1 may be more difficult due to the lack of data related to a log event. See the \fBprocess logging\f1 manual page for an example of the effect of \fB\-\-redactClientLogData\f1\f1 on log output. .PP -On a running \fBmongod\f1\f1, use \fBsetParameter\f1\f1 with the +On a running \fBmongod\f1, use \fBsetParameter\f1\f1 with the \fBredactClientLogData\f1\f1 parameter to configure this setting. .RE .PP @@ -759,7 +771,7 @@ On a running \fBmongod\f1\f1, use \fBsetParameter\f1\f1 with the \fIDefault\f1: snappy,zstd,zlib .PP Specifies the default compressor(s) to use for -communication between this \fBmongod\f1\f1 instance and: +communication between this \fBmongod\f1 instance and: .RS .IP \(bu 2 other members of the deployment if the instance is part of a replica set or a sharded cluster @@ -779,9 +791,8 @@ MongoDB supports the following compressors: \fBzstd\f1 .RE .PP -Both \fBmongod\f1\f1 and -\fBmongos\f1\f1 instances default to \fBsnappy,zstd,zlib\f1 -compressors, in that order. +Both \fBmongod\f1 and \fBmongos\f1\f1 instances default to +\fBsnappy,zstd,zlib\f1 compressors, in that order. .PP To disable network compression, set the value to \fBdisabled\f1\&. .PP @@ -808,7 +819,7 @@ compressed. .RS .PP The full path from which to load the time zone database. If this option -is not provided, then MongoDB will use its built\-in time zone database. +is not provided, then MongoDB uses its built\-in time zone database. .PP The configuration file included with Linux and macOS packages sets the time zone database path to \fB/usr/share/zoneinfo\f1 by default. @@ -831,8 +842,7 @@ could create inaccurate time zone conversions in older versions of MongoDB. .PP To explicitly link to the time zone database in versions of MongoDB -prior to 5.0, 4.4.7, and 4.2.14, download the time zone -database (https://downloads.mongodb.org/olson_tz_db/timezonedb\-latest.zip)\&. +prior to 5.0, download the time zone database (https://downloads.mongodb.org/olson_tz_db/timezonedb\-latest.zip)\&. and use the \fBtimeZoneInfo\f1\f1 parameter. .PP \fBprocessManagement.timeZoneInfo\f1\f1\&. @@ -841,8 +851,8 @@ and use the \fBtimeZoneInfo\f1\f1 parameter. \fBmongod \-\-outputConfig\f1 .RS .PP -Outputs the \fBmongod\f1\f1 instance\(aqs configuration options, formatted -in YAML, to \fBstdout\f1 and exits the \fBmongod\f1\f1 instance. For +Outputs the \fBmongod\f1 instance\(aqs configuration options, formatted +in YAML, to \fBstdout\f1 and exits the \fBmongod\f1 instance. For configuration options that uses \fBExternally Sourced Configuration File Values\f1, \fB\-\-outputConfig\f1\f1 returns the resolved value for those options. .PP @@ -864,7 +874,7 @@ For usage examples, see: .PP \fIAvailable in MongoDB Enterprise only.\f1 .PP -The LDAP server against which the \fBmongod\f1\f1 authenticates users or +The LDAP server against which the \fBmongod\f1 authenticates users or determines what actions a user is authorized to perform on a given database. If the LDAP server specified has any replicated instances, you may specify the host and port of each replicated server in a @@ -876,10 +886,10 @@ servers, specify \fIone\f1 LDAP server or any of its replicated instances to 4.1.10 (https://www.rfc\-editor.org/rfc/rfc4511.txt)\&. Do not use \fB\-\-ldapServers\f1\f1 for listing every LDAP server in your infrastructure. .PP -This setting can be configured on a running \fBmongod\f1\f1 using +This setting can be configured on a running \fBmongod\f1 using \fBsetParameter\f1\f1\&. .PP -If unset, \fBmongod\f1\f1 cannot use \fBLDAP authentication or authorization\f1\&. +If unset, \fBmongod\f1 cannot use \fBLDAP authentication or authorization\f1\&. .RE .PP \fBmongod \-\-ldapValidateLDAPServerConfig\f1 @@ -887,15 +897,15 @@ If unset, \fBmongod\f1\f1 cannot use \fBLDAP authentication or authorization\f1\ .PP \fIAvailable in MongoDB Enterprise\f1 .PP -A flag that determines if the \fBmongod\f1\f1 instance checks +A flag that determines if the \fBmongod\f1 instance checks the availability of the \fBLDAP server(s)\f1\f1 as part of its startup: .RS .IP \(bu 2 -If \fBtrue\f1, the \fBmongod\f1\f1 instance performs the +If \fBtrue\f1, the \fBmongod\f1 instance performs the availability check and only continues to start up if the LDAP server is available. .IP \(bu 2 -If \fBfalse\f1, the \fBmongod\f1\f1 instance skips the +If \fBfalse\f1, the \fBmongod\f1 instance skips the availability check; i.e. the instance starts up even if the LDAP server is unavailable. .RE @@ -906,7 +916,7 @@ server is unavailable. .PP \fIAvailable in MongoDB Enterprise only.\f1 .PP -The identity with which \fBmongod\f1\f1 binds as, when connecting to or +The identity with which \fBmongod\f1 binds as, when connecting to or performing queries on an LDAP server. .PP Only required if any of the following are true: @@ -921,9 +931,9 @@ The LDAP server disallows anonymous binds .PP You must use \fB\-\-ldapQueryUser\f1\f1 with \fB\-\-ldapQueryPassword\f1\f1\&. .PP -If unset, \fBmongod\f1\f1 will not attempt to bind to the LDAP server. +If unset, \fBmongod\f1 doesn\(aqt attempt to bind to the LDAP server. .PP -This setting can be configured on a running \fBmongod\f1\f1 using +This setting can be configured on a running \fBmongod\f1 using \fBsetParameter\f1\f1\&. .PP Windows MongoDB deployments can use \fB\-\-ldapBindWithOSDefaults\f1\f1 @@ -942,11 +952,10 @@ If not set, \fBmongod\f1\f1 does not attempt to bind to the LDAP server. You can configure this setting on a running \fBmongod\f1\f1 using \fBsetParameter\f1\f1\&. .PP -Starting in MongoDB 4.4, the \fBldapQueryPassword\f1 -\fBsetParameter\f1\f1 command accepts either a string or -an array of strings. If \fBldapQueryPassword\f1 is set to an array, MongoDB tries -each password in order until one succeeds. Use a password array to roll over the -LDAP account password without downtime. +The \fBldapQueryPassword\f1 \fBsetParameter\f1\f1 command accepts either a +string or an array of strings. If \fBldapQueryPassword\f1 is set to an array, +MongoDB tries each password in order until one succeeds. Use a password array +to roll over the LDAP account password without downtime. .PP Windows MongoDB deployments can use \fB\-\-ldapBindWithOSDefaults\f1\f1 instead of \fB\-\-ldapQueryUser\f1\f1 and \fB\-\-ldapQueryPassword\f1\f1\&. @@ -960,7 +969,7 @@ You cannot specify both \fB\-\-ldapQueryPassword\f1\f1 and .PP Available in MongoDB Enterprise for the Windows platform only. .PP -Allows \fBmongod\f1\f1 to authenticate, or bind, using your Windows login +Allows \fBmongod\f1 to authenticate, or bind, using your Windows login credentials when connecting to the LDAP server. .PP Only required if: @@ -984,20 +993,20 @@ Use \fB\-\-ldapBindWithOSDefaults\f1\f1 to replace \fB\-\-ldapQueryUser\f1\f1 an .PP \fIAvailable in MongoDB Enterprise only.\f1 .PP -The method \fBmongod\f1\f1 uses to authenticate to an LDAP server. +The method \fBmongod\f1 uses to authenticate to an LDAP server. Use with \fB\-\-ldapQueryUser\f1\f1 and \fB\-\-ldapQueryPassword\f1\f1 to connect to the LDAP server. .PP \fB\-\-ldapBindMethod\f1\f1 supports the following values: .RS .IP \(bu 2 -\fBsimple\f1 \- \fBmongod\f1\f1 uses simple authentication. +\fBsimple\f1 \- \fBmongod\f1 uses simple authentication. .IP \(bu 2 -\fBsasl\f1 \- \fBmongod\f1\f1 uses SASL protocol for authentication +\fBsasl\f1 \- \fBmongod\f1 uses SASL protocol for authentication .RE .PP If you specify \fBsasl\f1, you can configure the available SASL mechanisms -using \fB\-\-ldapBindSaslMechanisms\f1\f1\&. \fBmongod\f1\f1 defaults to +using \fB\-\-ldapBindSaslMechanisms\f1\f1\&. \fBmongod\f1 defaults to using \fBDIGEST\-MD5\f1 mechanism. .RE .PP @@ -1008,21 +1017,21 @@ using \fBDIGEST\-MD5\f1 mechanism. .PP \fIAvailable in MongoDB Enterprise only.\f1 .PP -A comma\-separated list of SASL mechanisms \fBmongod\f1\f1 can -use when authenticating to the LDAP server. The \fBmongod\f1\f1 and the -LDAP server must agree on at least one mechanism. The \fBmongod\f1\f1 +A comma\-separated list of SASL mechanisms \fBmongod\f1 can +use when authenticating to the LDAP server. The \fBmongod\f1 and the +LDAP server must agree on at least one mechanism. The \fBmongod\f1 dynamically loads any SASL mechanism libraries installed on the host machine at runtime. .PP Install and configure the appropriate libraries for the selected -SASL mechanism(s) on both the \fBmongod\f1\f1 host and the remote +SASL mechanism(s) on both the \fBmongod\f1 host and the remote LDAP server host. Your operating system may include certain SASL libraries by default. Defer to the documentation associated with each SASL mechanism for guidance on installation and configuration. .PP If using the \fBGSSAPI\f1 SASL mechanism for use with \fBKerberos Authentication\f1, verify the following for the -\fBmongod\f1\f1 host machine: +\fBmongod\f1 host machine: .PP \fBLinux\f1\f1 .RS @@ -1035,7 +1044,7 @@ variables, please defer to the Kerberos documentation (https://web.mit.edu/kerberos/krb5\-1.13/doc/admin/env_variables.html)\&. .IP \(bu 2 The client keytab includes a -\fBUser Principal\f1 for the \fBmongod\f1\f1 to use when +\fBUser Principal\f1 for the \fBmongod\f1 to use when connecting to the LDAP server and execute LDAP queries. .RE .RE @@ -1047,7 +1056,7 @@ If connecting to an Active Directory server, the Windows Kerberos configuration automatically generates a Ticket\-Granting\-Ticket (https://msdn.microsoft.com/en\-us/library/windows/desktop/aa380510(v=vs.85).aspx) when the user logs onto the system. Set \fB\-\-ldapBindWithOSDefaults\f1\f1 to -\fBtrue\f1 to allow \fBmongod\f1\f1 to use the generated credentials when +\fBtrue\f1 to allow \fBmongod\f1 to use the generated credentials when connecting to the Active Directory server and execute queries. .RE .PP @@ -1081,7 +1090,7 @@ For Windows, please see the Windows SASL documentation (https://msdn.microsoft.c .PP \fIAvailable in MongoDB Enterprise only.\f1 .PP -By default, \fBmongod\f1\f1 creates a TLS/SSL secured connection to the LDAP +By default, \fBmongod\f1 creates a TLS/SSL secured connection to the LDAP server. .PP For Linux deployments, you must configure the appropriate TLS Options in @@ -1097,11 +1106,11 @@ tool may vary depending on operating system version. Please see the documentation for your version of Windows for more information on certificate management. .PP -Set \fB\-\-ldapTransportSecurity\f1\f1 to \fBnone\f1 to disable TLS/SSL between \fBmongod\f1\f1 and the LDAP +Set \fB\-\-ldapTransportSecurity\f1\f1 to \fBnone\f1 to disable TLS/SSL between \fBmongod\f1 and the LDAP server. .PP Setting \fB\-\-ldapTransportSecurity\f1\f1 to \fBnone\f1 transmits plaintext information and possibly -credentials between \fBmongod\f1\f1 and the LDAP server. +credentials between \fBmongod\f1 and the LDAP server. .RE .PP \fBmongod \-\-ldapTimeoutMS\f1 @@ -1111,7 +1120,7 @@ credentials between \fBmongod\f1\f1 and the LDAP server. .PP \fIAvailable in MongoDB Enterprise only.\f1 .PP -The amount of time in milliseconds \fBmongod\f1\f1 should wait for an LDAP server +The amount of time in milliseconds \fBmongod\f1 should wait for an LDAP server to respond to a request. .PP Increasing the value of \fB\-\-ldapTimeoutMS\f1\f1 may prevent connection failure between the @@ -1119,7 +1128,7 @@ MongoDB server and the LDAP server, if the source of the failure is a connection timeout. Decreasing the value of \fB\-\-ldapTimeoutMS\f1\f1 reduces the time MongoDB waits for a response from the LDAP server. .PP -This setting can be configured on a running \fBmongod\f1\f1 using +This setting can be configured on a running \fBmongod\f1 using \fBsetParameter\f1\f1\&. .RE .PP @@ -1139,7 +1148,7 @@ network error. .PP \fIAvailable in MongoDB Enterprise only.\f1 .PP -Maps the username provided to \fBmongod\f1\f1 for authentication to a LDAP +Maps the username provided to \fBmongod\f1 for authentication to a LDAP Distinguished Name (DN). You may need to use \fB\-\-ldapUserToDNMapping\f1\f1 to transform a username into an LDAP DN in the following scenarios: .RS @@ -1149,9 +1158,9 @@ authenticate to MongoDB with usernames that are not full LDAP DNs. .IP \(bu 2 Using an \fBLDAP authorization query template\f1\f1 that requires a DN. .IP \(bu 2 -Transforming the usernames of clients authenticating to Mongo DB using -different authentication mechanisms (e.g. x.509, kerberos) to a full LDAP -DN for authorization. +Transforming the usernames of clients authenticating to Mongo DB +using different authentication mechanisms, such as x.509 or +kerberos, to a full LDAP DN for authorization. .RE .PP \fB\-\-ldapUserToDNMapping\f1\f1 expects a quote\-enclosed JSON\-string representing an ordered array @@ -1215,10 +1224,10 @@ name matched by the \fBmatch\f1 regex into an LDAP query URI encoded respecting RFC4515 and RFC4516. Each curly bracket\-enclosed numeric value is replaced by the corresponding regex capture group (http://www.regular\-expressions.info/refcapture.html) extracted from the authentication username via the \fBmatch\f1 expression. -\fBmongod\f1\f1 executes the query against the LDAP server to retrieve -the LDAP DN for the authenticated user. \fBmongod\f1\f1 requires +\fBmongod\f1 executes the query against the LDAP server to retrieve +the LDAP DN for the authenticated user. \fBmongod\f1 requires exactly one returned result for the transformation to be -successful, or \fBmongod\f1\f1 skips this transformation. +successful, or \fBmongod\f1 skips this transformation. .IP \(bu 4 \fB"ou=engineering,dc=example, dc=com??one?(user={0})"\f1 @@ -1234,31 +1243,30 @@ use your preferred LDAP resource. For each document in the array, you must use either \fBsubstitution\f1 or \fBldapQuery\f1\&. You \fIcannot\f1 specify both in the same document. .PP -When performing authentication or authorization, \fBmongod\f1\f1 steps through +When performing authentication or authorization, \fBmongod\f1 steps through each document in the array in the given order, checking the authentication username against the \fBmatch\f1 filter. If a match is found, -\fBmongod\f1\f1 applies the transformation and uses the output for -authenticating the user. \fBmongod\f1\f1 does not check the remaining documents +\fBmongod\f1 applies the transformation and uses the output for +authenticating the user. \fBmongod\f1 does not check the remaining documents in the array. .PP If the given document does not match the provided authentication -name, \fBmongod\f1\f1 continues through the list of documents +name, \fBmongod\f1 continues through the list of documents to find additional matches. If no matches are found in any document, or the transformation the document describes fails, -\fBmongod\f1\f1 returns an error. +\fBmongod\f1 returns an error. .PP -Starting in MongoDB 4.4, \fBmongod\f1\f1 also returns an error -if one of the transformations cannot be evaluated due to networking -or authentication failures to the LDAP server. \fBmongod\f1\f1 -rejects the connection request and does not check the remaining +\fBmongod\f1 also returns an error if one of the transformations cannot be +evaluated due to networking or authentication failures to the LDAP server. +\fBmongod\f1 rejects the connection request and does not check the remaining documents in the array. .PP Starting in MongoDB 5.0, \fB\-\-ldapUserToDNMapping\f1\f1 accepts an empty string \fB""\f1 or empty array \fB[ ]\f1 in place of a mapping documnent. If providing an empty string or empty array to -\fB\-\-ldapUserToDNMapping\f1\f1, MongoDB will map the -authenticated username as the LDAP DN. Previously, providing an -empty mapping document would cause mapping to fail. +\fB\-\-ldapUserToDNMapping\f1\f1, MongoDB maps the +authenticated username as the LDAP DN. In earlier versions, providing +an empty mapping document causes mapping to fail. .PP The following shows two transformation documents. The first document matches against any string ending in \fB@ENGINEERING\f1, placing @@ -1275,9 +1283,9 @@ anything preceeding the suffix into a regex capture group. { match: "(.+)@DBA.EXAMPLE.COM", ldapQuery: "ou=dba,dc=example,dc=com??one?(user={0})" - + } - + ]" .EE .PP @@ -1289,14 +1297,14 @@ document. The regex capture group \fB{0}\f1 corresponds to the string A user with username \fBbob@DBA.EXAMPLE.COM\f1 matches the second document. The regex capture group \fB{0}\f1 corresponds to the string \fBbob\f1\&. The resulting output is the LDAP query -\fB"ou=dba,dc=example,dc=com??one?(user=bob)"\f1\&. \fBmongod\f1\f1 executes this +\fB"ou=dba,dc=example,dc=com??one?(user=bob)"\f1\&. \fBmongod\f1 executes this query against the LDAP server, returning the result \fB"cn=bob,ou=dba,dc=example,dc=com"\f1\&. .PP -If \fB\-\-ldapUserToDNMapping\f1\f1 is unset, \fBmongod\f1\f1 applies no transformations to the username +If \fB\-\-ldapUserToDNMapping\f1\f1 is unset, \fBmongod\f1 applies no transformations to the username when attempting to authenticate or authorize a user against the LDAP server. .PP -This setting can be configured on a running \fBmongod\f1\f1 using the +This setting can be configured on a running \fBmongod\f1 using the \fBsetParameter\f1\f1 database command. .RE .PP @@ -1305,7 +1313,7 @@ This setting can be configured on a running \fBmongod\f1\f1 using the .PP \fIAvailable in MongoDB Enterprise only.\f1 .PP -A relative LDAP query URL formatted conforming to RFC4515 (https://tools.ietf.org/html/rfc4515) and RFC4516 (https://tools.ietf.org/html/rfc4516) that \fBmongod\f1\f1 executes to obtain +A relative LDAP query URL formatted conforming to RFC4515 (https://tools.ietf.org/html/rfc4515) and RFC4516 (https://tools.ietf.org/html/rfc4516) that \fBmongod\f1 executes to obtain the LDAP groups to which the authenticated user belongs to. The query is relative to the host or hosts specified in \fB\-\-ldapServers\f1\f1\&. .PP @@ -1344,15 +1352,15 @@ respects RFC4516: [ dn [ ? [attributes] [ ? [scope] [ ? [filter] [ ? [Extensions] ] ] ] ] ] .EE .PP -If your query includes an attribute, \fBmongod\f1\f1 assumes that the query +If your query includes an attribute, \fBmongod\f1 assumes that the query retrieves a the DNs which this entity is member of. .PP -If your query does not include an attribute, \fBmongod\f1\f1 assumes +If your query does not include an attribute, \fBmongod\f1 assumes the query retrieves all entities which the user is member of. .PP -For each LDAP DN returned by the query, \fBmongod\f1\f1 assigns the authorized +For each LDAP DN returned by the query, \fBmongod\f1 assigns the authorized user a corresponding role on the \fBadmin\f1 database. If a role on the on the -\fBadmin\f1 database exactly matches the DN, \fBmongod\f1\f1 grants the user the +\fBadmin\f1 database exactly matches the DN, \fBmongod\f1 grants the user the roles and privileges assigned to that role. See the \fBdb.createRole()\f1\f1 method for more information on creating roles. .PP @@ -1368,9 +1376,9 @@ of the user schema, may possess a different attribute for reporting group membership, or may not track group membership through attributes. Configure your query with respect to your own unique LDAP configuration. .PP -If unset, \fBmongod\f1\f1 cannot authorize users using LDAP. +If unset, \fBmongod\f1 cannot authorize users using LDAP. .PP -This setting can be configured on a running \fBmongod\f1\f1 using the +This setting can be configured on a running \fBmongod\f1 using the \fBsetParameter\f1\f1 database command. .PP An explanation of RFC4515 (https://tools.ietf.org/html/rfc4515), @@ -1385,10 +1393,7 @@ use your preferred LDAP resource. .PP \fIDefault\f1: \fBwiredTiger\f1 .PP -Starting in version 4.2, MongoDB removes the deprecated MMAPv1 storage -engine. -.PP -Specifies the storage engine for the \fBmongod\f1\f1 database. Available +Specifies the storage engine for the \fBmongod\f1 database. Available values include: .RS .IP \(bu 2 @@ -1416,10 +1421,10 @@ To specify the \fBIn\-Memory Storage Engine\f1\&. .RE .RE .PP -If you attempt to start a \fBmongod\f1\f1 with a +If you attempt to start a \fBmongod\f1 with a \fB\-\-dbpath\f1\f1 that contains data files produced by a -storage engine other than the one specified by \fB\-\-storageEngine\f1\f1, \fBmongod\f1\f1 -will refuse to start. +storage engine other than the one specified by +\fB\-\-storageEngine\f1\f1, \fBmongod\f1 doesn\(aqt start. .RE .PP \fBmongod \-\-dbpath\f1 @@ -1427,7 +1432,7 @@ will refuse to start. .PP \fIDefault\f1: \fB/data/db\f1 on Linux and macOS, \fB\data\db\f1 on Windows .PP -The directory where the \fBmongod\f1\f1 instance stores its data. +The directory where the \fBmongod\f1 instance stores its data. .PP If using the default \fBConfiguration File\f1 @@ -1437,8 +1442,7 @@ default. .PP The files in \fB\-\-dbpath\f1\f1 must correspond to the storage engine specified in \fB\-\-storageEngine\f1\f1\&. If the data files do not -correspond to \fB\-\-storageEngine\f1\f1, \fBmongod\f1\f1 will refuse to -start. +correspond to \fB\-\-storageEngine\f1\f1, \fBmongod\f1 doesn\(aqt start. .RE .PP \fBmongod \-\-directoryperdb\f1 @@ -1463,14 +1467,14 @@ For standalone instances: .RS .IP \(bu 4 Use \fBmongodump\f1\f1 on the existing -\fBmongod\f1\f1 instance to generate a backup. +\fBmongod\f1 instance to generate a backup. .IP \(bu 4 -Stop the \fBmongod\f1\f1 instance. +Stop the \fBmongod\f1 instance. .IP \(bu 4 Add the \fB\-\-directoryperdb\f1\f1 value \fBand\f1 configure a new data directory .IP \(bu 4 -Restart the \fBmongod\f1\f1 instance. +Restart the \fBmongod\f1 instance. .IP \(bu 4 Use \fBmongorestore\f1\f1 to populate the new data directory. @@ -1503,23 +1507,23 @@ same fashion. \fIDefault\f1: 60 .PP Controls how much time can pass before MongoDB flushes data to the data -files via an \fBfsync\f1 operation. +files. .PP \fBDo not set this value on production systems.\f1 In almost every situation, you should use the default setting. .PP -If you set \fB\-\-syncdelay\f1\f1 to \fB0\f1, MongoDB will not sync the -memory mapped files to disk. -.PP -The \fBmongod\f1\f1 process writes data very quickly to the journal and +The \fBmongod\f1 process writes data very quickly to the journal and lazily to the data files. \fB\-\-syncdelay\f1\f1 has no effect on \fBjournaling\f1, but if \fB\-\-syncdelay\f1\f1 is set to -\fB0\f1 the journal will eventually consume -all available disk space. +\fB0\f1 the journal eventually consumes all available disk space. .PP Not available for \fBmongod\f1\f1 instances that use the \fBin\-memory storage engine\f1\&. +.PP +To provide \fBdurable\f1 data, \fBWiredTiger\f1 +uses \fBcheckpoints\f1\&. For more +details, see \fBJournaling and the WiredTiger Storage Engine\f1\&. .RE .PP \fBmongod \-\-upgrade\f1 @@ -1528,7 +1532,7 @@ Not available for \fBmongod\f1\f1 instances that use the Upgrades the on\-disk data format of the files specified by the \fB\-\-dbpath\f1\f1 to the latest version, if needed. .PP -This option only affects the operation of the \fBmongod\f1\f1 if the data +This option only affects the operation of the \fBmongod\f1 if the data files are in an old format. .PP In most cases you should not set this value, so you can exercise the @@ -1539,7 +1543,7 @@ for more information about the upgrade process. \fBmongod \-\-repair\f1 .RS .PP -Runs a repair routine on all databases for a \fBmongod\f1\f1 +Runs a repair routine on all databases for a \fBmongod\f1 instance. .PP Starting in MongoDB 5.0: @@ -1554,20 +1558,6 @@ inconsistencies that the validate step is unable to fix, then all indexes are rebuilt. .RE .PP -In MongoDB 4.4 and previous versions, the repair operation attempts -to: -.RS -.IP \(bu 2 -Salvage corrupt data. The operation discards any corrupt -data that cannot be salvaged. -.IP \(bu 2 -Rebuild indexes. The operation validates collections and rebuilds -all indexes for collections with inconsistencies between the -collection data and one or more indexes. The operation also -rebuilds indexes for all salvaged and modified collections. -(\fIChanged in version 4.4.\f1) -.RE -.PP If you are running with \fBjournaling\f1 enabled, there is almost never any need to run repair since the server can use the journal files to restore the data files to a clean state automatically. @@ -1586,9 +1576,9 @@ a replica set member: To repair a \fBreplica set\f1 member, if you have an intact copy of your data available (e.g. a recent backup or an intact member of the \fBreplica set\f1), restore from that intact -copy instead(see \fBResync a Member of a Replica Set\f1). +copy instead. To learn more, see \fBResync a Member of a Replica Set\f1\&. .IP \(bu 4 -If you do choose to run \fBmongod \-\-repair\f1\f1 against a +If you choose to run \fBmongod \-\-repair\f1\f1 against a replica set member and the operation modifies the data or the metadata, you must still perform a full resync in order for the member to rejoin the replica set. @@ -1608,36 +1598,33 @@ instance using the \fB\-\-repair\f1\f1 option. \fIDefault\f1: 100 .PP The maximum amount of time in milliseconds that -the \fBmongod\f1\f1 process allows between +the \fBmongod\f1 process allows between journal operations. Values can range from 1 to 500 milliseconds. Lower values increase the durability of the journal, at the expense of disk performance. .PP On WiredTiger, the default journal commit interval is 100 -milliseconds. Additionally, a write that includes or implies -\fBj:true\f1 will cause an immediate sync of the journal. For details -or additional conditions that affect the frequency of the sync, see +milliseconds. A write that includes or implies +\fBj:true\f1 causes an immediate sync of the journal. For details +and additional conditions that affect the frequency of the sync, see \fBJournaling Process\f1\&. .PP Not available for \fBmongod\f1\f1 instances that use the \fBin\-memory storage engine\f1\&. -.PP -Known Issue in 4.2.0: The \fB\-\-journalCommitInterval\f1\f1 is missing in 4.2.0. .RE .SS WIREDTIGER OPTIONS .PP \fBmongod \-\-wiredTigerCacheSizeGB\f1 .RS .PP -Defines the maximum size of the internal cache that WiredTiger will -use for all data. The memory consumed by an index build (see +Defines the maximum size of the internal cache that WiredTiger +uses for all data. The memory consumed by an index build (see \fBmaxIndexBuildMemoryUsageMegabytes\f1\f1) is separate from the WiredTiger cache memory. .PP Values can range from \fB0.25\f1 GB to \fB10000\f1 GB. .PP -Starting in MongoDB 3.4, the default WiredTiger internal cache size is -the larger of either: +The default WiredTiger internal cache size is the larger of either: .RS .IP \(bu 2 50% of (RAM \- 1 GB), or @@ -1645,11 +1632,12 @@ the larger of either: 256 MB. .RE .PP -For example, on a system with a total of 4GB of RAM the WiredTiger -cache will use 1.5GB of RAM (\fB0.5 * (4 GB \- 1 GB) = 1.5 GB\f1). -Conversely, a system with a total of 1.25 GB of RAM will allocate 256 -MB to the WiredTiger cache because that is more than half of the -total RAM minus one gigabyte (\fB0.5 * (1.25 GB \- 1 GB) = 128 MB < 256 MB\f1). +For example, on a system with a total of 4GB of RAM the +WiredTiger cache uses 1.5GB of RAM (\fB0.5 * (4 GB \- 1 GB) = +1.5 GB\f1). Conversely, on a system with a total of 1.25 GB of +RAM WiredTiger allocates 256 MB to the WiredTiger cache +because that is more than half of the total RAM minus one +gigabyte (\fB0.5 * (1.25 GB \- 1 GB) = 128 MB < 256 MB\f1). .PP In some instances, such as when running in a container, the database can have memory constraints that are lower than the total system @@ -1664,14 +1652,14 @@ default value. With WiredTiger, MongoDB utilizes both the WiredTiger internal cache and the filesystem cache. .PP -Via the filesystem cache, MongoDB automatically uses all free memory +With the filesystem cache, MongoDB automatically uses all free memory that is not used by the WiredTiger cache or by other processes. .PP The \fB\-\-wiredTigerCacheSizeGB\f1\f1 limits the size of the WiredTiger internal -cache. The operating system will use the available free memory +cache. The operating system uses the available free memory for filesystem cache, which allows the compressed MongoDB data -files to stay in memory. In addition, the operating system will -use any free RAM to buffer file system blocks and file system +files to stay in memory. In addition, the operating system +uses any free RAM to buffer file system blocks and file system cache. .PP To accommodate the additional consumers of RAM, you may have to @@ -1683,7 +1671,7 @@ contains multiple MongoDB instances, then you should decrease the setting to accommodate the other \fBmongod\f1\f1 instances. .PP -If you run \fBmongod\f1\f1 in a container (e.g. \fBlxc\f1, +If you run \fBmongod\f1\f1 in a container (for example, \fBlxc\f1, \fBcgroups\f1, Docker, etc.) that does \fInot\f1 have access to all of the RAM available in a system, you must set \fB\-\-wiredTigerCacheSizeGB\f1\f1 to a value less than the amount of RAM available in the container. The exact @@ -1691,50 +1679,6 @@ amount depends on the other processes running in the container. See \fBmemLimitMB\f1\f1\&. .RE .PP -\fBmongod \-\-wiredTigerMaxCacheOverflowFileSizeGB\f1 -.RS -.PP -MongoDB deprecates the \fB\-\-wiredTigerMaxCacheOverflowFileSizeGB\f1 -option. The option has no effect starting in MongoDB 4.4. -.PP -Specifies the maximum size (in GB) for the "lookaside (or cache -overflow) table" file WiredTigerLAS.wt for MongoDB -4.2.1\-4.2.x. The file no longer exists starting in -version 4.4. -.PP -The setting can accept the following values: -.RS -.IP \(bu 2 -.RS -.IP \(bu 4 -Value -.IP \(bu 4 -Description -.RE -.IP \(bu 2 -.RS -.IP \(bu 4 -\fB0\f1 -.IP \(bu 4 -The default value. If set to \fB0\f1, the file size is -unbounded. -.RE -.IP \(bu 2 -.RS -.IP \(bu 4 -number >= 0.1 -.IP \(bu 4 -The maximum size (in GB). If the WiredTigerLAS.wt -file exceeds this size, \fBmongod\f1\f1 exits with a -fatal assertion. You can clear the WiredTigerLAS.wt -file and restart \fBmongod\f1\f1\&. -.RE -.RE -.PP -To change the maximum size during runtime, use the -\fBwiredTigerMaxCacheOverflowSizeGB\f1\f1 parameter. -.RE -.PP \fBmongod \-\-wiredTigerJournalCompressor\f1 .RS .PP @@ -1752,21 +1696,21 @@ Available compressors are: .IP \(bu 2 \fBzlib\f1 .IP \(bu 2 -\fBzstd\f1 (Available starting in MongoDB 4.2) +\fBzstd\f1 .RE .RE .PP \fBmongod \-\-wiredTigerDirectoryForIndexes\f1 .RS .PP -When you start \fBmongod\f1\f1 with \fB\-\-wiredTigerDirectoryForIndexes\f1\f1, \fBmongod\f1\f1 stores indexes and collections in separate +When you start \fBmongod\f1 with \fB\-\-wiredTigerDirectoryForIndexes\f1\f1, \fBmongod\f1 stores indexes and collections in separate subdirectories under the data (i.e. \fB\-\-dbpath\f1\f1) directory. -Specifically, \fBmongod\f1\f1 stores the indexes in a subdirectory named +Specifically, \fBmongod\f1 stores the indexes in a subdirectory named \fBindex\f1 and the collection data in a subdirectory named \fBcollection\f1\&. .PP By using a symbolic link, you can specify a different location for -the indexes. Specifically, when \fBmongod\f1\f1 instance is \fBnot\f1 +the indexes. Specifically, when \fBmongod\f1 instance is \fBnot\f1 running, move the \fBindex\f1 subdirectory to the destination and create a symbolic link named \fBindex\f1 under the data directory to the new destination. @@ -1789,13 +1733,13 @@ Available compressors are: .IP \(bu 2 \fBzlib\f1 .IP \(bu 2 -\fBzstd\f1 (Available starting MongoDB 4.2) +\fBzstd\f1 .RE .PP \fB\-\-wiredTigerCollectionBlockCompressor\f1\f1 affects all collections created. If you change the value of \fB\-\-wiredTigerCollectionBlockCompressor\f1\f1 on an existing MongoDB deployment, all new -collections will use the specified compressor. Existing collections -will continue to use the compressor specified when they were +collections use the specified compressor. Existing collections +continue to use the compressor specified when they were created, or the default compressor at that time. .RE .PP @@ -1811,7 +1755,7 @@ index data, or \fBfalse\f1 to disable prefix compression for index data. .PP The \fB\-\-wiredTigerIndexPrefixCompression\f1\f1 setting affects all indexes created. If you change the value of \fB\-\-wiredTigerIndexPrefixCompression\f1\f1 on an existing MongoDB deployment, all new -indexes will use prefix compression. Existing indexes +indexes use prefix compression. Existing indexes are not affected. .RE .SS REPLICATION OPTIONS @@ -1830,23 +1774,24 @@ replica set name. \fBmongod \-\-oplogSize\f1 .RS .PP -Specifies a maximum size in megabytes for the replication operation log -(i.e., the \fBoplog\f1). +The maximum size in megabytes for the \fBoplog\f1\&. The +\fBoplogSize\f1 setting configures the uncompressed size of the +oplog, not the size on disk. .PP The oplog can grow past its configured size limit to avoid deleting the \fBmajority commit point\f1\f1\&. .PP -By default, the \fBmongod\f1\f1 process creates an \fBoplog\f1 based on +By default, the \fBmongod\f1 process creates an \fBoplog\f1 based on the maximum amount of space available. For 64\-bit systems, the oplog is typically 5% of available disk space. .PP -Once the \fBmongod\f1\f1 has created the oplog for the first time, -changing the \fB\-\-oplogSize\f1\f1 option will not affect the size of +Once the \fBmongod\f1 has created the oplog for the first time, +changing the \fB\-\-oplogSize\f1\f1 option doesn\(aqt affect the size of the oplog. To change the minimum oplog retention period after -starting the \fBmongod\f1\f1, use +starting the \fBmongod\f1, use \fBreplSetResizeOplog\f1\f1\&. \fBreplSetResizeOplog\f1\f1 enables you to resize the oplog dynamically without restarting the -\fBmongod\f1\f1 process. To persist the changes made using +\fBmongod\f1 process. To persist the changes made using \fBreplSetResizeOplog\f1\f1 through a restart, update the value of \fB\-\-oplogSize\f1\f1\&. .PP @@ -1862,13 +1807,13 @@ example, a value of \fB1.5\f1 represents one hour and thirty minutes. .PP The value must be greater than or equal to \fB0\f1\&. A value of \fB0\f1 -indicates that the \fBmongod\f1\f1 should truncate the oplog +indicates that the \fBmongod\f1 should truncate the oplog starting with the oldest entries to maintain the configured maximum oplog size. .PP Defaults to \fB0\f1\&. .PP -A \fBmongod\f1\f1 started with \fB\-\-oplogMinRetentionHours\f1 +A \fBmongod\f1 started with \fB\-\-oplogMinRetentionHours\f1 only removes an oplog entry \fIif\f1: .RS .IP \(bu 2 @@ -1878,7 +1823,7 @@ The oplog entry is older than the configured number of hours based on the host system clock. .RE .PP -The \fBmongod\f1\f1 has the following behavior when configured +The \fBmongod\f1 has the following behavior when configured with a minimum oplog retention period: .RS .IP \(bu 2 @@ -1888,11 +1833,11 @@ exhaustion of system disk space due to a combination of high write volume and large retention period. .IP \(bu 2 If the oplog grows beyond its maximum size, the -\fBmongod\f1\f1 may continue to hold that disk space even if +\fBmongod\f1 may continue to hold that disk space even if the oplog returns to its maximum size \fIor\f1 is configured for a smaller maximum size. See \fBReducing Oplog Size Does Not Immediately Return Disk Space\f1\&. .IP \(bu 2 -The \fBmongod\f1\f1 compares the system wall clock to an +The \fBmongod\f1 compares the system wall clock to an oplog entries creation wall clock time when enforcing oplog entry retention. Clock drift between cluster components may result in unexpected oplog retention behavior. See @@ -1901,13 +1846,40 @@ clock synchronization across cluster members. .RE .PP To change the minimum oplog retention period after starting the -\fBmongod\f1\f1, use \fBreplSetResizeOplog\f1\f1\&. +\fBmongod\f1, use \fBreplSetResizeOplog\f1\f1\&. \fBreplSetResizeOplog\f1\f1 enables you to resize the oplog -dynamically without restarting the \fBmongod\f1\f1 process. To +dynamically without restarting the \fBmongod\f1 process. To persist the changes made using \fBreplSetResizeOplog\f1\f1 through a restart, update the value of \fB\-\-oplogMinRetentionHours\f1\f1\&. .RE +.PP +\fBmongod \-\-enableMajorityReadConcern\f1 +.RS +.PP +\fIDefault\f1: true +.PP +Configures support for \fB"majority"\f1\f1 read concern. +.PP +Starting in MongoDB 5.0, +\fB\-\-enableMajorityReadConcern\f1\f1 cannot be changed +and is always set to \fBtrue\f1\&. In earlier versions of MongoDB, +\fB\-\-enableMajorityReadConcern\f1\f1 was configurable. +.PP +If you are using a three\-member primary\-secondary\-arbiter (PSA) +architecture, consider the following: +.RS +.IP \(bu 2 +The write concern \fB"majority"\f1\f1 can cause +performance issues if a secondary is unavailable or lagging. For +advice on how to mitigate these issues, see +\fBMitigate Performance Issues with PSA Replica Set\f1\&. +.IP \(bu 2 +If you are using a global default \fB"majority"\f1\f1 +and the write concern is less than the size of the majority, +your queries may return stale (not fully replicated) data. +.RE +.RE .SS SHARDED CLUSTER OPTIONS .PP \fBmongod \-\-configsvr\f1 @@ -1915,18 +1887,18 @@ through a restart, update the value of .PP \fIRequired if starting a config server.\f1 .PP -Declares that this \fBmongod\f1\f1 instance serves as the \fBconfig +Declares that this \fBmongod\f1 instance serves as the \fBconfig server\f1 of a sharded cluster. When running with this option, clients (i.e. other cluster components) cannot write data to any database other than \fBconfig\f1 -and \fBadmin\f1\&. The default port for a \fBmongod\f1\f1 with this option is +and \fBadmin\f1\&. The default port for a \fBmongod\f1 with this option is \fB27019\f1 and the default \fB\-\-dbpath\f1\f1 directory is \fB/data/configdb\f1, unless specified. .PP When starting a MongoDB server with \fB\-\-configsvr\f1, you must also specify a \fB\-\-replSet\f1\f1\&. .PP -The use of the deprecated mirrored \fBmongod\f1\f1 instances as +The use of the deprecated mirrored \fBmongod\f1 instances as config servers (SCCC) is no longer supported. .PP The replica set config servers (CSRS) must run the @@ -1939,7 +1911,7 @@ servers cannot be a shard server. .PP Do not use the \fB\-\-configsvr\f1\f1 with the \fBskipShardingConfigurationChecks\f1\f1 parameter. That is, if -you are temporarily starting the \fBmongod\f1\f1 as a +you are temporarily starting the \fBmongod\f1 as a standalone for maintenance operations, include the parameter \fBskipShardingConfigurationChecks\f1\f1 and exclude \fB\-\-configsvr\f1\f1\&. Once maintenance has completed, remove the @@ -1952,7 +1924,7 @@ with \fB\-\-configsvr\f1\f1\&. .PP \fIRequired if starting a shard server.\f1 .PP -Configures this \fBmongod\f1\f1 instance as a shard in a +Configures this \fBmongod\f1 instance as a shard in a sharded cluster. The default port for these instances is \fB27018\f1\&. .PP @@ -1961,33 +1933,13 @@ specify a \fB\-\-replSet\f1\f1\&. .PP Do not use the \fB\-\-shardsvr\f1\f1 with the \fBskipShardingConfigurationChecks\f1\f1 parameter. That is, if -you are temporarily starting the \fBmongod\f1\f1 as a +you are temporarily starting the \fBmongod\f1 as a standalone for maintenance operations, include the parameter \fBskipShardingConfigurationChecks\f1\f1 and exclude \fB\-\-shardsvr\f1\f1\&. Once maintenance has completed, remove the \fBskipShardingConfigurationChecks\f1\f1 parameter and restart with \fB\-\-shardsvr\f1\f1\&. .RE -.PP -\fBmongod \-\-moveParanoia\f1 -.RS -.PP -If specified, during chunk migration, a shard saves, -to the \fBmoveChunk\f1 directory of the \fB\-\-dbpath\f1, all documents -migrated from that shard. -.PP -MongoDB does not automatically delete the data saved in the -\fBmoveChunk\f1 directory. -.RE -.PP -\fBmongod \-\-noMoveParanoia\f1 -.RS -.PP -During chunk migration, a shard does not save documents migrated from -the shard. -.PP -This is the default behavior. -.RE .SS TLS OPTIONS .PP \fBConfigure mongod\f1 and mongos\f1 for TLS/SSL\f1 for full @@ -2039,9 +1991,9 @@ The server uses and accepts only TLS encrypted connections. .RE .PP If \fB\-\-tlsCAFile\f1 or \fBtls.CAFile\f1 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\-enabled server. +specified and you are not using x.509 authentication, you must set the +\fBtlsUseSystemCA\f1\f1 parameter to \fBtrue\f1\&. This makes MongoDB use +the system\-wide CA certificate store when connecting to a TLS\-enabled server. .PP If using x.509 authentication, \fB\-\-tlsCAFile\f1 or \fBtls.CAFile\f1 must be specified unless using \fB\-\-tlsCertificateSelector\f1\f1\&. @@ -2054,8 +2006,8 @@ For more information about TLS and MongoDB, see \fBmongod \-\-tlsCertificateKeyFile\f1 .RS .PP -Specifies the \&.pem file that contains both the TLS -certificate and key. +Specifies the \&.pem file that contains both the TLS certificate and +key. .PP On macOS or Windows, you can use the \fB\-\-tlsCertificateSelector\f1\f1 option to specify a @@ -2073,7 +2025,7 @@ On Windows or macOS, you must specify either \fB\-\-tlsCertificateSelector\f1\f1 when TLS/SSL is enabled. .IP For Windows \fBonly\f1, MongoDB does not support -encrypted PEM files. The \fBmongod\f1\f1 fails to start if +encrypted PEM files. The \fBmongod\f1 fails to start if it encounters an encrypted PEM file. To securely store and access a certificate for use with TLS on Windows, use \fB\-\-tlsCertificateSelector\f1\f1\&. @@ -2091,12 +2043,12 @@ Specifies the password to decrypt the certificate\-key file (i.e. \fB\-\-tlsCertificateKeyFile\f1\f1). Use the \fB\-\-tlsCertificateKeyFilePassword\f1\f1 option only if the certificate\-key file is encrypted. In all cases, the -\fBmongod\f1\f1 will redact the password from all logging and +\fBmongod\f1 redacts the password from all logging and reporting output. .RS .IP \(bu 2 On Linux/BSD, if the private key in the PEM file is encrypted and -you do not specify the \fB\-\-tlsCertificateKeyFilePassword\f1\f1 option, MongoDB will prompt for a +you do not specify the \fB\-\-tlsCertificateKeyFilePassword\f1\f1 option, MongoDB prompts for a passphrase. See \fBTLS/SSL Certificate Passphrase\f1\&. .IP \(bu 2 On macOS, if the private key in the PEM file is @@ -2107,7 +2059,7 @@ you can use a certificate from the secure system store (see unencrypted PEM file. .IP \(bu 2 On Windows, MongoDB does not support encrypted certificates. -The \fBmongod\f1\f1 fails if it encounters an encrypted +The \fBmongod\f1 fails if it encounters an encrypted PEM file. Use \fB\-\-tlsCertificateSelector\f1\f1 instead. .RE .PP @@ -2169,9 +2121,9 @@ accept only x.509 certificates. .RE .PP If \fB\-\-tlsCAFile\f1 or \fBtls.CAFile\f1 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\-enabled server. +specified and you are not using x.509 authentication, you must set the +\fBtlsUseSystemCA\f1\f1 parameter to \fBtrue\f1\&. This makes MongoDB use +the system\-wide CA certificate store when connecting to a TLS\-enabled server. .PP If using x.509 authentication, \fB\-\-tlsCAFile\f1 or \fBtls.CAFile\f1 must be specified unless using \fB\-\-tlsCertificateSelector\f1\f1\&. @@ -2215,7 +2167,7 @@ For more information about TLS and MongoDB, see \fBTLS/SSL Configuration for Clients\f1 . .PP For Windows \fBonly\f1, MongoDB does not support -encrypted PEM files. The \fBmongod\f1\f1 fails to start if +encrypted PEM files. The \fBmongod\f1 fails to start if it encounters an encrypted PEM file. To securely store and access a certificate for use with membership authentication on Windows, use \fB\-\-tlsClusterCertificateSelector\f1\f1\&. @@ -2276,7 +2228,7 @@ When using the system SSL certificate store, OCSP (Online Certificate Status Protocol) is used to validate the revocation status of certificates. .PP -The \fBmongod\f1\f1 searches the operating system\(aqs secure +The \fBmongod\f1 searches the operating system\(aqs secure certificate store for the CA certificates required to validate the full certificate chain of the specified TLS certificate. Specifically, the secure certificate store must contain the root CA @@ -2305,7 +2257,7 @@ Available on Windows and macOS as an alternative to \fB\-\-tlsClusterFile\f1\f1\&. .PP Specifies a certificate property in order to select a matching -certificate from the operating system\(aqs certificate store to use +certificate from the operating system\(aqs certificate store for \fBinternal x.509 membership authentication\f1\&. .PP \fB\-\-tlsClusterFile\f1\f1 and @@ -2349,7 +2301,7 @@ The \fBthumbprint\f1 is sometimes referred to as a .RE .RE .PP -The \fBmongod\f1\f1 searches the operating system\(aqs secure +The \fBmongod\f1 searches the operating system\(aqs secure certificate store for the CA certificates required to validate the full certificate chain of the specified cluster certificate. Specifically, the secure certificate store must contain the root CA @@ -2377,13 +2329,13 @@ information. Specifies the password to decrypt the x.509 certificate\-key file specified with \fB\-\-tlsClusterFile\f1\f1\&. Use the \fB\-\-tlsClusterPassword\f1\f1 option only if the certificate\-key -file is encrypted. In all cases, the \fBmongod\f1\f1 will redact +file is encrypted. In all cases, the \fBmongod\f1 redacts the password from all logging and reporting output. .RS .IP \(bu 2 On Linux/BSD, if the private key in the x.509 file is encrypted and you do not specify the \fB\-\-tlsClusterPassword\f1\f1 option, -MongoDB will prompt for a passphrase. See +MongoDB prompts for a passphrase. See \fBTLS/SSL Certificate Passphrase\f1\&. .IP \(bu 2 On macOS, if the private key in the x.509 file is @@ -2394,7 +2346,7 @@ either use a certificate from the secure system store (see file or use an unencrypted PEM file. .IP \(bu 2 On Windows, MongoDB does not support encrypted certificates. -The \fBmongod\f1\f1 fails if it encounters an encrypted +The \fBmongod\f1 fails if it encounters an encrypted PEM file. Use \fB\-\-tlsClusterCertificateSelector\f1\f1 instead. .RE .PP @@ -2410,6 +2362,15 @@ Specifies the \&.pem file that contains the root certificate chain from the Certificate Authority. Specify the file name of the \&.pem file using relative or absolute paths. .PP +When starting a \fBmongod\f1\f1 instance with +\fBTLS/SSL enabled\f1, you must +specify a value for the \fB\-\-tlsCAFile\f1\f1 flag, the +\fBnet.tls.CAFile\f1\f1 configuration option, or the \fBtlsUseSystemCA\f1\f1 +parameter. +.PP +\fB\-\-tlsCAFile\f1, \fBtls.CAFile\f1, and \fBtlsUseSystemCA\f1 are all mutually +exclusive. +.PP \fBWindows/macOS Only\f1 .RS .PP @@ -2479,7 +2440,7 @@ validate the revocation status of certificates. See \fB\-\-tlsCertificateSelector\f1\f1 to use the system SSL certificate store. .IP \(bu 2 -Starting in version 4.4, to check for certificate revocation, +To check for certificate revocation, MongoDB \fBenables\f1\f1 the use of OCSP (Online Certificate Status Protocol) by default as an alternative to specifying a CRL file or using the system SSL @@ -2518,7 +2479,7 @@ For more information about TLS and MongoDB, see .PP 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 \fBmongod\f1\f1 to connect +for inter\-process authentication. This allows \fBmongod\f1 to connect to other members if the hostnames in their certificates do not match their configured hostname. .PP @@ -2530,16 +2491,24 @@ For more information about TLS and MongoDB, see \fBmongod \-\-tlsAllowConnectionsWithoutCertificates\f1 .RS .PP +By default, the server bypasses client certificate validation unless +the server is configured to use a CA file. If a CA file is provided, the +following rules apply: +.RS +.IP \(bu 2 For clients that don\(aqt provide certificates, \fBmongod\f1\f1 or \fBmongos\f1\f1 encrypts the TLS/SSL connection, assuming the connection is successfully made. -.PP -For clients that present a certificate, however, \fBmongod\f1\f1 performs +.IP \(bu 2 +For clients that present a certificate, \fBmongod\f1 performs certificate validation using the root certificate chain specified by -\fB\-\-tlsCAFile\f1 and reject clients with invalid certificates. +\fB\-\-tlsCAFile\f1\f1 and reject clients with invalid +certificates. +.RE .PP -Use the \fB\-\-tlsAllowConnectionsWithoutCertificates\f1\f1 option if you have a mixed deployment that includes -clients that do not or cannot present certificates to the \fBmongod\f1\f1\&. +Use the \fB\-\-tlsAllowConnectionsWithoutCertificates\f1\f1 option if you have +a mixed deployment that includes clients that do not or cannot present +certificates to the \fBmongod\f1\&. .PP For more information about TLS and MongoDB, see \fBConfigure mongod\f1 and mongos\f1 for TLS/SSL\f1 and @@ -2564,7 +2533,7 @@ two, for example, \fBTLS1_0,TLS1_1\f1\&. To list multiple protocols, specify as a comma separated list of protocols. For example \fBTLS1_0,TLS1_1\f1\&. .IP \(bu 2 -Specifying an unrecognized protocol will prevent the server from +Specifying an unrecognized protocol prevents the server from starting. .IP \(bu 2 The specified disabled protocols overrides any default disabled @@ -2573,7 +2542,7 @@ protocols. .PP 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\f1 to \fB\-\-tlsDisabledProtocols\f1\f1\&. See \fBDisable TLS 1.0\f1\&. +specify \fBnone\f1 to \fB\-\-tlsDisabledProtocols\f1\f1\&. .PP Members of replica sets and sharded clusters must speak at least one protocol in common. @@ -2584,7 +2553,7 @@ protocol in common. \fBmongod \-\-tlsFIPSMode\f1 .RS .PP -Directs the \fBmongod\f1\f1 to use the FIPS mode of the TLS +Directs the \fBmongod\f1 to use the FIPS mode of the TLS library. Your system must have a FIPS compliant library to use the \fB\-\-tlsFIPSMode\f1\f1 option. .PP @@ -2592,580 +2561,6 @@ FIPS\-compatible TLS/SSL is available only in MongoDB Enterprise (http://www.mongodb.com/products/mongodb\-enterprise\-advanced?tck=docs_server)\&. See \fBConfigure MongoDB for FIPS\f1 for more information. .RE -.SS SSL OPTIONS (DEPRECATED) -.PP -All SSL options are deprecated since 4.2. Use the \fBTLS counterparts\f1 instead, as they have identical functionality to the -SSL options. The SSL protocol is deprecated and MongoDB supports TLS 1.0 -and later. -.PP -\fBConfigure mongod\f1 and mongos\f1 for TLS/SSL\f1 for full -documentation of MongoDB\(aqs support. -.PP -\fBmongod \-\-sslOnNormalPorts\f1 -.RS -.PP -Use \fB\-\-tlsMode requireTLS\f1\f1 instead. -.PP -Enables TLS/SSL for \fBmongod\f1\f1\&. -.PP -With \fB\-\-sslOnNormalPorts\f1\f1, a \fBmongod\f1\f1 requires TLS/SSL encryption for all -connections on the default MongoDB port, or the port specified by -\fB\-\-port\f1\f1\&. By default, \fB\-\-sslOnNormalPorts\f1\f1 is -disabled. -.PP -For more information about TLS/SSL and MongoDB, see -\fBConfigure mongod\f1 and mongos\f1 for TLS/SSL\f1 and -\fBTLS/SSL Configuration for Clients\f1 . -.RE -.PP -\fBmongod \-\-sslMode\f1 -.RS -.PP -Use \fB\-\-tlsMode\f1\f1 instead. -.PP -Enables TLS/SSL or mixed TLS/SSL used for all network connections. The -argument to the \fB\-\-sslMode\f1\f1 option can be one of the following: -.RS -.IP \(bu 2 -.RS -.IP \(bu 4 -Value -.IP \(bu 4 -Description -.RE -.IP \(bu 2 -.RS -.IP \(bu 4 -\fBdisabled\f1 -.IP \(bu 4 -The server does not use TLS/SSL. -.RE -.IP \(bu 2 -.RS -.IP \(bu 4 -\fBallowSSL\f1 -.IP \(bu 4 -Connections between servers do not use TLS/SSL. For incoming -connections, the server accepts both TLS/SSL and non\-TLS/non\-SSL. -.RE -.IP \(bu 2 -.RS -.IP \(bu 4 -\fBpreferSSL\f1 -.IP \(bu 4 -Connections between servers use TLS/SSL. For incoming -connections, the server accepts both TLS/SSL and non\-TLS/non\-SSL. -.RE -.IP \(bu 2 -.RS -.IP \(bu 4 -\fBrequireSSL\f1 -.IP \(bu 4 -The server uses and accepts only TLS/SSL encrypted connections. -.RE -.RE -.PP -If \fB\-\-tlsCAFile\f1/\fBnet.tls.CAFile\f1 (or -their aliases \fB\-\-sslCAFile\f1/\fBnet.ssl.CAFile\f1) 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. -.PP -To use x.509 authentication, \fB\-\-tlsCAFile\f1 or \fBnet.tls.CAFile\f1 -must be specified unless you are using \fB\-\-tlsCertificateSelector\f1 -or \fB\-\-net.tls.certificateSelector\f1\&. -.PP -For more information about TLS/SSL and MongoDB, see -\fBConfigure mongod\f1 and mongos\f1 for TLS/SSL\f1 and -\fBTLS/SSL Configuration for Clients\f1 . -.RE -.PP -\fBmongod \-\-sslPEMKeyFile\f1 -.RS -.PP -Use \fB\-\-tlsCertificateKeyFile\f1\f1 instead. -.PP -Specifies the \&.pem file that contains both the TLS/SSL -certificate and key. -.PP -On macOS or Windows, you can use the -\fB\-\-sslCertificateSelector\f1\f1 option to specify a -certificate from the operating system\(aqs secure certificate store -instead of a PEM key file. \fB\-\-sslPEMKeyFile\f1\f1 and -\fB\-\-sslCertificateSelector\f1\f1 options are mutually exclusive. -You can only specify one. -.RS -.IP \(bu 2 -On Linux/BSD, you must specify \fB\-\-sslPEMKeyFile\f1\f1 when -TLS/SSL is enabled. -.IP \(bu 2 -On Windows or macOS, you must specify either -\fB\-\-sslPEMKeyFile\f1\f1 or \fB\-\-sslCertificateSelector\f1\f1 -when TLS/SSL is enabled. -.IP -For Windows \fBonly\f1, MongoDB does not support -encrypted PEM files. The \fBmongod\f1\f1 fails to start if -it encounters an encrypted PEM file. To securely store and -access a certificate for use with TLS/SSL on Windows, -use \fB\-\-sslCertificateSelector\f1\f1\&. -.RE -.PP -For more information about TLS/SSL and MongoDB, see -\fBConfigure mongod\f1 and mongos\f1 for TLS/SSL\f1 and -\fBTLS/SSL Configuration for Clients\f1 . -.RE -.PP -\fBmongod \-\-sslPEMKeyPassword\f1 -.RS -.PP -Use \fB\-\-tlsCertificateKeyFilePassword\f1\f1 instead. -.PP -Specifies the password to decrypt the certificate\-key file (i.e. -\fB\-\-sslPEMKeyFile\f1\f1). Use the \fB\-\-sslPEMKeyPassword\f1\f1 option only if the -certificate\-key file is encrypted. In all cases, the \fBmongod\f1\f1 will -redact the password from all logging and reporting output. -.RS -.IP \(bu 2 -On Linux/BSD, if the private key in the PEM file is encrypted and -you do not specify the \fB\-\-sslPEMKeyPassword\f1\f1 option, MongoDB will prompt for a -passphrase. See \fBTLS/SSL Certificate Passphrase\f1\&. -.IP \(bu 2 -On macOS, if the private key in the PEM file is -encrypted, you must explicitly specify the -\fB\-\-sslPEMKeyPassword\f1\f1 option. Alternatively, you can use a -certificate from the secure system store (see -\fB\-\-sslCertificateSelector\f1\f1) instead of a PEM key file or -use an unencrypted PEM file. -.IP \(bu 2 -On Windows, MongoDB does not support encrypted certificates. -The \fBmongod\f1\f1 fails if it encounters an encrypted -PEM file. Use \fB\-\-sslCertificateSelector\f1\f1 instead. -.RE -.PP -For more information about TLS/SSL and MongoDB, see -\fBConfigure mongod\f1 and mongos\f1 for TLS/SSL\f1 and -\fBTLS/SSL Configuration for Clients\f1 . -.RE -.PP -\fBmongod \-\-sslClusterFile\f1 -.RS -.PP -Use \fB\-\-tlsClusterFile\f1\f1 instead. -.PP -Specifies the \&.pem file that contains the x.509 -certificate\-key file for \fBmembership authentication\f1 for the cluster or replica set. -.PP -On macOS or Windows, you can use the -\fB\-\-sslClusterCertificateSelector\f1\f1 option to specify a -certificate from the operating system\(aqs secure certificate store -instead of a PEM key file. \fB\-\-sslClusterFile\f1\f1 and -\fB\-\-sslClusterCertificateSelector\f1\f1 options are mutually -exclusive. You can only specify one. -.PP -If \fB\-\-sslClusterFile\f1\f1 does not specify the \fB\&.pem\f1 file for -internal cluster authentication or the alternative -\fB\-\-sslClusterCertificateSelector\f1\f1, the cluster uses the -\fB\&.pem\f1 file specified in the \fB\-\-sslPEMKeyFile\f1\f1 option or -the certificate returned by the \fB\-\-sslCertificateSelector\f1\f1\&. -.PP -To use x.509 authentication, \fB\-\-tlsCAFile\f1 or \fBnet.tls.CAFile\f1 -must be specified unless you are using \fB\-\-tlsCertificateSelector\f1 -or \fB\-\-net.tls.certificateSelector\f1\&. -.PP -For more information about TLS/SSL and MongoDB, see -\fBConfigure mongod\f1 and mongos\f1 for TLS/SSL\f1 and -\fBTLS/SSL Configuration for Clients\f1 . -.PP -For Windows \fBonly\f1, MongoDB does not support -encrypted PEM files. The \fBmongod\f1\f1 fails to start if -it encounters an encrypted PEM file. To securely store and -access a certificate for use with membership authentication on -Windows, use \fB\-\-sslClusterCertificateSelector\f1\f1\&. -.RE -.PP -\fBmongod \-\-sslCertificateSelector\f1 -.RS -.PP -Use \fB\-\-tlsCertificateSelector\f1\f1 instead. -.PP -Available on Windows and macOS as an alternative to -\fB\-\-tlsCertificateKeyFile\f1\f1\&. -.PP -Specifies a certificate property to select a matching certificate -from the operating system\(aqs secure certificate store to use for -TLS/SSL. -.PP -\fB\-\-sslPEMKeyFile\f1\f1 and \fB\-\-sslCertificateSelector\f1\f1 -options are mutually exclusive. You can only specify one. -.PP -\fB\-\-sslCertificateSelector\f1\f1 accepts an argument of the format -\fB=\f1 where the property can be one of the -following: -.RS -.IP \(bu 2 -.RS -.IP \(bu 4 -Property -.IP \(bu 4 -Value type -.IP \(bu 4 -Description -.RE -.IP \(bu 2 -.RS -.IP \(bu 4 -\fBsubject\f1 -.IP \(bu 4 -ASCII string -.IP \(bu 4 -Subject name or common name on certificate -.RE -.IP \(bu 2 -.RS -.IP \(bu 4 -\fBthumbprint\f1 -.IP \(bu 4 -hex string -.IP \(bu 4 -A sequence of bytes, expressed as hexadecimal, used to -identify a public key by its SHA\-1 digest. -.IP -The \fBthumbprint\f1 is sometimes referred to as a -\fBfingerprint\f1\&. -.RE -.RE -.PP -When using the system SSL certificate store, OCSP (Online -Certificate Status Protocol) is used to validate the revocation -status of certificates. -.PP -The \fBmongod\f1\f1 searches the operating system\(aqs secure -certificate store for the CA certificates required to validate the -full certificate chain of the specified TLS/SSL certificate. -Specifically, the secure certificate store must contain the root CA -and any intermediate CA certificates required to build the full -certificate chain to the TLS/SSL certificate. Do \fBnot\f1 use -\fB\-\-sslCAFile\f1\f1 or \fB\-\-sslClusterCAFile\f1\f1 to specify the -root and intermediate CA certificate -.PP -For example, if the TLS/SSL certificate was signed with a single root -CA certificate, the secure certificate store must contain that root -CA certificate. If the TLS/SSL certificate was signed with an -intermediate CA certificate, the secure certificate store must -contain the intermedia CA certificate \fIand\f1 the root CA certificate. -.RE -.PP -\fBmongod \-\-sslClusterCertificateSelector\f1 -.RS -.PP -Use \fB\-\-tlsClusterCertificateSelector\f1\f1 instead. -.PP -Available on Windows and macOS as an alternative to -\fB\-\-sslClusterFile\f1\f1\&. -.PP -Specifies a certificate property to select a matching certificate -from the operating system\(aqs secure certificate store to use for -\fBinternal x.509 membership authentication\f1\&. -.PP -\fB\-\-sslClusterFile\f1\f1 and -\fB\-\-sslClusterCertificateSelector\f1\f1 options are mutually -exclusive. You can only specify one. -.PP -\fB\-\-sslClusterCertificateSelector\f1\f1 accepts an argument of the -format \fB=\f1 where the property can be one of the -following: -.RS -.IP \(bu 2 -.RS -.IP \(bu 4 -Property -.IP \(bu 4 -Value type -.IP \(bu 4 -Description -.RE -.IP \(bu 2 -.RS -.IP \(bu 4 -\fBsubject\f1 -.IP \(bu 4 -ASCII string -.IP \(bu 4 -Subject name or common name on certificate -.RE -.IP \(bu 2 -.RS -.IP \(bu 4 -\fBthumbprint\f1 -.IP \(bu 4 -hex string -.IP \(bu 4 -A sequence of bytes, expressed as hexadecimal, used to -identify a public key by its SHA\-1 digest. -.IP -The \fBthumbprint\f1 is sometimes referred to as a -\fBfingerprint\f1\&. -.RE -.RE -.PP -The \fBmongod\f1\f1 searches the operating system\(aqs secure -certificate store for the CA certificates required to validate the -full certificate chain of the specified cluster certificate. -Specifically, the secure certificate store must contain the root CA -and any intermediate CA certificates required to build the full -certificate chain to the cluster certificate. Do \fBnot\f1 use -\fB\-\-sslCAFile\f1\f1 or \fB\-\-sslClusterCAFile\f1\f1 to specify the -root and intermediate CA certificate. -.PP -For example, if the cluster certificate was signed with a single root -CA certificate, the secure certificate store must contain that root -CA certificate. If the cluster certificate was signed with an -intermediate CA certificate, the secure certificate store must -contain the intermedia CA certificate \fIand\f1 the root CA certificate. -.RE -.PP -\fBmongod \-\-sslClusterPassword\f1 -.RS -.PP -Use \fB\-\-tlsClusterPassword\f1\f1 instead. -.PP -Specifies the password to decrypt the x.509 certificate\-key file -specified with \fB\-\-sslClusterFile\f1\&. Use the \fB\-\-sslClusterPassword\f1\f1 option only -if the certificate\-key file is encrypted. In all cases, the \fBmongod\f1\f1 -will redact the password from all logging and reporting output. -.RS -.IP \(bu 2 -On Linux/BSD, if the private key in the x.509 file is encrypted and -you do not specify the \fB\-\-sslClusterPassword\f1\f1 option, MongoDB will prompt for a -passphrase. See \fBTLS/SSL Certificate Passphrase\f1\&. -.IP \(bu 2 -On macOS, if the private key in the x.509 file is encrypted, you -must explicitly specify the \fB\-\-sslClusterPassword\f1\f1 option. -Alternatively, you can either use a certificate from the secure -system store (see \fB\-\-sslClusterCertificateSelector\f1\f1) -instead of a cluster PEM file or use an unencrypted PEM file. -.IP \(bu 2 -On Windows, MongoDB does not support encrypted certificates. -The \fBmongod\f1\f1 fails if it encounters an encrypted -PEM file. Use \fB\-\-sslClusterCertificateSelector\f1\f1 instead. -.RE -.PP -For more information about TLS/SSL and MongoDB, see -\fBConfigure mongod\f1 and mongos\f1 for TLS/SSL\f1 and -\fBTLS/SSL Configuration for Clients\f1 . -.RE -.PP -\fBmongod \-\-sslCAFile\f1 -.RS -.PP -Use \fB\-\-tlsCAFile\f1\f1 instead. -.PP -Specifies the \&.pem file that contains the root certificate -chain from the Certificate Authority. Specify the file name of the -\&.pem file using relative or absolute paths. -.PP -\fBWindows/macOS Only\f1 -.RS -.PP -If using \fB\-\-sslCertificateSelector\f1\f1 and/or -\fB\-\-sslClusterCertificateSelector\f1\f1, do \fBnot\f1 use -\fB\-\-sslCAFile\f1\f1 to specify the root and intermediate CA -certificates. Store all CA certificates required to validate the -full trust chain of the \fB\-\-sslCertificateSelector\f1\f1 and/or -\fB\-\-sslClusterCertificateSelector\f1\f1 certificates in the -secure certificate store. -.RE -.PP -For more information about TLS/SSL and MongoDB, see -\fBConfigure mongod\f1 and mongos\f1 for TLS/SSL\f1 and -\fBTLS/SSL Configuration for Clients\f1 . -.RE -.PP -\fBmongod \-\-sslClusterCAFile\f1 -.RS -.PP -Use \fB\-\-tlsClusterCAFile\f1\f1 -instead. -.PP -Specifies the \&.pem 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 \&.pem file using relative or absolute paths. -\fB\-\-sslClusterCAFile\f1\f1 requires that -\fB\-\-sslCAFile\f1\f1 is set. -.PP -If \fB\-\-sslClusterCAFile\f1\f1 does not specify the \&.pem -file for validating the certificate from a client establishing a -connection, the cluster uses the \&.pem file specified in the -\fB\-\-sslCAFile\f1\f1 option. -.PP -\fB\-\-sslClusterCAFile\f1\f1 lets you use separate Certificate -Authorities to verify the client to server and server to client -portions of the TLS handshake. -.PP -\fBWindows/macOS Only\f1 -.RS -.PP -If using \fB\-\-sslCertificateSelector\f1\f1 and/or -\fB\-\-sslClusterCertificateSelector\f1\f1, do \fBnot\f1 use -\fB\-\-sslClusterCAFile\f1\f1 to specify the root and -intermediate CA certificates. Store all CA certificates required to -validate the full trust chain of the -\fB\-\-sslCertificateSelector\f1\f1 and/or -\fB\-\-sslClusterCertificateSelector\f1\f1 certificates in the -secure certificate store. -.RE -.PP -For more information about TLS/SSL and MongoDB, see -\fBConfigure mongod\f1 and mongos\f1 for TLS/SSL\f1 and -\fBTLS/SSL Configuration for Clients\f1 . -.RE -.PP -\fBmongod \-\-sslCRLFile\f1 -.RS -.PP -Use \fB\-\-tlsCRLFile\f1\f1 instead. -.PP -Specifies the \&.pem file that contains the Certificate Revocation -List. Specify the file name of the \&.pem file using relative or -absolute paths. -.RS -.IP \(bu 2 -You cannot specify a CRL file on -macOS. Instead, you can use the system SSL certificate store, -which uses OCSP (Online Certificate Status Protocol) to -validate the revocation status of certificates. See -\fB\-\-tlsCertificateSelector\f1\f1 in MongoDB 4.2+ to use the -system SSL certificate store. -.IP \(bu 2 -Starting in version 4.4, to check for certificate revocation, -MongoDB \fBenables\f1\f1 the use of OCSP -(Online Certificate Status Protocol) by default as an -alternative to specifying a CRL file or using the system SSL -certificate store. -.RE -.PP -For more information about TLS/SSL and MongoDB, see -\fBConfigure mongod\f1 and mongos\f1 for TLS/SSL\f1 and -\fBTLS/SSL Configuration for Clients\f1 . -.RE -.PP -\fBmongod \-\-sslAllowInvalidCertificates\f1 -.RS -.PP -Use \fB\-\-tlsAllowInvalidCertificates\f1\f1 instead. -.PP -Bypasses the validation checks for TLS/SSL certificates on other -servers in the cluster and allows the use of invalid certificates to -connect. -.PP -Starting in MongoDB 4.0, if you specify any of the following x.509 -authentication options, an invalid certificate is -sufficient only to establish a TLS connection but it is -\fIinsufficient\f1 for authentication: -.RS -.IP \(bu 2 -\fB\-\-sslAllowInvalidCertificates\f1 or \fBnet.ssl.allowInvalidCertificates: true\f1 for MongoDB 4.0 and later -.IP \(bu 2 -\fB\-\-tlsAllowInvalidCertificates\f1 or \fBnet.tls.allowInvalidCertificates: true\f1 for MongoDB 4.2 and later -.RE -.PP -When using -the \fB\-\-sslAllowInvalidCertificates\f1\f1 setting, MongoDB -logs a warning regarding the use of the invalid certificate. -.PP -For more information about TLS/SSL and MongoDB, see -\fBConfigure mongod\f1 and mongos\f1 for TLS/SSL\f1 and -\fBTLS/SSL Configuration for Clients\f1 . -.RE -.PP -\fBmongod \-\-sslAllowInvalidHostnames\f1 -.RS -.PP -Use \fB\-\-tlsAllowInvalidHostnames\f1\f1 instead. -.PP -Disables the validation of the hostnames in TLS/SSL certificates, -when connecting to other members of the replica set or sharded cluster -for inter\-process authentication. This allows \fBmongod\f1\f1 to connect -to other members if the hostnames in their certificates do not match -their configured hostname. -.PP -For more information about TLS/SSL and MongoDB, see -\fBConfigure mongod\f1 and mongos\f1 for TLS/SSL\f1 and -\fBTLS/SSL Configuration for Clients\f1 . -.RE -.PP -\fBmongod \-\-sslAllowConnectionsWithoutCertificates\f1 -.RS -.PP -Use \fB\-\-tlsAllowConnectionsWithoutCertificates\f1\f1 instead. -.PP -For clients that don\(aqt provide certificates, \fBmongod\f1\f1 or -\fBmongos\f1\f1 encrypts the TLS/SSL connection, assuming the -connection is successfully made. -.PP -For clients that present a certificate, however, \fBmongod\f1\f1 performs -certificate validation using the root certificate chain specified by -\fB\-\-sslCAFile\f1 and reject clients with invalid certificates. -.PP -Use the \fB\-\-sslAllowConnectionsWithoutCertificates\f1\f1 option if you have a mixed deployment that includes -clients that do not or cannot present certificates to the \fBmongod\f1\f1\&. -.PP -For more information about TLS/SSL and MongoDB, see -\fBConfigure mongod\f1 and mongos\f1 for TLS/SSL\f1 and -\fBTLS/SSL Configuration for Clients\f1 . -.RE -.PP -\fBmongod \-\-sslDisabledProtocols\f1 -.RS -.PP -Use \fB\-\-tlsDisabledProtocols\f1\f1 instead. -.PP -Prevents a MongoDB server running with TLS/SSL from accepting -incoming connections that use a specific protocol or protocols. To -specify multiple protocols, use a comma separated list of protocols. -.PP -\fB\-\-sslDisabledProtocols\f1\f1 recognizes the following protocols: \fBTLS1_0\f1, \fBTLS1_1\f1, -\fBTLS1_2\f1, and \fBTLS1_3\f1\&. -.RS -.IP \(bu 2 -On macOS, you cannot disable \fBTLS1_1\f1 and leave both \fBTLS1_0\f1 and -\fBTLS1_2\f1 enabled. You must disable at least one of the other -two, for example, \fBTLS1_0,TLS1_1\f1\&. -.IP \(bu 2 -To list multiple protocols, specify as a comma separated list of -protocols. For example \fBTLS1_0,TLS1_1\f1\&. -.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. -.RE -.PP -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\f1 to \fB\-\-sslDisabledProtocols\f1\f1\&. See \fBDisable TLS 1.0\f1\&. -.PP -Members of replica sets and sharded clusters must speak at least one -protocol in common. -.PP -\fBDisallow Protocols\f1 -.RE -.PP -\fBmongod \-\-sslFIPSMode\f1 -.RS -.PP -Use \fB\-\-tlsFIPSMode\f1\f1 instead. -.PP -Directs the \fBmongod\f1\f1 to use the FIPS mode of the TLS/SSL -library. Your system must have a FIPS -compliant library to use the \fB\-\-sslFIPSMode\f1\f1 option. -.PP -FIPS\-compatible TLS/SSL is -available only in MongoDB Enterprise (http://www.mongodb.com/products/mongodb\-enterprise\-advanced?tck=docs_server)\&. See -\fBConfigure MongoDB for FIPS\f1 for more information. -.RE .SS PROFILER OPTIONS .PP \fBmongod \-\-profile\f1 @@ -3196,8 +2591,8 @@ This is the default profiler level. .IP \(bu 4 \fB1\f1 .IP \(bu 4 -The profiler collects data for operations that take longer -than the value of \fBslowms\f1 or that match a \fBfilter\f1\&. +The profiler collects data for operations that exceed the +\fBslowms\f1 threshold or match a specified \fBfilter\f1\&. .IP When a filter is set: .RS @@ -3218,10 +2613,9 @@ The profiler collects data for all operations. .RE .RE .PP -Profiling can impact performance and shares settings with the system -log. Carefully consider any performance and security implications -before configuring and enabling the profiler on a production -deployment. +Profiling can degrade performance and expose unencrypted query data in the +system log. Carefully consider any performance and security implications +before configuring and enabling the profiler on a production deployment. .PP See \fBProfiler Overhead\f1 for more information on potential performance degradation. @@ -3232,8 +2626,13 @@ potential performance degradation. .PP \fIDefault\f1: 100 .PP -The \fIslow\f1 operation time threshold, in milliseconds. Operations -that run for longer than this threshold are considered \fIslow\f1\&. +The slow operation time threshold, in milliseconds. Operations that run +for longer than this threshold are considered \fIslow\f1\&. +.PP +Slow operations are logged based on \fBworkingMillis\f1, which is the +amount of time that MongoDB spends working on that operation. This means +that factors such as waiting for locks and flow control do not affect +whether an operation exceeds the slow operation threshold. .PP When \fBlogLevel\f1\f1 is set to \fB0\f1, MongoDB records \fIslow\f1 operations to the diagnostic log at a rate determined by @@ -3241,12 +2640,12 @@ operations to the diagnostic log at a rate determined by .PP At higher \fBlogLevel\f1\f1 settings, all operations appear in the diagnostic log regardless of their latency with the following -exception: the logging of \fBslow oplog entry messages by the -secondaries\f1\&. The secondaries log only the slow oplog +exception: the logging of slow oplog entry messages by the +secondaries. The secondaries log only the slow oplog entries; increasing the \fBlogLevel\f1\f1 does not log all oplog entries. .PP -For \fBmongod\f1\f1 instances, \fB\-\-slowms\f1\f1 affects the diagnostic log +For \fBmongod\f1 instances, \fB\-\-slowms\f1\f1 affects the diagnostic log and, if enabled, the profiler. .PP \fBDatabase Profiler\f1 @@ -3260,11 +2659,12 @@ and, if enabled, the profiler. The fraction of \fIslow\f1 operations that should be profiled or logged. \fB\-\-slowOpSampleRate\f1\f1 accepts values between 0 and 1, inclusive. .PP -\fB\-\-slowOpSampleRate\f1\f1 does not affect the \fBslow oplog entry logging\f1 by the secondary members of a replica set. Secondary +\fB\-\-slowOpSampleRate\f1\f1 does not affect the slow oplog entry logging +by the secondary members of a replica set. Secondary members log all oplog entries that take longer than the slow operation threshold regardless of the \fB\-\-slowOpSampleRate\f1\f1\&. .PP -For \fBmongod\f1\f1 instances, \fB\-\-slowOpSampleRate\f1\f1 affects the +For \fBmongod\f1 instances, \fB\-\-slowOpSampleRate\f1\f1 affects the diagnostic log and, if enabled, the profiler. .RE .SS AUDIT OPTIONS @@ -3310,7 +2710,7 @@ requirements. .RS .PP Enables \fBauditing\f1 and specifies where -\fBmongod\f1\f1 sends all audit events. +\fBmongod\f1 sends all audit events. .PP \fB\-\-auditDestination\f1\f1 can have one of the following values: .RS @@ -3331,8 +2731,8 @@ Windows. Audit messages have a syslog severity level of \fBinfo\f1 and a facility level of \fBuser\f1\&. .IP The syslog message limit can result in the truncation of -audit messages. The auditing system will neither detect the -truncation nor error upon its occurrence. +audit messages. The auditing system neither detects the +truncation nor errors upon its occurrence. .RE .IP \(bu 2 .RS @@ -3462,37 +2862,43 @@ the configuration file. Available only in MongoDB Enterprise (http://www.mongodb.com/products/mongodb\-enterprise\-advanced?tck=docs_server) and MongoDB Atlas (https://cloud.mongodb.com/user#/atlas/login)\&. .RE -.SS SNMP OPTIONS .PP -Starting in MongoDB 6.1, \fBSNMP\f1 is removed. -All related command line options prevent \fBmongod\f1 from starting. -To monitor your deployment, use MongoDB Ops Manager (https://www.mongodb.com/docs/ops\-manager/current/)\&. -.PP -\fBmongod \-\-snmp\-disabled\f1 +\fBmongod \-\-auditSchema\f1 .RS .PP -Disables SNMP access to \fBmongod\f1\f1\&. The option is incompatible -with \fB\-\-snmp\-subagent\f1\f1 and \fB\-\-snmp\-master\f1\f1\&. -.RE +\fIDefault\f1: \fBmongo\f1 .PP -\fBmongod \-\-snmp\-subagent\f1 -.RS -.PP -Runs SNMP as a subagent. The option is incompatible with \fB\-\-snmp\-disabled\f1\f1\&. -.RE -.PP -\fBmongod \-\-snmp\-master\f1 -.RS -.PP -Runs SNMP as a master. The option is incompatible with \fB\-\-snmp\-disabled\f1\f1\&. -.RE +Specifies the format used for audit logs. You can specify one of the +following values for \fB\-\-auditSchema\f1: .RS .IP \(bu 2 -\fBMonitor MongoDB With SNMP on Linux\f1 +.RS +.IP \(bu 4 +Value +.IP \(bu 4 +Description +.RE .IP \(bu 2 -\fBMonitor MongoDB Windows with SNMP\f1 +.RS +.IP \(bu 4 +\fBmongo\f1 +.IP \(bu 4 +Logs are written in a format designed by MongoDB. +.IP +For example log messages, see \fBmongo Schema Audit Messages\f1\&. +.RE .IP \(bu 2 -\fBTroubleshoot SNMP\f1 +.RS +.IP \(bu 4 +\fBOCSF\f1 +.IP \(bu 4 +Logs are written in OCSF (Open Cybersecurity Schema +Framework) format. This option provides logs in a standardized +format compatible with log processors. +.IP +For example log messages, see \fBOCSF Schema Audit Messages\f1\&. +.RE +.RE .RE .SS INMEMORY OPTIONS .PP @@ -3503,7 +2909,7 @@ Runs SNMP as a master. The option is incompatible with \fB\-\-snmp\-disabled\f1\ .PP Maximum amount of memory to allocate for the \fBin\-memory storage engine\f1 data, including indexes, the oplog (if the -\fBmongod\f1\f1 is part of a replica set), sharded +\fBmongod\f1 is part of a replica set), sharded cluster metadata, etc. .PP Values can range from 256MB to 10TB and can be a float. @@ -3546,8 +2952,7 @@ Description .IP \(bu 4 \fBAES256\-CBC\f1 .IP \(bu 4 -256\-bit Advanced Encryption Standard in Cipher Block Chaining -Mode +256\-bit Advanced Encryption Standard in Cipher Block Chaining Mode .RE .IP \(bu 2 .RS @@ -3556,8 +2961,10 @@ Mode .IP \(bu 4 256\-bit Advanced Encryption Standard in Galois/Counter Mode .IP -MongoDB Enterprise on Windows no longer supports \fBAES256\-GCM\f1\&. This -cipher is now available only on Linux. +Available only on Linux. +.IP +MongoDB Enterprise on Windows no longer supports \fBAES256\-GCM\f1 as a +block cipher for encryption at rest. This usage is only supported on Linux. .RE .RE .PP @@ -3569,7 +2976,7 @@ Available in MongoDB Enterprise only. .PP The path to the local keyfile when managing keys via process \fIother than\f1 KMIP. Only set when managing keys via process other than KMIP. -If data is already encrypted using KMIP, MongoDB will throw an error. +If data is already encrypted using KMIP, MongoDB throws an error. .PP The keyfile can contain only a single key. The key is either a 16 or 32 character string. @@ -3585,14 +2992,14 @@ Available in MongoDB Enterprise only. Unique KMIP identifier for an existing key within the KMIP server. Include to use the key associated with the identifier as the system key. You can only use the setting the first time you enable -encryption for the \fBmongod\f1\f1 instance. Requires +encryption for the \fBmongod\f1 instance. Requires \fB\-\-enableEncryption\f1\f1\&. .PP -If unspecified, MongoDB will request that the KMIP server create a +If unspecified, MongoDB requests that the KMIP server create a new key to utilize as the system key. .PP If the KMIP server cannot locate a key with the specified identifier -or the data is already encrypted with a key, MongoDB will throw an +or the data is already encrypted with a key, MongoDB throws an error .PP Available in MongoDB Enterprise only. @@ -3617,21 +3024,20 @@ Available in MongoDB Enterprise only. Hostname or IP address of the KMIP server to connect to. Requires \fB\-\-enableEncryption\f1\f1\&. .PP -Starting in MongoDB 4.2.1, you can specify multiple KMIP -servers as a comma\-separated list, e.g. +You can specify multiple KMIP servers as a comma\-separated list, for example: \fBserver1.example.com,server2.example.com\f1\&. On startup, the -\fBmongod\f1\f1 will attempt to establish a connection to each -server in the order listed, and will select the first server to +\fBmongod\f1 attempts to establish a connection to each +server in the order listed, and selects the first server to which it can successfully establish a connection. KMIP server selection occurs only at startup. .PP -When connecting to a KMIP server, the \fBmongod\f1\f1 +When connecting to a KMIP server, the \fBmongod\f1 verifies that the specified \fB\-\-kmipServerName\f1\f1 matches the Subject Alternative Name \fBSAN\f1 (or, if \fBSAN\f1 is not present, the Common Name \fBCN\f1) in the certificate presented by the KMIP server. -If \fBSAN\f1 is present, \fBmongod\f1\f1 does not match against +If \fBSAN\f1 is present, \fBmongod\f1 does not match against the \fBCN\f1\&. If the hostname does not match the \fBSAN\f1 (or \fBCN\f1), -the \fBmongod\f1\f1 will fail to connect. +the \fBmongod\f1 fails to connect. .PP Starting in MongoDB 4.2, when performing comparison of SAN, MongoDB supports comparison of DNS names or IP addresses. In previous versions, @@ -3650,7 +3056,7 @@ Requires \fB\-\-kmipServerName\f1\f1\&. Requires \fB\-\-enableEncryption\f1\f1\&. .PP If specifying multiple KMIP servers with \fB\-\-kmipServerName\f1\f1, -the \fBmongod\f1\f1 will use the port specified with +the \fBmongod\f1 uses the port specified with \fB\-\-kmipPort\f1\f1 for all provided KMIP servers. .PP Available in MongoDB Enterprise only. @@ -3663,7 +3069,7 @@ Available in MongoDB Enterprise only. .PP How many times to retry the initial connection to the KMIP server. Use together with \fB\-\-kmipConnectTimeoutMS\f1\f1 to -control how long the \fBmongod\f1\f1 waits for a response +control how long the \fBmongod\f1 waits for a response between each retry. .PP Available in MongoDB Enterprise only. @@ -3676,8 +3082,7 @@ Available in MongoDB Enterprise only. .PP Timeout in milliseconds to wait for a response from the KMIP server. If the \fB\-\-kmipConnectRetries\f1\f1 setting is specified, -the \fBmongod\f1\f1 will wait up to the value specified with -\fB\-\-kmipConnectTimeoutMS\f1\f1 for each retry. +the \fBmongod\f1 waits for the specified interval between retries. .PP Value must be \fB1000\f1 or greater. .PP @@ -3746,6 +3151,17 @@ certificate and key. To use this option, you must also specify the \fB\-\-kmipServerName\f1\f1 option. .PP +Enabling encryption using a KMIP server on Windows fails when using +\fB\-\-kmipClientCertificateFile\f1 and the KMIP server enforces TLS 1.2. +.PP +To enable encryption at rest with KMIP on Windows, you must: +.RS +.IP \(bu 2 +Import the client certificate into the Windows Certificate Store. +.IP \(bu 2 +Use the \fB\-\-kmipClientCertificateSelector\f1\f1 option. +.RE +.PP On macOS or Windows, you can use a certificate from the operating system\(aqs secure store instead of a PEM key file. See \fB\-\-kmipClientCertificateSelector\f1\f1\&. @@ -3785,11 +3201,11 @@ Activates all newly created KMIP keys upon creation and then periodically checks those keys are in an active state. .PP When \fB\-\-kmipActivateKeys\f1 is \fBtrue\f1 and you have existing keys on a -KMIP server, the key must be activated first or the \fBmongod\f1\f1 node -will fail to start. +KMIP server, the key must be activated first or the \fBmongod\f1\f1 +node fails to start. .PP If the key being used by the mongod transitions into a non\-active state, -the \fBmongod\f1\f1 node will shut down unless \fBkmipActivateKeys\f1 is +the \fBmongod\f1\f1 node shuts down unless \fBkmipActivateKeys\f1 is false. To ensure you have an active key, rotate the KMIP master key by using \fB\-\-kmipRotateMasterKey\f1\f1\&. .RE @@ -3824,7 +3240,7 @@ with KMIP version 1.0 or 1.1, you must specify Roll over the \fBencrypted storage engine\f1 database keys configured with \fBAES256\-GCM\f1 cipher. .PP -When \fBmongod\f1\f1 instance is started with this option, the +When \fBmongod\f1 instance is started with this option, the instance rotates the keys and exits. .PP Available in MongoDB Enterprise only. diff --git a/debian/mongodb-parameters.5 b/debian/mongodb-parameters.5 index 7f1e865b695..f2c1eaf63b9 100644 --- a/debian/mongodb-parameters.5 +++ b/debian/mongodb-parameters.5 @@ -104,8 +104,8 @@ is available only in MongoDB Enterprise (http://www.mongodb.com/products/mongodb .RE .RE .PP -You can only set \fBauthenticationMechanisms\f1\f1 during -start\-up. +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .PP For example, to specify both \fBPLAIN\f1 and \fBSCRAM\-SHA\-256\f1 as the authentication mechanisms, use the following command: @@ -115,6 +115,38 @@ authentication mechanisms, use the following command: .EE .RE .PP +\fBawsSTSRetryCount\f1 +.RS +.PP +In previous versions, AWS IAM authentication retried only when the +server returned an HTTP 500 error. +.PP +Available for both \fBmongod\f1\f1 and \fBmongos\f1\f1\&. +.PP +\fIType\f1: integer +.PP +\fIDefault\f1: 2 +.PP +For MongoDB deployments using AWS IAM credentials (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access\-keys.html) or AWS IAM environment variables (https://docs.aws.amazon.com/cli/latest/userguide/cli\-configure\-envvars.html#envvars\-list)\&. +.PP +Maximum number of AWS IAM authentication retries after a connection +failure. +.PP +The following example sets \fBawsSTSRetryCount\f1\f1 to \fB15\f1 +retries: +.PP +.EX + mongod \-\-setParameter awsSTSRetryCount=15 +.EE +.PP +Alternatively, the following examples uses the +\fBsetParameter\f1\f1 command within \fBmongosh\f1\f1: +.PP +.EX + db.adminCommand( { setParameter: 1, awsSTSRetryCount: 15 } ) +.EE +.RE +.PP \fBclusterAuthMode\f1 .RS .PP @@ -129,6 +161,9 @@ For more information about TLS/SSL and MongoDB, see \fBConfigure mongod\f1 and mongos\f1 for TLS/SSL\f1 and \fBTLS/SSL Configuration for Clients\f1 . .PP +This parameter is only available at runtime. To set the +parameter, use the \fBsetParameter\f1\f1 command. +.PP .EX db.adminCommand( { setParameter: 1, clusterAuthMode: "sendX509" } ) .EE @@ -139,18 +174,59 @@ For more information about TLS/SSL and MongoDB, see .PP Available for both \fBmongod\f1\f1 and \fBmongos\f1\f1\&. .PP +\fIDefault\f1: \fBtrue\f1 +.PP Specify \fB0\f1 or \fBfalse\f1 to disable localhost authentication bypass. Enabled by default. .PP -\fBenableLocalhostAuthBypass\f1\f1 is not available using -\fBsetParameter\f1\f1 database command. Use the -\fBsetParameter\f1\f1 option in the configuration file or the -\fB\-\-setParameter\f1\f1 option on the -command line. +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .PP See \fBLocalhost Exception\f1 for more information. .RE .PP +\fBenforceUserClusterSeparation\f1 +.RS +.PP +Available for both \fBmongod\f1\f1 and \fBmongos\f1\f1\&. +.PP +Set to \fBfalse\f1 to disable the \fBO/OU/DC\f1 check when +\fBclusterAuthMode\f1 is \fBkeyFile\f1 in your configuration file. This +allows clients possessing member certificates to authenticate as +users stored in the \fB$external\f1 database. The server won\(aqt start if +\fBclusterAuthMode\f1 isn\(aqt \fBkeyFile\f1 in your configuration file. +.PP +To set the \fBenforceUserClusterSeparation\f1 parameter to \fBfalse\f1, +run the following command during startup: +.PP +.EX + mongod \-\-setParameter enforceUserClusterSeparation=false +.EE +.PP +If you set the \fBenforceUserClusterSeparation\f1 parameter to \fBfalse\f1, +the server doesn\(aqt distinguish between client certificates, which +applications use to authenticate, and intra\-cluster certificates, which +have privileged access. This has no effect if your \fBclusterAuthMode\f1 +is \fBkeyFile\f1\&. However, if your \fBclusterAuthMode\f1 is \fBx509\f1, user +certificates that use the allowed scheme are conflated with cluster +certificates and granted privileged access. +.PP +Your existing certificates are granted internal privileges if you do the +following: +.RS +.IP \(bu 2 +Create a user, with a name allowed by this parameter. +.IP \(bu 2 +Set the \fBenforceUserClusterSeparation\f1 parameter to \fBfalse\f1\&. +.IP \(bu 2 +Set \fBclusterAuthMode\f1 to \fBx509\f1\&. +.RE +.PP +You must not upgrade from \fBkeyFile\f1 to \fBx509\f1 without validating +that you\(aqve removed users with elevated privileges that the +\fBenforceUserClusterSeparation\f1 flag allowed you to create. +.RE +.PP \fBKeysRotationIntervalSec\f1 .RS .PP @@ -160,9 +236,8 @@ Specifies the number of seconds for which an HMAC signing key (https://en.wikipe is valid before rotating to the next one. This parameter is intended primarily to facilitate authentication testing. .PP -You can only set \fBKeysRotationIntervalSec\f1\f1 during -start\-up, and cannot change this setting with the -\fBsetParameter\f1\f1 database command. +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .RE .PP \fBldapForceMultiThreadMode\f1 @@ -185,6 +260,32 @@ If you have any concerns regarding your MongoDB version, OS version or libldap version, please contact MongoDB Support. .RE .PP +\fBldapQueryPassword\f1 +.RS +.PP +Available for both \fBmongod\f1\f1 and \fBmongos\f1\f1\&. +.PP +\fIType\f1: string +.PP +The password used to bind to an LDAP server. You must use +\fBldapQueryUser\f1\f1 with this parameter. +.PP +If not set, mongod or mongos does not attempt to bind to the LDAP server. +.RE +.PP +\fBldapQueryUser\f1 +.RS +.PP +Available for both \fBmongod\f1\f1 and \fBmongos\f1\f1\&. +.PP +\fIType\f1: string +.PP +The user that binds to an LDAP server. You must use +\fBldapQueryPassword\f1\f1 with this parameter. +.PP +If not set, mongod or mongos does not attempt to bind to the LDAP server. +.RE +.PP \fBldapRetryCount\f1 .RS .PP @@ -392,7 +493,7 @@ start\-up, and cannot change this setting during run time with the \fBldapConnectionPoolMaximumConnectionsPerHost\f1 .RS .PP -\fIChanged starting in MongoDB versions 4.4.15, 5.0.9, and 6.0.0\f1 +\fIChanged starting in MongoDB versions 5.0.9 and 6.0.0\f1 Changed default value to \fB2147483647\f1\&. In previous versions, the default is unset. .PP @@ -409,7 +510,7 @@ start\-up, and cannot change this setting during run time with the \fBldapConnectionPoolMaximumConnectionsInProgressPerHost\f1 .RS .PP -\fIChanged starting in MongoDB versions 4.4.15, 5.0.9, and 6.0.0\f1 +\fIChanged starting in MongoDB versions 5.0.9 and 6.0.0\f1 Changed default value to \fB2\f1\&. In previous versions, the default is unset. .PP @@ -493,9 +594,15 @@ The maximum memory usage limit in megabytes for the \fBvalidate\f1\f1 returns as many results as possible and warns that not all corruption might be reported because of the limit. .PP -You can set \fBmaxValidateMemoryUsageMB\f1\f1 during startup, and -can change this setting using the \fBsetParameter\f1\f1 database -command. +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE .RE .PP \fBoidcIdentityProviders\f1 @@ -518,9 +625,9 @@ Field .IP \(bu 4 Necessity .IP \(bu 4 -Description -.IP \(bu 4 Type +.IP \(bu 4 +Description .RE .IP \(bu 2 .RS @@ -529,10 +636,23 @@ Type .IP \(bu 4 Required .IP \(bu 4 +string +.IP \(bu 4 The issuer URI of the IDP that the server should accept tokens from. This must match the \fBiss\f1 field in any JWT used for authentication. -.IP \(bu 4 -string +.IP +If you specify an unreachable issuer URI, MongoDB: +.RS +.IP \(bu 6 +Logs a warning. +.IP \(bu 6 +Continues server startup, which allows you to update the issuer +URI. +.IP \(bu 6 +Reattempts issuer contact. If MongoDB reaches the issuer URI +and validates the access token, authentication succeeds. If +the issuer URI remains unreachable, authentication fails. +.RE .RE .IP \(bu 2 .RS @@ -541,10 +661,19 @@ string .IP \(bu 4 Required .IP \(bu 4 -Unique prefix applied to each generated \fBUserName\f1 and \fBRoleName\f1 used -in authorization. -.IP \(bu 4 string +.IP \(bu 4 +Unique prefix applied to each generated \fBUserName\f1 and \fBRoleName\f1 used +in authorization. \fBauthNamePrefix\f1 can only contain the +following characters: +.RS +.IP \(bu 6 +alphanumeric characters (combination of \fBa\f1 to \fBz\f1 and \fB0\f1 to \fB9\f1) +.IP \(bu 6 +hyphens (\fB\-\f1) +.IP \(bu 6 +underscores (\fB_\f1) +.RE .RE .IP \(bu 2 .RS @@ -553,28 +682,42 @@ string .IP \(bu 4 Conditional .IP \(bu 4 -Required when more than one IDP is defined. -.IP +string +.IP \(bu 4 Regex pattern used to determine which IDP should be used. \fBmatchPattern\f1 matches against usernames. Array order determines the priority and the first IDP is always selected. .IP +\fBmatchPattern\f1 is required in some configurations, depending on +how the user sets \fBsupportsHumanFlows\f1: +.RS +.IP \(bu 6 +When only one IdP has \fBsupportsHumanFlows\f1 set to \fBtrue\f1 +(the default), \fBmatchPatterns\f1 is optional. +.IP \(bu 6 +When multiple IdP\(aqs have \fBsupportsHumanFlows\f1 set to \fBtrue\f1 +(the default), each of these requires \fBmatchPatterns\f1\&. +.IP \(bu 6 +\fBmatchPatterns\f1 is optional for any IdP where \fBsupportsHumanFlows\f1 +is set to \fBfalse\f1\&. +.RE +.IP This is not a security mechanism. \fBmatchPattern\f1 serves only as an advisory to clients. MongoDB accepts tokens issued by the IDP whose principal names do not match this pattern. -.IP \(bu 4 -string .RE .IP \(bu 2 .RS .IP \(bu 4 \fBclientId\f1 .IP \(bu 4 -Required -.IP \(bu 4 -ID provided by the IDP to identify the client that receives the access tokens. +Conditional .IP \(bu 4 string +.IP \(bu 4 +ID provided by the IDP to identify the client that receives the access tokens. +.IP +Required when \fBsupportsHumanFlows\f1 is set to \fBtrue\f1 (the default). .RE .IP \(bu 2 .RS @@ -583,9 +726,9 @@ string .IP \(bu 4 Required .IP \(bu 4 -Specifies the application or service that the access token is intended for. -.IP \(bu 4 string +.IP \(bu 4 +Specifies the application or service that the access token is intended for. .RE .IP \(bu 2 .RS @@ -594,9 +737,9 @@ string .IP \(bu 4 Optional .IP \(bu 4 -Permissions and access levels that MongoDB requests from the IDP. -.IP \(bu 4 array[ string ] +.IP \(bu 4 +Permissions and access levels that MongoDB requests from the IDP. .RE .IP \(bu 2 .RS @@ -605,23 +748,68 @@ array[ string ] .IP \(bu 4 Optional .IP \(bu 4 +string +.IP \(bu 4 The claim to be extracted from the access token containing MongoDB user identifiers. .IP The default value is \fBsub\f1 (stands for \fBsubject\f1). +.RE +.IP \(bu 2 +.RS .IP \(bu 4 -string +\fBuseAuthorizationClaim\f1 +.IP \(bu 4 +Optional +.IP \(bu 4 +boolean +.IP \(bu 4 +Determines if the \fBauthorizationClaim\f1 is required. The default value is +\fBtrue\f1\&. +.IP +If the \fBuseAuthorizationClaim\f1 field is set to \fBtrue\f1, the server requires +an \fBauthorizationClaim\f1 for the identity provider\(aqs config. This is the +default behavior. +.IP +If the \fBuseAuthorizationClaim\f1 field is set to \fBfalse\f1, the +\fBauthorizationClaim\f1 field is optional (and ignored if provided). +Instead, the server does the following: +.RS +.IP \(bu 6 +Searches the token for a claim whose name is listed in the +\fBprincipalNameClaim\f1 field. This is typically named \fBsub\f1\&. For +example: +.IP +\fBsub: "spencer.jackson@example.com"\f1 +.IP \(bu 6 +Constructs the internal username by concatenating the \fBauthNamePrefix\f1, +a forward slash (\fB/\f1), and the contents of the claim identified by +\fBprincipalNameClaim\f1 within the access token. For example, with a +\fBauthNamePrefix\f1 field value of "mdbinc", the internal username is: +.IP +\fBmdbinc/spencer.jackson@example.com\f1 +.IP \(bu 6 +Looks for the user with this username and authorizes the client with the +roles: +.IP +.EX + { user: "mdbinc/spencer.jackson@example.com", + db: "$external" } +.EE +.RE .RE .IP \(bu 2 .RS .IP \(bu 4 \fBauthorizationClaim\f1 .IP \(bu 4 -Required -.IP \(bu 4 -Claim extracted from access token that contains MongoDB role names. +Conditional .IP \(bu 4 string +.IP \(bu 4 +Required, unless \fBuseAuthorizationClaim\f1 is set to \fBfalse\f1\&. +.IP +Claim extracted from access token that contains MongoDB role names. .RE .IP \(bu 2 .RS @@ -630,10 +818,10 @@ string .IP \(bu 4 Optional .IP \(bu 4 +array[ string ] +.IP \(bu 4 List of access token claims to include in log and audit messages upon authentication completion. -.IP \(bu 4 -array[ string ] .RE .IP \(bu 2 .RS @@ -642,16 +830,32 @@ array[ string ] .IP \(bu 4 Optional .IP \(bu 4 +integer +.IP \(bu 4 Frequency, in seconds, to request an updated JSON Web Key Set (JWKS) from the IDP. A setting of 0 disables polling. +.RE +.IP \(bu 2 +.RS .IP \(bu 4 -integer +\fBsupportsHumanFlows\f1 +.IP \(bu 4 +Optional +.IP \(bu 4 +bool +.IP \(bu 4 +Whether the OIDC provider supports human or machine workflows. This +affects the \fBclientId\f1 and \fBmatchPattern\f1 fields. +.IP +You may find it useful to set this field to \fBfalse\f1 with machine workload +IdP\(aqs to allow them to omit the \fBclientId\f1 when it\(aqs unneeded. +.IP +Default: \fBtrue\f1\&. .RE .RE .PP -You can only set \fBoidcIdentityProviders\f1 during startup in the -\fBconfiguration file\f1\f1 or with the -\fB\-\-setParameter\f1 option on the command line. +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .RE .PP \fBocspEnabled\f1 @@ -663,14 +867,21 @@ Available on Linux and macOS. .PP The flag that enables or disables OCSP. .PP -You can only set \fBocspEnabled\f1\f1 during startup in the -\fBconfiguration file\f1\f1 or with the -\fB\-\-setParameter\f1 option on the command line. For example, the -following disables OCSP: +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. +.PP +For example, the following disables OCSP: .PP .EX mongod \-\-setParameter ocspEnabled=false ... .EE +.PP +Starting in MongoDB 6.0, if \fBocspEnabled\f1\f1 is set to \fBtrue\f1 during +initial sync, all nodes must be able to reach the \fBOCSP\f1 +responder. +.PP +If a member fails in the \fBSTARTUP2\f1\f1 state, set +\fBtlsOCSPVerifyTimeoutSecs\f1\f1 to a value that is less than \fB5\f1\&. .RS .IP \(bu 2 \fBocspValidationRefreshPeriodSecs\f1\f1 @@ -718,7 +929,7 @@ stapled OCSP responses. .PP With the use of native TLS/SSL libraries, the parameter \fBopensslCipherConfig\f1\f1 is supported for Linux/BSD and -no longer supported in Windows and macOS. See \fBTLS/SSL\f1\&. +no longer supported in Windows and macOS. .PP Specify the cipher string for OpenSSL when using TLS/SSL encryption. For a list of cipher strings, see @@ -729,15 +940,13 @@ This parameter is only for use with TLS 1.2 or earlier. To specify cipher suites for use with TLS 1.3, use the \fBopensslCipherSuiteConfig\f1\f1 parameter. .PP -You can only set \fBopensslCipherConfig\f1\f1 during start\-up, -and cannot change this setting using the \fBsetParameter\f1\f1 -database command. +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .PP -For version 4.2 and greater, the use of \fBTLS\f1 options is preferred -over \fBSSL\f1 options. The TLS options have the same functionality as -the \fBSSL\f1 options. For example, the following configures a -\fBmongod\f1\f1 with a \fBopensslCipherConfig\f1\f1 -cipher string of \fB\(aqHIGH:!EXPORT:!aNULL@STRENGTH\(aq\f1 in MongoDB 4.2: +The use of \fBTLS\f1 options is preferred over \fBSSL\f1 options. The TLS options +have the same functionality as the \fBSSL\f1 options. The following example +configures a \fBmongod\f1\f1 with a \fBopensslCipherConfig\f1\f1 +cipher string of \fB\(aqHIGH:!EXPORT:!aNULL@STRENGTH\(aq\f1: .PP .EX mongod \-\-setParameter opensslCipherConfig=\(aqHIGH:!EXPORT:!aNULL@STRENGTH\(aq \-\-tlsMode requireTLS \-\-tlsCertificateKeyFile Certs/server.pem @@ -760,11 +969,11 @@ This parameter is only for use with TLS 1.3. To specify cipher strings for use with TLS 1.2 or earlier, use the \fBopensslCipherConfig\f1\f1 parameter. .PP -You can only set \fBopensslCipherSuiteConfig\f1\f1 during -start\-up, and cannot change this setting using the -\fBsetParameter\f1\f1 database command. For example, the -following configures a \fBmongod\f1\f1 with a -\fBopensslCipherSuiteConfig\f1\f1 cipher suite of +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. +.PP +For example, the following configures a \fBmongod\f1\f1 +with a \fBopensslCipherSuiteConfig\f1\f1 cipher suite of \fB\(aqTLS_AES_256_GCM_SHA384\(aq\f1 for use with TLS 1.3: .PP .EX @@ -792,8 +1001,7 @@ private key but never transmitted. This ensures that even if a server\(aqs private key is compromised, you cannot decrypt past sessions with the compromised key. .PP -Starting in MongoDB 4.2, if -\fBopensslDiffieHellmanParameters\f1\f1 is unset but +If \fBopensslDiffieHellmanParameters\f1\f1 is unset but \fBECDHE\f1 is enabled, MongoDB enables DHE using the \fBffdhe3072\f1 Diffie\-Hellman parameter, as defined in RFC\-7919#appendix\-A.2 (https://tools.ietf.org/html/7919#appendix\-A.2)\&. The \fBffdhe3072\f1 is a strong parameter @@ -801,9 +1009,8 @@ RFC\-7919#appendix\-A.2 (https://tools.ietf.org/html/7919#appendix\-A.2)\&. The not supported with Java 6 and 7 unless extended support has been purchased from Oracle. .PP -You can only set \fBopensslDiffieHellmanParameters\f1\f1 during -startup, and cannot change this setting using the -\fBsetParameter\f1\f1 database command. +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .PP If for performance reasons, you need to disable support for DHE cipher suites, use the \fBopensslCipherConfig\f1\f1 parameter: @@ -820,6 +1027,9 @@ Available for both \fBmongod\f1\f1 and \fBmongos\f1\f1\&. .PP Specify the path to the Unix Domain Socket of the \fBsaslauthd\f1 instance to use for proxy authentication. +.PP +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .RE .PP \fBsaslHostName\f1 @@ -835,9 +1045,8 @@ authentication. \fBmongod\f1\f1 or \fBmongos\f1\f1 instance for any purpose beyond the configuration of SASL and Kerberos. .PP -You can only set \fBsaslHostName\f1\f1 during start\-up, and -cannot change this setting using the \fBsetParameter\f1\f1 -database command. +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .PP \fBsaslHostName\f1\f1 supports Kerberos authentication and is only included in MongoDB Enterprise. For more information, see the @@ -862,9 +1071,8 @@ service name component of the \fBKerberos\f1 principal name, on a per\-instance basis. If unspecified, the default value is \fBmongodb\f1\&. .PP -MongoDB only permits setting \fBsaslServiceName\f1\f1 at -startup. The \fBsetParameter\f1\f1 command can not change -this setting. +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .PP \fBsaslServiceName\f1\f1 is only available in MongoDB Enterprise. @@ -889,6 +1097,16 @@ If you modify this value, it does not change the iteration count for existing passwords. The \fBscramIterationCount\f1\f1 value must be \fB5000\f1 or greater. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP For example, the following sets the \fBscramIterationCount\f1\f1 to \fB12000\f1\&. .PP @@ -929,6 +1147,16 @@ If you modify this value, it does not change iteration count for existing passwords. The \fBscramSHA256IterationCount\f1\f1 value must be \fB5000\f1 or greater. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP For example, the following sets the \fBscramSHA256IterationCount\f1\f1 to \fB20000\f1\&. .PP @@ -957,13 +1185,16 @@ Or, if using the \fBsetParameter\f1\f1 command within .PP Available for both \fBmongod\f1\f1 and \fBmongos\f1\f1\&. .PP -Set the \fBnet.ssl.mode\f1\f1 to either \fBpreferSSL\f1 or +Set the \fBnet.ssl.mode\f1 to either \fBpreferSSL\f1 or \fBrequireSSL\f1\&. Useful during \fBrolling upgrade to TLS/SSL\f1 to minimize downtime. .PP For more information about TLS/SSL and MongoDB, see \fBConfigure mongod\f1 and mongos\f1 for TLS/SSL\f1 and \fBTLS/SSL Configuration for Clients\f1 . .PP +This parameter is only available at runtime. To set the +parameter, use the \fBsetParameter\f1\f1 command. +.PP .EX db.adminCommand( { setParameter: 1, sslMode: "preferSSL" } ) .EE @@ -988,6 +1219,9 @@ The \fBtlsMode\f1\f1 parameter is useful during \fBrolling upgrade to TLS/SSL\f1 to minimize downtime. .PP +This parameter is only available at runtime. To set the +parameter, use the \fBsetParameter\f1\f1 command. +.PP .EX db.adminCommand( { setParameter: 1, tlsMode: "preferTLS" } ) .EE @@ -1025,6 +1259,9 @@ it authorizes the connection as a peer. .PP Use this parameter to rotate certificates when the new certificates have different attributes or extension values. +.PP +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .RE .PP \fBtlsOCSPStaplingTimeoutSecs\f1 @@ -1040,11 +1277,11 @@ Specify an integer greater than or equal to (\fB>=\f1) 1. If unset, \fBtlsOCSPStaplingTimeoutSecs\f1\f1 uses the \fBtlsOCSPVerifyTimeoutSecs\f1\f1 value. .PP -You can only set \fBtlsOCSPStaplingTimeoutSecs\f1\f1 during -startup in the \fBconfiguration file\f1\f1 or with -the \fB\-\-setParameter\f1 option on the command line. For example, the -following sets the \fBtlsOCSPStaplingTimeoutSecs\f1\f1 to 20 -seconds: +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. +.PP +For example, the following sets the +\fBtlsOCSPStaplingTimeoutSecs\f1\f1 to 20 seconds: .PP .EX mongod \-\-setParameter tlsOCSPStaplingTimeoutSecs=20 ... @@ -1072,11 +1309,11 @@ response when verifying server certificates. .PP Specify an integer greater than or equal to (\fB>=\f1) 1. .PP -You can only set \fBtlsOCSPVerifyTimeoutSecs\f1\f1 during -startup in the \fBconfiguration file\f1\f1 or with -the \fB\-\-setParameter\f1 option on the command line. For example, the -following sets the \fBtlsOCSPVerifyTimeoutSecs\f1\f1 to 20 -seconds: +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. +.PP +For example, the following sets the +\fBtlsOCSPVerifyTimeoutSecs\f1\f1 to 20 seconds: .PP .EX mongod \-\-setParameter tlsOCSPVerifyTimeoutSecs=20 ... @@ -1091,6 +1328,41 @@ seconds: .RE .RE .PP +\fBtlsUseSystemCA\f1 +.RS +.PP +Available for \fBmongod\f1\f1 only. +.PP +\fIType\f1: boolean +.PP +\fIDefault\f1: false +.PP +Specifies whether MongoDB loads TLS certificates that are already +available to the operating system\(aqs certificate authority. +.PP +When starting a \fBmongod\f1\f1 instance with +\fBTLS/SSL enabled\f1, you must +specify a value for the \fB\-\-tlsCAFile\f1\f1 flag, the +\fBnet.tls.CAFile\f1\f1 configuration option, or the \fBtlsUseSystemCA\f1\f1 +parameter. +.PP +\fB\-\-tlsCAFile\f1, \fBtls.CAFile\f1, and \fBtlsUseSystemCA\f1 are all mutually +exclusive. +.PP +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. +.PP +For example, to set \fBtlsUseSystemCA\f1 to \fBtrue\f1: +.PP +.EX + mongod \-\-setParameter tlsUseSystemCA=true +.EE +.PP +For more information about TLS/SSL and MongoDB, see +\fBConfigure mongod\f1 and mongos\f1 for TLS/SSL\f1 and +\fBTLS/SSL Configuration for Clients\f1 . +.RE +.PP \fBtlsWithholdClientCertificate\f1 .RS .PP @@ -1113,6 +1385,9 @@ communications. Use this option with (to allow inbound connections without certificates) on all members of the deployment. \fBtlsWithholdClientCertificate\f1 is mutually exclusive with \fB\-\-clusterAuthMode x509\f1\f1\&. +.PP +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .RE .PP \fBtlsX509ClusterAuthDNOverride\f1 @@ -1146,6 +1421,16 @@ value. If set, you must set this parameter on all members of the deployment. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP You can use this parameter for a rolling update of certificates to new certificates that contain a new \fBDN\f1 value. See \fBRolling Update of x.509 Cluster Certificates that Contain New DN\f1\&. @@ -1161,10 +1446,10 @@ Available for both \fBmongod\f1\f1 and \fBmongos\f1\f1\&. .PP \fIDefault\f1 : 30 .PP -Starting in MongoDB 4.4, \fBmongod\f1\f1 / \fBmongos\f1\f1 -logs a warning on connection if the presented x.509 certificate -expires within \fB30\f1 days of the \fBmongod/mongos\f1 system clock. -Use the \fBtlsX509ExpirationWarningThresholdDays\f1\f1 parameter +\fBmongod\f1\f1 / \fBmongos\f1\f1 logs a warning on connection if the +presented x.509 certificate expires within \fB30\f1 days of the +\fBmongod/mongos\f1 system clock. Use the +\fBtlsX509ExpirationWarningThresholdDays\f1\f1 parameter to control the certificate expiration warning threshold: .RS .IP \(bu 2 @@ -1179,50 +1464,16 @@ Set the parameter to \fB0\f1 to disable the warning. .PP This parameter has a minimum value of \fB0\f1\&. .PP -You can only set \fBtlsX509ExpirationWarningThresholdDays\f1\f1 -during \fBmongod/mongos\f1 startup using either: -.RS -.IP \(bu 2 -The \fBsetParameter\f1\f1 configuration setting, \fIor\f1 -.IP \(bu 2 -The \fBmongod \-\-setParameter\f1\f1 / -\fBmongos \-\-setParameter\f1\f1 command -line option. -.RE +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .PP See \fBx.509 Certificates Nearing Expiry Trigger Warnings\f1 for more -information on x.509 expiration warnings in MongoDB 4.4. +information on x.509 expiration warnings. .PP For more information on x.509 certificate validity, see RFC 5280 4.1.2.5 (https://tools.ietf.org/html/rfc5280#section\-4.1.2.5)\&. .RE .PP -\fBsslWithholdClientCertificate\f1 -.RS -.PP -Use \fBtlsWithholdClientCertificate\f1\f1 instead. -.PP -Available for both \fBmongod\f1\f1 and \fBmongos\f1\f1\&. -.PP -\fIDefault\f1: false -.PP -A TLS certificate is set for a \fBmongod\f1\f1 or -\fBmongos\f1\f1 either by the -\fB\-\-tlsClusterFile\f1\f1 option or by the -\fB\-\-tlsCertificateKeyFile\f1\f1 option when -\fB\-\-tlsClusterFile\f1\f1 is not set. If the TLS -certificate is set, by default, the instance sends the certificate when -initiating intra\-cluster communications with other -\fBmongod\f1\f1 or \fBmongos\f1\f1 instances in -the deployment. Set \fBsslWithholdClientCertificate\f1 to \fB1\f1 or \fBtrue\f1 to -direct the instance to withhold sending its TLS certificate during these -communications. Use this option with -\fB\-\-tlsAllowConnectionsWithoutCertificates\f1\f1 -(to allow inbound connections without certificates) on all members of the -deployment. \fBsslWithholdClientCertificate\f1 is mutually exclusive with -\fB\-\-clusterAuthMode x509\f1\f1\&. -.RE -.PP \fBuserCacheInvalidationIntervalSecs\f1 .RS .PP @@ -1238,6 +1489,16 @@ clears the cache. If there are no changes to user objects, .PP This parameter has a minimum value of \fB1\f1 second and a maximum value of \fB86400\f1 seconds (24 hours). +.PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE .RE .PP \fBauthFailedDelayMs\f1 @@ -1270,8 +1531,8 @@ Available for both \fBmongod\f1\f1 and \fBmongos\f1\f1\&. A boolean flag that allows or disallows the retrieval of authorization roles from client x.509 certificates. .PP -You can only set \fBallowRolesFromX509Certificates\f1\f1 during -startup in the config file or on the command line. +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .RE .SS GENERAL PARAMETERS .PP @@ -1284,11 +1545,13 @@ Available for \fBmongod\f1\f1 only. .PP Starting in MongoDB 6.0, pipeline stages that require more than 100 megabytes of memory to execute write temporary files to disk by -default. In earlier verisons of MongoDB, you must pass -\fB{ allowDiskUse: true }\f1 to individual \fBfind\f1 and \fBaggregate\f1 -commands to enable this behavior. +default. These temporary files last for the duration of the pipeline +execution and can influence storage space on your instance. In earlier +versions of MongoDB, you must pass \fB{ allowDiskUse: true }\f1 to +individual \fBfind\f1 and \fBaggregate\f1 commands to enable this +behavior. .PP -Individual \fBfind\f1 and \fBaggregate\f1 commands may override the +Individual \fBfind\f1 and \fBaggregate\f1 commands can override the \fBallowDiskUseByDefault\f1\f1 parameter by either: .RS .IP \(bu 2 @@ -1299,6 +1562,16 @@ Using \fB{ allowDiskUse: false }\f1 to prohibit writing temporary files out to disk when \fBallowDiskUseByDefault\f1 is set to \fBtrue\f1 .RE .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP .EX mongod \-\-setParameter allowDiskUseByDefault=false .EE @@ -1320,72 +1593,28 @@ server is running: .EE .RE .PP -\fBconnPoolMaxShardedConnsPerHost\f1 +\fBhttpVerboseLogging\f1 .RS .PP Available for both \fBmongod\f1\f1 and \fBmongos\f1\f1\&. .PP -\fIDefault\f1: 200 -.PP -Sets the maximum size of the legacy connection pools for communication to the -shards. The size of a pool does not prevent the creation of -additional connections, but \fIdoes\f1 prevent the connection pools from -retaining connections above this limit. -.PP -The parameter is separate from the connections in TaskExecutor -pools. See \fBShardingTaskExecutorPoolMaxSize\f1\f1\&. -.PP -Increase the \fBconnPoolMaxShardedConnsPerHost\f1\f1 value -\fBonly\f1 if the number of connections in a connection pool has a -high level of churn or if the total number of created connections -increase. -.PP -You can only set \fBconnPoolMaxShardedConnsPerHost\f1\f1 during -startup in the config file or on the command line. For example: -.PP -.EX - mongos \-\-setParameter connPoolMaxShardedConnsPerHost=250 -.EE -.RE -.PP -\fBconnPoolMaxShardedInUseConnsPerHost\f1 -.RS -.PP -Available for both \fBmongod\f1\f1 and \fBmongos\f1\f1\&. -.PP -Sets the maximum number of in\-use connections at any given time for -the legacy sharded cluster connection pools. +Adds more verbose tracing for curl on Linux and macOS. Has no affect on Windows. .PP By default, the parameter is unset. .PP -You can only set \fBconnPoolMaxShardedConnsPerHost\f1\f1 during -startup in the config file or on the command line. For example: -.PP -.EX - mongos \-\-setParameter connPoolMaxShardedInUseConnsPerHost=100 -.EE -.PP -\fBconnPoolMaxShardedConnsPerHost\f1\f1 +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting .RE .PP -\fBshardedConnPoolIdleTimeoutMinutes\f1 -.RS -.PP -Available for both \fBmongod\f1\f1 and \fBmongos\f1\f1\&. -.PP -Sets the time limit that a connection in the legacy sharded cluster -connection pool can remain idle before being closed. -.PP -By default, the parameter is unset. -.PP -You can only set \fBshardedConnPoolIdleTimeoutMinutes\f1\f1 during -startup in the config file or on the command line. For example: -.PP .EX - mongos \-\-setParameter shardedConnPoolIdleTimeoutMinutes=10 + mongos \-\-setParameter httpVerboseLogging=true .EE -.PP -\fBconnPoolMaxShardedConnsPerHost\f1\f1 .RE .PP \fBslowConnectionThresholdMillis\f1 @@ -1403,6 +1632,16 @@ If a connection takes longer to establish than the added to the \fBlog\f1 with the message \fBmsg\f1 field set to \fB"Slow connection establishment"\f1\&. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP The following example sets \fBslowConnectionThresholdMillis\f1\f1 to \fB250\f1 milliseconds. .PP @@ -1438,8 +1677,8 @@ pools. See \fBShardingTaskExecutorPoolMaxSize\f1\f1\&. connections and you\(aqre using authentication in the context of a sharded cluster. .PP -You can only set \fBconnPoolMaxConnsPerHost\f1\f1 during startup -in the config file or on the command line. For example: +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .PP .EX mongod \-\-setParameter connPoolMaxConnsPerHost=250 @@ -1457,8 +1696,8 @@ the legacy global connection pool. .PP By default, the parameter is unset. .PP -You can only set \fBconnPoolMaxInUseConnsPerHost\f1\f1 during -startup in the config file or on the command line. For example: +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .PP .EX mongod \-\-setParameter connPoolMaxInUseConnsPerHost=100 @@ -1477,15 +1716,12 @@ pool can remain idle before being closed. .PP By default, the parameter is unset. .PP -You can only set \fBglobalConnPoolIdleTimeoutMinutes\f1\f1 -during startup in the config file or on the command line. For -example: +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .PP .EX mongos \-\-setParameter globalConnPoolIdleTimeoutMinutes=10 .EE -.PP -\fBconnPoolMaxShardedConnsPerHost\f1\f1 .RE .PP \fBcursorTimeoutMillis\f1 @@ -1499,6 +1735,16 @@ Sets the expiration threshold in milliseconds for idle cursors before MongoDB removes them; specifically, MongoDB removes cursors that have been idle for the specified \fBcursorTimeoutMillis\f1\f1\&. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP For example, the following sets the \fBcursorTimeoutMillis\f1\f1 to \fB300000\f1 milliseconds (5 minutes). .PP @@ -1519,48 +1765,18 @@ Generally, the timeout value should be greater than the average amount of time for a query to return results. Use tools like the \fBcursor.explain()\f1\f1 cursor modifier to analyze the average query time and select an appropriate timeout period. -.RE .PP -\fBfailIndexKeyTooLong\f1 -.RS +MongoDB cleans up \fBorphaned cursors\f1 linked to +sessions as part of session management. This means that orphaned cursors +with session ids do not use \fBcursorTimeoutMillis\f1 to control the +timeout. .PP -\fIRemoved in 4.4\f1 -.RS -.IP \(bu 2 -\fBMongoDB 4.4\f1 \fIremoves\f1 the deprecated -\fBfailIndexKeyTooLong\f1\f1 parameter. Attempting to use -this parameter with MongoDB 4.4 will result in an error. -.IP \(bu 2 -\fBMongoDB 4.2\f1 \fIdeprecates\f1 the -\fBfailIndexKeyTooLong\f1\f1 parameter and \fIremoves\f1 the -\fBIndex Key Length Limit\f1 for -\fBfeatureCompatibilityVersion\f1 (fCV) set to -\fB"4.2"\f1 or greater. -.RE -.PP -Setting \fBfailIndexKeyTooLong\f1\f1 to \fBfalse\f1 is -a temporary workaround, not a permanent solution to the -problem of oversized index keys. With -\fBfailIndexKeyTooLong\f1\f1 set to \fBfalse\f1, queries can -return incomplete results if they use indexes that skip over -documents whose indexed fields exceed the -\fBIndex Key Length Limit\f1\&. -.PP -\fBfailIndexKeyTooLong\f1\f1 defaults to \fBtrue\f1\&. -.PP -Issue the following command to disable the index key length -validation: -.PP -.EX - db.adminCommand( { setParameter: 1, failIndexKeyTooLong: false } ) -.EE -.PP -You can also set \fBfailIndexKeyTooLong\f1\f1 at startup with the -following option: -.PP -.EX - mongod \-\-setParameter failIndexKeyTooLong=false -.EE +For operations that return a cursor and have an idle period +longer than \fBlocalLogicalSessionTimeoutMinutes\f1\f1, +use \fBMongo.startSession()\f1\f1 to perform the operation +within an explicit session. To refresh the session, run +the \fBrefreshSessions\f1\f1 command. For details, see +\fBRefresh a Cursor with refreshSessions\f1\f1\&. .RE .PP \fBmaxNumActiveUserIndexBuilds\f1 @@ -1594,6 +1810,16 @@ index build is blocked, the server logs this message: number of active index builds is below the threshold. .EE .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP The following command sets a limit of 4 concurrent index builds: .PP .EX @@ -1630,7 +1856,7 @@ application queries, for example, to identify queries that scan an entire collection and cannot use an index. .PP To detect unindexed queries without \fBnotablescan\f1, consider reading -the \fBEvaluate Performance of Current Operations\f1 and +the \fBAnalyze Query Performance\f1 and \fBOptimize Query Performance\f1 sections and using the \fBlogLevel\f1\f1 parameter, \fBmongostat\f1\f1 and \fBprofiling\f1\&. @@ -1638,6 +1864,20 @@ sections and using the \fBlogLevel\f1\f1 parameter, Don\(aqt run production \fBmongod\f1\f1 instances with \fBnotablescan\f1\f1 because preventing collection scans can potentially affect queries in all databases, including administrative queries. +.PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP +\fBnotablescan\f1 does not allow unbounded queries that use a +clustered index because the queries require a full collection +scan. For more information, see \fBCollection Scans\f1\&. .RE .PP \fBttlMonitorEnabled\f1 @@ -1651,6 +1891,16 @@ To support \fBTTL Indexes\f1, \fBmongod\f1\f1 instances have a background thread that is responsible for deleting documents from collections with TTL indexes. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP To disable this worker thread for a \fBmongod\f1\f1, set \fBttlMonitorEnabled\f1\f1 to \fBfalse\f1, as in the following operations: @@ -1721,9 +1971,8 @@ Set to \fB3\f1 to enable inbound and outbound TFO connections. This parameter has no effect if the host operating system does not support \fIor\f1 is not configured to support TFO connections. .PP -You can only set this parameter on startup, using either the -\fBsetParameter\f1\f1 configuration file setting or the -\fB\-\-setParameter\f1\f1 command line option. +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .PP See \fBSupport for TCP Fast Open\f1 for more information on MongoDB TFO support. @@ -1759,9 +2008,8 @@ outbound TFO connections: This parameter has no effect if the host operating system does not support \fIor\f1 is not configured to support TFO connections. .PP -You can only set this parameter on startup, using either the -\fBsetParameter\f1\f1 configuration file setting or the -\fB\-\-setParameter\f1\f1 command line option. +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .PP See \fBSupport for TCP Fast Open\f1 for more information on MongoDB TFO support. @@ -1807,6 +2055,9 @@ This parameter has no effect on host operating systems that do not support or are not configured for TFO connections. See \fBSupport for TCP Fast Open\f1 for more information on MongoDB TFO support. +.PP +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .RS .IP \(bu 2 RFC7413 TCP Fast Open Section 5: Security Considerations (https://tools.ietf.org/html/rfc7413#section\-5) @@ -1823,6 +2074,16 @@ Available for \fBmongod\f1\f1 only. The MongoDB JavaScript engine uses SpiderMonkey, which implements Just\-in\-Time (JIT) compilation for improved performance when running scripts. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP To enable the JIT, set \fBdisableJavaScriptJIT\f1\f1 to \fBfalse\f1, as in the following example: .PP @@ -1842,6 +2103,54 @@ Alternately, you may enable the JIT at startup time by starting the .EE .RE .PP +\fBindexBuildMinAvailableDiskSpaceMB\f1 +.RS +.PP +Available for \fBmongod\f1\f1 only. +.PP +\fIDefault\f1: 500 MB +.PP +Sets the minimum available disk space in megabytes required for index +builds. +.PP +Must be greater than or equal to 0 MB, and less than or equal to 8 +TB. 0 disables the minimum disk space requirement. +.PP +A new index build cannot be started and a current index build is +cancelled if the available disk space is below +\fBindexBuildMinAvailableDiskSpaceMB\f1\&. +.PP +If you increase \fBindexBuildMinAvailableDiskSpaceMB\f1, ensure your +server has enough available disk space. Also, if you set +\fBindexBuildMinAvailableDiskSpaceMB\f1 too high, you might +needlessly prevent index builds when there is enough available +disk space and \fBindexBuildMinAvailableDiskSpaceMB\f1 could be +set lower. +.PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP +The following example sets \fBindexBuildMinAvailableDiskSpaceMB\f1 to 650 MB: +.PP +.EX + db.adminCommand( { setParameter: 1, indexBuildMinAvailableDiskSpaceMB: 650 } ) +.EE +.PP +You can also set \fBindexBuildMinAvailableDiskSpaceMB\f1 at startup. +For example: +.PP +.EX + mongod \-\-setParameter indexBuildMinAvailableDiskSpaceMB=650 +.EE +.RE +.PP \fBindexMaxNumGeneratedKeysPerDocument\f1 .RS .PP @@ -1852,18 +2161,15 @@ prevent out of memory errors. It is possible to raise the limit, but if an operation requires more keys than the \fBindexMaxNumGeneratedKeysPerDocument\f1\f1 parameter specifies, the operation will fail. +.PP +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .RE .PP \fBmaxIndexBuildMemoryUsageMegabytes\f1 .RS .PP -\fIDefault\f1: -.RS -.IP \(bu 2 -200 (For versions 4.2.3 and later) -.IP \(bu 2 -500 (For versions 4.2.2 and earlier) -.RE +\fIDefault\f1: 200 .PP Limits the amount of memory that simultaneous index builds on one collection may consume for the duration of the @@ -1872,10 +2178,26 @@ indexes built using a single \fBcreateIndexes\f1\f1 command or its shell helper \fBdb.collection.createIndexes()\f1\f1\&. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP The memory consumed by an index build is separate from the WiredTiger cache memory (see \fBcacheSizeGB\f1\f1). .PP +\fBmaxIndexBuildMemoryUsageMegabytes\f1 sets a limit on how much +memory the index build uses at once. This can impact performance +when the \fBindex build process\f1 generates +and sorts keys for the index. Increasing the memory limit +improves sorting performance during an index build. +.PP Index builds may be initiated either by a user command such as \fBcreateIndexes\f1\f1 or by an administrative process such as an \fBinitial sync\f1\&. Both are subject to the limit @@ -1891,6 +2213,12 @@ memory greater than the limit set by To minimize the impact of building an index on replica sets and sharded clusters with replica set shards, use a rolling index build procedure as described on \fBRolling Index Builds on Replica Sets\f1\&. +.PP +Changing \fBmaxIndexBuildMemoryUsageMegabytes\f1 does not affect an +in progress index build if it has already started a collection scan. +However, a forced replica set reconfiguration restarts the collection +scan and uses the most current +\fBmaxIndexBuildMemoryUsageMegabytes\f1 provided. .RS .IP \(bu 2 For \fBfeature compatibility version (fcv)\f1 \fB"4.2"\f1 @@ -1907,10 +2235,6 @@ A boolean flag that determines whether the \fBdb.serverStatus()\f1\f1 method and \fBserverStatus\f1\f1 command return \fBopWriteConcernCounters\f1\f1 information. .PP -You can only set -\fBreportOpWriteConcernCountersInServerStatus\f1\f1 during -startup in the config file or on the command line. For example: -.PP .EX mongod \-\-setParameter reportOpWriteConcernCountersInServerStatus=true .EE @@ -1996,19 +2320,102 @@ It is an error to set \fBwatchdogPeriodSeconds\f1\f1 at run time if the startup time. .RE .PP +\fBtcmallocAggressiveMemoryDecommit\f1 +.RS +.PP +To release memory back to the operating system, consider using +\fBtcmallocEnableBackgroundThread\f1\f1 instead. +.PP +\fIType\f1: integer (\fB0\f1 or \fB1\f1 only) +.PP +Default: 0 +.PP +If you enable \fBtcmallocAggressiveMemoryDecommit\f1, MongoDB: +.RS +.IP \(bu 2 +releases a \fBchunk\f1 of memory to system, and +.IP \(bu 2 +attempts to return all neighboring free chunks. +.RE +.PP +A value of \fB1\f1 enables \fBtcmallocAggressiveMemoryDecommit\f1; +\fB0\f1 disables this parameter. +.PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP +If you enable this parameter, the system will require new memory allocations +for use. Consider enabling \fBtcmallocAggressiveMemoryDecommit\f1 +only on memory\-constrained systems and after pursuing other memory and +performance options. +.RE +.PP +\fBtcmallocEnableBackgroundThread\f1 +.RS +.PP +\fIType\f1: boolean +.PP +Default: true +.PP +If set to \fBtrue\f1, \fBtcmallocEnableBackgroundThread\f1 creates a background +thread that periodically releases memory back to the operating system. The +value of \fBtcmallocReleaseRate\f1\f1 determines the rate, in bytes per +second, at which the background thread releases memory. +.PP +If \fBtcmallocEnableBackgroundThread\f1 is \fBtrue\f1 and \fBtcmallocReleaseRate\f1 +is \fB0\f1, MongoDB still releases memory. +.PP +For improved memory usage, we recommend using the default value +of \fBtrue\f1\&. To learn more about improvements to performance and memory +management, see \fBUpgraded TCMalloc\f1\&. +.PP +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. +.PP +The following operation sets \fBtcmallocEnableBackgroundThread\f1 +to \fBfalse\f1: +.PP +.EX + mongod \-\-setParameter "tcmallocEnableBackgroundThread=false" +.EE +.RE +.PP \fBtcmallocReleaseRate\f1 .RS .PP -Default: 1.0 +Default: 0 .PP -Specifies the tcmalloc release rate (TCMALLOC_RELEASE_RATE (https://gperftools.github.io/gperftools/tcmalloc.html#runtime)). -Per https://gperftools.github.io/gperftools/tcmalloc.html#runtime (https://gperftools.github.io/gperftools/tcmalloc.html#runtime) -TCMALLOC_RELEASE_RATE is described as the "Rate at which we release -unused memory to the system, via -madvise(MADV_DONTNEED), on systems that support it. Zero means we -never release memory back to the system. Increase this flag to -return memory faster; decrease it to return memory slower. -Reasonable rates are in the range [0,10]." +Specifies the tcmalloc release rate (https://github.com/google/tcmalloc/blob/master/docs/tuning.md) +in bytes per second. Release rate refers to the rate at which MongoDB +releases unused memory to the system. If \fBtcmallocReleaseRate\f1 is set to +\fB0\f1 MongoDB doesn\(aqt release memory back to the system. Increase +this value to return memory faster; decrease it to return memory slower. +.PP +If \fBtcmallocEnableBackgroundThread\f1 is \fBtrue\f1 and \fBtcmallocReleaseRate\f1 +is \fB0\f1, MongoDB still releases memory. +.PP +Starting in MongoDB 8.0, the default value of \fBtcmallocReleaseRate\f1 is +reduced to \fB0\f1 due to a \fBtcmalloc upgrade\f1 +that prioritizes CPU performance over memory release. Earlier versions of +MongoDB used an older version of \fBtcmalloc\f1 that set the default +\fBtcmallocReleaseRate\f1 to \fB1\f1 to balance memory release and performance. +.PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE .PP To modify the release rate during run time, you can use the \fBsetParameter\f1\f1 command; for example: @@ -2040,6 +2447,16 @@ successfully elect a new primary node and thus continue to be available. \fBfassertOnLockTimeoutForStepUpDown\f1 defaults to 15 seconds. To disable nodes from fasserting, set \fBfassertOnLockTimeoutForStepUpDown=0\f1\&. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP The following example disables nodes from fasserting: .PP .EX @@ -2059,6 +2476,16 @@ most verbose. .PP The default \fBlogLevel\f1\f1 is \fB0\f1 (Informational). .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP The following example sets the \fBlogLevel\f1\f1 to \fB2\f1: .PP .EX @@ -2187,6 +2614,16 @@ also applies to: \fBstorage.recovery\f1\f1\&. .RE .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP For example, the following sets the \fBdefault verbosity level\f1\f1 to \fB1\f1, the \fBquery\f1\f1 to \fB2\f1, the \fBstorage\f1\f1 to \fB2\f1, @@ -2249,6 +2686,16 @@ Using a large value, or disabling truncation with a value of \fB0\f1, may adversely affect system performance and negatively impact database operations. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP The following example sets the maximum log line size to \fB20\f1 kilobytes: .PP @@ -2257,6 +2704,28 @@ kilobytes: .EE .RE .PP +\fBprofileOperationResourceConsumptionMetrics\f1 +.RS +.PP +Available for \fBmongod\f1\f1 only. +.PP +\fIType\f1: boolean +.PP +\fIDefault\f1: false +.PP +Flag that determines whether operations collect resource +consumption metrics and report them in the slow query logs. +If you enable \fBprofiling\f1, +these metrics are also included. +.PP +If set to \fBtrue\f1, running the \fBexplain\f1\f1 command +returns \fBoperationMetrics\f1 when the verbosity +is \fBexecutionStats\f1 or higher. +.PP +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. +.RE +.PP \fBquiet\f1 .RS .PP @@ -2276,6 +2745,16 @@ the \fBdrop\f1\f1 command, the replication synchronization activities. .RE .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP Consider the following example which sets the \fBquiet\f1 parameter to \fB1\f1: .PP @@ -2364,6 +2843,16 @@ If the \fBredactClientLogData\f1\f1 parameter or all fields are redacted, regardless of the \fBredactEncryptedFields\f1 setting. .RE +.PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE .RE .PP \fBtraceExceptions\f1 @@ -2375,6 +2864,9 @@ Configures \fBmongod\f1\f1 to log full source code stack traces for every database and socket C++ exception, for use with debugging. If \fBtrue\f1, \fBmongod\f1\f1 will log full stack traces. .PP +This parameter is only available at runtime. To set the +parameter, use the \fBsetParameter\f1\f1 command. +.PP Consider the following example which sets the \fBtraceExceptions\f1 to \fBtrue\f1: .PP @@ -2396,12 +2888,15 @@ Available for both \fBmongod\f1\f1 and \fBmongos\f1\f1\&. .PP By default, a \fBmongod\f1\f1 or \fBmongos\f1\f1 with \fBTLS/SSL enabled\f1 and -\fBnet.ssl.allowConnectionsWithoutCertificates\f1\f1 : \fBtrue\f1 +\fBnet.ssl.allowConnectionsWithoutCertificates\f1 : \fBtrue\f1 lets clients connect without providing a certificate for validation while logging an warning. Set \fBsuppressNoTLSPeerCertificateWarning\f1 to \fB1\f1 or \fBtrue\f1 to suppress those warnings. .PP +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. +.PP The following operation sets \fBsuppressNoTLSPeerCertificateWarning\f1 to \fBtrue\f1: .PP @@ -2410,7 +2905,7 @@ to \fBtrue\f1: .EE .RE .PP -\fBgEnableDetailedConnectionHealthMetricLogLines\f1 +\fBenableDetailedConnectionHealthMetricLogLines\f1 .RS .PP Available for both \fBmongod\f1\f1 and \fBmongos\f1\f1\&. @@ -2421,7 +2916,7 @@ Available for both \fBmongod\f1\f1 and \fBmongos\f1\f1\&. .PP Determines whether to enable specific log messages related to cluster connection health metrics. If -\fBgEnableDetailedConnectionHealthMetricLogLines\f1\f1 is set to +\fBenableDetailedConnectionHealthMetricLogLines\f1\f1 is set to \fBfalse\f1, the following log messages are turned off, but MongoDB still collects data on the cluster connection health metrics: .RS @@ -2525,6 +3020,16 @@ outgoing request on an egress connection, counting from the instant when the connection establishes. .RE .RE +.PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE .RE .SS DIAGNOSTIC PARAMETERS .PP @@ -2569,6 +3074,16 @@ Available for both \fBmongod\f1\f1 and \fBmongos\f1\f1\&. Determines whether to enable the collecting and logging of data for diagnostic purposes. Diagnostic logging is enabled by default. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP For example, the following disables the diagnostic collection: .PP .EX @@ -2607,6 +3122,16 @@ diagnostic data capture is disabled for that instance. \fBmongos\f1\f1 may not be able to create the specified directory if a file with the same name already exists in the path or if the process does not have permissions to create the directory. +.PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE .RE .PP \fBdiagnosticDataCollectionDirectorySizeMB\f1 @@ -2620,9 +3145,19 @@ Available for both \fBmongod\f1\f1 and \fBmongos\f1\f1\&. .PP Specifies the maximum size, in megabytes, of the \fBdiagnostic.data\f1 directory. If directory size exceeds this number, the oldest -\fBdiagnostic files in the directory\f1 are automatically deleted based on +diagnostic files in the directory are automatically deleted based on the timestamp in the file name. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP For example, the following sets the maximum size of the directory to \fB250\f1 megabytes: .PP @@ -2646,9 +3181,18 @@ Available for both \fBmongod\f1\f1 and \fBmongos\f1\f1\&. .PP \fIDefault\f1: 10 .PP -Specifies the maximum size, in megabytes, of each \fBdiagnostic -file\f1\&. If the file exceeds the maximum -file size, MongoDB creates a new file. +Specifies the maximum size, in megabytes, of each diagnostic +file. If the file exceeds the maximum file size, MongoDB creates a new file. +.PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE .PP For example, the following sets the maximum size of each diagnostic file to \fB20\f1 megabytes: @@ -2673,6 +3217,16 @@ Available for both \fBmongod\f1\f1 and \fBmongos\f1\f1\&. Specifies the interval, in milliseconds, at which to collect diagnostic data. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP For example, the following sets the interval to \fB5000\f1 milliseconds or 5 seconds: .PP @@ -2694,7 +3248,6 @@ Available for both \fBmongod\f1\f1 and \fBmongos\f1\f1\&. \fIType\f1: boolean .PP \fIDefault\f1: false -.RE .PP To configure cluster nodes for split horizon DNS (https://en.wikipedia.org/wiki/Split\-horizon_DNS), use host names instead of IP addresses. @@ -2710,7 +3263,7 @@ configuration commands. \fBmongod\f1\f1 and \fBmongos\f1\f1 do not rely on \fBdisableSplitHorizonIPCheck\f1\f1 for validation at startup. Legacy \fBmongod\f1\f1 and \fBmongos\f1\f1 instances that use IP -addresses instead of host names will start after an upgrade. +addresses instead of host names can start after an upgrade. .PP Instances that are configured with IP addresses log a warning to use host names instead of IP addresses. @@ -2722,22 +3275,14 @@ To allow configuration changes using IP addresses, set /usr/local/bin/mongod \-\-setParameter disableSplitHorizonIPCheck=true \-f /etc/mongod.conf .EE .PP -To allow configuration changes using IP addresses, set -\fBdisableSplitHorizonIPCheck=true\f1 using the node\(aqs configuration -file: +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .PP .EX setParameter: disableSplitHorizonIPCheck: true .EE -.PP -If you attempt to update \fBdisableSplitHorizonIPCheck\f1 at run time, -\fBdb.adminCommand()\f1\f1 returns an error: -.PP -.EX - db.adminCommand( { setParameter: 1, "disableSplitHorizonIPCheck": true } ) - MongoServerError: not allowed to change [disableSplitHorizonIPCheck] at run time -.EE +.RE .PP \fBenableOverrideClusterChainingSetting\f1 .RS @@ -2753,9 +3298,8 @@ replica set \fBsecondary\f1 members can replicate data from other secondary members even if \fBsettings.chainingAllowed\f1\f1 is \fBfalse\f1\&. .PP -You can only set \fBenableOverrideClusterChainingSetting\f1\f1 at -startup and cannot change this setting with the -\fBsetParameter\f1\f1 command. +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .PP For example, to set the \fBenableOverrideClusterChainingSetting\f1\f1 for a @@ -2778,9 +3322,8 @@ Available for both \fBmongod\f1\f1 and \fBmongos\f1\f1\&. The interval (in milliseconds) at which the cache refreshes its logical session records against the main session store. .PP -You can only set \fBlogicalSessionRefreshMillis\f1\f1 at -startup and cannot change this setting with the -\fBsetParameter\f1\f1 command. +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .PP For example, to set the \fBlogicalSessionRefreshMillis\f1\f1 for a \fBmongod\f1\f1 instance to 10 minutes: @@ -2814,9 +3357,8 @@ set this parameter on replica sets and sharded clusters, you must specify the same value on every member; otherwise, sessions will not function properly. .PP -You can only set \fBlocalLogicalSessionTimeoutMinutes\f1\f1 at -startup and cannot change this setting with the -\fBsetParameter\f1\f1 command. +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .PP For example, to set the \fBlocalLogicalSessionTimeoutMinutes\f1\f1 for a test \fBmongod\f1\f1 instance to 20 minutes: @@ -2845,9 +3387,8 @@ You cannot advance the cluster time to a new value if the new cluster time differs from the current cluster time by more than \fBmaxAcceptableLogicalClockDriftSecs\f1\f1\&. .PP -You can only set \fBmaxAcceptableLogicalClockDriftSecs\f1\f1 at -startup and cannot change this setting with the -\fBsetParameter\f1\f1 command. +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .PP For example, to set the \fBmaxAcceptableLogicalClockDriftSecs\f1\f1 for a \fBmongod\f1\f1 instance to 15 minutes: @@ -2868,7 +3409,8 @@ Available for both \fBmongod\f1\f1 and \fBmongos\f1\f1\&. .PP The maximum number of sessions that can be cached. .PP -You can only set \fBmaxSessions\f1\f1 during start\-up. +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .PP For example, to set the \fBmaxSessions\f1\f1 for a \fBmongod\f1\f1 instance to 1000: @@ -2899,8 +3441,8 @@ larger amounts of data. This reduces IOPS (Input/Output Operations Per Second) on secondaries, but adds latency for writes with write concern \fB"majority"\f1\f1\&. .PP -You can only set \fBoplogBatchDelayMillis\f1 at startup. You cannot set -\fBoplogBatchDelayMillis\f1 during run time. +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .PP For example, run the following command to set the \fBoplogBatchDelayMillis\f1 for a \fBmongod\f1\f1 instance to 20 @@ -2911,6 +3453,31 @@ milliseconds: .EE .RE .PP +\fBperiodicNoopIntervalSecs\f1 +.RS +.PP +Available for \fBmongod\f1\f1 only. +.PP +\fIType\f1: integer +.PP +\fIDefault\f1: 10 +.PP +The duration in seconds between \fBnoop\f1 writes on each individual node. +.PP +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. +.PP +To modify this value for a MongoDB Atlas (https://www.mongodb.com/docs/atlas/) cluster, you +must contact Atlas Support (https://www.mongodb.com/docs/atlas/support/)\&. +.PP +The following example sets the \fBperiodicNoopIntervalSecs\f1 to 1 second at +startup: +.PP +.EX + mongod \-\-setParameter periodicNoopIntervalSecs=1 +.EE +.RE +.PP \fBstoreFindAndModifyImagesInSideCollection\f1 .RS .PP @@ -2925,7 +3492,7 @@ Determines whether the temporary documents required for commands are stored in the \fIside\f1 collection (\fBconfig.image_collection\f1). .PP -If \fBstoreFindAndModifyImagesInSideCollection\f1\f1 is: +If \fBstoreFindAndModifyImagesInSideCollection\f1 is: .RS .IP \(bu 2 \fBtrue\f1, the temporary documents are stored in the side @@ -2935,7 +3502,7 @@ collection. set oplog\f1\&. .RE .PP -Keep \fBstoreFindAndModifyImagesInSideCollection\f1\f1 set to +Keep \fBstoreFindAndModifyImagesInSideCollection\f1 set to \fBtrue\f1 if you: .RS .IP \(bu 2 @@ -2947,11 +3514,21 @@ available in the \fBreplica set oplog\f1\&. .RE .PP \fBSecondaries\f1 may experience increased CPU -usage when \fBstoreFindAndModifyImagesInSideCollection\f1\f1 +usage when \fBstoreFindAndModifyImagesInSideCollection\f1 is \fBtrue\f1\&. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP For example, to set -\fBstoreFindAndModifyImagesInSideCollection\f1\f1 to \fBfalse\f1 +\fBstoreFindAndModifyImagesInSideCollection\f1 to \fBfalse\f1 during startup: .PP .EX @@ -2979,9 +3556,8 @@ The minimum lifetime a transaction record exists in the \fBtransactions\f1\f1 collection before the record becomes eligible for cleanup. .PP -You can only set \fBTransactionRecordMinimumLifetimeMinutes\f1\f1 at -startup and cannot change this setting with the -\fBsetParameter\f1\f1 command. +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .PP For example, to set the \fBTransactionRecordMinimumLifetimeMinutes\f1\f1 for a \fBmongod\f1\f1 instance to 20 minutes: @@ -3005,6 +3581,16 @@ primary applies its writes with the goal of keeping the secondary members\(aq \fBmajority committed\f1\f1 lag under a configurable maximum value. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP For flow control to engage, the replica set/sharded cluster must have: \fBfeatureCompatibilityVersion (fCV)\f1 of \fB4.2\f1 and read concern \fBmajority enabled\f1\f1\&. That is, enabled flow @@ -3030,6 +3616,16 @@ The specified value must be greater than 0. In general, the default settings should suffice; however, if modifying from the default value, decreasing, rather than increasing, the value may prove to be more useful. +.PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE .RE .PP \fBflowControlWarnThresholdSeconds\f1 @@ -3044,6 +3640,16 @@ mechanism detects the majority commit point has not moved. .PP The specified value must be greater than or equal to 0, with 0 to disable warnings. +.PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE .RE .PP \fBinitialSyncTransientErrorRetryPeriodSeconds\f1 @@ -3056,6 +3662,16 @@ disable warnings. The amount of time in seconds a secondary performing initial sync attempts to resume the process if interrupted by a transient network error. The default value is equivalent to 24 hours. +.PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE .RE .PP \fBinitialSyncSourceReadPreference\f1 @@ -3101,10 +3717,8 @@ successfully completes initial sync, it defers to the value of \fBchainingAllowed\f1\f1 when selecting a replication sync source. .PP -You can only set this parameter on startup, using either the -\fBsetParameter\f1\f1 -configuration file setting or the -\fB\-\-setParameter\f1\f1 command line option. +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .RE .PP \fBinitialSyncMethod\f1 @@ -3128,9 +3742,8 @@ it is specified. Setting this parameter on a single replica set member does not affect the sync method of any other replica set members. .PP -You can only set this parameter on startup, using either the -\fBsetParameter\f1\f1 configuration file setting or the -\fB\-\-setParameter\f1\f1 command line option. +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .RE .PP \fBmaxNumSyncSourceChangesPerHour\f1 @@ -3153,6 +3766,16 @@ another node if it doesn\(aqt have a sync source. The node will re\-evaluate if a sync source becomes invalid. Similarly, if the primary changes and chaining is disabled, the node will update to sync from the new primary. +.PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE .RE .PP \fBoplogFetcherUsesExhaust\f1 @@ -3172,9 +3795,8 @@ disabled, secondaries fetch batches of \fBoplog\f1 entries by issuing a request to their \fIsync from\f1 source and waiting for a response. This requires a network roundtrip for each batch of \fBoplog\f1 entries. .PP -You can only set this parameter on startup, using either the -\fBsetParameter\f1\f1 configuration file setting or the -\fB\-\-setParameter\f1\f1 command line option. +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .RE .PP \fBoplogInitialFindMaxSeconds\f1 @@ -3189,6 +3811,16 @@ Available for \fBmongod\f1\f1 only. Maximum time in seconds for a member of a \fBreplica set\f1 to wait for the \fBfind\f1\f1 command to finish during \fBdata synchronization\f1\&. +.PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE .RE .PP \fBreplWriterThreadCount\f1 @@ -3205,9 +3837,8 @@ parallel. Values can range from 1 to 256 inclusive. However, the maximum number of threads used is capped at twice the number of available cores. .PP -You can only set \fBreplWriterThreadCount\f1\f1 at startup and -cannot change this setting with the \fBsetParameter\f1\f1 -command. +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .PP \fBreplWriterMinThreadCount\f1\f1 .RE @@ -3235,6 +3866,9 @@ pool is equal to \fBreplWriterMinThreadCount\f1\f1\&. .PP \fBreplWriterMinThreadCount\f1\f1 must be configured with a value that is less than or equal to \fBreplWriterThreadCount\f1\f1\&. +.PP +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .RE .PP \fBrollbackTimeLimitSecs\f1 @@ -3256,6 +3890,16 @@ rollback will fail. To effectively have an unlimited rollback period, set the value to \fB2147483647\f1 which is the maximum value allowed and equivalent to roughly 68 years. +.PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE .RE .PP \fBwaitForSecondaryBeforeNoopWriteMS\f1 @@ -3274,6 +3918,16 @@ if the \fBafterClusterTime\f1 is still greater than the last applied time, the secondary makes a no\-op write to advance the last applied time. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP The following example sets the \fBwaitForSecondaryBeforeNoopWriteMS\f1\f1 to 20 milliseconds: .PP @@ -3304,6 +3958,16 @@ rollback. By default, \fBcreateRollbackDataFiles\f1\f1 is \fBtrue\f1 and MongoDB creates the rollback files. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP The following example sets \fBcreateRollbackDataFiles\f1\f1 to false so that the rollback files are not created: .PP @@ -3330,8 +3994,18 @@ Sets the maximum oplog application batch size in bytes. .PP Values can range from 16777216 (16MB) to 104857600 (100MB) inclusive. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP The following example sets \fBreplBatchLimitBytes\f1\f1 -to 64 MB so that the rollback files are not created: +to 64 MB to limit the oplog application batch size: .PP .EX mongod \-\-setParameter replBatchLimitBytes=67108864 @@ -3434,11 +4108,18 @@ The \fBmaxTimeMS\f1 for the mirrored reads is separate from the .RE .RE .PP -You can set \fBmirrorReads\f1\f1 during startup in the -\fBconfiguration file\f1\f1 or with the -\fB\-\-setParameter\f1 option on the command line. If specifying from -the configuration file or on the command line, \fBenclose the\f1 -\fBmirrorReads\f1 \fBdocument in quotes\f1\&. +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP +If you specify from the configuration file or on the command +line, \fBenclose the\f1 \fBmirrorReads\f1 \fBdocument in quotes\f1\&. .PP For example, the following sets the mirror reads sampling rate to \fB0.10\f1 from the command line: @@ -3490,7 +4171,8 @@ replica set doesn\(aqt have sufficient secondaries for data replication. For more information, see \fBConcerns with Multiple Arbiters\f1\&. .PP -The parameter can only be set during startup: +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .PP .EX mongod \-\-setParameter allowMultipleArbiters=true @@ -3498,9 +4180,161 @@ The parameter can only be set during startup: .RE .SS SHARDING PARAMETERS .PP -Starting in version 4.2, MongoDB removes the parameter -\fBAsyncRequestsSenderUseBaton\f1 and always enables the performance -enhancement controlled by the parameter. +\fBanalyzeShardKeyCharacteristicsDefaultSampleSize\f1 +.RS +.PP +Available for \fBmongod\f1\f1 only. +.PP +\fIType\f1: integer +.PP +\fIDefault\f1: 10000000 +.PP +If \fBsampleRate\f1 and \fBsampleSize\f1 are not set when +you run \fBanalyzeShardKey\f1, specifies the number of documents to +sample when calculating shard key characteristics metrics. Must be +greater than \fB0\f1\&. +.PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP +This example sets \fBanalyzeShardKeyCharacteristicsDefaultSampleSize\f1 +to \fB10000\f1 at startup: +.PP +.EX + mongod \-\-setParameter analyzeShardKeyCharacteristicsDefaultSampleSize=10000 +.EE +.PP +During run time, you can set or modify the parameter with the +\fBsetParameter\f1\f1 command: +.PP +.EX + db.adminCommand( { setParameter: 1, analyzeShardKeyCharacteristicsDefaultSampleSize: 10000 } ) +.EE +.RE +.PP +\fBanalyzeShardKeyNumMostCommonValues\f1 +.RS +.PP +Available for \fBmongod\f1\f1 only. +.PP +\fIType\f1: integer +.PP +\fIDefault\f1: 5 +.PP +Specifies the number of most common shard key values to return. If +the collection contains fewer unique shard keys than this value, +\fBanalyzeShardKeyNumMostCommonValues\f1 returns that number of +most common values. Must be greater than \fB0\f1 and less than or equal +to \fB1000\f1\&. +.PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP +This example sets \fBanalyzeShardKeyNumMostCommonValues\f1 +to \fB3\f1 at startup: +.PP +.EX + mongod \-\-setParameter analyzeShardKeyNumMostCommonValues=3 +.EE +.PP +During run time, you can set or modify the parameter with the +\fBsetParameter\f1\f1 command: +.PP +.EX + db.adminCommand( { setParameter: 1, analyzeShardKeyNumMostCommonValues: 3 } ) +.EE +.RE +.PP +\fBanalyzeShardKeyNumRanges\f1 +.RS +.PP +Available for \fBmongod\f1\f1 only. +.PP +\fIType\f1: integer +.PP +\fIDefault\f1: 100 +.PP +Specifies the number of ranges to partition the shard key space into +when calculating the \fBhotness\f1 of shard key +ranges. Must be greater than \fB0\f1 and less than or equal to +\fB10000\f1\&. +.PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP +This example sets \fBanalyzeShardKeyNumRanges\f1 to \fB50\f1 at startup: +.PP +.EX + mongod \-\-setParameter analyzeShardKeyNumRanges=50 +.EE +.PP +During run time, you can set or modify the parameter with the +\fBsetParameter\f1\f1 command: +.PP +.EX + db.adminCommand( { setParameter: 1, analyzeShardKeyNumRanges: 50 } ) +.EE +.RE +.PP +\fBanalyzeShardKeyMonotonicityCorrelationCoefficientThreshold\f1 +.RS +.PP +Available for \fBmongod\f1\f1 only. +.PP +\fIType\f1: double +.PP +\fIDefault\f1: 0.7 +.PP +Specifies the \fBRecordId\f1 correlation coefficient threshold used to +determine if a shard key is monotonically changing in insertion order. +Must be greater than \fB0\f1 and less than or equal to \fB1\f1\&. +.PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP +This example sets +\fBanalyzeShardKeyMonotonicityCorrelationCoefficientThreshold\f1 to +\fB1\f1 at startup: +.PP +.EX + mongod \-\-setParameter analyzeShardKeyMonotonicityCorrelationCoefficientThreshold=1 +.EE +.PP +During run time, you can set or modify the parameter with the +\fBsetParameter\f1\f1 command: +.PP +.EX + db.adminCommand( { setParameter: 1, analyzeShardKeyMonotonicityCorrelationCoefficientThreshold: 1 } ) +.EE +.RE .PP \fBautoMergerIntervalSecs\f1 .RS @@ -3517,18 +4351,28 @@ is 3600 seconds, or one hour. .PP \fBautoMergerIntervalSecs\f1 can only be set on config servers. .PP -This example sets \fBautoMergerIntervalSecs\f1 to 7200 milliseconds, +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP +This example sets \fBautoMergerIntervalSecs\f1 to 7200 seconds, or two hours, at startup: .PP .EX - mongod \-\-setParameter autoMergeInterval=7200 + mongod \-\-setParameter autoMergerIntervalSecs=7200 .EE .PP During run time, you can set or modify the parameter with the \fBsetParameter\f1\f1 command: .PP .EX - db.adminCommand( { setParameter: 1, autoMergeInterval: 7200 } ) + db.adminCommand( { setParameter: 1, autoMergerIntervalSecs: 7200 } ) .EE .RE .PP @@ -3547,6 +4391,16 @@ collection, in milliseconds. .PP \fBautoMergerThrottlingMS\f1 can only be set on config servers. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP This example sets \fBautoMergerThrottlingMS\f1 to 60000 milliseconds, or one minute, at startup: .PP @@ -3575,6 +4429,16 @@ Specifies the minimum amount of time between two consecutive balancing rounds. This allows you to throttle the balancing rate. This parameter only takes effect on config server nodes. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP This example sets \fBbalancerMigrationsThrottlingMs\f1 to 2000 milliseconds at startup: .PP @@ -3605,6 +4469,16 @@ the \fBchunks\f1 in a \fBsharded\f1 collection are defragmented. \fBchunkDefragmentationThrottlingMS\f1\f1 limits the rate of split and merge commands. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP The following example sets \fBchunkDefragmentationThrottlingMS\f1\f1 to \fB10\f1 milliseconds: .PP @@ -3623,7 +4497,7 @@ During run time, you can also set the parameter with the \fBchunkMigrationConcurrency\f1 .RS .PP -\fIAvailable starting in MongoDB 6.3 (and 5.0.15).\f1 +\fIAvailable starting in MongoDB 7.0, 6.3, 6.0.6 (and 5.0.15).\f1 .PP Available for \fBmongod\f1\f1 only. .PP @@ -3632,7 +4506,9 @@ Available for \fBmongod\f1\f1 only. \fIDefault\f1: 1 .PP Specifies an integer that sets the number of threads on the source -shard and the receiving shard for \fBchunk migration\f1\&. +shard and the receiving shard for \fBchunk migration\f1\&. Chunk migrations use the number +of threads that you set on the receiving shard for both the source +and receiving shard. .PP Increasing the concurrency improves chunk migration performance, but also increases the workload and disk IOPS usage on the source @@ -3650,6 +4526,16 @@ If \fBchunkMigrationConcurrency\f1 is greater than \fB1\f1, the proceeds with the next document in the chunk. For details, see \fBRange Migration and Replication\f1\&. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP The following example sets \fBchunkMigrationConcurrency\f1 to \fB5\f1: .PP .EX @@ -3703,8 +4589,8 @@ the shard\(aqs replica set. In the event of a failover, this setting\(aqs value on the new primary dictates the behavior of the range deleter. .PP -You can only set this parameter during start\-up and cannot change -this setting using the \fBsetParameter\f1\f1 database command. +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .PP .EX mongod \-\-setParameter disableResumableRangeDeleter=false @@ -3725,6 +4611,16 @@ consistency check for sharded collections. The parameter has no effect on the \fBmongod\f1\f1 if it is not the config server\(aqs primary. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP The following example sets \fBenableShardedIndexConsistencyCheck\f1\f1 to \fBfalse\f1 for a config server primary: @@ -3773,6 +4669,16 @@ opening of unnecessary connections from \fBmongos\f1\f1 to This parameter should not be enabled unless your application has a specific need for the feature. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP For example, to set \fBopportunisticSecondaryTargeting\f1 during startup: .PP .EX @@ -3794,8 +4700,8 @@ milliseconds, at which the config server\(aqs primary checks the index consistency of sharded collections. The parameter has no effect on the \fBmongod\f1\f1 if it is not the config server\(aqs primary. .PP -You can only set the parameter during startup, and cannot change -this setting using the \fBsetParameter\f1\f1 database command. +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .PP For example, the following sets the interval at 300000 milliseconds (5 minutes) at startup: @@ -3812,6 +4718,29 @@ For example, the following sets the interval at 300000 milliseconds .RE .RE .PP +\fBenableFinerGrainedCatalogCacheRefresh\f1 +.RS +.PP +Available for both \fBmongod\f1\f1 and \fBmongos\f1\f1\&. +.PP +\fIType\f1: boolean +.PP +\fIDefault\f1: true +.PP +This parameter allows the catalog cache to be refreshed only if the +shard needs to be refreshed. If disabled, any stale chunk will cause +the entire chunk distribution for a collection to be considered stale +and force all \fBrouters\f1 who +contact the shard to refresh their shard catalog cache. +.PP +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. +.PP +.EX + mongod \-\-setParameter enableFinerGrainedCatalogCacheRefresh=true + mongos \-\-setParameter enableFinerGrainedCatalogCacheRefresh=true +.EE +.RS .IP \(bu 2 \fBSharding\f1 .IP \(bu 2 @@ -3822,6 +4751,11 @@ For example, the following sets the interval at 300000 milliseconds \fBmaxTimeMSForHedgedReads\f1 .RS .PP +Starting in MongoDB 8.0, hedged reads are deprecated. Queries that +specify the read preference \fBnearest\f1\f1 no longer use hedged +reads by default. If you explicitly specify a hedged read, MongoDB +performs a hedged read and logs a warning. +.PP Available for \fBmongos\f1\f1 only. .PP \fIType\f1: integer @@ -3835,6 +4769,16 @@ of \fBmaxTimeMSForHedgedReads\f1\f1 while the read operation that is being hedged uses the \fBmaxTimeMS\f1 value specified for the operation. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP For example, to set the limit to 200 milliseconds, you can issue the following during startup: .PP @@ -3876,6 +4820,12 @@ it takes for the migration to complete at the cost of increased latency during concurrent \fBupsert\f1\f1 and \fBdelete\f1\f1 operations. .PP +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. +.PP +Starting in MongoDB 7.1 (and 7.0.1), you can set the parameter during +runtime. +.PP For example, to set the maximum percentage to 20, you can issue the following during startup: .PP @@ -3883,8 +4833,13 @@ following during startup: mongod \-\-setParameter maxCatchUpPercentageBeforeBlockingWrites=20 .EE .PP -You cannot change -\fBmaxCatchUpPercentageBeforeBlockingWrites\f1\f1 during run time. +Starting in MongoDB 7.1 (and 7.0.1), you can +set the parameter during runtime with the +\fBsetParameter\f1\f1 command: +.PP +.EX + db.adminCommand( { setParameter: 1, maxCatchUpPercentageBeforeBlockingWrites: 20} ) +.EE .PP Live Migration Protocol (https://github.com/mongodb/mongo/blob/master/src/mongo/db/s/README.md#the\-live\-migration\-protocol) .RE @@ -3922,9 +4877,15 @@ If \fBmetadataRefreshInTransactionMaxWaitBehindCritSecMS\f1\f1 is too low, \fBmongos\f1\f1 could use all of its retry attempts and return an error. .PP -You can set -\fBmetadataRefreshInTransactionMaxWaitBehindCritSecMS\f1\f1 at -startup and during run time. +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE .PP For example, to set \fBmetadataRefreshInTransactionMaxWaitBehindCritSecMS\f1\f1 to 400 milliseconds: @@ -3934,6 +4895,191 @@ to 400 milliseconds: .EE .RE .PP +\fBqueryAnalysisSamplerConfigurationRefreshSecs\f1 +.RS +.PP +Available for both \fBmongod\f1\f1 and \fBmongos\f1\f1\&. +.PP +\fIType\f1: integer +.PP +\fIDefault\f1: 10 +.PP +Interval that a sampler (\fBmongos\f1 or \fBmongod\f1) refreshes its +query analyzer sample rates. +.PP +The sample rate configured by the \fBconfigureQueryAnalyzer\f1 +command is divided among \fBmongos\f1 instances in the sharded cluster +or \fBmongod\f1 instances in the replica set based on the traffic going +through them. To make the sample rate assignment for a \fBmongos\f1 or +\fBmongod\f1 more responsive to the traffic going through it, decrease +this value. +.PP +We recommend using the default value. +.PP +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. +.PP +Starting in MongoDB 7.0.1, you can set +\fBqueryAnalysisSamplerConfigurationRefreshSecs\f1 during run time. +.PP +This example sets \fBqueryAnalysisSamplerConfigurationRefreshSecs\f1 to +60 seconds at startup on a \fBmongod\f1 instance: +.PP +.EX + mongod \-\-setParameter queryAnalysisSamplerConfigurationRefreshSecs=60 +.EE +.PP +This example sets \fBqueryAnalysisSamplerConfigurationRefreshSecs\f1 to +60 seconds at startup on a \fBmongos\f1 instance: +.PP +.EX + mongos \-\-setParameter queryAnalysisSamplerConfigurationRefreshSecs=60 +.EE +.PP +To set the value to 30 seconds, run the following: +.PP +.EX + db.adminCommand( { setParameter: 1, queryAnalysisSamplerConfigurationRefreshSecs: 30 } ) +.EE +.RE +.PP +\fBqueryAnalysisWriterIntervalSecs\f1 +.RS +.PP +Available for \fBmongod\f1\f1 only. +.PP +\fIType\f1: integer +.PP +\fIDefault\f1: 90 +.PP +Interval that sampled queries are written to disk, in seconds. +.PP +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. +.PP +Starting in MongoDB 7.0.1, you can set +\fBqueryAnalysisWriterIntervalSecs\f1 during run time. +.PP +This example sets \fBqueryAnalysisWriterIntervalSecs\f1 to +60 seconds at startup on a \fBmongod\f1 instance: +.PP +.EX + mongod \-\-setParameter queryAnalysisWriterIntervalSecs=60 + To set the value to 60 seconds, run the following: +.EE +.PP +.EX + db.adminCommand( { setParameter: 1, queryAnalysisWriterIntervalSecs: 60 } ) +.EE +.RE +.PP +\fBqueryAnalysisWriterMaxMemoryUsageBytes\f1 +.RS +.PP +Available for \fBmongod\f1\f1 only. +.PP +\fIType\f1: integer +.PP +\fIDefault\f1: 100 * 1024 * 1024 +.PP +Maximum amount of memory in bytes that the query sampling writer is +allowed to use. Once the limit is reached, all new queries and diffs +are discarded from sampling until the buffer is flushed. Must be +greater than \fB0\f1\&. +.PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP +This example sets \fBqueryAnalysisWriterMaxMemoryUsageBytes\f1 to +\fB10000000\f1 at startup on a \fBmongod\f1 instance: +.PP +.EX + mongod \-\-setParameter queryAnalysisWriterMaxMemoryUsageBytes=10000000 +.EE +.RE +.PP +\fBqueryAnalysisWriterMaxBatchSize\f1 +.RS +.PP +Available for \fBmongod\f1\f1 only. +.PP +\fIType\f1: integer +.PP +\fIDefault\f1: 100000 +.PP +Maximum number of sampled queries to write to disk at once. Must be +greater than \fB0\f1 and less than or equal to \fB100000\f1\&. +.PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP +This example sets \fBqueryAnalysisWriterMaxBatchSize\f1 to +\fB1000\f1 at startup on a \fBmongod\f1 instance: +.PP +.EX + mongod \-\-setParameter queryAnalysisWriterMaxBatchSize=1000 +.EE +.PP +During run time, you can also set the parameter with the +\fBsetParameter\f1\f1 command: +.PP +.EX + db.adminCommand( { setParameter: 1, queryAnalysisWriterMaxBatchSize: 1000 } ) +.EE +.RE +.PP +\fBqueryAnalysisSampleExpirationSecs\f1 +.RS +.PP +Available for \fBmongod\f1\f1 only. +.PP +\fIType\f1: integer +.PP +\fIDefault\f1: 7 * 24 * 3600 +.PP +Amount of time that a sampled query document exists before +being removed by the TTL monitor, in seconds. Must be greater +than \fB0\f1\&. +.PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP +This example sets \fBqueryAnalysisSampleExpirationSecs\f1 to +\fB691200\f1 (\fB8 * 24 * 3600\f1) at startup on a \fBmongod\f1 instance: +.PP +.EX + mongod \-\-setParameter queryAnalysisSampleExpirationSecs=691200 +.EE +.PP +During run time, you can also set the parameter with the +\fBsetParameter\f1\f1 command: +.PP +.EX + db.adminCommand( { setParameter: 1, queryAnalysisSampleExpirationSecs: 691200 } ) +.EE +.RE +.PP \fBreadHedgingMode\f1 .RS .PP @@ -3975,6 +5121,16 @@ option. .RE .RE .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP For example, to turn off hedged read support for a \fBmongos\f1\f1 instance, you can issue the following during startup: @@ -3998,6 +5154,29 @@ Or if using the \fBsetParameter\f1\f1 command in a .RE .RE .PP +\fBroutingTableCacheChunkBucketSize\f1 +.RS +.PP +Available for both \fBmongod\f1\f1 and \fBmongos\f1\f1\&. +.PP +\fIType\f1: integer +.PP +\fIDefault\f1: 500 +.PP +Specifies the size of the routing table cache buckets used to +implement chunk grouping optimization. Must be greater than \fB0\f1\&. +.PP +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. +.PP +For example, to set the cache chunk bucket size to \fB250\f1 on a +\fBmongod\f1, issue the following command at startup: +.PP +.EX + mongod \-\-setParameter routingTableCacheChunkBucketSize=250 +.EE +.RE +.PP \fBshutdownTimeoutMillisForSignaledShutdown\f1 .RS .PP @@ -4011,6 +5190,16 @@ Specifies the time (in milliseconds) to wait for any ongoing database operations to complete before initiating a shutdown of \fBmongod\f1\f1 in response to a \fBSIGTERM\f1 signal. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP For example, to set the time to 250 milliseconds, you can issue the following during startup: .PP @@ -4040,6 +5229,16 @@ Specifies the time (in milliseconds) to wait for any ongoing database operations to complete before initiating a shutdown of \fBmongos\f1\f1 in response to a \fBSIGTERM\f1 signal. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP For example, to set the time to 250 milliseconds, you can issue the following during startup: .PP @@ -4076,6 +5275,16 @@ greater than the sum of \fBShardingTaskExecutorPoolHostTimeoutMS\f1\f1 to be greater than the sum. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP The following example sets \fBShardingTaskExecutorPoolHostTimeoutMS\f1\f1 to \fB120000\f1 during startup: @@ -4112,6 +5321,16 @@ less than or equal to \fBShardingTaskExecutorPoolMaxSize\f1\f1\&. If it is greater, \fBmongos\f1\f1 ignores the \fBShardingTaskExecutorPoolMaxConnecting\f1\f1 value. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP The following example sets \fBShardingTaskExecutorPoolMaxConnecting\f1\f1 to \fB20\f1 during startup: @@ -4146,6 +5365,16 @@ is: ShardingTaskExecutorPoolMaxSize * taskExecutorPoolSize .EE .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP The following example sets \fBShardingTaskExecutorPoolMaxSize\f1\f1 to \fB20\f1 during startup: @@ -4198,6 +5427,16 @@ sets the maximum number of outbound connections each TaskExecutor connection pool can open to a configuration server to \fB2\f1: .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP .EX mongos \-\-setParameter ShardingTaskExecutorPoolMaxSizeForConfigServers=2 .EE @@ -4235,9 +5474,15 @@ controls how many connections to each shard host are established on startup of the \fBmongos\f1\f1 instance before it begins accepting incoming client connections. .PP -In MongoDB 4.4, the -\fBwarmMinConnectionsInShardingTaskExecutorPoolOnStartup\f1\f1 -parameter is enabled by default for the \fBmongos\f1\f1\&. +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE .PP The following example sets \fBShardingTaskExecutorPoolMinSize\f1\f1 to \fB2\f1 @@ -4295,6 +5540,16 @@ sets the minimum number of outbound connections each TaskExecutor connection pool can open to a configuration server to \fB2\f1: .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP .EX mongos \-\-setParameter ShardingTaskExecutorPoolMinSizeForConfigServers=2 .EE @@ -4317,7 +5572,7 @@ Type: integer Default: 60000 (1 minute) .PP Maximum time the \fBmongos\f1\f1 waits before attempting to -heartbeat a resting connection in the pool. An idle connection may be +heartbeat an idle connection in the pool. An idle connection may be discarded during the refresh if the pool is above its \fBminimum size\f1\&. .PP @@ -4327,6 +5582,16 @@ Otherwise, \fBmongos\f1\f1 adjusts the value of \fBShardingTaskExecutorPoolRefreshTimeoutMS\f1\f1 to be less than \fBShardingTaskExecutorPoolRefreshRequirementMS\f1\f1\&. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP The following example sets \fBShardingTaskExecutorPoolRefreshRequirementMS\f1\f1 to \fB90000\f1 during startup: @@ -4361,6 +5626,16 @@ Otherwise, \fBmongos\f1\f1 adjusts the value of \fBShardingTaskExecutorPoolRefreshTimeoutMS\f1\f1 to be less than \fBShardingTaskExecutorPoolRefreshRequirementMS\f1\f1\&. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP The following example sets \fBShardingTaskExecutorPoolRefreshTimeoutMS\f1\f1 to \fB30000\f1 during startup: @@ -4411,8 +5686,7 @@ Description .IP \(bu 4 \fB"automatic"\f1 (Default) .IP \(bu 4 -Starting in 5.0 (and 4.4.5 and 4.2.13), \fB"automatic"\f1 is the -new default value. +Starting in 5.0, \fB"automatic"\f1 is the new default value. .IP When set for a \fBmongos\f1\f1, the instance follows the behavior specified for the \fB"matchPrimaryNode"\f1 option. @@ -4499,6 +5773,16 @@ to the \fBShardingTaskExecutorPoolMinSize\f1\f1\&. .RE .RE .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP The following example sets the \fBShardingTaskExecutorPoolReplicaSetMatching\f1\f1 to \fB"automatic"\f1 during startup: @@ -4544,12 +5828,16 @@ When running MongoDB 6.2 or newer on Linux, you cannot modify the You may modify this parameter when running MongoDB on Windows or macOS. .PP The default value of \fBtaskExecutorPoolSize\f1\f1 is \fB1\f1: -In MongoDB 4.2+ deployments, MongoDB removes the -\fBAsyncRequestsSenderUseBaton\f1 parameter and always enables the -performance enhancement controlled by the parameter. .PP -You can only set this parameter during start\-up and cannot change -this setting using the \fBsetParameter\f1\f1 database command. +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE .PP .EX mongos \-\-setParameter taskExecutorPoolSize=6 @@ -4589,9 +5877,8 @@ of initial client connections once started. .PP \fBloadRoutingTableOnStartup\f1\f1 is enabled by default. .PP -You can only set this parameter on startup, using either the -\fBsetParameter\f1\f1 configuration file setting or the -\fB\-\-setParameter\f1\f1 command line option. +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .RE .PP \fBwarmMinConnectionsInShardingTaskExecutorPoolOnStartup\f1 @@ -4623,9 +5910,8 @@ of initial client connections once started. \fBwarmMinConnectionsInShardingTaskExecutorPoolOnStartup\f1\f1 is enabled by default. .PP -You can only set this parameter on startup, using either the -\fBsetParameter\f1\f1 configuration file setting or the -\fB\-\-setParameter\f1\f1 command line option. +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .RS .IP \(bu 2 \fBwarmMinConnectionsInShardingTaskExecutorPoolOnStartupWaitMS\f1\f1 @@ -4651,9 +5937,8 @@ parameter. If this timeout is reached, the \fBmongos\f1\f1 will begin accepting client connections regardless of the size of its connection pool. .PP -You can only set this parameter on startup, using either the -\fBsetParameter\f1\f1 configuration file setting or the -\fB\-\-setParameter\f1\f1 command line option. +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .RS .IP \(bu 2 \fBwarmMinConnectionsInShardingTaskExecutorPoolOnStartup\f1\f1 @@ -4677,6 +5962,16 @@ the \fBsecondaryThrottle\f1\&. .PP The default value of \fB0\f1 indicates no additional wait. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP The following sets the \fBmigrateCloneInsertionBatchDelayMS\f1\f1 to 200 milliseconds: .PP @@ -4708,6 +6003,16 @@ The default value of \fB0\f1 indicates no maximum number of documents per batch. However, in practice, this results in batches that contain up to 16 MB of documents. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP The following sets the \fBmigrateCloneInsertionBatchSize\f1\f1 to 100 documents: .PP @@ -4752,6 +6057,16 @@ If a shard has storage constraints, consider reducing this value temporarily. If running queries that exceed 15 minutes on shard secondaries, consider increasing this value. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP The following sets the \fBorphanCleanupDelaySecs\f1\f1 to 20 minutes: .PP .EX @@ -4763,6 +6078,61 @@ This may also be set using the \fBsetParameter\f1\f1 command: .EX db.adminCommand( { setParameter: 1, orphanCleanupDelaySecs: 1200 } ) .EE +.PP +In all versions, the new value of \fBorphanCleanupDelaySecs\f1\f1 is +only applied to range deletions created after the value is changed. To +apply the new value to existing range deletions, \fBforce a step down\f1\&. +.RE +.PP +\fBpersistedChunkCacheUpdateMaxBatchSize\f1 +.RS +.PP +Available for \fBmongod\f1\f1 only. +.PP +Type: Integer +.PP +Default: 1000 +.PP +To route and serve operations, shards must know the routing and +ownership information associated with their collections. This +information propogates from a shard\(aqs primary node to its +secondary nodes through the replication of the internal cache +collections \fBconfig.cache.collections\f1 and +\fBconfig.cache.chunks.\f1\&. +.PP +In previous versions, updates on the chunk cache collection were +performed individually (meaning that an entry was deleted and a new +entry was inserted). Starting in MongoDB 7.2, these updates are +performed as a batch of deletions followed by a batch of insertions. +The updated logic improves performance for collections that contain a +large number of chunks. +.PP +The \fBpersistedChunkCacheUpdateMaxBatchSize\f1 parameter specifies the +maximum batch size used for updating the persisted chunk cache. +.PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP +The following example sets \fBpersistedChunkCacheUpdateMaxBatchSize\f1 +to 700 at startup: +.PP +.EX + mongod \-\-setParameter persistedChunkCacheUpdateMaxBatchSize=700 +.EE +.PP +You can also set \fBpersistedChunkCacheUpdateMaxBatchSize\f1 during +runtime: +.PP +.EX + db.adminCommand( { setParameter: 1, persistedChunkCacheUpdateMaxBatchSize: 700 } ) +.EE .RE .PP \fBrangeDeleterBatchDelayMS\f1 @@ -4780,6 +6150,16 @@ command). .PP The \fB_secondaryThrottle replication delay\f1 occurs after each batch deletion. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP The following sets the \fBrangeDeleterBatchDelayMS\f1\f1 to 200 milliseconds: .PP @@ -4793,6 +6173,13 @@ command: .EX db.adminCommand( { setParameter: 1, rangeDeleterBatchDelayMS: 200 } ) .EE +.PP +In versions prior to 6.0.3, the new value of \fBrangeDeleterBatchDelayMS\f1\f1 is +only applied to range deletions created after the value is changed. To +apply the new value to existing range deletions, \fBforce a step down\f1\&. +.PP +From 6.0.3 on, the new value of the parameter is applied to all the range deletions processed +after the update, regardless of when the range deletion was created. .RE .PP \fBrangeDeleterBatchSize\f1 @@ -4802,8 +6189,7 @@ Available for \fBmongod\f1\f1 only. .PP Type: Non\-negative integer .PP -Default: 2147483647 starting in MongoDB 5.1.2, 5.0.6, and 4.4.12 (128 -in earlier MongoDB versions) +Default: 2147483647 starting in MongoDB 5.1.2 and 5.0.6 .PP The maximum number of documents in each batch to delete during the cleanup stage of \fBrange migration\f1 @@ -4811,6 +6197,16 @@ cleanup stage of \fBrange migration\f1 .PP A value of \fB0\f1 indicates that the system chooses the default value. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP The following example sets \fBrangeDeleterBatchSize\f1\f1 to 32 documents: .PP @@ -4824,6 +6220,51 @@ command: .EX db.adminCommand( { setParameter: 1, rangeDeleterBatchSize: 32 } ) .EE +.PP +In versions prior to 6.0.3, the new value of \fBrangeDeleterBatchSize\f1\f1 is +only applied to range deletions created after the value is changed. To +apply the new value to existing range deletions, \fBforce a step down\f1\&. +.PP +From 6.0.3 on, the new value of the parameter is applied to all the range deletions processed +after the update, regardless of when the range deletion was created. +.RE +.PP +\fBrangeDeleterHighPriority\f1 +.RS +.PP +Available for \fBmongod\f1\f1 only. +.PP +Type: boolean +.PP +Default: false +.PP +When \fBtrue\f1, prioritizes cleanup of \fBorphaned documents\f1 over user operations. By default, this is set to +\fBfalse\f1 to prioritize user operations over cleanup of orphaned +documents. +.PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP +The following example sets \fBrangeDeleterHighPriority\f1\f1 to +\fBtrue\f1: +.PP +.EX + mongod \-\-setParameter rangeDeleterHighPriority=true +.EE +.PP +The parameter may also be set using the \fBsetParameter\f1\f1 +command: +.PP +.EX + db.adminCommand( { setParameter: 1, rangeDeleterBatchSize: true } ) +.EE .RE .PP \fBskipShardingConfigurationChecks\f1 @@ -4839,8 +6280,8 @@ When \fBtrue\f1, allows for starting a shard member or config server member as a standalone for maintenance operations. This parameter is mutually exclusive with the \fB\-\-configsvr\f1\f1 or \fB\-\-shardsvr\f1\f1 options. .PP -You can only set this parameter during start\-up and cannot change -this setting using the \fBsetParameter\f1\f1 database command. +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .PP .EX mongod \-\-setParameter skipShardingConfigurationChecks=true @@ -4870,6 +6311,16 @@ value: .EX mongod \-\-setParameter findChunksOnConfigTimeoutMS=1000000 .EE +.PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE .RE .SS HEALTH MANAGER PARAMETERS .PP @@ -4887,6 +6338,16 @@ When a failure is detected and a Health Manager is configured as \fBcritical\f1, the server waits for the specified interval before removing the \fBmongos\f1 from the cluster. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP For example, to set the duration from failure to crash to five minutes, issue the following at startup: .PP @@ -4929,6 +6390,16 @@ Available for \fBmongos\f1\f1 only. .PP Use this parameter to set intensity levels for Health Managers\&. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP \fBhealthMonitoringIntensities\f1 accepts an array of documents, \fBvalues\f1\&. Each document in \fBvalues\f1 takes two fields: .RS @@ -5049,6 +6520,16 @@ Available for \fBmongos\f1\f1 only. .PP How often this Health Manager will run, in milliseconds. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP \fBhealthMonitoringIntervals\f1 accepts an array of documents, \fBvalues\f1\&. Each document in \fBvalues\f1 takes two fields: .RS @@ -5135,6 +6616,16 @@ unresponsive. Progress Monitor runs these tests in intervals specified by \fBinterval\f1\&. If a health check begins but does not complete within the timeout given by \fBdeadline\f1, Progress Monitor stops the \fBmongos\f1 and removes it from the cluster. +.PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE .SS PROGRESSMONITOR FIELDS .RS .IP \(bu 2 @@ -5220,8 +6711,8 @@ permissions set to \fB700\f1\&. You can use \fBprocessUmask\f1\f1 to override the default permissions for groups and other users on all new files created by MongoDB. .PP -You can only set this parameter during start\-up and cannot change -this setting using the \fBsetParameter\f1\f1 database command. +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. .PP .EX mongod \-\-setParameter honorSystemUmask=true @@ -5238,6 +6729,16 @@ Available for \fBmongod\f1\f1 only. Specify an integer between \fB1\f1 and \fB500\f1 signifying the number of milliseconds (ms) between journal commits. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP Consider the following example which sets the \fBjournalCommitInterval\f1\f1 to \fB200\f1 ms: .PP @@ -5262,6 +6763,16 @@ the snapshot history. If you query data using read concern \fBminSnapshotHistoryWindowInSeconds\f1, \fBmongod\f1\f1 returns a \fBSnapshotTooOld\f1 error. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP Specify an integer greater than or equal to (\fB>=\f1) 0. .PP Consider the following example which sets the @@ -5292,10 +6803,11 @@ created by MongoDB have permissions set to \fB600\f1\&. Use the \fBumask\f1 value. The file owner inherits permissions from the system \fBumask\f1\&. .PP +This parameter is only available at startup. To set the +parameter, use the \fBsetParameter\f1\f1 setting. +.PP You cannot set this parameter if \fBhonorSystemUmask\f1\f1 is set -to \fBtrue\f1\&. You can only set this parameter during start\-up and cannot -change this setting using the \fBsetParameter\f1\f1 database -command. +to \fBtrue\f1\&. .PP Consider the following example, which sets the permissions for groups and other users to read/write only and retains the system \fBumask\f1 @@ -5308,23 +6820,130 @@ settings for the owner: \fBprocessUmask\f1\f1 is not available on Windows systems. .RE .PP +\fBstorageEngineConcurrentReadTransactions\f1 +.RS +.PP +Available for \fBmongod\f1\f1 only. +.PP +\fIType\f1: integer +.PP +\fIDefault\f1: 128 +.PP +Starting in MongoDB 7.0, this parameter is available for all storage +engines. In earlier versions, this parameter is available for the +WiredTiger storage engine only. +.PP +Specify the maximum number of concurrent read transactions (read tickets) +allowed into the storage engine. +.PP +If you use the default value, MongoDB dynamically adjusts the number of tickets +to optimize performance, with a highest possible value of 128. +.PP +Starting in MongoDB 7.0, if you set \fBstorageEngineConcurrentReadTransactions\f1 to a non\-default value, it +disables an algorithm that dynamically adjusts the number of concurrent storage +engine transactions. +.PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP +.EX + db.adminCommand( { setParameter: 1, storageEngineConcurrentReadTransactions: } ) +.EE +.PP +The \fBwiredTigerConcurrentReadTransactions\f1 parameter was renamed to +\fBstorageEngineConcurrentReadTransactions\f1\&. +.PP +\fBwiredTiger.concurrentTransactions\f1\f1 +.RE +.PP +\fBstorageEngineConcurrentWriteTransactions\f1 +.RS +.PP +Available for \fBmongod\f1\f1 only. +.PP +\fIType\f1: integer +.PP +Starting in MongoDB 7.0, this parameter is available for all storage +engines. In earlier versions, this parameter is available for the +WiredTiger storage engine only. +.PP +Specify the maximum number of concurrent write transactions allowed +into the WiredTiger storage engine. +.PP +By default, MongoDB sets \fBstorageEngineConcurrentWriteTransactions\f1 to +whichever value is higher: +.RS +.IP \(bu 2 +Number of cores on the machine running MongoDB +.IP \(bu 2 +4 +.RE +.PP +If you use the default value, MongoDB dynamically adjusts the number of tickets +to optimize performance, with a highest possible value of 128. +.PP +Starting in MongoDB 7.0, if you set \fBstorageEngineConcurrentWriteTransactions\f1 to a non\-default value, it +disables an algorithm that dynamically adjusts the number of concurrent storage +engine transactions. +.PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP +.EX + db.adminCommand( { setParameter: 1, storageEngineConcurrentWriteTransactions: } ) +.EE +.PP +The \fBwiredTigerConcurrentWriteTransactions\f1 parameter was renamed to +\fBstorageEngineConcurrentWriteTransactions\f1\&. +.PP +\fBwiredTiger.concurrentTransactions\f1\f1 +.RE +.PP \fBsyncdelay\f1 .RS .PP Available for \fBmongod\f1\f1 only. .PP -Specify the interval in seconds between \fBfsync\f1 operations -where \fBmongod\f1\f1 flushes its working memory to disk. By +Specify the interval in seconds when +\fBmongod\f1\f1 flushes its working memory to disk. By default, \fBmongod\f1\f1 flushes memory to disk every 60 seconds. In almost every situation you should not set this value and use the default setting. .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP Consider the following example which sets the \fBsyncdelay\f1 to \fB60\f1 seconds: .PP .EX db.adminCommand( { setParameter: 1, syncdelay: 60 } ) .EE +.PP +To provide \fBdurable\f1 data, \fBWiredTiger\f1 +uses \fBcheckpoints\f1\&. For more +details, see \fBJournaling and the WiredTiger Storage Engine\f1\&. .RS .IP \(bu 2 \fBjournalCommitInterval\f1\f1 @@ -5344,7 +6963,7 @@ rolled back due to cache pressure. In rare circumstances, a write can fail due to cache pressure. When this happens MongoDB issues a \fBTemporarilyUnavailable\f1 error and increments the \fBtemporarilyUnavailableErrors\f1 counter in two places: -the slow query log and the \fBFull Time Diagnostic Data Collection +the slow query log and the \fBFull Time Diagnostic Data Capture (FTDC)\f1\&. .PP Individual operations within multi\-document transactions never return @@ -5378,6 +6997,16 @@ To configure number of retries, use .RE .RE .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP To set a new value, use \fBdb.adminCommand()\f1\f1: .PP .EX @@ -5396,7 +7025,7 @@ rolled back due to cache pressure. In rare circumstances, a write can fail due to cache pressure. When this happens MongoDB issues a \fBTemporarilyUnavailable\f1 error and increments the \fBtemporarilyUnavailableErrors\f1 counter in two places: -the slow query log and the \fBFull Time Diagnostic Data Collection +the slow query log and the \fBFull Time Diagnostic Data Capture (FTDC)\f1\&. .PP Individual operations within multi\-document transactions never return @@ -5428,6 +7057,16 @@ the backoff time, use .RE .RE .PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP To set a new value, use \fBdb.adminCommand()\f1\f1: .PP .EX @@ -5436,74 +7075,41 @@ To set a new value, use \fBdb.adminCommand()\f1\f1: .RE .SS WIREDTIGER PARAMETERS .PP -\fBwiredTigerMaxCacheOverflowSizeGB\f1 -.RS -.PP -MongoDB deprecates the \fBwiredTigerMaxCacheOverflowSizeGB\f1 -parameter. The parameter has no effect starting in MongoDB 4.4. -.PP -Available for \fBmongod\f1\f1 only. -.PP -\fIDefault\f1: 0 (No specified maximum) -.PP -Specify the maximum size (in GB) for the "lookaside (or cache -overflow) table" file WiredTigerLAS.wt for MongoDB -4.2.1\-4.2.x. The file no longer exists starting in -version 4.4. -.PP -The parameter can accept the following values: -.RS -.IP \(bu 2 -.RS -.IP \(bu 4 -Value -.IP \(bu 4 -Description -.RE -.IP \(bu 2 -.RS -.IP \(bu 4 -\fB0\f1 -.IP \(bu 4 -The default value. If set to \fB0\f1, the file size is -unbounded. -.RE -.IP \(bu 2 -.RS -.IP \(bu 4 -number >= 0.1 -.IP \(bu 4 -The maximum size (in GB). If the WiredTigerLAS.wt -file exceeds this size, \fBmongod\f1\f1 exits with a -fatal assertion. You can clear the WiredTigerLAS.wt -file and restart \fBmongod\f1\f1\&. -.RE -.RE -.PP -You can only set this parameter during run time using the -\fBsetParameter\f1\f1 database command: -.PP -.EX - db.adminCommand( { setParameter: 1, wiredTigerMaxCacheOverflowSizeGB: 100 } ) -.EE -.PP -To set the maximum size during start up, use the -\fBstorage.wiredTiger.engineConfig.maxCacheOverflowFileSizeGB\f1\f1 -instead. -.RE -.PP \fBwiredTigerConcurrentReadTransactions\f1 .RS .PP Available for \fBmongod\f1\f1 only. .PP -Available for the WiredTiger storage engine only. +\fIType\f1: integer .PP -Specify the maximum number of concurrent read transactions allowed -into the WiredTiger storage engine. +\fIDefault\f1: 128 +.PP +Starting in MongoDB 7.0, this parameter is available for all storage +engines. In earlier versions, this parameter is available for the +WiredTiger storage engine only. +.PP +Specify the maximum number of concurrent read transactions (read tickets) +allowed into the storage engine. +.PP +If you use the default value, MongoDB dynamically adjusts the number of tickets +to optimize performance, with a highest possible value of 128. +.PP +Starting in MongoDB 7.0, if you set \fBwiredTigerConcurrentReadTransactions\f1 to a non\-default value, it +disables an algorithm that dynamically adjusts the number of concurrent storage +engine transactions. +.PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE .PP .EX - db.adminCommand( { setParameter: 1, wiredTigerConcurrentReadTransactions: } ) + db.adminCommand( { setParameter: 1, wiredTigerConcurrentReadTransactions: } ) .EE .PP \fBwiredTiger.concurrentTransactions\f1\f1 @@ -5514,13 +7120,43 @@ into the WiredTiger storage engine. .PP Available for \fBmongod\f1\f1 only. .PP -Available for the WiredTiger storage engine only. +\fIType\f1: integer +.PP +Starting in MongoDB 7.0, this parameter is available for all storage +engines. In earlier versions, this parameter is available for the +WiredTiger storage engine only. .PP Specify the maximum number of concurrent write transactions allowed into the WiredTiger storage engine. .PP +By default, MongoDB sets \fBwiredTigerConcurrentWriteTransactions\f1 to +whichever value is higher: +.RS +.IP \(bu 2 +Number of cores on the machine running MongoDB +.IP \(bu 2 +4 +.RE +.PP +If you use the default value, MongoDB dynamically adjusts the number of tickets +to optimize performance, with a highest possible value of 128. +.PP +Starting in MongoDB 7.0, if you set \fBwiredTigerConcurrentWriteTransactions\f1 to a non\-default value, it +disables an algorithm that dynamically adjusts the number of concurrent storage +engine transactions. +.PP +This parameter is available both at runtime and at startup: +.RS +.IP \(bu 2 +To set the parameter at runtime, use the +\fBsetParameter\f1\f1 command +.IP \(bu 2 +To set the parameter at startup, use the +\fBsetParameter\f1\f1 setting +.RE +.PP .EX - db.adminCommand( { setParameter: 1, wiredTigerConcurrentWriteTransactions: } ) + db.adminCommand( { setParameter: 1, wiredTigerConcurrentWriteTransactions: } ) .EE .PP \fBwiredTiger.concurrentTransactions\f1\f1 @@ -5532,9 +7168,10 @@ into the WiredTiger storage engine. Available for \fBmongod\f1\f1 only. .PP Specify \fBwiredTiger\f1 storage engine configuration options for a -running \fBmongod\f1\f1 instance. You can \fIonly\f1 set this -parameter using the \fBsetParameter\f1\f1 command and \fInot\f1 -using the command line or configuration file option. +running \fBmongod\f1\f1 instance. +.PP +This parameter is only available at runtime. To set the +parameter, use the \fBsetParameter\f1\f1 command. .PP Avoid modifying the \fBwiredTigerEngineRuntimeConfig\f1\f1 unless under the direction from MongoDB engineers as this setting has @@ -5548,10 +7185,35 @@ Consider the following operation prototype: "wiredTigerEngineRuntimeConfig": "