Navigation
This version of the documentation is archived and no longer supported.

MongoDB Server Parameters

Synopsis

MongoDB provides a number of configuration options that you can set using:

  • the setParameter command:

    db.adminCommand( { setParameter: 1, <parameter>: <value>  } )
    
  • the setParameter configuration setting:

    setParameter:
       <parameter1>: <value1>
       ...
    
  • the --setParameter command-line option for mongod and mongos:

    mongod --setParameter <parameter>=<value>
    mongos --setParameter <parameter>=<value>
    

For additional configuration options, see Configuration File Options, mongod and mongos.

Parameters

Authentication Parameters

authenticationMechanisms

Changed in version 2.6: Added support for the PLAIN and MONGODB-X509 authentication mechanisms.

Changed in version 3.0: Added support for the SCRAM-SHA-1 authentication mechanism.

Available for both mongod and mongos.

Specifies the list of authentication mechanisms the server accepts. Set this to one or more of the following values. If you specify multiple values, use a comma-separated list and no spaces. For descriptions of the authentication mechanisms, see Authentication.

Value Description
SCRAM-SHA-1 RFC 5802 standard Salted Challenge Response Authentication Mechanism using the SHA-1 hash function.
MONGODB-CR MongoDB challenge/response authentication. (Deprecated in MongoDB 3.6)
MONGODB-X509 MongoDB TLS/SSL certificate authentication.
GSSAPI (Kerberos) External authentication using Kerberos. This mechanism is available only in MongoDB Enterprise.
PLAIN (LDAP SASL) PLAIN transmits passwords in plain text. Required for LDAP Proxy Authentication. Optional for authenticating non-$external users.

For example, to specify PLAIN as the authentication mechanism, use the following command:

mongod --setParameter authenticationMechanisms=PLAIN --auth
clusterAuthMode

New in version 2.6.

Available for both mongod and mongos.

Set the clusterAuthMode to either sendX509 or x509. Useful during rolling upgrade to use x509 for membership authentication to minimize downtime.

For more information about TLS/SSL and MongoDB, see Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients .

db.adminCommand( { setParameter: 1, clusterAuthMode: "sendX509" } )
enableLocalhostAuthBypass

Available for both mongod and mongos.

Specify 0 or false to disable localhost authentication bypass. Enabled by default.

enableLocalhostAuthBypass is not available using setParameter database command. Use the setParameter option in the configuration file or the --setParameter option on the command line.

See Localhost Exception for more information.

KeysRotationIntervalSec

New in version 3.6.

Default: 7776000 seconds (90 days)

Specifies the number of seconds for which an HMAC signing key is valid before rotating to the next one. This parameter is intended primarily to facilitate authentication testing.

You can only set KeysRotationIntervalSec during start-up, and cannot change this setting with the setParameter database command.

ldapUserCacheInvalidationInterval

For use with MongoDB deployments using LDAP Authorization. Available for mongod instances only.

The interval (in seconds) that the mongod instance waits between external user cache flushes. After MongoDB flushes the external user cache, MongoDB reacquires authorization data from the LDAP server the next time an LDAP-authorized user issues an operation.

Increasing the value specified increases the amount of time MongoDB and the LDAP server can be out of sync, but reduces the load on the LDAP server. Conversely, decreasing the value specified decreases the time MongoDB and the LDAP server can be out of sync while increasing the load on the LDAP server.

Defaults to 30 seconds.

opensslCipherConfig

New in version 3.6.

Specify the cipher string for OpenSSL when using TLS/SSL encryption. For a list of cipher strings, see https://www.openssl.org/docs/man1.0.2/apps/ciphers.html#CIPHER-STRINGS

You can only set opensslCipherConfig during start-up, and cannot change this setting using the setParameter database command.

mongod --setParameter opensslCipherConfig=HIGH:!EXPORT:!aNULL@STRENGTH --sslMode requireSSL --sslPEMKeyFile Certs/server.pem
saslauthdPath

Note

Available only in MongoDB Enterprise (except MongoDB Enterprise for Windows).

Available for both mongod and mongos.

Specify the path to the Unix Domain Socket of the saslauthd instance to use for proxy authentication.

saslHostName

Available for both mongod and mongos.

saslHostName overrides MongoDB’s default hostname detection for the purpose of configuring SASL and Kerberos authentication.

saslHostName does not affect the hostname of the mongod or mongos instance for any purpose beyond the configuration of SASL and Kerberos.

You can only set saslHostName during start-up, and cannot change this setting using the setParameter database command.

Note

saslHostName supports Kerberos authentication and is only included in MongoDB Enterprise. For Linux systems, see Configure MongoDB with Kerberos Authentication on Linux for more information.

saslServiceName

Available for both mongod and mongos.

Allows users to override the default Kerberos service name component of the Kerberos principal name, on a per-instance basis. If unspecified, the default value is mongodb.

MongoDB only permits setting saslServiceName at startup. The setParameter command can not change this setting.

saslServiceName is only available in MongoDB Enterprise.

Important

Ensure that your driver supports alternate service names.

scramIterationCount

New in version 3.0.0.

Default: 10000

Available for both mongod and mongos.

Changes the number of hashing iterations used for all new stored passwords. More iterations increase the amount of time required for clients to authenticate to MongoDB, but makes passwords less susceptible to brute-force attempts. The default value is ideal for most common use cases and requirements. If you modify this value, it does not change the number of iterations for existing passwords.

You can set scramIterationCount when starting MongoDB or on running mongod instances.

sslMode

New in version 2.6.

Available for both mongod and mongos.

Set the net.ssl.mode to either preferSSL or requireSSL. Useful during rolling upgrade to TLS/SSL to minimize downtime.

For more information about TLS/SSL and MongoDB, see Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients .

db.adminCommand( { setParameter: 1, sslMode: "preferSSL" } )
sslWithholdClientCertificate

Default: false

