OPTIONS

Configuration File Options

Synopsis

Administrators and users can control mongod or mongos instances at runtime either directly from mongod’s command line arguments or using a configuration file.

While both methods are functionally equivalent and all settings are similar, the configuration file method is preferable. If you installed from a package and have started MongoDB using your system’s control script, you’re already using a configuration file.

To start mongod or mongos using a config file, use one of the following forms:

mongod --config /etc/mongodb.conf
mongod -f /etc/mongodb.conf
mongos --config /srv/mongodb/mongos.conf
mongos -f /srv/mongodb/mongos.conf

Declare all settings in this file using the following form:

<setting> = <value>

New in version 2.0: Before version 2.0, Boolean (i.e. true|false) or “flag” parameters, register as true, if they appear in the configuration file, regardless of their value.

Note

Ensure the configuration file uses ASCII encoding. mongod does not support configuration files with non-ASCII encoding, including UTF-8.

Settings

verbose

Default: false

Increases the amount of internal reporting returned on standard output or in the log file generated by logpath. To enable verbose or to enable increased verbosity with vvvv, set these options as in the following example:

verbose = true
vvvv = true

MongoDB has the following levels of verbosity:

v

Default: false

Alternate form of verbose.

vv

Default: false

Additional increase in verbosity of output and logging.

vvv

Default: false

Additional increase in verbosity of output and logging.

vvvv

Default: false

Additional increase in verbosity of output and logging.

vvvvv

Default: false

Additional increase in verbosity of output and logging.

port

Default: 27017

Specifies a TCP port for the mongod or mongos instance to listen for client connections. UNIX-like systems require root access for ports with numbers lower than 1024.

bind_ip

Default: All interfaces.

Set this option to configure the mongod or mongos process to bind to and listen for connections from applications on this address. You may attach mongod or mongos instances to any interface; however, if you attach the process to a publicly accessible interface, implement proper authentication or firewall restrictions to protect the integrity of your database.

You may concatenate a list of comma separated values to bind mongod to multiple IP addresses.

maxConns

Default: depends on system (i.e. ulimit and file descriptor) limits. Unless set, MongoDB will not limit its own connections.

Specifies a value to set the maximum number of simultaneous connections that mongod or mongos will accept. This setting has no effect if it is higher than your operating system’s configured maximum connection tracking threshold.

This is particularly useful for mongos if you have a client that creates a number of connections but allows them to timeout rather than close the connections. When you set maxConns, ensure the value is slightly higher than the size of the connection pool or the total number of connections to prevent erroneous connection spikes from propagating to the members of a shard cluster.

Note

You cannot set maxConns to a value higher than 20000.

objcheck

Default: true

Changed in version 2.4: The default setting for objcheck became true in 2.4. In earlier versions objcheck was false by default.

Forces the mongod to validate all requests from clients upon receipt to ensure that clients never insert invalid documents into the database. For objects with a high degree of sub-document nesting, objcheck can have a small impact on performance. You can set noobjcheck to disable object checking at run-time.

noobjcheck

New in version 2.4.

Default: false

Disables the default object validation that MongoDB performs on all incoming BSON documents.

logpath

Default: None. (i.e. /dev/stdout)

Specify the path to a file name for the log file that will hold all diagnostic logging information.

Unless specified, mongod will output all log information to the standard output. Unless logappend is true, the logfile will be overwritten when the process restarts.

Note

Currently, MongoDB will overwrite the contents of the log file if the logappend is not used. This behavior may change in the future depending on the outcome of SERVER-4499.

logappend

Default: false

Set to true to add new entries to the end of the logfile rather than overwriting the content of the log when the process restarts.

If this setting is not specified, then MongoDB will overwrite the existing logfile upon start up.

Note

The behavior of the logging system may change in the near future in response to the SERVER-4499 case.

syslog

New in version 2.2.

Sends all logging output to the host’s syslog system rather than to standard output or a log file as with logpath.

