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

Run-time Database Configuration

On this page

The command line and configuration file interfaces provide MongoDB administrators with a large number of options and settings for controlling the operation of the database system. This document provides an overview of common configurations and examples of best-practice configurations for common use cases.

While both interfaces provide access to the same collection of options and settings, this document primarily uses the configuration file interface. If you run MongoDB using a init script or if you installed from a package for your operating system, you likely already have a configuration file located at /etc/mongod.conf. Confirm this by checking the contents of the /etc/init.d/mongod or /etc/rc.d/mongod script to ensure that the init scripts start the mongod with the appropriate configuration file.

To start a MongoDB instance using this configuration file, issue a command in the following form:

copy 
mongod --config /etc/mongod.conf
mongod -f /etc/mongod.conf

Modify the values in the /etc/mongod.conf file on your system to control the configuration of your database instance.

Configure the Database

Consider the following basic configuration which uses the YAML format:

copy 
processManagement:
   fork: true
net:
   bindIp: 127.0.0.1
   port: 27017
storage:
   dbPath: /srv/mongodb
systemLog:
   destination: file
   path: "/var/log/mongodb/mongod.log"
   logAppend: true
storage:
   journal:
      enabled: true

Or, if using the older .ini configuration file format:

copy 
fork = true
bind_ip = 127.0.0.1
port = 27017
quiet = true
dbpath = /srv/mongodb
logpath = /var/log/mongodb/mongod.log
logappend = true
journal = true

For most standalone servers, this is a sufficient base configuration. It makes several assumptions, but consider the following explanation:

  • fork is true, which enables a daemon mode for mongod, which detaches (i.e. “forks”) the MongoDB from the current session and allows you to run the database as a conventional server.

  • bindIp is 127.0.0.1, which forces the server to only listen for requests on the localhost IP. Only bind to secure interfaces that the application-level systems can access with access control provided by system network filtering (i.e. “firewall”).

    New in version 2.6: mongod installed from official .deb and .rpm packages have the bind_ip configuration set to 127.0.0.1 by default.

  • port is 27017, which is the default MongoDB port for database instances. MongoDB can bind to any port. You can also filter access based on port using network filtering tools.

    Note

    UNIX-like systems require superuser privileges to attach processes to ports lower than 1024.

  • quiet is true. This disables all but the most critical entries in output/log file, and is not recommended for production systems. If you do set this option, you can use setParameter to modify this setting during run time.

  • dbPath is /srv/mongodb, which specifies where MongoDB will store its data files. /srv/mongodb and /var/lib/mongodb are popular locations. The user account that mongod runs under will need read and write access to this directory.

  • systemLog.path is /var/log/mongodb/mongod.log which is where mongod will write its output. If you do not set this value, mongod writes all output to standard output (e.g. stdout.)

  • logAppend is true, which ensures that mongod does not overwrite an existing log file following the server start operation.

  • storage.journal.enabled is true, which enables journaling. Journaling ensures single instance write-durability. 64-bit builds of mongod enable journaling by default. Thus, this setting may be redundant.

Given the default configuration, some of these values may be redundant. However, in many situations explicitly stating the configuration increases overall system intelligibility.

Security Considerations

The following collection of configuration options are useful for limiting access to a mongod instance. Consider the following settings, shown in both YAML and older configuration file format:

In YAML format

copy 
security:
   authorization: enabled
net:
   bindIp: 127.0.0.1,10.8.0.10,192.168.4.24

Or, if using the older older configuration file format:

copy 
bind_ip = 127.0.0.1,10.8.0.10,192.168.4.24
auth = true

Consider the following explanation for these configuration decisions:

  • “bindIp” has three values: 127.0.0.1, the localhost interface; 10.8.0.10, a private IP address typically used for local networks and VPN interfaces; and 192.168.4.24, a private network interface typically used for local networks.

    Because production MongoDB instances need to be accessible from multiple database servers, it is important to bind MongoDB to multiple interfaces that are accessible from your application servers. At the same time it’s important to limit these interfaces to interfaces controlled and protected at the network layer.

  • “authorization” is true enables the authorization system within MongoDB. If enabled you will need to log in by connecting over the localhost interface for the first time to create user credentials.

See also

Security

Replication and Sharding Configuration

Replication Configuration

Replica set configuration is straightforward, and only requires that the replSetName have a value that is consistent among all members of the set. Consider the following:

In YAML format

copy 
replication:
   replSetName: set0

Or, if using the older configuration file format:

copy 
replSet = set0

