Find file
Fetching contributors…
Cannot retrieve contributors at this time
795 lines (561 sloc) 26.5 KB
Production Notes
.. default-domain:: mongodb
.. contents:: On this page
:backlinks: none
:depth: 1
:class: twocols
This page details system configurations that affect MongoDB,
especially when running in production.
.. include:: /includes/fact-mms-summary.rst
MongoDB Binaries
.. _prod-notes-supported-platforms:
Supported Platforms
MongoDB provides builds for the following supported platforms. For
running **in production**, refer to the
:ref:`prod-notes-recommended-platforms` for operating system
.. include:: /includes/fact-platforms.rst
.. versionchanged:: 3.2
MongoDB can now use the :ref:`WiredTiger storage engine <storage-wiredtiger>`
on all supported platforms.
.. _prod-notes-recommended-platforms:
Recommended Platforms
While MongoDB supports a variety of platorms, the following operating
systems are recommended for production use:
- Amazon Linux
- Debian 7.1
- RHEL / CentOS 6.2+
- SLES 11+
- Ubuntu LTS 12.04
- Ubuntu LTS 14.04
- Windows Server 2012 & 2012 R2
.. seealso:: :ref:`prod-notes-platform-considerations`
Use the Latest Stable Packages
Be sure you have the latest stable release.
All MongoDB releases are available on the `Downloads
<>`_ page. The `Downloads
<>`_ page is a good place to verify the
current stable release, even if you are installing via a package
Use 64-bit Builds
Always use 64-bit builds for production.
.. important::
.. include:: /includes/fact-deprecated-32bit.rst
Although the 32-bit builds exist for Linux and Windows, they are **unsuitable** for
production deployments. 32-bit builds also do **not** support the
WiredTiger storage engine. For more information, see the :ref:`32-bit
limitations page <faq-32-bit-limitations>`
MongoDB ``dbPath``
The files in the :setting:`~storage.dbPath` directory must correspond
to the configured :term:`storage engine`. :program:`mongod` will not start if
:setting:`~storage.dbPath` contains data files created by a storage
engine other than the one specified by :option:`--storageEngine`.
.. versionchanged:: 3.2
As of MongoDB 3.2, MongoDB uses the :ref:`WiredTiger
<storage-wiredtiger>` storage engine by default.
.. versionchanged:: 3.0
MongoDB includes support for two storage engines: :ref:`MMAPv1
<storage-mmapv1>`, the storage engine available in previous versions
of MongoDB, and :ref:`WiredTiger <storage-wiredtiger>`.
:program:`mongod` must possess read and write permissions for the specified
.. _prod-notes-concurrency:
.. versionchanged:: 3.0
Beginning with MongoDB 3.0, :ref:`MMAPv1 <storage-mmapv1>` provides
*collection-level locking*: All collections have a unique
readers-writer lock that allows multiple clients to modify documents
in different collections at the same time.
For MongoDB versions 2.2 through 2.6 series, each database has a
readers-writer lock that allows concurrent read access to a
database, but gives exclusive access to a single write operation per
database. See the :doc:`Concurrency </faq/concurrency>` page for
more information. In earlier versions of MongoDB, all write
operations contended for a single readers-writer lock for the entire
:program:`mongod` instance.
.. _prod-notes-wired-tiger-concurrency:
:ref:`WiredTiger <storage-wiredtiger>` supports concurrent access by
readers and writers to the documents in a collection. Clients can read
documents while write operations are in progress, and multiple threads
can modify different documents in a collection at the same time.
.. seealso:: :ref:`prod-notes-ram` provides information about how WiredTiger
takes advantage of multiple CPU cores and how to improve operation
Data Consistency
MongoDB uses *write ahead logging* to an on-disk :term:`journal`.
Journaling guarantees that MongoDB can quickly recover :doc:`write
operations </crud>` that were written to the journal
but not written to data files in cases where :program:`mongod`
terminated due to a crash or other serious failure.
Leave journaling enabled in order to ensure that :program:`mongod` will
be able to recover its data files and keep the data files in a valid
state following a crash. See :doc:`Journaling </core/journaling/>` for
more information.
Read Concern
.. versionadded:: 3.2
If using :readconcern:`"majority"` :doc:`read concern
</reference/read-concern>`, use :writeconcern:`{ w: "majority" }
<"majority">` :doc:`write concern </reference/write-concern>` for write
operations to ensure that a single thread can read its own writes.
.. include:: /includes/fact-enable-majority-readConcern.rst
Write Concern
.. include:: /includes/introduction-write-concern.rst
See the :doc:`Write Concern </reference/write-concern>` document for more
information about choosing an appropriate write concern level for your
Use Trusted Networking Environments
Always run MongoDB in a *trusted environment*, with network rules that
prevent access from *all* unknown machines, systems, and networks. As
with any sensitive system that is dependent on network access, your
MongoDB deployment should only be accessible to specific systems that
require access, such as application servers, monitoring services, and
other MongoDB components.
.. important::
By default, :doc:`authorization </core/authorization>` is not
enabled, and :program:`mongod` assumes a trusted environment. Enable
:setting:`~security.authorization` mode as needed. For more
information on authentication mechanisms supported in MongoDB as
well as authorization in MongoDB, see :doc:`/core/authentication`
and :doc:`/core/authorization`.
For additional information and considerations on security, refer to the
documents in the :doc:`Security Section </security>`, specifically:
- :doc:`/administration/security-checklist`
- :doc:`/core/security-mongodb-configuration`
- :doc:`/core/security-network`
For Windows users, consider the `Windows Server Technet Article on TCP
Configuration <>`_
when deploying MongoDB on Windows.
Disable HTTP Interface
MongoDB provides an HTTP interface to check the status of the server
and, optionally, run queries. The HTTP interface is disabled by default. Do
not enable the HTTP interface in production environments.
.. include:: /includes/fact-deprecated-http-interface.rst
See :ref:`http-interface-security`.
.. _prod-notes-connection-pools:
Manage Connection Pool Sizes
Avoid overloading the connection resources of a :program:`mongod` or
:program:`mongos` instance by adjusting the connection pool size to suit
your use case. Start at 110-115% of the typical number of current database
requests, and modify the connection pool size as needed. Refer to the
:ref:`connection-pool-options` for adjusting the connection pool size.
The :dbcommand:`connPoolStats` command returns information regarding
the number of open connections to the current database for
:program:`mongos` and :program:`mongod` instances in sharded clusters.
See also :ref:`prod-notes-ram`.
Hardware Considerations
MongoDB is designed specifically with commodity hardware in mind and
has few hardware requirements or limitations. MongoDB's core components
run on little-endian hardware, primarily x86/x86_64 processors. Client
libraries (i.e. drivers) can run on big or little endian systems.
.. _prod-notes-ram:
Allocate Sufficient RAM and CPU
Due to its concurrency model, the :ref:`MMAPv1 <storage-mmapv1>` storage engine does not
require many CPU cores. As such, increasing the number of cores can
improve performance but does not provide significant return.
At a minimum, ensure that your :program:`mongod` or :program:`mongos`
has access to two real cores or one physical CPU.
Increasing the amount of RAM accessible to MongoDB may help reduce the
frequency of page faults.
The :ref:`WiredTiger <storage-wiredtiger>` storage engine is multithreaded and can take advantage
of additional CPU cores. Specifically, the total number of active threads
(i.e. concurrent operations) relative to the number of available CPUs can impact
- Throughput *increases* as the number of concurrent active operations
increases up to the number of CPUs.
- Throughput *decreases* as the number of concurrent active operations
exceeds the number of CPUs by some threshold amount.
The threshold depends on your application. You can determine the
optimum number of concurrent active operations for your application by
experimenting and measuring throughput. The output from
:program:`mongostat` provides statistics on the number of active
reads/writes in the (``ar|aw``) column.
.. include:: /includes/extracts/wt-configure-cache.rst
.. seealso:: :ref:`prod-notes-concurrency`
Use Solid State Disks (SSDs)
MongoDB has good results and a good price-performance ratio with
SATA SSD (Solid State Disk).
Use SSD if available and economical. Spinning disks can be
performant, but SSDs' capacity for random I/O operations works well
with the update model of MMAPv1.
Commodity (SATA) spinning drives are often a good option, as the
random I/O performance increase with more expensive spinning drives
is not that dramatic (only on the order of 2x). Using SSDs or
increasing RAM may be more effective in increasing I/O throughput.
.. _production-numa:
MongoDB and NUMA Hardware
Running MongoDB on a system with Non-Uniform Access Memory (NUMA) can
cause a number of operational problems, including slow performance for
periods of time and high system process usage.
When running MongoDB servers and clients on NUMA hardware, you should configure
a memory interleave policy so that the host behaves in a non-NUMA fashion.
MongoDB checks NUMA settings on start up when deployed on Linux (since version
2.0) and Windows (since version 2.6) machines. If the
NUMA configuration may degrade performance, MongoDB prints a warning.
.. seealso::
- `The MySQL "swap insanity" problem and the effects of NUMA
post, which describes the effects of
NUMA on databases. The post introduces NUMA and its goals, and
illustrates how these goals are not compatible with production
databases. Although the blog post addresses the impact of NUMA for
MySQL, the issues for MongoDB are similar.
- `NUMA: An Overview <>`_.
Configuring NUMA on Windows
On Windows, memory interleaving must be enabled through the machine's BIOS.
Consult your system documentation for details.
Configuring NUMA on Linux
When running MongoDB on Linux, you should disable *zone reclaim* in the
``sysctl`` settings using one of the following commands:
.. code-block:: sh
echo 0 | sudo tee /proc/sys/vm/zone_reclaim_mode
.. code-block:: sh
sudo sysctl -w vm.zone_reclaim_mode=0
Then, you should use the ``numactl`` command to start the MongoDB programs
(:program:`mongod`, including the :doc:`config servers
</core/sharded-cluster-config-servers>`; :program:`mongos`; and clients) in
the following manner:
.. code-block:: sh
numactl --interleave=all <path> <options>
where ``<path>`` is the path to the program you are starting, and ``<options>``
are any optional arguments to pass to the program.
To fully disable NUMA behavior, you must perform both operations. For more
information, see the `Documentation for /proc/sys/vm/*
Disk and Storage Systems
Assign swap space for your systems. Allocating swap space can avoid issues
with memory contention and can prevent the OOM Killer on Linux systems
from killing :program:`mongod`.
For the MMAPv1 storage engine, the method :program:`mongod` uses
to map files to memory ensures that the operating system will never
store MongoDB data in swap space. On Windows systems, using MMAPv1
requires extra swap space due to commitment limits. For details,
see :ref:`MongoDB on Windows <production-windows-pagefile>`.
For the WiredTiger storage engine, given sufficient memory pressure,
WiredTiger may store data in swap space.
Most MongoDB deployments should use disks backed by RAID-10.
RAID-5 and RAID-6 do not typically provide sufficient performance to
support a MongoDB deployment.
Avoid RAID-0 with MongoDB deployments. While RAID-0 provides good write
performance, it also provides limited availability and can lead to
reduced performance on read operations, particularly when using
Amazon's EBS volumes.
.. _production-nfs:
Remote Filesystems
With the MMAPv1 storage engine, the Network File System protocol (NFS)
is not recommended as you may see performance problems when both the
data files and the journal files are hosted on NFS. You may experience
better performance if you place the journal on local or ``iscsi``
With the WiredTiger storage engine, WiredTiger objects may be stored on
remote file systems if the remote file system conforms to ISO/IEC
9945-1:1996 (POSIX.1). Because remote file systems are often slower
than local file systems, using a remote file system for storage may
degrade performance.
If you decide to use NFS, add the following NFS options to your
``/etc/fstab`` file: ``bg``, ``nolock``, and ``noatime``.
Separate Components onto Different Storage Devices
For improved performance, consider separating your database's data,
journal, and logs onto different storage devices, based on your application's
access and write pattern.
For the WiredTiger storage engine, you can also store the indexes on a
different storage device. See
.. note::
Using different storage devices will affect your ability to create
snapshot-style backups of your data, since the files will be on
different devices and volumes.
.. _virtualized-disks-scheduling:
Scheduling for Virtual Devices
Local block devices attached to virtual machine instances via the
hypervisor should use a *noop* scheduler for best performance. The
*noop* scheduler allows the operating system to defer I/O scheduling to
the underlying hypervisor.
Replica Sets
See the :doc:`Replica Set Architectures </core/replica-set-architectures>`
document for an overview of architectural considerations for replica
set deployments.
Sharded Clusters
See :doc:`Sharded Cluster Production Architecture
</core/sharded-cluster-components>` for an
overview of recommended sharded cluster architectures for production
.. seealso:: :doc:`/administration/production-checklist-development`
WiredTiger can compress collection data using either :term:`snappy` or
:term:`zlib` compression library. :term:`snappy` provides a lower
compression rate but has little performance cost, whereas ``zlib``
provides better compression rate but has a higher performance cost.
By default, WiredTiger uses :term:`snappy` compression library. To
change the compression setting, see
WiredTiger uses :term:`prefix compression` on all indexes by default.
.. _prod-notes-platform-considerations:
Platform Specific Considerations
.. include:: /includes/note-minimum-glibc.rst
MongoDB on Linux
Kernel and File Systems
When running MongoDB in production on Linux, you should use Linux
kernel version 2.6.36 or later, with either the XFS or EXT4 filesystem.
If possible, use XFS as it generally performs better with MongoDB.
With the :ref:`WiredTiger storage engine <storage-wiredtiger>`, use of
XFS is **strongly recommended** to avoid performance issues that may
occur when using EXT4 with WiredTiger.
With the :ref:`MMAPv1 storage engine <storage-mmapv1>`, MongoDB
preallocates its database files before using them and often creates
large files. As such, you should use the XFS or EXT4 file systems. If
possible, use XFS as it generally performs better with MongoDB.
- In general, if you use the XFS file system, use at least version
``2.6.25`` of the Linux Kernel.
.. Required for fallocate()
- If you use the EXT4 file system, use at least version
``2.6.28`` of the Linux Kernel.
- On Red Hat Enterprise Linux and CentOS, use at least version
``2.6.18-194`` of the Linux kernel.
``fsync()`` on Directories
.. important::
MongoDB requires a filesystem that supports ``fsync()``
*on directories*. For example, HGFS and Virtual Box's shared
folders do *not* support this operation.
.. _linux-recommended-configuration:
Recommended Configuration
For **all** MongoDB deployments:
- Use the Network Time Protocol (NTP) to synchronize time among
your hosts. This is especially important in sharded clusters.
For the **WiredTiger and MMAPv1** storage engines,
consider the following recommendations:
- Turn off ``atime`` for the storage volume containing the :term:`database
files <dbpath>`.
- Set the file descriptor limit, ``-n``, and the user process limit
(ulimit), ``-u``, above 20,000, according to the suggestions in the
:doc:`ulimit </reference/ulimit>` reference. A low ulimit will affect
MongoDB when under heavy use and can produce errors and lead to
failed connections to MongoDB processes and loss of service.
- Disable Transparent Huge Pages. MongoDB performs better with
normal (4096 bytes) virtual memory pages. See :doc:`Transparent Huge
Pages Settings </tutorial/transparent-huge-pages>`.
- Disable NUMA in your BIOS. If that is not possible, see
:ref:`MongoDB on NUMA Hardware <production-numa>`.
- Problems have been reported when using MongoDB with SELinux enabled.
To avoid issues, disable SELinux when possible.
If you are using SELinux on Red Hat, you must configure SELinux
to be able to run MongoDB. See:
:ref:`Configure SELinux for MongoDB <install-rhel-configure-selinux>`
and :ref:`Configure SELinux for MongoDB Enterprise
<install-enterprise-rhel-configure-selinux>` for the required
.. include:: /includes/fact-selinux-server-side-js.rst
For the **MMAPv1** storage engine:
.. _readahead:
- Ensure that readahead settings for the block devices that store the
database files are appropriate. For random access use patterns, set
low readahead values. A readahead of 32 (16 kB) often works well.
For a standard block device, you can run ``sudo blockdev --report``
to get the readahead settings and ``sudo blockdev --setra <value>
<device>`` to change the readahead settings. Refer to your specific
operating system manual for more information.
MongoDB and TLS/SSL Libraries
On Linux platforms, you may observe one of the following statements in
the MongoDB log:
.. code-block:: none
<path to SSL libs>/<version>: no version information available (required by /usr/bin/mongod)
<path to SSL libs>/<version>: no version information available (required by /usr/bin/mongod)
These warnings indicate that the system's TLS/SSL libraries are different
from the TLS/SSL libraries that the :program:`mongod` was compiled against.
Typically these messages do not require intervention; however, you can
use the following operations to determine the symbol versions that
:program:`mongod` expects:
.. code-block:: sh
objdump -T <path to mongod>/mongod | grep " SSL_"
objdump -T <path to mongod>/mongod | grep " CRYPTO_"
These operations will return output that resembles one the of the
following lines:
.. code-block:: none
0000000000000000 DF *UND* 0000000000000000 SSL_write
0000000000000000 DF *UND* 0000000000000000 OPENSSL_1.0.0 SSL_write
The last two strings in this output are the symbol version and symbol
name. Compare these values with the values returned by the following
operations to detect symbol version mismatches:
.. code-block:: sh
objdump -T <path to TLS/SSL libs>/*
objdump -T <path to TLS/SSL libs>/*
This procedure is neither exact nor exhaustive: many symbols used by
:program:`mongod` from the ``libcrypto`` library do not begin with
.. _production-virtualization:
MongoDB on Windows
MongoDB 3.0 Using WiredTiger
For MongoDB instances using the WiredTiger storage engine, performance
on Windows is comparable to performance on Linux.
MongoDB Using MMAPv1
Install Hotfix for MongoDB 2.6.6 and Later
Microsoft has released a hotfix for Windows 7 and Windows Server 2008
R2, `KB2731284 <>`_, that repairs a bug
in these operating systems' use of memory-mapped files that adversely affects
the performance of MongoDB using the MMAPv1 storage engine.
Install this hotfix to obtain significant performance improvements on MongoDB
2.6.6 and later releases in the 2.6 series, which use MMAPv1 exclusively,
and on 3.0 and later when using MMAPv1 as the storage engine.
.. _production-windows-pagefile:
Configure Windows Page File For MMAPv1
Configure the page file such that the minimum and maximum page file
size are equal and at least 32 GB. Use a multiple of this size if,
during peak usage, you expect concurrent writes to many databases or
collections. However, the page file size does not need to exceed the
maximum size of the database.
A large page file is needed as Windows requires enough space to
accommodate all regions of memory mapped files made writable during
peak usage, regardless of whether writes actually occur.
The page file is not used for database storage and will not receive
writes during normal MongoDB operation. As such, the page file will not
affect performance, but it must exist and be large enough to
accommodate Windows' commitment rules during peak database use.
.. note::
Dynamic page file sizing is too slow to accommodate the rapidly
fluctuating commit charge of an active MongoDB deployment. This can
result in transient overcommitment situations that may lead to
abrupt server shutdown with a VirtualProtect error 1455.
MongoDB on Virtual Environments
This section describes considerations when running MongoDB in some of the
more common virtual environments.
For all platforms, consider :ref:`virtualized-disks-scheduling`.
MongoDB is compatible with EC2.
|mms-home| provides
integration with Amazon Web Services (AWS) and lets you deploy new EC2
instances directly from |MMS|. See :mms-docs:`Configure AWS Integration
</tutorial/configure-aws-settings/>` for more details.
Use `Premium Storage
Microsoft Azure offers two general types of storage:
Standard storage, and Premium storage. MongoDB on Azure has better
performance when using Premium storage than it does with Standard
For all :ref:`MMAPv1 <storage-mmapv1>` MongoDB deployments using Azure,
you **must** mount the volume
that hosts the :program:`mongod` instance's :setting:`~storage.dbPath`
with the *Host Cache Preference* ``READ/WRITE``.
This applies to all Azure deployments running MMAPv1, using any guest operating
If your volumes have inappropriate cache settings, MongoDB may
eventually shut down with the following error:
.. code-block:: none
[DataFileSync] FlushViewOfFile for <data file> failed with error 1 ...
[DataFileSync] Fatal Assertion 16387
These shut downs do not produce data loss when
:setting:`storage.journal.enabled` is set to ``true``. You can safely
restart :program:`mongod` at any time following this event.
The performance characteristics of MongoDB may change with
``READ/WRITE`` caching enabled.
The TCP keepalive on the Azure load balancer is 240 seconds by
default, which can cause it to silently drop connections if the TCP
keepalive on your Azure systems is greater than this value. You
should set ``tcp_keepalive_time`` to 120 to ameliorate this problem.
.. include:: /includes/fact-tcp-keepalive-linux.rst
.. include:: /includes/fact-tcp-keepalive-windows.rst
.. include:: /includes/extracts/vm-memory-considerations-vmware.rst
Disable VMWare's Migration with vMotion ("live migration"). The live migration of
a virtual machine can cause performance problems and affect
:doc:`replica set </core/replica-set-high-availability>` and
:doc:`sharded cluster high availability
</tutorial/troubleshoot-sharded-clusters>` mechanisms.
It is possible to clone a virtual machine running MongoDB.
You might use this function to
spin up a new virtual host to add as a member of a replica
set. If you clone a VM with journaling enabled, the clone snapshot will
be valid. If not using journaling, first stop :program:`mongod`,
then clone the VM, and finally, restart :program:`mongod`.
.. include:: /includes/extracts/vm-memory-considerations-kvm.rst
Performance Monitoring
On Linux, use the ``iostat`` command to check if disk I/O is a bottleneck
for your database. Specify a number of seconds when running iostat to
avoid displaying stats covering the time since server boot.
For example, the following command will display extended statistics and
the time for each displayed report, with traffic in MB/s, at one second
.. code-block:: bash
iostat -xmt 1
Key fields from ``iostat``:
- ``%util``: this is the most useful field for a quick check, it
indicates what percent of the time the device/drive is in use.
- ``avgrq-sz``: average request size. Smaller number for this value
reflect more random IO operations.
`bwm-ng <>`_ is a
command-line tool for monitoring network use. If you suspect a
network-based bottleneck, you may use ``bwm-ng`` to begin your
diagnostic process.
To make backups of your MongoDB database, please refer to
:doc:`MongoDB Backup Methods Overview </core/backups>`.
.. include:: /includes/unicode-checkmark.rst