If your client will dynamically spawn more child processes as traffic increases (most
application servers will do this), it is important to make sure that these child processes
are not so numerous that they can max out MongoDB’s limits. For example, if you have
20 application servers, each one of which is allowed to spawn 100 child processes and
each child process can spawn 10 threads that all connect to MongoDB, that could spawn
20 × 100 × 10 = 20,000 connections at peak traffic. MongoDB is probably not going to
be very happy about spawning tens of thousands of threads and, if you run out of threads
per process, will simply start refusing new connections.
The other limit to modify is the number of file descriptors MongoDB is allowed to open.
Every incoming and outgoing connection uses a file descriptor, so having the client
connection storm above would create 20,000 open filehandles (incidentally, the maxi‐
mum number MongoDB will allow).
mongos in particular tends to create connections to many shards. When a client connects
to a mongos and makes a request, the mongos opens connections to any and all shards
necessary to fulfill that request. Thus, if a cluster had 100 shards and a client connects
to a mongos and tries to query for all of their data, the mongos must open 100 connec‐
tions: one connection to each shard. This can quickly mount in number of connections,
as you can imagine from the previous example. Suppose a liberally configured app server
made a hundred connections to a mongos process. Then this could get translated to 100
inbound connections × 100 shards = 10,000 connections to shards! (This assumes a
non-targeted query on each connection, which would be a bad design, so this is a
somewhat extreme example).
Thus, there are a couple adjustments to make: many people purposefully configure
mongos processes to only allow a certain number of incoming connections by using the
maxConns option. This is a good way to enforce that your client is behaving well.
You should also increase the limit on the number of file descriptors, as the default (gen‐
erally 1024) is simply too low. Set the max number of file descriptors to unlimited or, if
you’re nervous about that, 20,000. Each system has a different way of changing these
limits, but in general, make sure that you change both the hard and soft limits. A hard
limit is enforced by the kernel and can only be changed by an administrator, versus a
soft limit, which is user-configurable.
If the number of connections is left at 1024, MMS will warn you by displaying the host
in yellow on the host list (as shown in the NUMA example above). If low limits are the
issue, the “Last Ping” tab should display a message similar to that shown in Figure 23-12.
Configuring System Settings | 381
Figure 23-12. MMS low ulimit warning
Even if you have a non-sharded setup and an application that only uses a small number
of connections, increase the hard and soft limits to at least 4096. That will stop MongoDB
from warning you about them and give you some breathing room, just in case.
Configuring Your Network
This section covers which servers should have connectivity to which other servers.
Often, for reasons of network security (and sensibility), you may want to limit the con‐
nectivity of MongoDB servers. Note that multiserver MongoDB deployments should
handle networks being partitioned or down, but it isn’t recommended as a general de‐
For a standalone server, clients must be able to make connections to the mongod.
Members of a replica set must be able to make connections to every other member.
Clients must be able to connect to all nonhidden, nonarbiter members. Depending on
network configuration, members may also attempt to connect to themselves, so you
should allow mongods to create connections to themselves.
Sharding is a bit more complicated. There are four components: mongos servers, shards,
config servers, and clients. Connectivity can be summarized in the following three
• A client must be able to connect to a mongos.
• A mongos must be able to connect to the shards and config servers.
• A shard must be able to connect to the other shards and the config servers.
The full connectivity chart is described in Table 23-1.
Table 23-1. Sharding connectivity
Connectivity from server type
to server type e mongos
Config server r Client
Not required d Not required d Not required d Required
Not required d Not recommended
Config server r Required
Not required d Not recommended
Not required d Not required d Not required d Not MongoDB-related
382 | Chapter 23: Deploying MongoDB
There are three possible values in the table: “Required” means that connectivity between
these two components is required for sharding to work as designed. MongoDB will
attempt to degrade gracefully if it loses these connections due to network issues, but
you shouldn’t purposely configure it that way.
“Not required” means that these two elements never talk in the direction specified, so
no connectivity is needed.
“Not recommended” means that these two elements never talk, but due to user error
they could. For example, it is recommended that clients only make connections to the
mongos, not the shards, so that clients do not inadvertently make requests directly to
shards. Similarly, clients should not be able to directly access config servers so that they
cannot accidentally modify config data.
Note that mongos processes and shards talk to config servers, but config servers don’t
make connections to anyone, even one another.
Shards must communicate during migrates: shards connect to one another directly to
As mentioned earlier, replica set members that compose shards should be able to con‐
nect to themselves.
This section covers some common issues you should be aware of before deploying.
In general, it’s safest to have your systems’ clocks within a second of each other. Replica
sets should be able to handle nearly any clock skew. Sharding can handle some skew (if
it gets beyond a few minutes, you’ll start seeing warnings in the logs), but it’s best to
minimize. Having in-sync clocks also makes figuring out what’s happening from logs
You can keep clocks synchronized using the w32tm tool on Windows and the ntp
daemon on Linux.
The OOM Killer
Very occasionally, MongoDB will allocate enough memory that it will be targeted by
the OOM killer (out-of-memory killer). This particularly tends to happen during index
builds, as that is one of the only times when MongoDB’s resident memory should put
any strain on the system.
System Housekeeping | 383
If your MongoDB process suddenly dies with no errors or exit messages in the logs,
check /var/log/messages (or wherever your kernel logs such things) to see if it has any
messages about terminating mongod.
If the kernel has killed MongoDB for memory overuse, you should see something like
this in the kernel log:
kernel: Killed process 2771 (mongod)
kernel: init invoked oom-killer: gfp_mask=0x201d2, order=0, oomkilladj=0
If you were running with journaling, you can simply restart mongod at this point. If you
were not, restore from a backup or resync the data from a replica.
The OOM killer gets particularly nervous if you have no swap space and start running
low on memory, so a good way to prevent it from going on a spree is to configure a
modest amount of swap. MongoDB should never use it, but it makes the OOM killer
If the OOM killer kills a mongos, you can simply restart it.
Turn Off Periodic Tasks
Check that there aren’t any cron jobs or daemons that might periodically pop to life and
steal resources. One culprit we’ve seen is package managers’ automatic update. These
programs will come to life, consume a ton of RAM and CPU, and then disappear. This
is not something that you want running on your production server.
384 | Chapter 23: Deploying MongoDB
MongoDB binaries are available for Linux, Mac OS X, Windows, and Solaris. This means
that, on most platforms, you can download an archive from http://www.mongodb.org/
downloads, inflate it, and run the binary.
The MongoDB server requires a directory it can write database files to and a port it can
listen for connections on. This section covers the entire install on the two variants of
system: Windows and everything else (Linux, Max, Solaris).
When we speak of “installing MongoDB,” generally what we are talking about is setting
up mongod, the core database server. mongod can be used as a standalone server or as a
member of a replica set. Most of the time, this will be the MongoDB process you are
Choosing a Version
MongoDB uses a fairly simple versioning scheme: even-point releases are stable, and
odd-point releases are development versions. For example, anything starting with 2.4
is a stable release, such as 2.4.0, 2.4.1, and 2.4.15. Anything starting with 2.5 is a devel‐
opment release, such as 2.5.0, 2.5.2, or 2.5.10. Let’s take the 2.4/2.5 release as a sample
case to demonstrate how the versioning timeline works:
1. MongoDB 2.4.0 is released. This is a major release and will have an extensive
2. After the developers start working on the milestones for 2.6 (the next major stable
release), they release 2.5.0. This is the new development branch that is fairly similar
to 2.4.0 but probably with an extra feature or two and maybe some bugs.
3. As the developers continue to add features, they will release 2.5.1, 2.5.2, and so on.
These releases should not be used in production.
4. Some minor bug fixes may be backported to the 2.4 branch, which will cause releases
of 2.4.1, 2.4.2, and so on. Developers are conservative about what is backported;
few new features are ever added to a stable release. Generally, only bug fixes are
5. After all of the major milestones have been reached for 2.6.0, 2.5.7 (or whatever the
latest development release is) will be turned into 2.6.0-rc0.
6. After extensive testing of 2.6.0-rc0, usually there are a couple minor bugs that need
to be fixed. Developers fix these bugs and release 2.6.0-rc1.
7. Developers repeat step 6 until no new bugs are apparent, and then 2.6.0-rc2 (or
whatever the latest release ended up being) is renamed 2.6.0.
8. Start over from step 1, incrementing all versions by 0.2.
You can see how close a production release is by browsing the core server roadmap on
the MongoDB bug tracker.
If you are running in production, you should use a stable release. If you are planning
to use a development release in production, ask about it first on the mailing list or IRC
to get the developers’ advice.
If you are just starting development on a project, using a development release may be
a better choice. By the time you deploy to production, there will probably be a stable
release with the features you’re using (MongoDB attempts to stick to a regular cycle of
stable releases every six months). However, you must balance this against the possibility
that you would run into server bugs, which can be discouraging to a new user.
To install MongoDB on Windows, download the Windows zip from the MongoDB
downloads page. Use the advice in the previous section to choose the correct version of
MongoDB. There are 32-bit and 64-bit releases for Windows, so select whichever ver‐
sion you’re running. When you click the link, it will download the .zip. Use your favorite
extraction tool to unzip the archive.
Now you need to make a directory in which MongoDB can write database files. By
default, MongoDB tries to use the \data\db directory on the current drive as its data
directory (for example, if you’re running mongod on C:, it’ll use C:\data\db). You can
create this directory or any other empty directory anywhere on the filesystem. If you
chose to use a directory other than \data\db, you’ll need to specify the path when you
start MongoDB, which is covered in a moment.
Now that you have a data directory, open the command prompt (cmd.exe). Navigate to
the directory where you unzipped the MongoDB binaries and run the following:
386 | Appendix A: Installing MongoDB
If you chose a directory other than C:\data\db, you’ll have to specify it here, with the
$ bin\mongod.exe --dbpath C:\Documents and Settings\Username\My Documents\db
See Chapter 20 for more common options, or run mongod.exe --help to see all options.
Installing as a Service
MongoDB can also be installed as a service on Windows. To install, simply run with the
full path, escape any spaces, and use the --install option. For example:
--dbpath "\"C:\Documents and Settings\Username\My Documents\db\"" --install
It can then be started and stopped from the Control Panel.
POSIX (Linux, Mac OS X, and Solaris) Install
Choose a version of MongoDB, based on the advice in the section “Choosing a Ver‐
sion” on page 385. Go to the MongoDB downloads page, and select the correct version
for your OS.
If you are using a Mac, check whether you’re running 32-bit or 64-bit.
Macs are especially picky that you choose the correct build and will
refuse to start MongoDB and give confusing error messages if you
choose the wrong build. You can check what you’re running by clicking
the apple in the upper-left corner and selecting the About This Mac
You must create a directory for the database to put its files. By default, the database will
use /data/db, although you can specify any other directory. If you create the default
directory, make sure it has the correct write permissions. You can create the directory
and set the permissions by running the following:
$ mkdir -p /data/db
$ chown -R $USER:$USER /data/db
mkdir -p creates the directory and all its parents, if necessary (i.e., if the /data directory
didn’t exist, it will create the /data directory and then the /data/db directory). chown
changes the ownership of /data/db so that your user can write to it. Of course, you can
also just create a directory in your home folder and specify that MongoDB should use
that when you start the database, to avoid any permissions issues.
Decompress the .tar.gz file you downloaded from http://www.mongodb.org:
POSIX (Linux, Mac OS X, and Solaris) Install | 387
$ tar zxf mongodb-linux-i686-1.6.0.tar.gz
$ cd mongodb-linux-i686-1.6.0
Now you can start the database:
Or if you’d like to use an alternate database path, specify it with the --dbpath option:
$ bin/mongod --dbpath ~/db
See section TODO for a summary of the most common options, or run mongod with
--help to see all the possible options.
Installing from a Package Manager
On these systems, there are many package managers that can also be used to install
MongoDB. If you prefer using one of these, there are official packages for RedHat,
Debian, and Ubuntu as well as unofficial packages for many other systems. If you use
an unofficial version, make sure it installs a relatively recent version.
On OS X, there are unofficial packages for Homebrew and MacPorts. If you go for the
MacPorts version, be forewarned: it takes hours to compile all the Boost libraries, which
are MongoDB prerequisites. Start the download and leave it overnight.
Regardless of the package manager you use, it is a good idea to figure out where it is
putting the MongoDB log files before you have a problem and need to find them. It’s
important to make sure they’re being saved properly in advance of any possible issues.
388 | Appendix A: Installing MongoDB
Documents you may be interested
Documents you may be interested