Important

You cannot use syslog with logpath.

pidfilepath

Default: None.

Specify a file location to hold the PID or process ID of the mongod process. Useful for tracking the mongod process in combination with the fork setting.

Without a specified pidfilepath, mongos creates no PID file.

Without this option, mongod creates no PID file.

keyFile

Default: None.

Specify the path to a key file to store authentication information. This option is used for interprocess authentication among the mongos and mongod instances of a sharded cluster or replica set.

nounixsocket

Default: false

Set to true to disable listening on the UNIX socket.

MongoDB always creates and listens on the UNIX socket, unless nounixsocket is set, or bind_ip is not set, or bind_ip does not specify 127.0.0.1.

unixSocketPrefix

Default: /tmp

Specifies a path for the UNIX socket. Unless this option has a value mongod creates a socket with /tmp as a prefix.

MongoDB will always create and listen on a UNIX socket, unless nounixsocket is set, bind_ip is not set. or bind_ip does not specify 127.0.0.1.

fork

Default: false

Set to true to enable a daemon mode for mongod that runs the process in the background.

auth

Default: false

Set to true to enable database authentication for users connecting from remote hosts. Configure users via the mongo shell. If no users exist, the localhost interface will continue to have access to the database until you create the first user.

saslServiceName

New in version 2.4.6: 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.

Only available in MongoDB Enterprise.

Important

Ensure that your driver supports alternate service names.

cpu

Default: false

Set to true to force mongod to report every four seconds CPU utilization and the amount of time that the processor waits for I/O operations to complete (i.e. I/O wait.) MongoDB writes this data to standard output, or the logfile if using the logpath option.

dbpath

Default: /data/db/

Set this value to designate a directory for the mongod instance to store its data. Typical locations include: /srv/mongodb, /var/lib/mongodb or /opt/mongodb

Unless specified, mongod will look for data files in the default /data/db directory. (Windows systems use the \data\db directory.) If you installed using a package management system. Check the /etc/mongodb.conf file provided by your packages to see the configuration of the dbpath.

diaglog

Default: 0

Creates a very verbose diagnostic log for troubleshooting and recording various errors. MongoDB writes these log files in the dbpath directory and names them diaglog.<time in hex>, where <time-in-hex> is the initiation time of logging as a hexadecimal string.

The value of this setting configures the level of verbosity. Possible values, and their impact are as follows.

Value Setting
0 Off. No logging.
1 Log write operations.
2 Log read operations.
3 Log both read and write operations.
7 Log write and some read operations.

You can use the mongosniff tool to replay this output for investigation. Given a typical diaglog file, located at /data/db/diaglog.4f76a58c, you might use a command in the following form to read these files:

mongosniff --source DIAGLOG /data/db/diaglog.4f76a58c

diaglog is for internal use and not intended for most users.

Warning

Setting the diagnostic level to 0 will cause mongod to stop writing data to the diagnostic log file. However, the mongod instance will continue to keep the file open, even if it is no longer writing data to the file. If you want to rename, move, or delete the diagnostic log you must cleanly shut down the mongod instance before doing so.

directoryperdb

Default: false

Set to true to modify the storage pattern of the data directory to store each database’s files in a distinct folder. This option will create directories within the dbpath named for each database.

Use this option in conjunction with your file system and device configuration so that MongoDB will store data on a number of distinct disk devices to increase write throughput or disk capacity.

Warning

If you have an existing mongod instance and dbpath, and you want to enable directoryperdb, you must migrate your existing databases to directories before setting directoryperdb to access those databases.

Example

Given a dbpath directory with the following items:

journal
mongod.lock
local.0
local.1
local.ns
test.0
test.1
test.ns

To enable directoryperdb you would need to modify the dbpath to resemble the following:

journal
mongod.lock
local/local.0
local/local.1
local/local.ns
test/test.0
test/test.1
test/test.ns
journal

Default: (on 64-bit systems) true

