- Reference >
- Configuration File 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:
Declare all settings in this file using the following form:
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 enableverbose
or to enable increased verbosity withvvvv
, set these options as in the following example:MongoDB has the following levels of verbosity:
-
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
ormongos
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
ormongos
process to bind to and listen for connections from applications on this address. You may attachmongod
ormongos
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
ormongos
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 setmaxConns
, 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
becametrue
in 2.4. In earlier versionsobjcheck
wasfalse
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 setnoobjcheck
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. Unlesslogappend
istrue
, 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
.
-
pidfilepath
¶ Default: None.
Specify a file location to hold the PID or process ID of the
mongod
process. Useful for tracking themongod
process in combination with thefork
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
andmongod
instances of a sharded cluster or replica set.See also
-
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, orbind_ip
is not set, orbind_ip
does not specify127.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. orbind_ip
does not specify127.0.0.1
.
-
fork
¶ Default: false
Set to
true
to enable a daemon mode formongod
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. ThesetParameter
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 forcemongod
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 thelogpath
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 thedbpath
.
-
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 themdiaglog.<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:diaglog
is for internal use and not intended for most users.Warning
Setting the diagnostic level to
0
will causemongod
to stop writing data to the diagnostic log file. However, themongod
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 themongod
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 thedbpath
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 anddbpath
, and you want to enabledirectoryperdb
, you must migrate your existing databases to directories before settingdirectoryperdb
to access those databases.Example
Given a
dbpath
directory with the following items:To enable
directoryperdb
you would need to modify thedbpath
to resemble the following:
-
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 setsmallfiles
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 specifyj:true
. When a write operation withj:true
is pending,mongod
will reducejournalCommitInterval
to a third of the set value.
-
ipv6
¶ Default: false
Set to
true
to IPv6 support to allow clients to connect tomongod
using IPv6 networks.mongod
disables IPv6 support by default inmongod
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 therest
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 formongos
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 bylogpath
. 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, whenquota
is true. Adjust the quota size with the with thequotaFiles
setting.
-
quotaFiles
¶ Default: 8
Modify limit on the number of data files per database. This option requires the
quota
setting.
-
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.
-
repairpath
¶ Default: A
_tmp
directory in thedbpath
.Specify the path to the directory containing MongoDB data files, to use in conjunction with the
repair
setting ormongod --repair
operation. Defaults to a_tmp
directory within thedbpath
.
-
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 thesystem.profile
collection.See also
-
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. Thesmallfiles
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. Thesmallfiles
setting can leadmongod
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 thebackgroundFlushing
field.syncdelay
has no effect on thejournal
files or journaling.Warning
If you set
syncdelay
to0
, 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 thesysinfo
, onlymongod
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 thedbpath
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
ormongos
instance in a quiet mode that attempts to limit the amount of output. This option suppresses:- output from database commands,
including
drop
,dropIndexes
,diagLogging
,validate
, andclean
. - replication activity.
- connection accepted events.
- connection closed events.
Note
For production systems this option is not recommended as it may make tracking problems during particular connections much more difficult.
- output from database commands,
including
-
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. ThesetParameter
database command provides access to many of these parameters.Declare all
setParameter
settings in this file using the following form:For
mongod
the following options are available usingsetParameter
:enableLocalhostAuthBypass
enableTestCommands
journalCommitInterval
logLevel
logUserIds
notablescan
quiet
replApplyBatchSize
replIndexPrefetch
supportCompatibilityFormPrivilegeDocuments
syncdelay
textSearchEnabled
traceExceptions
For
mongos
the following options are available usingsetParameter
:
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.
See also
Replication, Replica Set Deployment Tutorials, and Replica Set Configuration
-
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, changingoplogSize
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 themongod
will attempt to perform an initial sync, as though the member were a new member.
-
replIndexPrefetch
¶ New in version 2.2.
Default:
all
Values:
all
,none
, and_id_only
You can only use
replIndexPrefetch
in conjunction withreplSet
.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
ornone
to prevent themongod
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
-
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, setautoresync
totrue
to force the slave to automatically resync if it is more than 10 seconds behind the master. This setting may be problematic if theoplogSize
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 theautoresync
option tofalse
, 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 thismongod
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 thanconfig
andadmin
. The default port for amongod
with this option is27019
and the defaultdbpath
directory is/data/configdb
, unless specified.Changed in version 2.2:
configsvr
also setssmallfiles
.Do not use
configsvr
withreplSet
orshardsvr
. Config servers cannot be a shard server or part of a replica set.default port for
mongod
with this option is27019
andmongod
writes all data files to the/configdb
sub-directory of thedbpath
directory.
Default: false
Set this value to
true
to configure thismongod
instance as a shard in a partitioned cluster. The default port for these instances is27018
. The only effect ofshardsvr
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. Allmongos
instances must specify the hosts to theconfigdb
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 yourmongos
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 thatmongos
uses when selecting replica set members to pass reads operations to from clients. Specify a value tolocalThreshold
in milliseconds. The default value is15
, 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, themongos
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 themongos
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 onmongos
instances.New in version 2.0.7.
noAutoSplit
disablesmongos
from automatically splitting chunks for sharded collections. If set on allmongos
, 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 setnoAutoSplit
on allmongos
.Warning
With
noAutoSplit
specified, the data in your sharded cluster may become imbalanced over time. Use the option with caution.
-
moveParanoia
¶ Default: false
New in version 2.4.
During chunk migrations,
moveParanoia
forces themongod
instances to save all documents migrated from this shard in themoveChunk
directory of thedbpath
. MongoDB does not delete data from this directory.Prior to 2.4,
moveParanoia
behavior 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
ormongos
. With--sslOnNormalPorts
, amongod
ormongos
requires SSL encryption for all connections on the default MongoDB port, or the port specified by--port
. By default,--sslOnNormalPorts
is disabled.
-
--sslPEMKeyFile
<filename>
¶ 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 pathsWhen using
--sslOnNormalPorts
, you must specify--sslPEMKeyFile
.
-
--sslPEMKeyPassword
<value>
¶ 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
ormongos
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 versionsmongod
ormongos
would require--sslPEMKeyPassword
whenever using--sslOnNormalPorts
, even when the private key was not encrypted.
-
--sslCAFile
<filename>
¶ 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
<filename>
¶ 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
-
--sslWeakCertificateValidation
¶
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--sslWeakCertificateValidation
,mongod
ormongos
will accept connections if the client does not present a certificate when establishing the connection.If the client presents a certificate and
mongod
ormongos
has--sslWeakCertificateValidation
enabled,mongod
ormongos
will validate the certificate using the root certificate chain specified by--sslCAFile
, and reject clients with invalid certificates.Use
--sslWeakCertificateValidation
if you have a mixed deployment that includes clients that do not or cannot present certificates tomongod
ormongos
.
-
--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
ormongos
will use the FIPS mode of the installed OpenSSL library. Your system must have a FIPS compliant OpenSSL library to use--sslFIPSMode
.