Use descriptive names for sets. Once configured, use the mongo shell to add hosts to the replica set.

See also

Replica set reconfiguration.

To enable authentication for the replica set, add the following keyFile option:

In YAML format

copy 
security:
   keyFile: /srv/mongodb/keyfile

Or, if using the older configuration file format:

copy 
keyFile = /srv/mongodb/keyfile

Setting keyFile enables authentication and specifies a key file for the replica set member use to when authenticating to each other. The content of the key file is arbitrary, but must be the same on all members of the replica set and mongos instances that connect to the set. The keyfile must be less than one kilobyte in size and may only contain characters in the base64 set and the file must not have group or “world” permissions on UNIX systems.

See also

The Replica Set Security section for information on configuring authentication with replica sets.

The Replication document for more information on replication in MongoDB and replica set configuration in general.

Sharding Configuration

Sharding requires a number of mongod instances with different configurations. The config servers store the cluster’s metadata, while the cluster distributes data among one or more shard servers.

Note

Config servers are not replica sets.

To set up one or three “config server” instances as normal mongod instances, and then add the following configuration option:

In YAML format

copy 
sharding:
   clusterRole: configsvr
net:
   bindIp: 10.8.0.12
   port: 27001

Or, if using the older configuration file format:

copy 
configsvr = true

bind_ip = 10.8.0.12
port = 27001

This creates a config server running on the private IP address 10.8.0.12 on port 27001. Make sure that there are no port conflicts, and that your config server is accessible from all of your mongos and mongod instances.

To set up shards, configure two or more mongod instance using your base configuration, with the shardsvr value for the sharding.clusterRole setting:

copy 
sharding:
   clusterRole: shardsvr

Or, if using the older configuration file format:

copy 
shardsvr = true

Finally, to establish the cluster, configure at least one mongos process with the following settings:

In YAML format:

copy 
sharding:
   configDB: 10.8.0.12:27001
   chunkSize: 64

Or, if using the older configuration file format:

copy 
configdb = 10.8.0.12:27001
chunkSize = 64

Important

Always use 3 config servers in production environments.

You can specify multiple configDB instances by specifying hostnames and ports in the form of a comma separated list.

In general, avoid modifying the chunkSize from the default value of 64, [1] and ensure this setting is consistent among all mongos instances.

[1]Chunk size is 64 megabytes by default, which provides the ideal balance between the most even distribution of data, for which smaller chunk sizes are best, and minimizing chunk migration, for which larger chunk sizes are optimal.

See also

The Sharding section of the manual for more information on sharding and cluster configuration.

Run Multiple Database Instances on the Same System

In many cases running multiple instances of mongod on a single system is not recommended. On some types of deployments [2] and for testing purposes you may need to run more than one mongod on a single system.

In these cases, use a base configuration for each instance, but consider the following configuration values:

In YAML format:

copy 
storage:
   dbPath: /srv/mongodb/db0/
processManagement:
   pidFilePath: /srv/mongodb/db0.pid

Or, if using the older configuration file format:

copy 
dbpath = /srv/mongodb/db0/
pidfilepath = /srv/mongodb/db0.pid

The dbPath value controls the location of the mongod instance’s data directory. Ensure that each database has a distinct and well labeled data directory. The pidFilePath controls where mongod process places it’s process id file. As this tracks the specific mongod file, it is crucial that file be unique and well labeled to make it easy to start and stop these processes.

Create additional init scripts and/or adjust your existing MongoDB configuration and init script as needed to control these processes.

[2]Single-tenant systems with SSD or other high performance disks may provide acceptable performance levels for multiple mongod instances. Additionally, you may find that multiple databases with small working sets may function acceptably on a single system.

Diagnostic Configurations

The following configuration options control various mongod behaviors for diagnostic purposes:

  • operationProfiling.mode sets the database profiler level. The profiler is not active by default because of the possible impact on the profiler itself on performance. Unless this setting is on, queries are not profiled.

  • operationProfiling.slowOpThresholdMs configures the threshold which determines whether a query is “slow” for the purpose of the logging system and the profiler. The default value is 100 milliseconds. Set a lower value if the database profiler does not return useful results or a higher value to only log the longest running queries.

  • systemLog.verbosity controls the amount of logging output that mongod write to the log. Only use this option if you are experiencing an issue that is not reflected in the normal logging level.

    Changed in version 3.0: You can also specify verbosity level for specific components using the systemLog.component.<name>.verbosity setting. For the available components, see component verbosity settings.

For more information, see also Database Profiling and Analyzing MongoDB Performance.

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.