Configuration File Options

The following page describes the configuration options available in MongoDB 3.6. For configuration file options for other versions of MongoDB, see the appropriate version of the MongoDB Manual.

Configuration File

You can configure mongod and mongos instances at startup using a configuration file. The configuration file contains settings that are equivalent to the mongod and mongos command-line options.

Using a configuration file makes managing mongod and mongos options easier, especially for large-scale deployments. You can also add comments to the configuration file to explain the server’s settings.

  • On Linux, a default /etc/mongod.conf configuration file is included when using a package manager to install MongoDB.
  • On macOS, a default /usr/local/etc/mongod.conf configuration file is included when installing from MongoDB’s official Homebrew tap.

File Format

Changed in version 2.6: MongoDB 2.6 introduced a YAML-based configuration file format. The 2.4 configuration file format remains for backward compatibility.

MongoDB configuration files use the YAML format [1].

The following sample configuration file contains several mongod settings that you may adapt to your local configuration:

Note

YAML does not support tab characters for indentation: use spaces instead.

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

The Linux package init scripts included in the official MongoDB packages depend on specific values for systemLog.path, storage.dbPath, and processManagement.fork. If you modify these settings in the default configuration file, mongod may not start.

[1] YAML is a superset of JSON.

Use the Configuration File

To start mongod or mongos using a config file, specify the config file with the --config option or the -f option, as in the following examples:

The following examples use mongod --config and mongos --config to specify the configuration file:

mongod --config /etc/mongod.conf

mongos --config /etc/mongos.conf

You can also use the -f alias to specify the configuration file, as in the following:

mongod -f /etc/mongod.conf

mongos -f /etc/mongos.conf

If you installed from a package and have started MongoDB using your system’s init script, you are already using a configuration file.

Core Options

systemLog Options

systemLog:
   verbosity: <int>
   quiet: <boolean>
   traceAllExceptions: <boolean>
   syslogFacility: <string>
   path: <string>
   logAppend: <boolean>
   logRotate: <string>
   destination: <string>
   timeStampFormat: <string>
   component:
      accessControl:
         verbosity: <int>
      command:
         verbosity: <int>

      # COMMENT additional component verbosity settings omitted for brevity
systemLog. verbosity

Type: integer

Default: 0

Changed in version 3.0.

The default log message verbosity level for components. 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.

To use a different verbosity level for a named component, use the component’s verbosity setting. For example, use the systemLog.component.accessControl.verbosity to set the verbosity level specifically for ACCESS components.

See the systemLog.component.<name>.verbosity settings for specific component verbosity settings.

For various ways to set the log verbosity level, see Configure Log Verbosity Levels.

systemLog. quiet

Type: boolean

Run mongos or mongod in a quiet mode that attempts to limit the amount of output.

systemLog.quiet is not recommended for production systems as it may make tracking problems during particular connections much more difficult.

systemLog. traceAllExceptions

Type: boolean

Print verbose information for debugging. Use for additional logging for support-related troubleshooting.

systemLog. syslogFacility

Type: string

Default: user

The facility level used when logging messages to syslog. The value you specify must be supported by your operating system’s implementation of syslog. To use this option, you must set systemLog.destination to syslog.

systemLog. path

Type: string

The path of the log file to which mongod or mongos should send all diagnostic logging information, rather than the standard output or the host’s syslog. MongoDB creates the log file at the specified path.

The Linux package init scripts do not expect systemLog.path to change from the defaults. If you use the Linux packages and change systemLog.path, you will have to use your own init scripts and disable the built-in scripts.

systemLog. logAppend

Type: boolean

Default: false

When true, mongos or mongod appends new entries to the end of the existing log file when the mongos or mongod instance restarts. Without this option, mongod will back up the existing log and create a new file.

systemLog. logRotate

Type: string

Default: rename

New in version 3.0.0.

The behavior for the logRotate command. Specify either rename or reopen:

  • rename renames the log file.

  • reopen closes and reopens the log file following the typical Linux/Unix log rotate behavior. Use reopen when using the Linux/Unix logrotate utility to avoid log loss.

    If you specify reopen, you must also set systemLog.logAppend to true.

systemLog. destination

Type: string

The destination to which MongoDB sends all log output. Specify either file or syslog. If you specify file, you must also specify systemLog.path.

If you do not specify systemLog.destination, MongoDB sends all log output to standard output.

Warning

The syslog daemon generates timestamps when it logs a message, not when MongoDB issues the message. This can lead to misleading timestamps for log entries, especially when the system is under heavy load. We recommend using the file option for production systems to ensure accurate timestamps.

systemLog. timeStampFormat

Type: string

Default: iso8601-local

The time format for timestamps in log messages. Specify one of the following values:

Value Description
ctime Displays timestamps as Wed Dec 31 18:17:54.811.
iso8601-utc Displays timestamps in Coordinated Universal Time (UTC) in the ISO-8601 format. For example, for New York at the start of the Epoch: 1970-01-01T00:00:00.000Z
iso8601-local Displays timestamps in local time in the ISO-8601 format. For example, for New York at the start of the Epoch: 1969-12-31T19:00:00.000-0500

systemLog.component Options

systemLog:
   component:
      accessControl:
         verbosity: <int>
      command:
         verbosity: <int>

      # COMMENT some component verbosity settings omitted for brevity

      replication:
         verbosity: <int>
         heartbeats:
            verbosity: <int>
         rollback:
            verbosity: <int>
      storage:
         verbosity: <int>
         journal:
            verbosity: <int>
      write:
         verbosity: <int>
systemLog.component.accessControl. verbosity

Type: integer

Default: 0

New in version 3.0.

The log message verbosity level for components related to access control. See ACCESS components.

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.
systemLog.component.command. verbosity

Type: integer

D