New in version 3.6.9.

Available for both mongod and mongos.

A TLS certificate is set for a mongod or mongos either by the --sslClusterFile option or by the --sslPEMKeyFile option when --sslClusterFile is not set. If the TLS certificate is set, by default, the instance sends the certificate when initiating intra-cluster communications with other mongod or mongos instances in the deployment. Set sslWithholdClientCertificate to 1 or true to direct the instance to withhold sending its TLS certificate during these communications. Use this option with --sslAllowConnectionsWithoutCertificates (to allow inbound connections without certificates) on all members of the deployment. sslWithholdClientCertificate is mutually exclusive with --clusterAuthMode x509.

userCacheInvalidationIntervalSecs

Default: 30

Available for mongos only.

On a mongos instance, specifies the interval (in seconds) at which the mongos instance checks to determine whether the in-memory cache of user objects has stale data, and if so, clears the cache. If there are no changes to user objects, mongos will not clear the cache.

This parameter has a minimum value of 1 second and a maximum value of 86400 seconds (24 hours).

Changed in version 3.0: Default value has changed to 30 seconds, and the minimum value allowed has changed to 1 second. mongos only clears the user cache if there are changes.

authFailedDelayMs

Default: 0

Available for both mongod and mongos.

New in version 3.4.

Enterprise Feature

Available in MongoDB Enterprise only.

The number of milliseconds to wait before informing clients that their authentication attempt has failed. This parameter may be in the range 0 to 5000, inclusive.

Setting this parameter makes brute-force login attacks on a database more time-consuming. However, clients waiting for a response from the MongoDB server still consume server resources, and this may adversely impact benign login attempts if the server is denying access to many other clients simultaneously.

allowRolesFromX509Certificates

Default: true

Available for both mongod and mongos.

Available starting in MongoDB 3.6.14 (and 3.4.22)

A boolean flag that allows or disallows the retrieval of authorization roles from client x.509 certificates.

You can only set allowRolesFromX509Certificates during startup in the config file or on the command line.

General Parameters

connPoolMaxShardedConnsPerHost

New in version 2.6.

Default: 200

Available for both mongod and mongos.

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 does prevent the connection pools from retaining connections above this limit.

Note

The parameter is separate from the connections in TaskExecutor pools. See ShardingTaskExecutorPoolMaxSize.

Increase the connPoolMaxShardedConnsPerHost value only if the number of connections in a connection pool has a high level of churn or if the total number of created connections increase.

You can only set connPoolMaxShardedConnsPerHost during startup in the config file or on the command line. For example:

mongos --setParameter connPoolMaxShardedConnsPerHost=250
connPoolMaxShardedInUseConnsPerHost

New in version 3.6.3.

Available for both mongod and mongos.

Sets the maximum number of in-use connections at any given time for the legacy sharded cluster connection pools.

By default, the parameter is unset.

You can only set connPoolMaxShardedConnsPerHost during startup in the config file or on the command line. For example:

mongos --setParameter connPoolMaxShardedInUseConnsPerHost=100
shardedConnPoolIdleTimeoutMinutes

New in version 3.6.3.

Available for both mongod and mongos.

Sets the time limit that a connection in the legacy sharded cluster connection pool can remain idle before being closed.

By default, the parameter is unset.

You can only set shardedConnPoolIdleTimeoutMinutes during startup in the config file or on the command line. For example:

mongos --setParameter shardedConnPoolIdleTimeoutMinutes=10
connPoolMaxConnsPerHost

New in version 2.6.

Default: 200

Available for both mongod and mongos.

Sets the maximum size of the legacy connection pools for outgoing connections to other mongod instances. The size of a pool does not prevent the creation of additional connections, but does prevent a connection pool from retaining connections in excess of the value of connPoolMaxConnsPerHost.

Note

The parameter is separate from the connections in TaskExecutor pools. See ShardingTaskExecutorPoolMaxSize.

Only adjust this setting if your driver does not pool connections and you’re using authentication in the context of a sharded cluster.

You can only set connPoolMaxConnsPerHost during startup in the config file or on the command line. For example:

mongod --setParameter connPoolMaxConnsPerHost=250
connPoolMaxInUseConnsPerHost

New in version 3.6.3.

Available for both mongod and mongos.

Sets the maximum number of in-use connections at any given time for for outgoing connections to other mongod instances in the legacy global connection pool.

By default, the parameter is unset.

You can only set connPoolMaxInUseConnsPerHost during startup in the config file or on the command line. For example:

mongod --setParameter connPoolMaxInUseConnsPerHost=100
globalConnPoolIdleTimeoutMinutes

New in version 3.6.3.

Available for both mongod and mongos.

Sets the time limit that connection in the legacy global connection pool can remain idle before being closed.

By default, the parameter is unset.

You can only set globalConnPoolIdleTimeoutMinutes during startup in the config file or on the command line. For example:

mongos --setParameter globalConnPoolIdleTimeoutMinutes=10
cursorTimeoutMillis

New in version 3.0.2.

Default: 600000 (i.e. 10 minutes)

Available for both mongod and mongos.

Sets the expiration threshold in milliseconds for idle cursors before MongoDB removes them; i.e. MongoDB removes cursors that have been idle for the specified cursorTimeoutMillis.

For example, the following sets the cursorTimeoutMillis to 300000 milliseconds (i.e. 5 minutes).

mongod --setParameter cursorTimeoutMillis=300000

Or, if using the setParameter command within the mongo shell:

db.adminCommand( { setParameter: 1, cursorTimeoutMillis: 300000 } )

Setting cursorTimeoutMillis to less than or equal to 0 results in all cursors being immediately eligible for timeout. Generally, the timeout value should be greater than the average amount of time for a query to return results. Use tools like the cursor.explain() cursor modifier to analyze the average query time and select an appropriate timeout period.

failIndexKeyTooLong

New in version 2.6.

Available for mongod only.