Default: (on 32-bit systems) false

Set to true to enable operation journaling to ensure write durability and data consistency.

Set to false to prevent the overhead of journaling in situations where durability is not required. To reduce the impact of the journaling on disk usage, you can leave journal enabled, and set smallfiles to true to reduce the size of the data and journal files.

Note

You must use nojournal to disable journaling on 64-bit systems.

journalCommitInterval

Default: 100 or 30

Set this value to specify the maximum amount of time for mongod to allow between journal operations. Lower values increase the durability of the journal, at the possible expense of disk performance.

The default journal commit interval is 100 milliseconds if a single block device (e.g. physical volume, RAID device, or LVM volume) contains both the journal and the data files.

If the journal is on a different block device than the data files the default journal commit interval is 30 milliseconds.

This option accepts values between 2 and 300 milliseconds.

To force mongod to commit to the journal more frequently, you can specify j:true. When a write operation with j:true is pending, mongod will reduce journalCommitInterval to a third of the set value.

ipv6

Default: false

Set to true to IPv6 support to allow clients to connect to mongod using IPv6 networks. mongod disables IPv6 support by default in mongod and all utilities.

jsonp

Default: false

Set to true to permit JSONP access via an HTTP interface. Consider the security implications of allowing this activity before setting this option.

noauth

Default: true

Disable authentication. Currently the default. Exists for future compatibility and clarity.

For consistency use the auth option.

nohttpinterface

Default: false

Set to true to disable the HTTP interface. This command will override the rest and disable the HTTP interface if you specify both.

Note

In MongoDB Enterprise, the HTTP Console does not support Kerberos Authentication.

Changed in version 2.1.2: The nohttpinterface option is not available for mongos instances before 2.1.2

nojournal

Default: (on 64-bit systems) false

Default: (on 32-bit systems) true

Set nojournal = true to disable durability journaling. By default, mongod enables journaling in 64-bit versions after v2.0.

Note

You must use journal to enable journaling on 32-bit systems.

noprealloc

Default: false

Set noprealloc = true to disable the preallocation of data files. This will shorten the start up time in some cases, but can cause significant performance penalties during normal operations.

noscripting

Default: false

Set noscripting = true to disable the scripting engine.

notablescan

Default: false

Set notablescan = true to forbid operations that require a table scan.

nssize

Default: 16

Specify this value in megabytes. The maximum size is 2047 megabytes.

Use this setting to control the default size for all newly created namespace files (i.e .ns). This option has no impact on the size of existing namespace files.

See Limits on namespaces.

profile

Default: 0

Modify this value to changes the level of database profiling, which inserts information about operation performance into output of mongod or the log file if specified by logpath. The following levels are available:

Level Setting
0 Off. No profiling.
1 On. Only includes slow operations.
2 On. Includes all operations.

By default, mongod disables profiling. Database profiling can impact database performance because the profiler must record and process all database operations. Enable this option only after careful consideration.

quota

Default: false

Set to true to enable a maximum limit for the number data files each database can have. The default quota is 8 data files, when quota is true. Adjust the quota size with the with the quotaFiles setting.

quotaFiles

Default: 8

Modify limit on the number of data files per database. This option requires the quota setting.

rest

Default: false

Set to true to enable a simple REST interface.

repair

Default: false

Set to true to run a repair routine on all databases following start up. In general you should set this option on the command line and not in the configuration file or in a control script.

Use the mongod --repair option to access this functionality.

Note

Because mongod rewrites all of the database files during the repair routine, if you do not run repair under the same user account as mongod usually runs, you will need to run chown on your database files to correct the permissions before starting mongod again.

repairpath

Default: A _tmp directory in the dbpath.

Specify the path to the directory containing MongoDB data files, to use in conjunction with the repair setting or mongod --repair operation. Defaults to a _tmp directory within the dbpath.

slowms

Default: 100

Specify values in milliseconds.

