How to rename a field in MongoDB using MongoChef

Every now and then you may need to change the name of a field within your MongoDB documents. Whether you need to do it for a single document, or perhaps for multiple documents, this task can be easily accomplished with only a few steps from within the MongoChef app.

Renaming A Field Name In A Single Document Within MongoDB

The simplest of these tasks is changing a field name in single document. See the steps below:

  1. Open the document in which the field to be renamed is located
  2. Double click on the field name (In this case “dob”)
  3. You will now have the option to type the new field name into this space
  4. Once you press “Enter” the new field name will be saved

MongoChef Support, MongoChef, MongoDB

Renaming A Field Name Within Documents Matching A Query

Should you wish to change all documents matching a particular query then this can also be easily achieved in just a few steps. In this example we are changing the “dob” field in all documents relating to customers with the last name “Miller”. See below:

  1. Type in your query: {last:"Miller"} – and hit “Enter”
  2. Open one of the documents resulting from the query search
  3. Find the field that you would like to rename (“dob”) and right click it.
  4. Select “Rename Field”
  5. Type in the new field name (“date_of_birth”) and hit“Enter”
  6. Select “Documents matching query criteria” from the dropdown box
  7. Click “Enter”
  8. Now every document within this query will have the field name “date_of_birth” in place of “dob”

MongoChef Support, MongoChef, MongoDB

Renaming A Field Name In All Documents Within A Collection

Finally, to rename a field in all documents within a collection follow the steps below (identical to the steps above apart from no. 4):

  1. Find the field that you would like to rename (again “dob”) and right click it
  2. Select “Rename Field”
  3. Type in the new field name (“date_of_birth”) and hit “Enter”
  4. Select “All documents in collection” from the dropdown box
  5. Click “Rename”
  6. Now every document in the entire collection will have the field name “date_of_birth” in place of “dob”

MongoChef Support, MongoChef, MongoDB


That’s it for this post, but if you still have a little time, please check out the other very useful features of MongoChef!

How to Do MongoDB Map-Reduce Queries Easily with 3T MongoChef

In this post, we will see how 3T MongoChef can make your life easy with writing, debugging and running Map-Reduce jobs using the amazing new Map-Reduce Screen.

MongoDB’s Map-Reduce is the flexible cousin of the Aggregation pipeline. In general, it works by taking the data through two stages:

  • a map stage that processes each document and emits one or more objects for each input document
  • a reduce stage that combines emitted objects from the output of the map operation

The main advantage over the Aggregation pipeline is that Map-Reduce may use arbitrary JavaScript for each stage enabling otherwise impossible operations though at the expense of lower performance (potentially higher execution times). You can read more about it in MongoDB’s reference documentation.