In MongoDB 2.6, if you attempt to insert or update a document so that the value of an indexed field is longer than the Index Key Length Limit, the operation will fail and return an error to the client. In previous versions of MongoDB, these operations would successfully insert or modify a document but the index or indexes would not include references to the document.

To avoid this issue, consider using hashed indexes or indexing a computed value. If you have an existing data set and want to disable this behavior so you can upgrade and then gradually resolve these indexing issues, you can use failIndexKeyTooLong to disable this behavior.

failIndexKeyTooLong defaults to true. When false, a 2.6 mongod instance will provide the 2.4 behavior.

Issue the following command to disable the index key length validation:

db.adminCommand( { setParameter: 1, failIndexKeyTooLong: false } )

You can also set failIndexKeyTooLong at startup time with the following option:

mongod --setParameter failIndexKeyTooLong=false
newCollectionsUsePowerOf2Sizes

Deprecated since version 3.0.0: MongoDB deprecates the newCollectionsUsePowerOf2Sizes parameter such that you cannot set the newCollectionsUsePowerOf2Sizes to false and newCollectionsUsePowerOf2Sizes set to true is a no-op. To disable the power of 2 allocation for a collection, use the collMod command with the noPadding flag or the db.createCollection() method with the noPadding option.

Default: true.

Available for mongod only.

Available for the MMAPv1 storage engine only.

notablescan

Available for mongod only.

Specify whether all queries must use indexes. If 1, MongoDB will not execute queries that require a collection scan and will return an error.

Consider the following example which sets notablescan to 1 or true:

db.adminCommand( { setParameter: 1, notablescan: 1 } )

Setting notablescan to 1 can be useful for testing application queries, for example, to identify queries that scan an entire collection and cannot use an index.

To detect unindexed queries without notablescan, consider reading the Evaluate Performance of Current Operations and Optimize Query Performance sections and using the logLevel parameter, mongostat and profiling.

Don’t run production mongod instances with notablescan because preventing collection scans can potentially affect queries in all databases, including administrative queries.

ttlMonitorEnabled

Available for mongod only.

Default: true

To support TTL Indexes, mongod instances have a background thread that is responsible for deleting documents from collections with TTL indexes.

To disable this worker thread for a mongod, set ttlMonitorEnabled to false, as in the following operations:

db.adminCommand( { setParameter: 1, ttlMonitorEnabled: false } )

Alternately, you may disable the thread at startup time by starting the mongod instance with the following option:

mongod --setParameter ttlMonitorEnabled=false

Important

Do not run production mongod instances with ttlMonitorEnabled disabled, except under guidance from MongoDB support. Preventing TTL document removal can negatively impact MongoDB internal system operations that depend on TTL Indexes.

disableJavaScriptJIT

New in version 3.2.

Available for mongod only.

The MongoDB JavaScript engine uses SpiderMonkey, which implements Just-in-Time (JIT) compilation for improved performance when running scripts.

To disable the JIT, set disableJavaScriptJIT to true, as in the following example:

db.adminCommand( { setParameter: 1, disableJavaScriptJIT: true } )

Be aware that group and $where will reuse existing JavaScript interpreter contexts, so changes to disableJavaScriptJIT may not take effect immediately for these operations.

Alternately, you may disable the JIT at startup time by starting the mongod instance with the following option:

mongod --setParameter disableJavaScriptJIT=true
maxIndexBuildMemoryUsageMegabytes

New in version 3.4.

Default: 500

Limits the amount of memory that simultaneous foreground index builds on one collection may consume for the duration of the builds.

The memory consumed by an index build is separate from the WiredTiger cache memory (see cacheSizeGB).

Foreground index builds may be initiated either by a user command such as Create Index or by an administrative process such as an initial sync. Both are subject to the limit set by maxIndexBuildMemoryUsageMegabytes.

An initial sync operation populates only one collection at a time and has no risk of exceeding the memory limit. However, it is possible for a user to start foreground index builds on multiple collections in multiple databases simultaneously and potentially consume an amount of memory greater than the limit set in maxIndexBuildMemoryUsageMegabytes.

Tip

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 Build Indexes on Replica Sets.

reportOpWriteConcernCountersInServerStatus

New in version 3.6.11.

Default: false

A boolean flag that determines whether the db.serverStatus() method and serverStatus command return opWriteConcernCounters information. [1]

You can only set reportOpWriteConcernCountersInServerStatus during startup in the config file or on the command line. For example:

mongod --setParameter reportOpWriteConcernCountersInServerStatus=true
[1]Enabling reportOpWriteConcernCountersInServerStatus can have a negative performance impact; specificaly, when running without TLS.
watchdogPeriodSeconds

New in version 3.6.

Available for mongod only.

Type: integer

Default: -1 (disabled)

Note

Available only in MongoDB Enterprise. Not available on macOS.

Determines how often the Storage Node Watchdog checks the status of the monitored filesystems.

Note

If a filesystem on a monitored directory becomes unresponsive, it can take a maximum of nearly twice the value of watchdogPeriodSeconds to terminate the mongod.

Valid values are -1, meaning the Storage Node Watchdog is disabled, or an integer greater than or equal to 60.

By default the Storage Node Watchdog is disabled. To enable it, watchdogPeriodSeconds must be set at startup time.

mongod --setParameter watchdogPeriodSeconds=60

You can only enable the Storage Node Watchdog at startup.

However, once enabled, you can pause the Storage Node Watchdog or change the watchdogPeriodSeconds during runtime.

To pause the Storage Node Watchdog during runtime, set watchdogPeriodSeconds to -1.

db.adminCommand( { setParameter: 1, watchdogPeriodSeconds: -1 } )

To resume or change the period during runtime, set watchdogPeriodSeconds to a number greater than or equal to 60.

db.adminCommand( { setParameter: 1, watchdogPeriodSeconds: 120 } )

Note