Sets the threshold for mongod to consider a query “slow” for the database profiler. The database logs all slow queries to the log, even when the profiler is not turned on. When the database profiler is on, mongod the profiler writes to the system.profile collection.

See also

profile

smallfiles

Default: false

Set to true to modify MongoDB to use a smaller default data file size. Specifically, smallfiles reduces the initial size for data files and limits them to 512 megabytes. The smallfiles setting also reduces the size of each journal files from 1 gigabyte to 128 megabytes.

Use the smallfiles setting if you have a large number of databases that each hold a small quantity of data. The smallfiles setting can lead mongod to create many files, which may affect performance for larger databases.

syncdelay

Default: 60

mongod writes data very quickly to the journal, and lazily to the data files. syncdelay controls how much time can pass before MongoDB flushes data to the database files via an fsync operation. The default setting is 60 seconds. In almost every situation you should not set this value and use the default setting.

The serverStatus command reports the background flush thread’s status via the backgroundFlushing field.

syncdelay has no effect on the journal files or journaling.

Warning

If you set syncdelay to 0, MongoDB will not sync the memory mapped files to disk. Do not set this value on production systems.

sysinfo

Default: false

When set to true, mongod returns diagnostic system information regarding the page size, the number of physical pages, and the number of available physical pages to standard output.

More typically, run this operation by way of the mongod --sysinfo command. When running with the sysinfo, only mongod only outputs the page information and no database process will start.

upgrade

Default: false

When set to true this option upgrades the on-disk data format of the files specified by the dbpath to the latest version, if needed.

This option only affects the operation of mongod if the data files are in an old format.

When specified for a mongos instance, this option updates the meta data format used by the config database.

Note

In most cases you should not set this value, so you can exercise the most control over your upgrade process. See the MongoDB release notes (on the download page) for more information about the upgrade process.

traceExceptions

Default: false

For internal diagnostic use only.

quiet

Default: false

Runs the mongod or mongos instance in a quiet mode that attempts to limit the amount of output. This option suppresses:

Note

For production systems this option is not recommended as it may make tracking problems during particular connections much more difficult.

setParameter

New in version 2.4.

Specifies an option to configure on startup. Specify multiple options with multiple setParameter options. See mongod Parameters for full documentation of these parameters. The setParameter database command provides access to many of these parameters.

Declare all setParameter settings in this file using the following form:

setParameter = <parameter>=<value>

For mongod the following options are available using setParameter:

For mongos the following options are available using setParameter:

Replication Options

replSet

Default: <none>

Form: <setname>

Use this setting to configure replication with replica sets. Specify a replica set name as an argument to this set. All hosts must have the same set name.

oplogSize

Specifies a maximum size in megabytes for the replication operation log (e.g. oplog.) mongod creates an oplog based on the maximum amount of space available. For 64-bit systems, the oplog is typically 5% of available disk space.

Once the mongod has created the oplog for the first time, changing oplogSize will not affect the size of the oplog.

fastsync

Default: false

In the context of replica set replication, set this option to true if you have seeded this member with a snapshot of the dbpath of another member of the set. Otherwise the mongod will attempt to perform an initial sync, as though the member were a new member.

Warning

If the data is not perfectly synchronized and mongod starts with fastsync, then the secondary or slave will be permanently out of sync with the primary, which may cause significant consistency problems.

replIndexPrefetch

New in version 2.2.

Default: all

Values: all, none, and _id_only

You can only use replIndexPrefetch in conjunction with replSet.

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.

Master/Slave Replication

master

Default: false

Set to true to configure the current instance to act as master instance in a replication configuration.

slave

Default: false

Set to true to configure the current instance to act as slave instance in a replication configuration.

source

Default: <>

Form: <host><:port>

Used with the slave setting to specify the master instance from which this slave instance will replicate

only

Default: <>

Used with the slave option, only specifies only a single database to replicate.

slavedelay

Default: 0