For this tutorial, we will Map-Reduce a collection of documents with image metadata. The relevant parts of the schema are:

    "_id" : 592341,
    "tags" : [

If you haven’t installed 3T MongoChef already, it’s available for Windows, Mac and Linux here:

Objective: Group Images by Tag except for Those Which Include The “work” Tag

To achieve this, we will need to write a Map-Reduce job that will:

  1. Exclude all images which include the “work” tag.
  2. Have the map() function emit the image id for each of the tags as key.
  3. Have the reduce() function combine the image ids for each tag.

Let us start by opening MongoChef’s new Map-Reduce screen by selecting the Open Map-Reduce option from the context menu:

Open Map-Reduce in MongoChef

Opening the Map-Reduce in 3T MongoChef

Filtering the Input Data

Clicking on the “Input data” tab and then the “Preview Input” toolbar button shows us a preview of the collection data. It is here that we can shape the data fed into the Map-Reduce job and omit any image tagged “work”. This is achieved by the following query

{ "tags": { $ne: "work" } }

We can inspect the data that will be fed into the map function by clicking the “Preview Output” toolbar button.

Input data sample

Input data sample

Mapping the Collection

For the second step, we move to the “map()” tab.

In this tab we want to specify the function responsible for emitting one or more key-pairs for each document. The following function gets the job done:

function () {
    for (var index in this.tags) {
        emit ( this.tags[index] , this._id );

We can sample the map() function’s output by clicking the preview button verifying that this indeed did the trick. This feature comes in particularly handy, especially before submitting a job that could potentially run for hours. The “map() sample output” tab gives us a rich view of how our map() function works, showing emitted key/value pairs along with the document that produced them and its _id.

Map output preview

Map output preview

Reducing the Data

MongoChef’s default implementation of the reduce() function just so happens to do the rest for us:

function (key, values) {    
    var reducedValue = "" + values;
    return reducedValue;

Again, the Preview Output toolbar button will let us verify we did it right. Were we writing a more complex reduce() function or trying to debug what was being fed in, we could sample the input by clicking on the preview input button. That gives us a few of the key-value pairs that are emitted and then reduced.

Reduce sample input

Reduce sample input


MongoDB allows for a final stage to a Map-Reduce job for doing some final processing with use of a finalize() function. Let’s use this just so the output is easier to read:

function (key, reducedValue) {
    var finalValue = "tag '" + key + "' was found in images: " + reducedValue;
    return finalValue;

A quick inspection of finalize()’s sample output and we are ready to submit a job that will process all of the data.

Finalize sample output

Finalize sample output

Running the Map-Reduce Job

Now that we have set all the parameters of the job, and are sure that all our functions run as intended, we can submit the Map-Reduce job to run through the whole collection dataset by clicking the “Execute” button on the toolbar.

This action will open a new tab which will contain the results of the job when it is finished:

Finished job

Finished Job!

Clicking on Show details will bring up a dialog showing execution statistics as well as a configuration summary for this job.

Job statistics

Finished Map-Reduce job statistics

Map-Reduce Epilogue

Now that the Map-Reduce job is finished, we can save all this work as a script. The format is 100% JavaScript code, which allows the saved file to be run in IntelliShell or even the basic mongo shell and will produce identical results.

// *** 3T Software Labs, MongoChef: MapReduce Job ****

// Variable for db
var __3t_mongochef_db = "exam";

// Variable for map
var __3t_mongochef_map = function () {
	for (var index in this.tags) {
    		emit ( this.tags[index] , this._id );

// Variable for reduce
var __3t_mongochef_reduce = function (key, values) {    
    var reducedValue = "" + values;
    return reducedValue;

// Variable for finalize
var __3t_mongochef_finalize = function (key, reducedValue) {
    var finalValue = "tag '" + key + "' was found in images: " + reducedValue;
    return finalValue;

    mapReduce: "images",
    map: __3t_mongochef_map,
    reduce: __3t_mongochef_reduce,
    finalize: __3t_mongochef_finalize,
    out: { "inline" : 1},
    query: { "tags": { $ne: "work" } },
    sort: { },
    inputDB: "exam",

Do you have an existing script that you’ve been working with already? No problem, MongoChef will load it into the Map-Reduce screen, just click on the “Open Map-Reduce File” toolbar button, select the file and there you have it!

How to prevent your connection from dropping with hosted MongoDB instances

If you are connected to a hosted instance of MongoDB, you may experience odd connection drops or timeouts that manifest themselves like this:

After a relatively short period of inactivity, you try to run a query from within MongoChef, but you are presented with a server error message box. If you try again, the query will work properly again.

The reason is that in some configurations, the connection can get dropped by a firewall or a load balancer. This issue is common with MongoDBs hosted on Azure. The folks over at MongoLab have some interesting details on this matter: The solution is to manually set the max connection idle time to 60s (60000ms) in the Connection Manager:

MongoChef set connection idle timeout

After that, your connection should no longer drop.

How to Do MongoDB Aggregation Queries Easily with 3T MongoChef

In this post we’re going to take a look at how to do MongoDB aggregation queries easily with the amazing new Aggregation Screen in 3T MongoChef.

Prefer to watch?
See the accompanying MongoDB Aggregation video.

For this tutorial, we’re going to build a query based on the freely available housing data from the City of Chicago Data Portal to learn how to use the incredible new features and query support the Aggregation Screen provides.

If you haven’t installed 3T MongoChef 3.0 already, it’s available for Windows, Mac and Linux here:

Creating the Aggregation Query

Once we’ve opened up 3T MongoChef and connected to the database, we can select the collection we wish to query:

Select Collection for MongoDB Aggregation Query

We can open the Aggregation Screen by clicking the large ‘Aggregate‘ button in the main tool bar at the top, selecting ‘Open Aggregation Screen‘ from the right-click context menu or by pressing the ‘F4‘ shortcut key.

We now have an empty aggregation query, ready to be filled up, so let’s get cracking!

New Pipeline MongoDB Aggregation Query

Identifying the Question We Want to Answer

The question we want to ask of our data is simple:

Which zip codes have the greatest number of senior housing units available?

To think how we’ll answer this and how we’ll form our query, let’s take a look at the data. Click ‘Execute full pipeline‘ (executing an empty pipeline simply shows the contents of the collection).

Full Pipeline Results MongoDB Aggregation Query

If you prefer a JSON view of the data (and 3T MongoChef supports dynamically switching between tree, table and JSON views of your result data), it’s included below:

    "_id" : ObjectId("544f9533d4c6dc758c28fde4"), 
    "community_area" : {
        "name" : "Albany Park", 
        "number" : 14
    "property" : {
        "type" : "Senior", 
        "name" : "Mayfair Commons"
    "address" : "4444 W. Lawrence Ave.", 
    "zip_code" : "60630", 
    "phone_number" : "773-205-7862", 
    "management_company" : "Metroplex, Inc.", 
    "units" : 97, 
    "location" : {
        "x_coordinate" : 1145674.7538177613, 
        "y_coordinate" : 1931569.979044555, 
        "latitude" : 41.9682242321, 
        "longitude" : -87.7397474866, 
        "description" : "4444 W Lawrence Ave\n(41.968224232060564, -87.73974748655358)"

OK, so we can see we have the fields we need – we can check "property.type" to see that it’s senior housing, and "zip_code" and "units" give us the zip code and number of available units there are, respectively.

To answer our question, we need to combine these into the right aggregation query. Let’s create the first stage of our query where we’ll match against the senior property type.

Adding a New Stage

Click ‘Add New Stage‘ and you’ll see a new stage in the ‘Pipeline‘ tab.

New Stage MongoDB Aggregation Query

Double click the new stage to edit it (or simply select the ‘Stage 1‘ tab):

Match Operator MongoDB Aggregation Query

The screenshot above jumps ahead a little bit as the stage specification has already been filled, but let’s break down each piece in turn.

First, notice the ‘$match‘ in the combo box. It’s here where we select the stage’s ‘operator’. A stage operator defines what the stage actually does. The ‘$match‘ operator takes the input set of documents and outputs only those that match the given criteria. It is essentially a filter. A full list of the supported operators and their meaning is available here: (this link is always readily available by clicking ‘Operator Quick Reference’ in the app).

For convenience, the specification of the Stage 1 ‘$match‘ operator is repeated below:

    "property.type": "Senior"

In the stage’s specification, we can see that we are matching against the "Senior" property type, meaning only documents with a value of "Senior" for the field "property.type" will be passed onto the (yet to be created) next stage of the pipeline for further processing.

We can check the output of this and any other stage at any time by clicking ‘Show output from the selected stage‘. Similarly, we can see the input of any stage at any time by clicking ‘Show input to the selected stage‘. This is a really nice and convenient feature, as it makes keeping track of the precise form of the data we are working at each stage in the pipeline really easy.

We can see in the ‘Stage 1 output‘ tab that we have the results we need from this stage, and so let’s go on and create the next.

Grouping Results

We now need a way to group together the results from Stage 1 on zip code and then add up each of the available units figures. The ‘$group‘ operator is exactly what we need for this.

Group Operator MongoDB Aggregation Query

The Stage 2 ‘$group‘ operator specification is repeated below:

    _id: "$zip_code",
    totalUnits: { $sum: "$units" }

The specification of Stage 2 states that the output of this stage will be documents that have an “_id" with a distinct zip code as a value and so will group together documents input to this stage that have the same zip code, and a “totalUnits" field whose value is the sum of all the "units" field values from each of the documents in the group. We can see the input to and output from tabs for this stage in the screenshot and can confirm that a reduction has taken place – of the 70 documents input to this stage, there were 36 distinct zip codes, and so the corresponding 36 documents are output from this stage.

Finding the Answer

As we want to know the zip codes that have the greatest number of senior housing units available, it would be convenient to sort the results from the greatest to the least total units available.

To do this, we’ll create a third stage using the ‘$sort‘ operator with the following specification, giving us exactly what we want:

    totalUnits: -1

Full Query and Results MongoDB Aggregation Query

Going back to the ‘Pipeline‘ tab we can see the result of the execution of the full query, as well as the full query itself, all in one one place. We can see we have the expected number of results from the full pipeline, and we can now answer our question – we have a list of the zip codes that have the greatest number of senior housing units available.

Wasn’t that easy? :-)

Specifying Query Options

Depending on your own particular query, you may wish to specify options such as to use a database cursor for the results (if the results are large), allow the query to write temporary intermediate results to disk or rather than run the query, explain aspects of the processing of the query.

These options can be set in the ‘Options‘ tab. Note that these options only became available in MongoDB 2.6, so if you are connected to a MongoDB 2.4 or earlier instance, the ‘Options‘ tab is not shown.

Options MongoDB Aggregation Query

Sharing Aggregation Queries

The aggregation queries you have created can be saved to and loaded from file, so not only can you reload them in future sessions, but you can also share them with other colleagues and users.  There is also a preview of the raw MongoDB script of the aggregation query available by selecting ‘Show Query Preview‘ from the context menu. This can be rather handy if you simply wish to examine the raw underlying script, or make a quick copy to stick in an email, or perhaps combine in it in a larger, more complex query in 3T MongoChef’s IntelliShell.

Query Preview MongoDB Aggregation Query

Handy References

It can take a bit of time to master all the different operators available in the aggregation pipeline, so links to the MongoDB Aggregation Pipeline Quick Reference and the Aggregation Section of the MongoDB Manual are always available within a click’s reach directly in the app itself via the ‘Operator Quick Reference‘ and ‘Aggregation Tutorial‘ links, respectively. It wont be too long before you’re masterfully producing complex MongoDB aggregation queries of your own!


OK, that’s it for this post. I hope you feel the same delight as we do about the amazing new features, convenience and boost to productivity the new Aggregation Screen in 3T MongoChef offers.

Please do check out 3T MongoChef, the best GUI for MongoDB. A little example of the rich code completion and easy in-line editing experience it offers is shown below:

IntelliShell for MongoDB

We’re always very keen to hear about your experiences and ideas for 3T MongoChef. If you’d like to tell us about them please visit our feedback page or click the ‘Feedback‘ tool bar button in the app.

Also, please check out our Schema Explorer & Documentation and Data Compare & Sync tools at, as I expect they’ll also help in making you a much more powerful and productive MongoDB user.

Running MongoChef on CentOS

When trying to run MongoChef on CentOS, you may experience the following issue:

java: cairo-misc.c:380: _cairo_operator_bounded_by_source: Assertion `NOT_REACHED' failed.
./ line 11: 28030 Aborted (core dumped) $DIR/../jre/bin/java -jar $DIR/../lib/data-man-mongodb-pro-*.jar

This is a general issue for all SWT-based applications on CentOS and is related to the Cairo 2D graphics library on CentOS.

The work-around is to pass ‘-Dorg.eclipse.swt.internal.gtk.cairoGraphics=false‘ to the application. In order to do that, open in the bin directory of your MongoChef installation and add the (highlighted) parameter to the last line of the script.


while [ -h "$SOURCE" ]; do # resolve $SOURCE until the file is no longer a symlink
DIR="$( cd -P "$( dirname "$SOURCE" )" && pwd )"
SOURCE="$(readlink "$SOURCE")"
[[ $SOURCE != /* ]] && SOURCE="$DIR/$SOURCE" # if $SOURCE was a relative symlink, we need to resolve it relative to the path where the symlink file was located
DIR="$( cd -P "$( dirname "$SOURCE" )" && pwd )"

$DIR/../jre/bin/java -Dorg.eclipse.swt.internal.gtk.cairoGraphics=false -jar $DIR/../lib/data-man-mongodb-pro-*.jar

Save your script and you are good to go!

Updated: MongoChef on OS X 10.11 (El Capitan)

MongoChef, Data Compare & Sync, and Schema Explorer will work properly with the Public Beta 2 (Developer Preview 4) release of OS X 10.11 (El Capitan).

Issues with the Public Beta (Developer Preview 3) release of OS X 10.11 were discussed in the following thread

Getting Started with MongoChef’s IntelliShell

In this post, I’ll show you how to install and configure MongoChef and the necessary MongoDB tools to get you started with IntelliShell and enjoy the richest MongoDB editing experience currently available for Windows, Mac and Linux.

Everybody ready? Then let’s go!

Install 3T MongoChef

First of all, let’s download MongoChef! It’s available at

Here, you can download MongoChef for your particular platform and ‘bitness’. For example, if you wish to download the 64-bit Windows version, click on ‘Download (64-bit)’ in the ‘WINDOWS’ section. Or if you wished to download the 32-bit Windows version, you would click on the ‘Download for 32-bit systems’ link at the bottom of the ‘WINDOWS’ section. Likewise for Linux, but this time in the rightmost ‘LINUX’ column, and Mac is on the left. Note that there is only a 64-bit version for Mac.

For Windows, there is a standard installer. For Mac, there is a standard ‘drag to the Applications folder’ style installer. On Linux, you can unpack the download to a location of your choice by issuing the command

tar -zvxf mongochef-linux-x64-dist.tar.gz

(or tar -zvxf mongochef-linux-x86-dist.tar.gz if you downloaded the 32-bit version) and then run the


launch script from within the unpacked directory.

Install the MongoDB Client Tools

MongoDB provides a number of command line tools for client machines. MongoChef’s IntelliShell requires one of these, the mongo shell executable, to be accessible on your machine. To install these, go to

MongoDB Download PageYou may need to scroll down a bit on that page to get to the downloads section. Here, you can download the distribution for your platform and ‘bitness’. There’s no separate distribution for just the client tools, the downloads on this page are what you need. In the Windows installer, there is an option to install just the client tools.

Note the mongo shell is typically backward compatible with MongoDB database deployments of previous versions. For example, if you have to work with say a legacy MongoDB 2.4 system, a current 2.6 system and a new 3.0 system, you do not need to install the distribution for all those different versions. Simply install the latest version of the distribution (3.0 in our example), and you’ll be able to use it with all of the different versions of MongoDB deployments you need to work with.

Also note that if you are going to work with a MongoDB deployment that requires SSL encryption to connect to it, be sure to download a distribution that supports SSL encryption. As of this writing, the latest (3.0.3) versions of the Windows and Linux distributions do (though on Linux, you must also have the OpenSSL libraries installed). On Mac, the Homebrew package manager provides options to install an SSL-enabled version of the mongodb package. You can also enable SSL support by building the tools from source, which is actually not as scary as it sounds.

The Windows MongoDB distribution is a standard Windows installer, the Mac and Linux distributions must be unpacked to a location of your choice using the command

tar -zvxf mongodb-<...>.tgz

where mongodb-<...>.tgz refers to the name of the file you downloaded. (On Mac, you can also just double click the file to unpack it.)

OK, that’s us got everything we need installed, so let’s start MongoChef.

Configure IntelliShell

We need to configure MongoChef so that it knows where to find the mongo shell executable we just installed.

First of all, we click on the ‘Preferences…’ menu (located in the application menu on Mac and in the ‘Edit’ menu on Windows and Linux) and then on the ‘IntelliShell’ tab. If you have previously had MongoDB installed on your system and the mongo shell is available on your PATH, it will be shown in the first option here.

3T MongoChef MongoDB GUI IntelliShell PreferencesHowever, in this post we are going to select the particular version we just installed. To do this, select the second option and locate the mongo shell executable. On Mac and Linux, this will be a binary file simply called mongo located in the ‘bin’ directory where you unpacked the distribution. On Windows, it is a binary file called mongo.exe and is located in the ‘bin’ directory of the MongoDB install location in ‘Program Files’. It will be a path similar to ‘C:\Program Files\MongoDB\Server\3.0\bin\mongo.exe‘.

Now that that is configured, click OK, and we can start using IntelliShell!

Opening 3T MongoChef for MongoDB GUI IntelliShell on a CollectionAn IntelliShell instance can be opened on the connection, database or collection level by selecting the particular connection, database or collection and then clicking the IntelliShell toolbar button, right-clicking it and selecting ‘Open IntelliShell…’ or using the keyboard shortcut ‘Ctrl+L‘ / ‘⌘L’. (Note that if you do open at the connection level, you’ll be connected to the ‘test’ database as per the MongoDB default. So if your queries suddenly start returning no results – check you’re actually using the database you think you are!)

We can now begin using the amazing MongoChef IntelliShell – the richest MongoDB editing experience of any MongoDB GUI. Note there’s auto-completion not only of collection names and shell methods, but also of document key names, operators and further completions on return values, just the way you want it.

IntelliShell for MongoDB

Special Note for Secondary Replica Set Members

Note that if you are connected to a replica set and want to run IntelliShell on a secondary member (for example, the replica set connection has a read preference of secondary or secondaryPreferred), you will first need to run rs.slaveOk() to be able to query freely. This is because, by default, MongoDB does not permit read operations from non-master (that is, slave or secondary) instances.

In MongoDB, reads to a primary have strict consistency, meaning that the data it provides reflects the latest writes at all times. This is more familiar and easier to work with when coming from other database systems.

Reads to secondaries in MongoDB however, have eventual consistency, meaning that changes to the system can propagate gradually and readable members are not required to reflect the latest writes at all times. This is less common and may surprise some users coming from other database systems.

By calling rs.slaveOk() you are indicating to the system that you acknowledge that reads will be eventually consistent and wish to be able to query the secondary anyway. Following the principle of self-documenting code, rs.slaveOk() should really be called rs.iUnderstandThatHereReadsAreEventuallyConsistent AndIAmHappyToLiveWithTheConsequences SoPleaseLetMeQueryFreely(), but unless you have the amazing IntelliShell code completion available to you, that would be a little straining on the fingers.


OK, that’s it for this post. I hope you’re now successfully up and running with MongoChef’s IntelliShell. We’re always very keen to hear about your experiences and ideas for MongoChef. If you’d like to tell us about them please visit our feedback page or click the ‘Feedback’ toolbar button in the app.

Also, please check out our Schema Explorer & Documentation and Data Compare & Sync tools at, as I expect they’ll also help in making you a much more powerful and productive MongoDB user.

How to create new users in MongoDB with MongoChef

Creating and managing users in MongoDB from the command line can be a very cumbersome and unwieldy task. Luckily, MongoChef makes it super-easy to manage your users and their roles for your MongoDB instance.

In this tutorial, I will assume that you have already set up a user administrator for your database. If not, please first read our tutorial on how to bootstrap user authentication in MongoDB.

1. Select the MongoDB database for which you want to create a new user

In MongoDB, users are defined for a particular database. Although it is possible to grant a user from a database A access to another database B, users are typically defined in the database that they will access primarily.

So, start by connecting to your MongoDB instance with your user administrator or with any other user that has sufficient privileges to create new users (usually via roles dbAdmin or dbAdminAnyDatabase). Next, right-click the database for which you want to create a new user and select “Manage Users” from the context menu. This will open the user management tab for your database. Here, you can see all users that have already been created for this database. You can also expand users to immediately see all the roles they have been granted. To create a new user, simply click the “Add…” button.

Manage MongoDB Users

2. Enter the new user

This will bring up the Add User dialog where you can enter the name of the new user (in our case “sarah”) and their password. Next, we need to grant the new user a role so that they’ll actually be able to do something. For that, click the “Grant Roles…” button.

Assign MongoDB Role

3. Grant roles to the user

In this dialog, you will be presented with all roles that are currently defined for your database. Built-in roles will be marked by a yellow icon, custom roles by a green icon. You can also click the combo-box at the top to choose from roles in other databases of your MongoDB instance in case you want your new user to access other databases as well. For our example, we will simply make our new user an administrator of their database and also grant them read-write access to it by selecting the roles dbAdmin and readWrite. When done, click the “Grant” button.

Manage MongoDB Roles and Users

4. Create the new user

You return to the previous dialog where you can now see the roles that will be granted to your new user. To create the new user, click the “Add User” button. After that, you will be taken back to the user management tab.

Manage MongoDB Roles and Users

Manage MongoDB Roles and Users

How to install MongoChef on Linux

On Linux, MongoChef is distributed as a gzipped tarball (.tar.gz). We follow a common directory pattern on Linux in that MongoChef’s root directory contains a “bin” folder that contains a runnable .sh file that starts MongoChef.

To install MongoChef, open your shell and cd to a directory of your choice. There, unpack and run MongoChef like so:

For the 64-bit version of MongoChef 3.5.0 for example:

$ tar -xvzf mongochef-linux-x64-dist.tar.gz
$ ./mongochef-3.5.0-linux-x64-dist/bin/

For the 32-bit version of MongoChef 3.5.0 for example:

$ tar -xvzf mongochef-linux-x86-dist.tar.gz
$ ./mongochef-3.5.0-linux-x86-dist/bin/

MongoDB 3.0: Setting up user authentication with MongoChef

Needless to say: you need to secure your MongoDB instances. Leaving aside complementary network-level security such as VPNs or SSH, MongoDB 3.0 itself provides robust built-in user authentication that governs and restricts what users can and cannot see and do inside your MongoDB instances. At the very least, you should run your MongoDB server(s) with user authentication enabled. Always.

Luckily, MongoChef makes user management – a task that can sometimes seem somewhat daunting – incredibly easy. In this post, we’ll see how MongoChef gets you up and running with MongoDB user authentication in no time.

Of Chickens and Eggs

Some background first. There is of course a bit of a chicken-egg situation when you start with user authentication. If you start your mongod / mongos server(s) with user authentication enabled right away, you will of course need to have a user to authenticate with when you try to connect to your server. If, on the other hand, you run your mongod / mongos server(s) without user authentication, you can define as many users as you like, they will simply remain inactive. Therefore, there are two general approaches to bootstrapping user authentication in MongoDB:

1. Enable Authentication after Creating the User Administrator

This straight-forward approach involves the following 3 sequential steps:

  1. Start your MongoDB server without authentication.
  2. Create the system user administrator.
  3. Restart your MongoDB, this time with authentication enabled. You can now connect to your server as that user administrator.

2. Enable Authentication Right Away and Use the Localhost Exception

This approach lets you run your MongoDB server with authentication right from the beginning. However, you need to have localhost access to your server:

  1. Start your MongoDB server with authentication enabled straight away.
  2. Now connect to your MongoDB server from localhost. This localhost exception grants you full access (i.e. without any authentication required) to your instance via the localhost interface. Note that the localhost exception is only active as long as no users have been created in your MongoDB instance. Btw, you can always disable the local host exception by passing —setParameter enableLocalhostAuthBypass=0 to your server.
  3. Proceed to create your system user administration – which must be the first user you create this way.

Bootstrapping User Administration

Since it won’t always be possible to connect to your MongoDB server via your localhost interface, we will use the first approach in this post and create the user administrator before we restart our MongoDB server with authentication.

1. Start your MongoDB server without authentication

From your command line (on your server), start your MongoDB server. For the sake of simplicity, we’ll just start a single mongod instance using the new WiredTiger storage engine:

mongod —dbpath ./data/3.0.0 —storageEngine wiredTiger —port 27017

Note that your data path, your port and other options may differ from this simple example.
The main thing is that you start the server without authentication (i.e. you do not pass —auth to it).

2. Create the system user administrator

Now, let’s quickly connect to our MongoDB server. In MongoChef, click the “Connect” icon in the toolbar and then choose “Quick Connect” in the Connection Manager. Here, simply enter the name or the IP address of your server, and then just click “Connect”.

QuickConnect to a MongoDB with MongoChef GUI

In MongoDB, system-wide users (i.e. users that can have access to all other databases on the server) need to be created in a special database “admin”. If you have only just started your server for the first time, you probably won’t have an “admin” database yet. So, let’s quickly create one (if you already have an “admin” database, just skip this step).
To add the “admin” database to your MongoDB instance, simply right-click your connection, choose “Add Database…” and name your new database admin:

MongoDB Add Admin Database

Now, we can add our system-wide user administrator. A system-wide user administrator is simply an (arbitrarily named) user defined in your “admin” database that has – at least – been granted privileges to create other users. To start, select your “admin” database, right-click, and choose “Manage Users”. This will open a user management tab for the “admin” database. Of course, since we are only just getting started, there aren’t any users defined yet. Click the “Add…” button to add a new user.

MongoDB Add Admin User

Enter a name (anything goes) for your new user and a password. In order to make this new user a system-wide user administrator, we now need to assign it an appropriate role. For this, click the “Grant Roles…” button.

MongoDB Create Admin User

Now, choose from the list of all built-in roles defined for database “admin” the role “userAdminAnyDatabase”. This role will grant the user the privileges required to create (additional) users in any database on your server. Click “Grant” to close the roles selection dialog.
Your Add User dialog will now show that role for your new user:

MongoDB Grant User Admin Role

Click “Add User” to create your new system-wide user administrator.

3. Restart your MongoDB instance with authentication enabled

OK, now that we have a user administrator, we need to restart our MongoDB instance – this time with authentication enabled – as part of the process to bootstrap MongoDB user authentication.

Before restarting your server, disconnect MongoChef from it first. Simply right-click your connection and choose “Disconnect” from the context menu. Next, let’s restart our MongoDB instance with authentication enabled, again from your command line (on your server):

mongod —dbpath ./data/3.0.0 —storageEngine wiredTiger —auth —port 27017

That’s it! You have successfully set up user authentication on your MongoDB server!

Connect to your MongoDB instance with your system-wide user administrator

You can now connect to your MongoDB instance with your system-wide user administrator and create additional users. As before, open your Connection Manager. Since adding new users will probably not be a one-off task, we recommend that this time you create a new connection (rather than just quick-connect to your server).

The IP and port of your server will be the same as before, but this time we need to specify the user we want to connect with in the “Authentication” tab. Enter the name and the password of your system-wide user administrator here and make sure that you specify the database “admin” as that is where the user was defined. Note that MongoChef will automatically use the new challenge-response SCRAM-SHA-1 user authentication mechanism introduced in MongoDB 3.0.

MongoChef for MongoDB: Authenticate User Admin

After you have connected, you can then go on and define additional users for any database on your server. See this tutorial video for more details.