It is an error to set watchdogPeriodSeconds at runtime if the Storage Node Watchdog was not enabled at startup time.

tcmallocReleaseRate

New in version 3.6.17.

Default: 1.0

Specifies the tcmalloc release rate (TCMALLOC_RELEASE_RATE). Per https://gperftools.github.io/gperftools/tcmalloc.html#runtime TCMALLOC_RELEASE_RATE is described as:

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

https://gperftools.github.io/gperftools/tcmalloc.html#runtime

To modify the release rate during runtime, you can use the setParameter command; for example:

db.adminCommand( { setParameter: 1, tcmallocReleaseRate: 5.0 } )

You can also set tcmallocReleaseRate at startup time; for example:

mongod --setParameter "tcmallocReleaseRate=5.0"

Logging Parameters

logLevel

Available for both mongod and mongos.

Specify an integer between 0 and 5 signifying the verbosity of the logging, where 5 is the most verbose.

Consider the following example which sets the logLevel to 2:

db.adminCommand( { setParameter: 1, logLevel: 2 } )

The default logLevel is 0.

logComponentVerbosity

New in version 3.0.0.

Available for both mongod and mongos.

Sets the verbosity levels of various components for log messages. The verbosity level determines the amount of Informational and Debug messages MongoDB outputs.

The verbosity level can range from 0 to 5:

  • 0 is the MongoDB’s default log verbosity level, to include Informational messages.
  • 1 to 5 increases the verbosity level to include Debug messages.

For a component, you can also specify -1 to inherit the parent’s verbosity level.

To specify the verbosity level, use a document similar to the following:

{
  verbosity: <int>,
  <component1>: { verbosity: <int> },
  <component2>: {
     verbosity: <int>,
     <component3>: { verbosity: <int> }
  },
  ...
}

For the components, you can specify just the <component>: <int> in the document, unless you are setting both the parent verbosity level and that of the child component(s) as well:

{
  verbosity: <int>,
  <component1>: <int> ,
  <component2>: {
     verbosity: <int>,
     <component3>: <int>
  }
  ...
}

The top-level verbosity field corresponds to systemLog.verbosity which sets the default level for all components. The default value of systemLog.verbosity is 0.

The components correspond to the following settings:

Unless explicitly set, the component has the verbosity level of its parent. For example, storage is the parent of storage.journal. That is, if you specify a storage verbosity level, this level also applies to storage.journal components unless you specify the verbosity level for storage.journal.

For example, the following sets the default verbosity level to 1, the query to 2, the storage to 2, and the storage.journal to 1.

db.adminCommand( {
   setParameter: 1,
   logComponentVerbosity: {
      verbosity: 1,
      query: { verbosity: 2 },
      storage: {
         verbosity: 2,
         journal: {
            verbosity: 1
         }
      }
   }
} )

You can also set parameter logComponentVerbosity at startup time, passing the verbosity level document as a string.

mongod --setParameter "logComponentVerbosity={command: 3}"

The mongo shell also provides the db.setLogLevel() to set the log level for a single component. For various ways to set the log verbosity level, see Configure Log Verbosity Levels.

logUserIds

Available for both mongod and mongos.

Specify 1 to enable logging of userids.

Disabled by default.

maxLogSizeKB

New in version 3.4.

Available for both mongod and mongos.

Type: integer

Default: 10

Specifies the maximum size, in kilobytes, for a log line. Lines exceeding this limit print only the beginning and end of the line, excising the middle portion.

For example, the following sets the maximum size to 20 kilobytes:

mongod --setParameter maxLogSizeKB=20

Warning

Using a large value for maxLogSizeKB may adversely affect system performance and negatively impact database operations.

quiet

Available for both mongod and mongos.

Sets quiet logging mode. If 1, mongod will go into a quiet logging mode which will not log the following events/activities:

Consider the following example which sets the quiet parameter to 1:

db.adminCommand( { setParameter: 1, quiet: 1 } )

See also

systemLog.quiet

redactClientLogData

New in version 3.4.

Available for both mongod and mongos.

Type: boolean

Enterprise Feature

Available in MongoDB Enterprise only.

Configure the mongod or mongos to redact any message accompanying a given log event before logging. This prevents the program 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.

Use redactClientLogData in conjunction with Encryption at Rest and TLS/SSL (Transport Encryption) to assist compliance with regulatory requirements.

To enable log redaction on a running mongod or mongos, use the following command:

db.adminCommand( { setParameter: 1, redactClientLogData : true } )
traceExceptions

Available for both mongod and mongos.

Configures mongod to log full source code stack traces for every database and socket C++ exception, for use with debugging. If true, mongod will log full stack traces.

Consider the following example which sets the traceExceptions to true:

db.adminCommand( { setParameter: 1, traceExceptions: true } )
suppressNoTLSPeerCertificateWarning

New in version 3.6.6.

Available for both mongod and mongos.

Type: boolean

Default: false

By default, a mongod or mongos with TLS/SSL enabled and net.ssl.allowConnectionsWithoutCertificates : true lets clients connect without providing a certificate for validation while logging an warning. Set suppressNoTLSPeerCertificateWarning to 1 or true to suppress those warnings.

The following operation sets suppressNoTLSPeerCertificateWarning to true:

db.adminCommand( { setParameter: 1, suppressNoTLSPeerCertificateWarning: true} )

Diagnostic Parameters

To facilitate analysis of the MongoDB server behavior by MongoDB engineers, MongoDB logs server statistics to diagnostic files at periodic intervals.

For mongod, the diagnostic data files are stored in the diagnostic.data directory under the mongod instance’s --dbpath or storage.dbPath.

For mongos, the diagnostic data files, by default, are stored in a directory under the mongos instance’s --logpath or systemLog.path directory. The diagnostic data directory is computed by truncating the logpath’s file extension(s) and concatenating diagnostic.data to the remaining name.