Used with the slave setting, slavedelay configures a “delay” in seconds, for this slave to wait to apply operations from the master instance.

autoresync

Default: false

Used with the slave setting, set autoresync to true to force the slave to automatically resync if it is more than 10 seconds behind the master. This setting may be problematic if the oplogSize of the oplog is too small. If the oplog is not large enough to store the difference in changes between the master’s current state and the state of the slave, this instance will forcibly resync itself unnecessarily. When you set the autoresync option to false, the slave will not attempt an automatic resync more than once in a ten minute period.

Sharded Cluster Options

configsvr

Default: false

Set this value to true to configure this mongod instance to operate as the config database of a shard cluster. When running with this option, clients will not be able to write data to any database other than config and admin. The default port for a mongod with this option is 27019 and the default dbpath directory is /data/configdb, unless specified.

Changed in version 2.2: configsvr also sets smallfiles.

Changed in version 2.4: configsvr creates a local oplog.

Do not use configsvr with replSet or shardsvr. Config servers cannot be a shard server or part of a replica set.

default port for mongod with this option is 27019 and mongod writes all data files to the /configdb sub-directory of the dbpath directory.

shardsvr

Default: false

Set this value to true to configure this mongod instance as a shard in a partitioned cluster. The default port for these instances is 27018. The only effect of shardsvr is to change the port number.

configdb

Default: None.

Format: <config1>,<config2><:port>,<config3>

Set this option to specify a configuration database (i.e. config database) for the sharded cluster. You must specify either 1 configuration server or 3 configuration servers, in a comma separated list.

This setting only affects mongos processes.

Note

mongos instances read from the first config server in the list provided. All mongos instances must specify the hosts to the configdb setting in the same order.

If your configuration databases reside in more that one data center, order the hosts in the configdb setting so that the config database that is closest to the majority of your mongos instances is first servers in the list.

Warning

Never remove a config server from the configdb parameter, even if the config server or servers are not available, or offline.

test

Default: false

Only runs unit tests and does not start a mongos instance.

This setting only affects mongos processes and is for internal testing use only.

chunkSize

Default: 64

The value of this option determines the size of each chunk of data distributed around the sharded cluster. The default value is 64 megabytes. Larger chunks may lead to an uneven distribution of data, while smaller chunks may lead to frequent and unnecessary migrations. However, in some circumstances it may be necessary to set a different chunk size.

This setting only affects mongos processes. Furthermore, chunkSize only sets the chunk size when initializing the cluster for the first time. If you modify the run-time option later, the new value will have no effect. See the Modify Chunk Size in a Sharded Cluster procedure if you need to change the chunk size on an existing sharded cluster.

localThreshold

New in version 2.2.

localThreshold affects the logic that mongos uses when selecting replica set members to pass reads operations to from clients. Specify a value to localThreshold in milliseconds. The default value is 15, which corresponds to the default value in all of the client drivers.

This setting only affects mongos processes.

When mongos receives a request that permits reads to secondary members, the mongos will:

  • find the member of the set with the lowest ping time.

  • construct a list of replica set members that is within a ping time of 15 milliseconds of the nearest suitable member of the set.

    If you specify a value for localThreshold, mongos will construct the list of replica members that are within the latency allowed by this value.

  • The mongos will select a member to read from at random from this list.

The ping time used for a set member compared by the localThreshold setting is a moving average of recent ping times, calculated, at most, every 10 seconds. As a result, some queries may reach members above the threshold until the mongos recalculates the average.

See the Member Selection section of the read preference documentation for more information.

noAutoSplit

noAutoSplit is for internal use and is only available on mongos instances.

New in version 2.0.7.

noAutoSplit prevents mongos from automatically inserting metadata splits in a sharded collection. If set on all mongos, this will prevent MongoDB from creating new chunks as the data in a collection grows.

Because any mongos in a cluster can create a split, to totally disable splitting in a cluster you must set noAutoSplit on all mongos.

Warning

