Each database in a MongoDB instance can have any number of users. When security is enabled, only authenticated users of a database are able to perform read or write operations.

There are two special databases: users in the admin and local databases can perform operations on any database. A user that belongs to either one of these databases can be thought of as a superuser. After authenticating, admin users are able to read or write from any database and are able to perform certain admin-only commands, such as listDatabases or shutdown.

Before starting the database with security turned on, it’s important that at least one admin user has been added. Let’s run through a quick example, starting from a shell connected to a server without authentication turned on:

> use admin
switched to db admin
> db.addUser("root", "abcd");
{
    "user" : "root",
    "readOnly" : false,
    "pwd" : "1a0f1c3c3aa1d592f490a2addc559383"
}
> use test
switched to db test
> db.addUser("test_user", "efgh");
{
    "user" : "test_user",
    "readOnly" : false,
    "pwd" : "6076b96fc3fe6002c810268702646eec"
}
> db.addUser("read_user", "ijkl", true);
{
    "user" : "read_user",
    "readOnly" : true,
    "pwd" : "f497e180c9dc0655292fee5893c162f1"
}

Here we’ve added an admin user, root, and two users on the test database. One of those users, "read_only", has read permissions only and cannot write to the database. From the shell, a read-only user is created by passing true as the third argument to addUser. To call addUser, you must have write permissions for the database in question; in this case we can call addUser on any database because we have not enabled security yet.

Now let’s restart the server, this time adding the --auth command-line option to enable security. After enabling security, we can reconnect from the shell and try it:

> use test
switched to db test
> db.test.find();
error: { "$err" : "unauthorized for db [test] lock type: -1 " }
> db.auth("read_user", "ijkl");
1
> db.test.find();
{ "_id" : ObjectId("4bb007f53e8424663ea6848a"), "x" : 1 }
> db.test.insert({"x" : 2});
unauthorized
> db.auth("test_user", "efgh");
1
> db.test.insert({"x": 2});
> db.test.find();
{ "_id" : ObjectId("4bb007f53e8424663ea6848a"), "x" : 1 }
{ "_id" : ObjectId("4bb0088cbe17157d7b9cac07"), "x" : 2 }
> show dbs
assert: assert failed : listDatabases failed:{
    "assertion" : "unauthorized for db [admin] lock type: 1
",
    "errmsg" : "db assertion failure",
    "ok" : 0
}
> use admin
switched to db admin
> db.auth("root", "abcd");
1
> show dbs
admin
local
test

When we first connect, we are unable to perform any operations (read or write) on the test database. After authenticating as the read_user user, however, we are able to perform a simple find. When we try to insert data, we are again met with a failure because of the lack of authorization. test_user, which was not created as read-only, is able to insert data normally. As a non-admin user, though, test_user is not able to list all the available databases using the show dbs helper. The final step is to authenticate as an admin user, root, who is able to perform operations on any database.

If authentication is enabled, clients must be logged in to perform any reads or writes. However, there is one oddity in MongoDB’s authentication scheme: before you create a user in the admin database, clients that are “local” to the server can perform reads and writes on the database.

Generally, this is not an issue: create your admin user and use authentication normally. The only exception is sharding. With sharding, the admin database is kept on the config servers, so shard mongods have no idea it even exists. Therefore, as far as they know, they are running with authentication enabled but no admin user. Thus, shards will allow a local client to read and write from them without authentication.

Hopefully this wouldn’t be an issue: optimally your network will be configured so that only mongos processes are accessible to clients. However, if you are worried about clients running locally on shards and connecting directly to them instead of going through the mongos, you may wish to add admin users to your shards.

Note that you do not want the sharded cluster to know about these admin users: it already has an admin database. The admin databases you’re creating on the shards are for your use only. To do this, connect to the primary of each shard and run the addUser() function:

> db.addUser("someUser", "theirPassword")

Make sure that the replica sets you create users on are already shards in the cluster. If you create an admin user and then try to add the mongods as a shard the addShard command will not work (because the cluster already contains an admin database).

Users of a given database are stored as documents in its system.users collection. The structure of a user document is {"user" : username, "readOnly" : true, "pwd" : password hash}. The password hash is a hash based on the username and password chosen.

Knowing where and how user information is stored makes performing some common administration tasks trivial. For example, to remove a user, simply remove the user document from the system.users collection:

> db.auth("test_user", "efgh");
1
> db.system.users.remove({"user" : "test_user"});
> db.auth("test_user", "efgh");
0

When a user authenticates, the server keeps track of that authentication by tying it to the connection used for the authenticate command. This means that if a driver or tool is employing connection pooling or fails over to another node, authenticated users will need to reauthenticate on new connections. This should be handled invisibly by the driver.

On a standalone server, build the index in the background during an off-time. There isn’t much else you can do to minimize impact. To build an index in the background, run ensureIndex with the "background" : true option:

> db.foo.ensureIndex({"someField" : 1}, {"background" : true})

Any type of index can be built in the background.

A foreground index build takes less time than a background index build but locks the database for the duration of the process. Thus, no other operations can read or write to the database while a foreground index is building. Background indexes yield the write lock regularly to allow other operations to go. This means that they can take longer—much longer on write-heavy servers—but the server can serve other clients while building an index.

The easiest way to create an index on a replica set is to create it on the primary and wait for it to be replicated to the secondaries. On small collections, this should have minimal impact.

If you have a large collection, this can lead to the situation where all of your secondaries start building the index at the same time. Suddenly all of your secondaries will be unavailable for client reads and may fall behind in replication. Thus, for larger collections, this is the preferred technique:

When you have finished this process, only the primary should be left without an index. Now there are two options: you can either build the index on the primary in the background (which will put more strain on the primary) or you can step down the primary and then follow steps 1 through 4 to build the index on it as you did with the other members of the set. This involves a failover, which may be more or less preferable than adding load to the primary.

You can also use this isolate-and-build technique to build an index on a member of the set that isn’t configured to build indexes (one that has the "buildIndexes" : false option set): start it as a standalone member, build the index, and add it back into the set.

If you cannot use the rotation method for whatever reason, plan to build new indexes during an off time (at night, a holiday, a weekend, etc.).

To create indexes on a sharded cluster, we want to follow the same procedure as described for replica sets and build the index on one shard at a time.

First, turn off the balancer. Then follow the procedure outlined in the previous section for each shard, treating it as a individual replica set. Finally, run ensureIndex through the mongos and turn the balancer back on again.

This procedure is only required for adding an index to existing shards: new shards will pick up on the index when they start receiving chunks from a collection.

If an index is no longer necessary, you can remove it with the dropIndexes command and the index name. Query the system.indexes collection to figure out what the index name is, as even the autogenerated names vary somewhat from driver to driver:

> db.runCommand({"dropIndexes" : "foo", "index" : "alphabet"})

You can drop all indexes on a collection by passing in "*" as the value for the "index" key:

> db.runCommand({"dropIndexes" : "foo", "index" : "*"})

This leaves the "_id" index. The only way to get rid of that one is to drop the whole collection. Removing all the documents in a collection (with remove) does not affect the indexes; they will be repopulated when new documents are inserted.

The Linux out-of-memory killer will kill processes that are using a lot of memory. Because of the way MongoDB uses memory, it is not usually an issue, but index creations are the one time it can be. If you are building an index and your mongod suddenly disappears, check /var/log/messages for notices from the OOM killer. Running a background index build or adding some swap space can prevent this. If you have administrative permissions on the machine, you may want to make MongoDB unkillable.

See The OOM Killer for more information.

If you need a database in RAM, you can use the UNIX dd tool to load it before starting the mongod:

$ for file in /data/db/brains.*
> do
> dd if=$file of=/dev/null
> done

Replace brains with the name of the database you want to load.

Replacing /data/db/brains.* with /data/db/* will load the whole data directory (all databases) into RAM (assuming there’s enough room for all of them). If you load a database or set of databases into memory and it takes up more memory than you have, some of its data will fall back out of memory immediately. In this situation, you may want to use one of the techniques outlined in the next section to move more specific parts of your data into memory.

When you start the mongod, it will ask the operating system for the data files and the operating system, knowing that the data files are in memory, will be able to quickly access it.

However, this technique is only helpful if your entire database fits in memory. If it does not, you can do more fine-grained preheating using the following techniques.

MongoDB has a command for preheating data called touch. Start mongod (perhaps on a different port or firewalled off from your application) and touch a collection to load it into memory:

> db.runCommand({"touch" : "logs", "data" : true, "index" : true})

This will load all the documents and indexes into memory for the logs collection. You can specify to only load documents or only load indexes. Once touch completes, you can allow your application to access MongoDB.

However, an entire collection (even just the indexes) can still be too much data. For example, your application might only require one index to be in memory, or only a small fraction of the documents. In that case, you’ll have to custom preheat the data.

When you have more complex preheating needs, you may have to roll your own preheating scripts. Here are some common preheating requirements and how to deal with them:

These techniques can be combined: you could load a couple of indexes while replaying the diaglog, for example. You can also run them all at the same time if you aren’t bottlenecked on disk IO, either through multiple shells or the startParallelShell command (if the shell is local to the mongod):

> p1 = startParallelShell("db.find({}, {x:1}).hint({x:1}).explain()", port)
> p2 = startParallelShell("db.find({}, {y:1}).hint({y:1}).explain()", port)
> p3 = startParallelShell("db.find({}, {z:1}).hint({z:1}).explain()", port)

Replace port with the port on which mongod is running.