For example, if mongos has --logpath /var/log/mongodb/mongos.log.201708015, then the diagnostic data directory is /var/log/mongodb/mongos.diagnostic.data/ directory. To specify a different diagnostic data directory for mongos, set the diagnosticDataCollectionDirectoryPath parameter.

The following parameters support diagnostic data capture (FTDC):

Note

The default values for the diagnostic data capture interval and the maximum sizes are chosen to provide useful data to MongoDB engineers with minimal impact on performance and storage size. Typically, these values will only need modifications as requested by MongoDB engineers for specific diagnostic purposes.

diagnosticDataCollectionEnabled

New in version 3.2.

Changed in version 3.4.14: Available for both mongod and mongos.

Type: boolean

Default: true

Determines whether to enable the collecting and logging of data for diagnostic purposes. Diagnostic logging is enabled by default.

For example, the following disables the diagnostic collection:

mongod --setParameter diagnosticDataCollectionEnabled=false
diagnosticDataCollectionDirectoryPath

New in version 3.4.14.

Type: String

Available for mongos only.

Specify the directory for the diagnostic directory for mongos. If the directory does not exist, mongos creates the directory.

If unspecified, the diagnostic data directory is computed by truncating the mongos instance’s --logpath or systemLog.path file extension(s) and concatenating diagnostic.data.

For example, if mongos has --logpath /var/log/mongodb/mongos.log.201708015, then the diagnostic data directory is /var/log/mongodb/mongos.diagnostic.data/.

Important

If mongos cannot create the specified directory, e.g. a file exists with the same name in the path or the process does not have permissions to create the directory, the diagnostic data capture will be disabled for that instance.

diagnosticDataCollectionDirectorySizeMB

New in version 3.2.

Changed in version 3.4: Increased default size to 200 megabytes.

Changed in version 3.4.14: Available for both mongod and mongos.

Type: integer

Default: 200

Specifies the maximum size, in megabytes, of the diagnostic.data directory. If directory size exceeds this number, the oldest diagnostic files in the directory are automatically deleted based on the timestamp in the file name.

For example, the following sets the maximum size of the directory to 250 megabytes:

mongod --setParameter diagnosticDataCollectionDirectorySizeMB=250

The minimum value for diagnosticDataCollectionDirectorySizeMB is 10 megabytes. diagnosticDataCollectionDirectorySizeMB must be greater than maximum diagnostic file size diagnosticDataCollectionFileSizeMB.

diagnosticDataCollectionFileSizeMB

New in version 3.2.

Changed in version 3.4.14: Available for both mongod and mongos.

Type: integer

Default: 10

Specifies the maximum size, in megabytes, of each diagnostic file. If the file exceeds the maximum file size, MongoDB creates a new file.

For example, the following sets the maximum size of each diagnostic file to 20 megabytes:

mongod --setParameter diagnosticDataCollectionFileSizeMB=20

The minimum value for diagnosticDataCollectionFileSizeMB is 1 megabyte.

diagnosticDataCollectionPeriodMillis

New in version 3.2.

Changed in version 3.4.14: Available for both mongod and mongos.

Type: integer

Default: 1000

Specifies the interval, in milliseconds, at which to collect diagnostic data.

For example, the following sets the interval to 5000 milliseconds or 5 seconds:

mongod --setParameter diagnosticDataCollectionPeriodMillis=5000

The minimum value for diagnosticDataCollectionPeriodMillis is 100 milliseconds.

Logical Session Parameters

logicalSessionRefreshMillis

Availability

New in version 3.6.9.

Available for both mongod and mongos.

Type: integer

Default: 300000 (i.e. 5 minutes)

The interval (in milliseconds) at which the cache refreshes its logical session records against the main session store.

You can only set logicalSessionRefreshMillis at startup and cannot change this setting with the setParameter command.

For example, to set the logicalSessionRefreshMillis for a mongod instance to 10 minutes:

mongod --setParameter logicalSessionRefreshMillis=600000
logicalSessionRefreshMinutes

Availability

Only for MongoDB 3.6.0-3.6.8. Starting in 3.6.9, see logicalSessionRefreshMillis instead.

Available for both mongod and mongos.

Type: integer

Default: 5

The interval (in minutes) at which the cache refreshes its logical session records against the main session store.

You can only set logicalSessionRefreshMinutes at startup and cannot change this setting with the setParameter command.

For example, to set the logicalSessionRefreshMinutes for a mongod instance to 10 minutes:

mongod --setParameter logicalSessionRefreshMinutes=10
localLogicalSessionTimeoutMinutes

New in version 3.6.

Available for both mongod and mongos.

Type: integer

Default: 30

For testing purposes only

This parameter is intended for testing purposes only and not for production use.

The time in minutes that a session remains active after its most recent use. Sessions that have not received a new read/write operation from the client or been refreshed with refreshSessions within this threshold are cleared from the cache. State associated with an expired session may be cleaned up by the server at any time.

This parameter applies only to the instance on which it is set. To set this parameter on replica sets and sharded clusters, you must specify the same value on every member; otherwise, sessions will not function properly.

You can only set localLogicalSessionTimeoutMinutes at startup and cannot change this setting with the setParameter command.

For example, to set the localLogicalSessionTimeoutMinutes for a test mongod instance to 20 minutes:

mongod --setParameter localLogicalSessionTimeoutMinutes=20
maxAcceptableLogicalClockDriftSecs

New in version 3.6.

Available for both mongod and mongos.

Type: integer

Default: 31536000 (1 year)

The maximum amount by which the current cluster time can be advanced; i.e., maxAcceptableLogicalClockDriftSecs is the maximum difference between the new value of the cluster time and the current cluster time. Cluster time is a logical time used for ordering of operations.

You cannot advance the cluster time to a new value if the new cluster time differs from the current cluster time by more than maxAcceptableLogicalClockDriftSecs,

You can only set maxAcceptableLogicalClockDriftSecs at startup and cannot change this setting with the setParameter command.