With noAutoSplit enabled, the data in your sharded cluster may become imbalanced over time. Enable with caution.

moveParanoia

New in version 2.4.

During chunk migrations, moveParanoia forces the mongod instances to save all documents migrated from this shard in the moveChunk directory of the dbpath. MongoDB does not delete data from this directory.

Prior to 2.4, moveParanoia was the default behavior of MongoDB.

SSL Options

sslOnNormalPorts

New in version 2.2.

Note

The default distribution of MongoDB does not contain support for SSL. To use SSL you can either compile MongoDB with SSL support or use MongoDB Enterprise. See Connect to MongoDB with SSL for more information about SSL and MongoDB.

Enables SSL for mongod or mongos. With sslOnNormalPorts, a mongod or mongos requires SSL encryption for all connections on the default MongoDB port, or the port specified by port. By default, sslOnNormalPorts is disabled.

sslPEMKeyFile

New in version 2.2.

Note

The default distribution of MongoDB does not contain support for SSL. To use SSL you can either compile MongoDB with SSL support or use MongoDB Enterprise. See Connect to MongoDB with SSL for more information about SSL and MongoDB.

Specifies the .pem file that contains both the SSL certificate and key. Specify the file name of the .pem file using relative or absolute paths

When using sslOnNormalPorts, you must specify sslPEMKeyFile.

sslPEMKeyPassword

New in version 2.2.

Note

The default distribution of MongoDB does not contain support for SSL. To use SSL you can either compile MongoDB with SSL support or use MongoDB Enterprise. See Connect to MongoDB with SSL for more information about SSL and MongoDB.

Specifies the password to de-crypt the certificate-key file (i.e. sslPEMKeyFile). Only use sslPEMKeyPassword if the certificate-key file is encrypted. In all cases, mongod or mongos will redact the password from all logging and reporting output.

Changed in version 2.4: sslPEMKeyPassword is only needed when the private key is encrypted. In earlier versions mongod or mongos would require sslPEMKeyPassword whenever using sslOnNormalPorts, even when the private key was not encrypted.

sslCAFile

New in version 2.4.

Note

The default distribution of MongoDB does not contain support for SSL. To use SSL you can either compile MongoDB with SSL support or use MongoDB Enterprise. See Connect to MongoDB with SSL for more information about SSL and MongoDB.

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

sslCRLFile

New in version 2.4.

Note

The default distribution of MongoDB does not contain support for SSL. To use SSL you can either compile MongoDB with SSL support or use MongoDB Enterprise. See Connect to MongoDB with SSL for more information about SSL and MongoDB.

Specifies the .pem file that contains the Certificate Revocation List. Specify the file name of the .pem file using relative or absolute paths

sslAllowConnectionsWithoutCertificates

New in version 2.4.

Note

The default distribution of MongoDB does not contain support for SSL. To use SSL you can either compile MongoDB with SSL support or use MongoDB Enterprise. See Connect to MongoDB with SSL for more information about SSL and MongoDB.

Disables the requirement for SSL certificate validation, that sslCAFile enables. With sslAllowConnectionsWithoutCertificates, mongod or mongos will accept connections if the client does not present a certificate when establishing the connection.

If the client presents a certificate and mongod or mongos has sslAllowConnectionsWithoutCertificates enabled, mongod or mongos will validate the certificate using the root certificate chain specified by sslCAFile, and reject clients with invalid certificates.

Use sslAllowConnectionsWithoutCertificates if you have a mixed deployment that includes clients that do not or cannot present certificates to mongod or mongos.

sslFIPSMode

New in version 2.4.

Note

The default distribution of MongoDB does not contain support for SSL. To use SSL you can either compile MongoDB with SSL support or use MongoDB Enterprise. See Connect to MongoDB with SSL for more information about SSL and MongoDB.

When specified, mongod or mongos will use the FIPS mode of the installed OpenSSL library. Your system must have a FIPS compliant OpenSSL library to use sslFIPSMode.