For example, to set the maxAcceptableLogicalClockDriftSecs for a mongod instance to 15 minutes:

mongod --setParameter maxAcceptableLogicalClockDriftSecs=900
maxSessions

New in version 3.6.7.

Available for both mongod and mongos.

Type: integer

Default: 1000000

The maximum number of sessions that can be cached.

You can only set maxSessions during start-up.

For example, to set the maxSessions for a mongod instance to 1000:

mongod --setParameter maxSessions=1000
TransactionRecordMinimumLifetimeMinutes

New in version 3.6.

Available for mongod only.

Type: integer

Default: 30

The minimum lifetime a transaction record exists in the transactions collection before the record becomes eligible for cleanup.

You can only set TransactionRecordMinimumLifetimeMinutes at startup and cannot change this setting with the setParameter command.

For example, to set the TransactionRecordMinimumLifetimeMinutes for a mongod instance to 20 minutes:

mongod --setParameter TransactionRecordMinimumLifetimeMinutes=20

Replication Parameters

replApplyBatchSize

Available for mongod only.

Specify the number of oplog entries to apply as a single batch. replApplyBatchSize must be an integer between 1 and 1024. The default value is 1. This option only applies to master/slave configurations and is valid only on a mongod started with the --slave command line option.

Batch sizes must be 1 for members with slavedelay configured.

replIndexPrefetch

Available for mongod only.

Use replIndexPrefetch in conjunction with replSetName when configuring a replica set. The default value is all and available options are:

  • none
  • all
  • _id_only

By default secondary members of a replica set will load all indexes related to an operation into memory before applying operations from the oplog. You can modify this behavior so that the secondaries will only load the _id index. Specify _id_only or none to prevent the mongod from loading any index into memory.

replWriterThreadCount

New in version 3.2.

Type: integer

Default: 16

Available for mongod only.

Number of threads to use to apply replicated operations in parallel. Values can range from 1 to 256 inclusive. You can only set replWriterThreadCount at startup and cannot change this setting with the setParameter command.

oplogInitialFindMaxSeconds

New in version 3.6.

Type: integer

Default: 60

Available for mongod only.

Maximum time in seconds for a member of a replica set to wait for its find command to finish during data synchronization.

waitForSecondaryBeforeNoopWriteMS

New in version 3.6.

Available for mongod only.

Type: integer

Default: 10

The length of time (in milliseconds) that a secondary must wait if the afterClusterTime is greater than the last applied time from the oplog. After the waitForSecondaryBeforeNoopWriteMS passes, if the afterClusterTime is still greater than the last applied time, the secondary makes a no-op write to advance the last applied time.

The following example sets the waitForSecondaryBeforeNoopWriteMS to 20 milliseconds:

mongod --setParameter waitForSecondaryBeforeNoopWriteMS=20

During runtime, you can also set the parameter with the setParameter command:

db.adminCommand( { setParameter: 1, waitForSecondaryBeforeNoopWriteMS: 20 } )
enableElectionHandoff

New in version 3.6.7.

Type: boolean

Default: true

A flag that can reduce the downtime after the primary steps down from either the rs.stepDown() method or the replSetStepDown command. Specifically, if true, when a primary steps down after rs.stepDown() (or the replSetStepDown command without the force: true), it nominates an eligible secondary to call an election immediately. If false, after the step down, secondaries can wait up to settings.electionTimeoutMillis before calling an election.

An eligible secondary must be caught up with the stepped down primary and have priority greater than 0. If multiple secondary members meet this criteria, the stepped down primary selects the eligible secondary with the highest priority. If the more than one eligible secondary members have the same priority, the stepped down primary selects the secondary with the lowest _id. The stepped down primary does not wait for the effects of the handoff.

The parameter has no impact if the primary steps down for reasons other than rs.stepDown() (or the replSetStepDown command without the force: true).

Sharding Parameters

replMonitorMaxFailedChecks

Available in MongoDB 3.2 only

Type: integer

Default: 30

The number of times the mongod or mongos instance tries to reach the replica sets in the sharded cluster (e.g. shard replica sets, config server replica set) to monitor the replica set status and topology.

When the number of consecutive unsuccessful attempts exceeds this parameter value, the mongod or mongos instance denotes the monitored replica set as unavailable. If the monitored replica set is the config server replica set:

timeOutMonitoringReplicaSets

Available in MongoDB 3.2.10 and later 3.2-series only

Type: integer

Default: false

The flag that determines whether the mongod or mongos instance should stop its attempt to reach the monitored replica set after unsuccessfully trying replMonitorMaxFailedChecks number of times.

If the monitored replica set is the config server replica set and timeOutMonitoringReplicaSets is set to true, you must restart mongod or mongos if the mongod or mongos instance cannot reach any of the config servers for the specified number of times. See the troubleshooting guide for more details.

ShardingTaskExecutorPoolHostTimeoutMS

Type: integer

Default: 300000 (i.e. 5 minutes)

Available for mongos only.

Maximum time that mongos goes without communication to a host before mongos drops all connections to the host.

You can only set this parameter during start-up and cannot change this setting using the setParameter database command.

If set, ShardingTaskExecutorPoolHostTimeoutMS should be greater than the sum of ShardingTaskExecutorPoolRefreshRequirementMS and ShardingTaskExecutorPoolRefreshTimeoutMS. Otherwise, mongos adjusts the value of ShardingTaskExecutorPoolHostTimeoutMS to be greater than the sum.

mongos --setParameter ShardingTaskExecutorPoolHostTimeoutMS=120000
ShardingTaskExecutorPoolMaxConnecting

New in version 3.6.

Type: integer

Default: 2

Available for mongos only.

Maximum number of simultaneous initiating connections (including pending connections in setup/refresh state) each TaskExecutor connection pool can have to a mongod instance. You can set this parameter to control the rate at which mongos adds connections to a mongod instance.

If set, ShardingTaskExecutorPoolMaxConnecting should be less than or equal to ShardingTaskExecutorPoolMaxSize. If it is greater, mongos ignores the ShardingTaskExecutorPoolMaxConnecting value.

You can only set this parameter during start-up and cannot change this setting using the setParameter database command.

mongos --setParameter ShardingTaskExecutorPoolMaxConnecting=20
ShardingTaskExecutorPoolMaxSize

Type: integer

Default: 264 - 1

Available for mongos only.

Maximum number of outbound connections each TaskExecutor connection pool can open to any given mongod instance. The maximum possible connections to any given host across all TaskExecutor pools is:

ShardingTaskExecutorPoolMaxSize * taskExecutorPoolSize

You can only set this parameter during start-up and cannot change this setting using the setParameter database command.

mongos --setParameter ShardingTaskExecutorPoolMaxSize=4

mongos can have up to n TaskExecutor connection pools, where n is the number of cores. See taskExecutorPoolSize.

ShardingTaskExecutorPoolMinSize

Type: integer

Default: 1

Available for mongos only.

Minimum number of outbound connections each TaskExecutor connection pool can open to any given mongod instance.

ShardingTaskExecutorPoolMinSize connections are created the first time a connection to a new host is requested from the pool. While the pool is idle, the pool maintains this number of connections until ShardingTaskExecutorPoolHostTimeoutMS milliseconds pass without any application using that pool.

You can only set this parameter during start-up and cannot change this setting using the setParameter database command.

mongos --setParameter ShardingTaskExecutorPoolMinSize=2

mongos can have up to n TaskExecutor connection pools, where n is the number of cores. See taskExecutorPoolSize.

ShardingTaskExecutorPoolRefreshRequirementMS

Type: integer

Default: 60000 (1 minute)

Available for mongos only.

Maximum time the mongos waits before attempting to heartbeat a resting connection in the pool.

You can only set this parameter during start-up and cannot change this setting using the setParameter database command.

If set, ShardingTaskExecutorPoolRefreshRequirementMS should be greater than ShardingTaskExecutorPoolRefreshTimeoutMS. Otherwise, mongos adjusts the value of ShardingTaskExecutorPoolRefreshTimeoutMS to be less than ShardingTaskExecutorPoolRefreshRequirementMS.

mongos --setParameter ShardingTaskExecutorPoolRefreshRequirementMS=90000
ShardingTaskExecutorPoolRefreshTimeoutMS

Type: integer

Default: 20000 (20 seconds)

Available for mongos only.

Maximum time the mongos waits for a heartbeat before timing out the heartbeat.

You can only set this parameter during start-up and cannot change this setting using the setParameter database command.

If set, ShardingTaskExecutorPoolRefreshTimeoutMS should be less than ShardingTaskExecutorPoolRefreshRequirementMS. Otherwise, mongos adjusts the value of ShardingTaskExecutorPoolRefreshTimeoutMS to be less than ShardingTaskExecutorPoolRefreshRequirementMS.

mongos --setParameter ShardingTaskExecutorPoolRefreshTimeoutMS=30000
taskExecutorPoolSize

Type: integer

Default: Number of cores

Available for mongos only.

The number of Task Executor connection pools to use for a given mongos. The parameter has a minimum value of 4 and a maximum value of 64.

You can only set this parameter during start-up and cannot change this setting using the setParameter database command.

mongos --setParameter taskExecutorPoolSize=6
migrateCloneInsertionBatchDelayMS

New in version 3.6.10: The parameter is also available starting in 3.4.18.

Available for mongod only.

Type: Non-negative integer

Default: 0

Time in milliseconds to wait between batches of insertions during cloning step of the migration process. This wait is in addition to the secondaryThrottle.

The default value of 0 indicates no additional wait.

The following sets the migrateCloneInsertionBatchDelayMS to 200 milliseconds:

mongod --setParameter migrateCloneInsertionBatchDelayMS=200

The parameter may also be set using the setParameter command:

db.adminCommand( { setParameter: 1, migrateCloneInsertionBatchDelayMS: 200 } )
migrateCloneInsertionBatchSize

New in version 3.6.10: The parameter is also available starting in 3.4.18.

Available for mongod only.

Type: Non-negative integer

Default: 0

The maximum number of documents to insert in a single batch during the cloning step of the migration process.

The default value of 0 indicates no maximum number of documents per batch. However, in practice, this results in batches that contain up to 16 MB of documents.

The following sets the migrateCloneInsertionBatchSize to 100 documents:

mongod --setParameter migrateCloneInsertionBatchSize=100

The parameter may also be set using the setParameter command:

db.adminCommand( { setParameter: 1, migrateCloneInsertionBatchSize: 100 } )
orphanCleanupDelaySecs

New in version 3.6.

Default: 900 (15 minutes)

Available for mongod only.

Minimum delay before a migrated chunk is deleted from the source shard.

Before deleting the chunk during chunk migration, MongoDB waits for orphanCleanupDelaySecs or for in-progress queries involving the chunk to complete on the shard primary, whichever is longer.

However, because the shard primary has no knowledge of in-progress queries run on the shard secondaries, queries that use the chunk but are run on secondaries may see documents disappear if these queries take longer than the time to complete the shard primary queries and the orphanCleanupDelaySecs.

Note

This behavior only affects in-progress queries that start before the chunk migration. Queries that start after the chunk migration starts will not use the migrating chunk.

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.

The following sets the orphanCleanupDelaySecs to 20 minutes:

mongod --setParameter orphanCleanupDelaySecs=1200

This may also be set using the setParameter command:

db.adminCommand( { setParameter: 1, orphanCleanupDelaySecs: 1200 } )
rangeDeleterBatchDelayMS

New in version 3.6.7: The parameter is also available starting in 3.4.17.

Available for mongod only.

Type: Non-negative integer

Default: 20

The amount of time in milliseconds to wait before the next batch of deletion during the cleanup stage of chunk migration (or the cleanupOrphaned command).

In MongoDB 3.4, consider whether _secondaryThrottle is set before modifying the rangeDeleterBatchDelayMS. In MongoDB 3.4, the _secondaryThrottle replication delay occurs after each document deletion instead of after the batch deletion.

In MongoDB 3.6+, the _secondaryThrottle replication delay occurs after each batch deletion.

The following sets the rangeDeleterBatchDelayMS to 200 milliseconds:

mongod --setParameter rangeDeleterBatchDelayMS=200

The parameter may also be set using the setParameter command:

db.adminCommand( { setParameter: 1, rangeDeleterBatchDelayMS: 200 } )
rangeDeleterBatchSize

New in version 3.6.10: The parameter is also available starting in 3.4.19.

Available for mongod only.

Type: Non-negative integer

Default: 0

The maximum number of documents in each batch to delete during the cleanup stage of chunk migration (or the cleanupOrphaned command).

The default value of 0 indicates that the system chooses an appropriate value, generally 128 documents.

The following sets the rangeDeleterBatchSize to 100 documents:

mongod --setParameter rangeDeleterBatchSize=100

The parameter may also be set using the setParameter command:

db.adminCommand( { setParameter: 1, rangeDeleterBatchSize: 100 } )
skipShardingConfigurationChecks

New in version 3.6.3.

Available for mongod only.

Type: boolean

Default: false

When true, allows for starting a shard member or config server member as a standalone for maintenance operations. This parameter is mutually exclusive with the --configsvr or --shardsvr options.

You can only set this parameter during start-up and cannot change this setting using the setParameter database command.

mongod --setParameter skipShardingConfigurationChecks=true

Important

Once maintenance has completed, remove the skipShardingConfigurationChecks parameter when restarting the mongod.

The parameter is also available for MongoDB versions:

  • MongoDB 3.2.19+
  • MongoDB 3.4.11+

Storage Parameters

journalCommitInterval

Available for mongod only.

Specify an integer between 1 and 500 signifying the number of milliseconds (ms) between journal commits.

Consider the following example which sets the journalCommitInterval to 200 ms:

db.adminCommand( { setParameter: 1, journalCommitInterval: 200 } )
syncdelay

Available for mongod only.

Specify the interval in seconds between fsync operations where mongod flushes its working memory to disk. By default, mongod flushes memory to disk every 60 seconds. In almost every situation you should not set this value and use the default setting.

Consider the following example which sets the syncdelay to 60 seconds:

db.adminCommand( { setParameter: 1, syncdelay: 60 } )
honorSystemUmask

New in version 3.6.

Default: false

If honorSystemUmask is set to true, new files created by MongoDB have permissions in accordance with the user’s umask settings.

If honorSystemUmask is set to false, new files created by MongoDB have permissions set to 600, which gives read and write permissions only to the owner. New directories have permissions set to 700.

You can only set this parameter during start-up and cannot change this setting using the setParameter database command.

mongod --setParameter honorSystemUmask=true

Note

honorSystemUmask is not available on Windows systems.

WiredTiger Parameters

wiredTigerMaxCacheOverflowSizeGB

Available in 3.6-series starting in 3.6.15

Default: 0 (No specified maximum)

Available for mongod only.

Specify the maximum size (in GB) for the “lookaside (or cache overflow) table” file WiredTigerLAS.wt.

The parameter can accept the following values:

Value Description
0 The default value. If set to 0, the file size is unbounded.
number >= 0.1 The maximum size (in GB). If the WiredTigerLAS.wt file exceeds this size, mongod exits with a fatal assertion. You can clear the WiredTigerLAS.wt file and restart mongod.

You can only set this parameter during runtime using the setParameter database command:

db.adminCommand( { setParameter: 1, wiredTigerMaxCacheOverflowSizeGB: 100 } )

To set the maximum size during start up, use the storage.wiredTiger.engineConfig.maxCacheOverflowFileSizeGB instead.

wiredTigerConcurrentReadTransactions

New in version 3.0.0.

Available for mongod only.

Available for the WiredTiger storage engine only.

Specify the maximum number of concurrent read transactions allowed into the WiredTiger storage engine.

db.adminCommand( { setParameter: 1, wiredTigerConcurrentReadTransactions: <num> } )
wiredTigerConcurrentWriteTransactions

New in version 3.0.0.

Available for mongod only.

Available for the WiredTiger storage engine only.

Specify the maximum number of concurrent write transactions allowed into the WiredTiger storage engine.

db.adminCommand( { setParameter: 1, wiredTigerConcurrentWriteTransactions: <num> } )
wiredTigerEngineRuntimeConfig

New in version 3.0.0.

Available for mongod only.

Specify wiredTiger storage engine configuration options for a running mongod instance. You can only set this parameter using the setParameter command and not using the command line or configuration file option.

Warning

Avoid modifying the wiredTigerEngineRuntimeConfig unless under the direction from MongoDB engineers as this setting has major implication across both WiredTiger and MongoDB.

Consider the following operation prototype:

db.adminCommand({
   "setParameter": 1,
   "wiredTigerEngineRuntimeConfig": "<option>=<setting>,<option>=<setting>"
})

See the WiredTiger documentation for all available WiredTiger configuration options.

Auditing Parameters

auditAuthorizationSuccess

New in version 2.6.5.

Default: false

Note

Available only in MongoDB Enterprise.

Available for both mongod and mongos.

Enables the auditing of authorization successes for the authCheck action.

When auditAuthorizationSuccess is false, the audit system only logs the authorization failures for authCheck.

To enable the audit of authorization successes, issue the following command:

db.adminCommand( { setParameter: 1, auditAuthorizationSuccess: true } )

Enabling auditAuthorizationSuccess degrades performance more than logging only the authorization failures.

See also

getParameter