MongoDB Manual Master

(1)

Release 3.2.3

MongoDB, Inc.

(2)

(3)

(4)

1 Introduction to MongoDB 3

1.1 What is MongoDB . . . 3

2 Install MongoDB 5 2.1 Supported Platforms . . . 5

2.2 Deprecation of 32-bit Versions. . . 5

2.3 Tutorials . . . 6

2.4 Additional Resources. . . 59

3 MongoDB CRUD Operations 61 3.1 MongoDB CRUD Introduction . . . 61

3.2 MongoDB CRUD Concepts . . . 63

3.3 MongoDB CRUD Tutorials . . . 99

3.4 MongoDB CRUD Reference. . . 140

4 Data Models 157 4.1 Data Modeling Introduction . . . 157

4.2 Document Validation . . . 160

4.3 Data Modeling Concepts . . . 162

4.4 Data Model Examples and Patterns . . . 167

4.5 Data Model Reference . . . 185

5 Administration 199 5.1 Administration Concepts . . . 199 5.2 Administration Tutorials . . . 240 5.3 Administration Reference . . . 295 5.4 Production Checklist . . . 308 6 Security 315 6.1 Security Checklist . . . 315 6.2 Authentication . . . 317

6.3 Role-Based Access Control . . . 331

6.4 Encryption . . . 336 6.5 Auditing . . . 340 6.6 Security Hardening. . . 341 6.7 Security Tutorials. . . 344 6.8 Security Reference . . . 413 6.9 Additional Resources. . . 441

(5)

7.2 Map-Reduce . . . 445

7.3 Single Purpose Aggregation Operations . . . 446

7.4 Additional Features and Behaviors. . . 446

7.5 Additional Resources. . . 485 8 Indexes 487 8.1 Index Introduction . . . 487 8.2 Index Concepts . . . 492 8.3 Indexing Tutorials . . . 531 8.4 Indexing Reference. . . 579 9 Storage 587 9.1 Storage Engines . . . 587 9.2 Journaling . . . 598 9.3 GridFS . . . 603

9.4 FAQ: MongoDB Storage . . . 606

10 Replication 613 10.1 Replication Introduction . . . 613

10.2 Replication Concepts. . . 617

10.3 Replica Set Tutorials . . . 655

10.4 Replication Reference . . . 708

11 Sharding 725 11.1 Sharding Introduction . . . 725

11.2 Sharding Concepts . . . 731

11.3 Sharded Cluster Tutorials . . . 756

11.4 Sharding Reference . . . 810

12 Frequently Asked Questions 819 12.1 FAQ: MongoDB Fundamentals . . . 819

12.2 FAQ: MongoDB for Application Developers . . . 821

12.3 FAQ: Concurrency . . . 831

12.4 FAQ: Sharding with MongoDB . . . 837

12.5 FAQ: Replication and Replica Sets . . . 843

12.6 FAQ: MongoDB Storage . . . 846

12.7 FAQ: Indexes . . . 852

12.8 FAQ: MongoDB Diagnostics. . . 853

13 Release Notes 861 13.1 Current Stable Release . . . 861

13.2 Previous Stable Releases . . . 895

13.3 MongoDB Version Numbers . . . 1051

14 About MongoDB Documentation 1053 14.1 License . . . 1053

14.2 Editions. . . 1053

14.3 Version and Revisions . . . 1054

14.4 Report an Issue or Make a Change Request . . . 1054

(6)

Note: This version of the PDF does not include the reference section, seeMongoDB Reference Manual1for a PDF edition of all MongoDB Reference Material.

(7)

(8)

Introduction to MongoDB

On this page

• What is MongoDB(page 3)

Welcome to MongoDB. This document provides a brief introduction to MongoDB and some key concepts. See the installation guides(page 5) for information on downloading and installing MongoDB.

1.1 What is MongoDB

MongoDB is an open-source document database that provides high performance, high availability, and automatic scaling.

1.1.1 Document Database

A record in MongoDB is a document, which is a data structure composed of field and value pairs. MongoDB docu-ments are similar to JSON objects. The values of fields may include other docudocu-ments, arrays, and arrays of docudocu-ments.

The advantages of using documents are:

• Documents (i.e. objects) correspond to native data types in many programming languages. • Embedded documents and arrays reduce need for expensive joins.

(9)

1.1.2 Key Features

High Performance

MongoDB provides high performance data persistence. In particular,

• Support for embedded data models reduces I/O activity on database system.

• Indexes support faster queries and can include keys from embedded documents and arrays.

High Availability

To provide high availability, MongoDB’s replication facility, called replica sets, provide: • automatic failover.

• data redundancy.

Areplica set(page 613) is a group of MongoDB servers that maintain the same data set, providing redundancy and increasing data availability.

Automatic Scaling

MongoDB provides horizontal scalability as part of its core functionality.

• Automaticsharding(page 725) distributes data across a cluster of machines.

(10)

Install MongoDB

On this page

• Supported Platforms(page 5)

• Deprecation of 32-bit Versions(page 5) • Tutorials(page 6)

• Additional Resources(page 59)

This section of the manual contains tutorials on installation of MongoDB.

2.1 Supported Platforms

Platform 3.2 3.0 2.6 2.4 2.2 Amazon Linux Y Y Y Y Y Debian 7 Y Y Y Y Y Fedora 8+ Y Y Y RHEL/CentOS 6.2+ Y Y Y Y Y RHEL/CentOS 7.0+ Y Y Y SLES 11 Y Y Y Y Y SLES 12 Y Solaris 64-bit Y Y Y Y Y Ubuntu 12.04 Y Y Y Y Y Ubuntu 14.04 Y Y Y Microsoft Azure Y Y Y Y Y Windows Vista/Server 2008R2/2012+ Y Y Y Y Y OSX 10.7+ Y Y Y Y

2.2 Deprecation of 32-bit Versions

Changed in version 3.2: Starting in MongoDB 3.2, 32-bit binaries are deprecated and will be unavailable in future releases.

Changed in version 3.0: Commercial support is no longer provided for MongoDB on 32-bit platforms (Linux and Windows). SeePlatform Support(page 934).

(11)

• 32-bit versions of MongoDB do not support the WiredTiger storage engine.

• 32-bit builds disable journaling by default because journaling further limits the maximum amount of data that the database can store.

• When running a 32-bit build of MongoDB, the total storage size for the server, including data and indexes, is 2 gigabytes. For this reason, do not deploy MongoDB to production on 32-bit machines.

If you’re running a 64-bit build of MongoDB, there’s virtually no limit to storage size. For production deployments, 64-bit builds and operating systems are strongly recommended.

2.3 Tutorials

2.3.1 MongoDB Community Edition

Install on Linux(page 6) Install MongoDB Community Edition and required dependencies on Linux.

Install on OS X(page 26) Install MongoDB Community Edition on OS X systems from Homebrew packages or from MongoDB archives.

Install on Windows(page 28) Install MongoDB Community Edition on Windows systems and optionally start Mon-goDB as a Windows service.

2.3.2 MongoDB Enterprise

Install on Linux(page 34) Install the official builds of MongoDB Enterprise on Linux-based systems. Install on OS X(page 51) Install the official build of MongoDB Enterprise on OS X

Install on Windows(page 52) Install MongoDB Enterprise on Windows using the .msi installer.

Install MongoDB Community Edition

These documents provide instructions to install MongoDB Community Edition.

Install on Linux(page 6) Install MongoDB Community Edition and required dependencies on Linux.

Install on OS X(page 26) Install MongoDB Community Edition on OS X systems from Homebrew packages or from MongoDB archives.

Install on Windows(page 28) Install MongoDB Community Edition on Windows systems and optionally start Mon-goDB as a Windows service.

Install MongoDB Community Edition on Linux

On this page

• Recommended(page 7) • Manual Installation(page 7)

(12)

These documents provide instructions to install MongoDB Community Edition for various Linux systems. Note: Starting in MongoDB 3.2, 32-bit binaries are deprecated and will be unavailable in future releases.

Recommended For the best installation experience, MongoDB provides packages for popular Linux distributions. These packages, which support specific platforms and provide improved performance and TLS/SSL support, are the preferred way to run MongoDB. The following guides detail the installation process for these systems:

Install on Red Hat(page 7) Install MongoDB Community Edition on Red Hat Enterprise and related Linux systems using .rpm packages.

Install on SUSE(page 11) Install MongoDB Community Edition on SUSE Linux systems using .rpm packages. Install on Amazon Linux(page 14) Install MongoDB Community Edition on Amazon Linux systems using .rpm

packages.

Install on Ubuntu(page 17) Install MongoDB Community Edition on Ubuntu Linux systems using .deb packages. Install on Debian(page 20) Install MongoDB Community Edition on Debian systems using .deb packages. For systems without supported packages, refer to the Manual Installation tutorial.

Manual Installation For Linux systems without supported packages, MongoDB provides a generic Linux release. These versions of MongoDB don’t include TLS/SSL, and may not perform as well as the targeted packages, but are compatible on most contemporary Linux systems. See the following guides for installation:

Install MongoDB From Tarball(page 23) Install the official build of MongoDB Community Edition on other Linux systems from MongoDB archives.

Install MongoDB Community Edition on Red Hat Enterprise or CentOS Linux On this page

• Overview(page 7) • Packages(page 7) • Init Scripts(page 8)

• Install MongoDB Community Edition(page 8) • Run MongoDB Community Edition(page 9) • Uninstall MongoDB Community Edition(page 11)

Overview Use this tutorial to install MongoDB Community Edition on Red Hat Enterprise Linux or CentOS Linux versions 6 and 7 using .rpm packages. While some of these distributions include their own MongoDB packages, the official MongoDB Community Edition packages are generally more up to date.

Platform Support

This installation guide only supports 64-bit systems. SeePlatform Support(page 934) for details. MongoDB 3.2 deprecates support for Red Hat Enterprise Linux 5.

Packages MongoDB provides officially supported packages in their own repository. This repository contains the following packages:

(13)

mongodb-org A metapackage that will automatically install the four component packages listed below. mongodb-org-serverContains the mongod daemon and associated configuration and init scripts.

mongodb-org-mongosContains the mongos daemon. mongodb-org-shellContains the mongo shell.

mongodb-org-toolsContains the following MongoDB tools: mongoimport bsondump, mongodump, mongoexport, mongofiles, mongooplog, mongoperf, mongorestore, mongostat, and mongotop.

The default /etc/mongod.conf configuration file supplied by the packages have bind_ip set to 127.0.0.1 by default. Modify this setting as needed for your environment before initializing a replica set.

Init Scripts The mongodb-org package includes various init scripts, including the init script /etc/rc.d/init.d/mongod. You can use these scripts to stop, start, and restart daemon processes.

The package configures MongoDB using the /etc/mongod.conf file in conjunction with the init scripts. See the Configuration Filereference for documentation of settings available in the configuration file.

As of version 3.2.3, there are no init scripts for mongos. The mongos process is used only insharding(page 731). You can use the mongod init script to derive your own mongos init script for use in such environments. See the mongosreference for configuration details.

Install MongoDB Community Edition

Note: To install a version of MongoDB prior to 3.2, please refer to that version’s documentation. For example, see version3.02.

This installation guide only supports 64-bit systems. SeePlatform Support(page 934) for details.

Step 1: Configure the package management system (yum). Create a /etc/yum.repos.d/mongodb-org-3.2.repo file so that you can install MongoDB directly, using yum.

Changed in version 3.0: MongoDB Linux packages are in a new repository beginning with 3.0.

For the latest stable release of MongoDB Use the following repository file: [mongodb-org-3.2]

name=MongoDB Repository

baseurl=https://repo.mongodb.org/yum/redhat/$releasever/mongodb-org/3.2/x86_64/ gpgcheck=0

enabled=1

For versions of MongoDB earlier than 3.0 To install the packages from an earlierrelease series(page 1051), such as 2.4 or 2.6, you can specify the release series in the repository configuration. For example, to restrict your system to the 2.6 release series, create a /etc/yum.repos.d/mongodb-org-2.6.repo file to hold the following configuration information for the MongoDB 2.6 repository:

[mongodb-org-2.6]

name=MongoDB 2.6 Repository

baseurl=http://downloads-distro.mongodb.org/repo/redhat/os/x86_64/ gpgcheck=0

enabled=1

(14)

You can find .repo files for each releasein the repository itself3. Remember that odd-numbered minor release versions (e.g. 2.5) are development versions and are unsuitable for production use.

Step 2: Install the MongoDB packages and associated tools. When you install the packages, you choose whether to install the current release or a previous one. This step provides the commands for both.

To install the latest stable version of MongoDB, issue the following command:

sudo yum install -y mongodb-org

To install a specific release of MongoDB, specify each component package individually and append the version number to the package name, as in the following example:

sudo yum install -y mongodb-org-3.2.3 mongodb-org-server-3.2.3 mongodb-org-shell-3.2.3 mongodb-org-mongos-3.2.3 mongodb-org-tools-3.2.3

You can specify any available version of MongoDB. However yum will upgrade the packages when a newer version becomes available. To prevent unintended upgrades, pin the package. To pin a package, add the following exclude directive to your /etc/yum.conf file:

exclude=mongodb-org,mongodb-org-server,mongodb-org-shell,mongodb-org-mongos,mongodb-org-tools

Run MongoDB Community Edition

Prerequisites Configure SELinux

Important: You must configure SELinux to allow MongoDB to start on Red Hat Linux-based systems (Red Hat Enterprise Linux or CentOS Linux).

To configure SELinux, administrators have three options:

Note: All three options require root privileges. The first two options each requires a system reboot and may have larger implications for your deployment.

• Disable SELinux entirely by changing the SELINUX setting to disabled in /etc/selinux/config.

SELINUX=disabled

• Set SELinux to permissive mode in /etc/selinux/config by changing the SELINUX setting to permissive.

SELINUX=permissive

Note: You can use setenforce to change to permissive mode; this method does not require a reboot but is not persistent.

• Enable access to the relevant ports (e.g. 27017) for SELinux if in enforcing mode. See https://docs.mongodb.org/manual/reference/default-mongodb-port for more infor-mation on MongoDB’s default ports. For default settings, this can be accomplished by running

semanage port -a -t mongod_port_t -p tcp 27017

(15)

Warning: On RHEL 7.0, if you change the data path, the default SELinux policies will prevent mongod from having write access on the new data path if you do not change the security context.

You may alternatively choose not to install the SELinux packages when you are installing your Linux operating system, or choose to remove the relevant packages. This option is the most invasive and is not recommended.

Data Directories and Permissions Warning: On RHEL 7.0, if you change the data path, the default SELinux policies will prevent mongod from having write access on the new data path if you do not change the security context.

The MongoDB instance stores its data files in /var/lib/mongo and its log files in /var/log/mongodb by default, and runs using the mongod user account. You can specify alternate log and data file directories in /etc/mongod.conf. See systemLog.path and storage.dbPath for additional information.

If you change the user that runs the MongoDB process, you must modify the access control rights to the /var/lib/mongoand /var/log/mongodb directories to give this user access to these directories.

Procedure

Step 1: Start MongoDB. You can start the mongod process by issuing the following command:

sudo service mongod start

Step 2: Verify that MongoDB has started successfully You can verify that the mongod process has started suc-cessfully by checking the contents of the log file at /var/log/mongodb/mongod.log for a line reading

[initandlisten] waiting for connections on port <port>

where <port> is the port configured in /etc/mongod.conf, 27017 by default.

You can optionally ensure that MongoDB will start following a system reboot by issuing the following command:

sudo chkconfig mongod on

Step 3: Stop MongoDB. As needed, you can stop the mongod process by issuing the following command:

sudo service mongod stop

Step 4: Restart MongoDB. You can restart the mongod process by issuing the following command:

sudo service mongod restart

You can follow the state of the process for errors or important messages by watching the output in the /var/log/mongodb/mongod.logfile.

Step 5: Begin using MongoDB. To help you start using MongoDB, MongoDB provides Getting Started Guides in various driver editions. See getting-started for the available editions.

Before deploying MongoDB in a production environment, consider theProduction Notes(page 214) document. Later, to stop MongoDB, press Control+C in the terminal where the mongod instance is running.

(16)

Uninstall MongoDB Community Edition To completely remove MongoDB from a system, you must remove the MongoDB applications themselves, the configuration files, and any directories containing data and logs. The following section guides you through the necessary steps.

Warning: This process will completely remove MongoDB, its configuration, and all databases. This process is not reversible, so ensure that all of your configuration and data is backed up before proceeding.

Step 1: Stop MongoDB. Stop the mongod process by issuing the following command:

Step 2: Remove Packages. Remove any MongoDB packages that you had previously installed.

sudo yum erase $(rpm -qa | grep mongodb-org)

Step 3: Remove Data Directories. Remove MongoDB databases and log files.

sudo rm -r /var/log/mongodb sudo rm -r /var/lib/mongo

Install MongoDB Community Edition on SUSE

On this page

Overview Use this tutorial to install MongoDB Community Edition on SUSE Linux from .rpm packages. While SUSE distributions include their own MongoDB Community Edition packages, the official MongoDB Community Edition packages are generally more up to date.

Platform Support

(17)

These packages conflict with the mongodb, mongodb-server, and mongodb-clients packages provided by Ubuntu.

Note: SUSE Linux Enterprise Server and potentially other SUSE distributions ship with virtual memory address space limited to 8 GB by default. You must adjust this in order to prevent virtual memory allocation failures as the database grows.

The SLES packages for MongoDB adjust these limits in the default scripts, but you will need to make this change manually if you are using custom scripts and/or the tarball release rather than the SLES packages.

Note: To install a version of MongoDB prior to 3.2, please refer to that version’s documentation. For example, see version3.04_.

Step 1: Configure the package management system (zypper). Add the repository so that you can install Mon-goDB using zypper.

For the latest stable release of MongoDB Use the following command:

sudo zypper addrepo --no-gpgcheck https://repo.mongodb.org/zypper/suse/$(sed -rn _{'s/VERSION=.*([0-9]{2}).*/\1/p'} /etc/os-release)/mongodb-org/3.2/x86_64/ mongodb

For versions of MongoDB earlier than 3.2 To install MongoDB packages from a previous release series (page 1051), such as 3.0, you can specify the release series in the repository configuration. For example, to restrict your SUSE 11 system to the 3.0 release series, use the following command:

sudo zypper addrepo --no-gpgcheck https://repo.mongodb.org/zypper/suse/11/mongodb-org/3.0/x86_64/ mongodb

To install the latest stable version of MongoDB, issue the following command:

sudo zypper -n install mongodb-org

(18)

sudo zypper install mongodb-org-3.2.3 mongodb-org-server-3.2.3 mongodb-org-shell-3.2.3 mongodb-org-mongos-3.2.3 mongodb-org-tools-3.2.3

You can specify any available version of MongoDB. However zypper will upgrade the packages when a newer version becomes available. To prevent unintended upgrades, pin the packages by running the following command:

sudo zypper addlock mongodb-org-3.2.3 mongodb-org-server-3.2.3 mongodb-org-shell-3.2.3 mongodb-org-mongos-3.2.3 mongodb-org-tools-3.2.3

Previous versions of MongoDB packages use a different repository location. Refer to the version of the documentation appropriate for your MongoDB version.

Prerequisites The MongoDB instance stores its data files in /var/lib/mongo and its log files in /var/log/mongodb by default, and runs using the mongod user account. You can specify alternate log and data file directories in /etc/mongod.conf. See systemLog.path and storage.dbPath for additional in-formation.

Procedure

(19)

sudo zypper remove $(rpm -qa | grep mongodb-org)

Install MongoDB Community Edition on Amazon Linux

On this page

Overview Use this tutorial to install MongoDB Community Edition on Amazon Linux from .rpm packages. This installation guide only supports 64-bit systems. SeePlatform Support(page 934) for details.

(20)

Step 1: Configure the package management system (yum). Create a /etc/yum.repos.d/mongodb-org-3.2.repo file so that you can install MongoDB directly, using yum.

For the latest stable release of MongoDB Use the following repository file: [mongodb-org-3.2]

name=MongoDB Repository

baseurl=https://repo.mongodb.org/yum/amazon/2013.03/mongodb-org/3.2/x86_64/ gpgcheck=0

enabled=1

For versions of MongoDB earlier than 3.0 To install the packages from an earlierrelease series(page 1051), such as 2.4 or 2.6, you can specify the release series in the repository configuration. For example, to restrict your system to the 2.6 release series, create a /etc/yum.repos.d/mongodb-org-2.6.repo file to hold the following configuration information for the MongoDB 2.6 repository:

[mongodb-org-2.6]

name=MongoDB 2.6 Repository

baseurl=http://downloads-distro.mongodb.org/repo/redhat/os/x86_64/ gpgcheck=0

enabled=1

You can find .repo files for each releasein the repository itself6_{. Remember that odd-numbered minor release} versions (e.g. 2.5) are development versions and are unsuitable for production use.

To install the latest stable version of MongoDB, issue the following command: 5_{https://docs.mongodb.org/v3.0/tutorial/install-mongodb-on-amazon/}

(21)

sudo yum install -y mongodb-org

sudo yum install -y mongodb-org-3.2.3 mongodb-org-server-3.2.3 mongodb-org-shell-3.2.3 mongodb-org-mongos-3.2.3 mongodb-org-tools-3.2.3

You can specify any available version of MongoDB. However yum will upgrade the packages when a newer version becomes available. To prevent unintended upgrades, pin the package. To pin a package, add the following exclude directive to your /etc/yum.conf file:

exclude=mongodb-org,mongodb-org-server,mongodb-org-shell,mongodb-org-mongos,mongodb-org-tools

Run MongoDB Community Edition The MongoDB instance stores its data files in /var/lib/mongo and its log files in /var/log/mongodb by default, and runs using the mongod user account. You can specify alternate log and data file directories in /etc/mongod.conf. See systemLog.path and storage.dbPath for additional information.

(22)

sudo yum erase $(rpm -qa | grep mongodb-org)

Install MongoDB Community Edition on Ubuntu

On this page

Overview Use this tutorial to install MongoDB Community Edition on LTS Ubuntu Linux systems from .deb packages. While Ubuntu includes its own MongoDB packages, the official MongoDB Community Edition packages are generally more up-to-date.

Platform Support

MongoDB only provides packages for 64-bit long-term support Ubuntu releases. Currently, this means 12.04 LTS (Precise Pangolin) and 14.04 LTS (Trusty Tahr). While the packages may work with other Ubuntu releases, this is not a supported configuration.

(23)

These packages conflict with the mongodb, mongodb-server, and mongodb-clients packages provided by Ubuntu.

Init Scripts The mongodb-org package includes various init scripts, including the init script /etc/init.d/mongod. You can use these scripts to stop, start, and restart daemon processes.

MongoDB only provides packages for 64-bit long-term support Ubuntu releases. Currently, this means 12.04 LTS (Precise Pangolin) and 14.04 LTS (Trusty Tahr). While the packages may work with other Ubuntu releases, this is not a supported configuration.

Step 1: Import the public key used by the package management system. The Ubuntu package management tools (i.e. dpkg and apt) ensure package consistency and authenticity by requiring that distributors sign packages with GPG keys. Issue the following command to import theMongoDB public GPG Key8_:

sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv EA312927

Step 2: Create a list file for MongoDB. Create the /etc/apt/sources.list.d/mongodb-org-3.2.list list file using the command appropriate for your version of Ubuntu:

Ubuntu 12.04

echo "deb http://repo.mongodb.org/apt/ubuntu precise/mongodb-org/3.2 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-3.2.list

Ubuntu 14.04

echo "deb http://repo.mongodb.org/apt/ubuntu trusty/mongodb-org/3.2 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-3.2.list

Step 3: Reload local package database. Issue the following command to reload the local package database:

sudo apt-get update

Step 4: Install the MongoDB packages. You can install either the latest stable version of MongoDB or a specific version of MongoDB.

7_{https://docs.mongodb.org/v3.0/tutorial/install-mongodb-on-ubuntu/} 8_{https://www.mongodb.org/static/pgp/server-3.2.asc}

(24)

Install the latest stable version of MongoDB. Issue the following command:

sudo apt-get install -y mongodb-org

Install a specific release of MongoDB. To install a specific release, you must specify each component package individually along with the version number, as in the following example:

sudo apt-get install -y mongodb-org=3.2.3 mongodb-org-server=3.2.3 mongodb-org-shell=3.2.3 mongodb-org-mongos=3.2.3 mongodb-org-tools=3.2.3

If you only install mongodb-org=3.2.3 and do not include the component packages, the latest version of each MongoDB package will be installed regardless of what version you specified.

Pin a specific version of MongoDB. Although you can specify any available version of MongoDB, apt-get will upgrade the packages when a newer version becomes available. To prevent unintended upgrades, pin the package. To pin the version of MongoDB at the currently installed version, issue the following command sequence:

echo "mongodb-org hold" | sudo dpkg --set-selections

echo "mongodb-org-server hold" | sudo dpkg --set-selections

echo "mongodb-org-shell hold" | sudo dpkg --set-selections

echo "mongodb-org-mongos hold" | sudo dpkg --set-selections

echo "mongodb-org-tools hold" | sudo dpkg --set-selections

Run MongoDB Community Edition The MongoDB instance stores its data files in /var/lib/mongodb and its log files in /var/log/mongodb by default, and runs using the mongodb user account. You can specify alter-nate log and data file directories in /etc/mongod.conf. See systemLog.path and storage.dbPath for additional information.

If you change the user that runs the MongoDB process, you must modify the access control rights to the /var/lib/mongodband /var/log/mongodb directories to give this user access to these directories.

Step 1: Start MongoDB. Issue the following command to start mongod:

Step 2: Verify that MongoDB has started successfully Verify that the mongod process has started successfully by checking the contents of the log file at /var/log/mongodb/mongod.log for a line reading

Step 4: Restart MongoDB. Issue the following command to restart mongod:

(25)

sudo apt-get purge mongodb-org*

sudo rm -r /var/log/mongodb sudo rm -r /var/lib/mongodb

Install MongoDB Community Edition on Debian

On this page

Overview Use this tutorial to install MongoDB Community Edition from .deb packages on Debian 7 “Wheezy”. While Debian includes its own MongoDB packages, the official MongoDB Community Edition packages are more up to date.

MongoDB only provides packages for 64-bit Debian “Wheezy”. These packages may work with other Debian releases, but this is not a supported configuration.

(26)

These packages conflict with the mongodb, mongodb-server, and mongodb-clients packages provided by Debian.

Init Scripts The mongodb-org package includes various init scripts, including the init script /etc/init.d/mongod. You can use these scripts to stop, start, and restart daemon processes.

The Debian package management tools (i.e. dpkg and apt) ensure package consistency and authenticity by requiring that distributors sign packages with GPG keys.

Step 1: Import the public key used by the package management system. The Ubuntu package management tools (i.e. dpkg and apt) ensure package consistency and authenticity by requiring that distributors sign packages with GPG keys. Issue the following command to import theMongoDB public GPG Key10_:

sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv EA312927

Step 2: Create a /etc/apt/sources.list.d/mongodb-org-3.2.list file for MongoDB. Create the list file using the following command:

echo "deb http://repo.mongodb.org/apt/debian wheezy/mongodb-org/3.2 main" | sudo tee /etc/apt/sources.list.d/mongodb-org-3.2.list

Currently packages are only available for Debian 7 (Wheezy).

Step 3: Reload local package database. Issue the following command to reload the local package database:

sudo apt-get update

Step 4: Install the MongoDB packages. You can install either the latest stable version of MongoDB or a specific version of MongoDB.

9_{https://docs.mongodb.org/v3.0/tutorial/install-mongodb-on-debian/} 10_{https://www.mongodb.org/static/pgp/server-3.2.asc}

(27)

Install the latest stable version of MongoDB. Issue the following command:

sudo apt-get install -y mongodb-org

Install a specific release of MongoDB. To install a specific release, you must specify each component package individually along with the version number, as in the following example:

sudo apt-get install -y mongodb-org=3.2.3 mongodb-org-server=3.2.3 mongodb-org-shell=3.2.3 mongodb-org-mongos=3.2.3 mongodb-org-tools=3.2.3

If you only install mongodb-org=3.2.3 and do not include the component packages, the latest version of each MongoDB package will be installed regardless of what version you specified.

Pin a specific version of MongoDB. Although you can specify any available version of MongoDB, apt-get will upgrade the packages when a newer version becomes available. To prevent unintended upgrades, pin the package. To pin the version of MongoDB at the currently installed version, issue the following command sequence:

echo "mongodb-org hold" | sudo dpkg --set-selections

echo "mongodb-org-server hold" | sudo dpkg --set-selections

echo "mongodb-org-shell hold" | sudo dpkg --set-selections

echo "mongodb-org-mongos hold" | sudo dpkg --set-selections

echo "mongodb-org-tools hold" | sudo dpkg --set-selections

Run MongoDB Community Edition The MongoDB instance stores its data files in /var/lib/mongodb and its log files in /var/log/mongodb by default, and runs using the mongodb user account. You can specify alter-nate log and data file directories in /etc/mongod.conf. See systemLog.path and storage.dbPath for additional information.

If you change the user that runs the MongoDB process, you must modify the access control rights to the /var/lib/mongodband /var/log/mongodb directories to give this user access to these directories.

Step 1: Start MongoDB. Issue the following command to start mongod:

Step 2: Verify that MongoDB has started successfully Verify that the mongod process has started successfully by checking the contents of the log file at /var/log/mongodb/mongod.log for a line reading

Step 4: Restart MongoDB. Issue the following command to restart mongod:

(28)

sudo apt-get purge mongodb-org*

sudo rm -r /var/log/mongodb sudo rm -r /var/lib/mongodb

Install MongoDB Community Edition From Tarball

On this page

• Overview(page 23)

• Install MongoDB Community Edition(page 23) • Run MongoDB Community Edition(page 25)

Overview Compiled versions of MongoDB Community Edition for Linux provide a simple option for installing MongoDB Community Edition for other Linux systems without supported packages.

Install MongoDB Community Edition MongoDB provides archives for both 64-bit and 32-bit (depreciated) builds of Linux. Follow the installation procedure appropriate for your system.

Install for 64-bit Linux

(29)

Step 1: Download the binary files for the desired release of MongoDB. Download the binaries from https://www.mongodb.org/downloads.

For example, to download the latest release through the shell, issue the following:

curl -O https://fastdl.mongodb.org/linux/mongodb-linux-x86_64-3.2.3.tgz

Step 2: Extract the files from the downloaded archive. For example, from a system shell, you can extract through the tar command:

tar -zxvf mongodb-linux-x86_64-3.2.3.tgz

Step 3: Copy the extracted archive to the target directory. Copy the extracted folder to the location from which MongoDB will run.

mkdir -p mongodb

cp -R -n mongodb-linux-x86_64-3.2.3/ mongodb

Step 4: Ensure the location of the binaries is in the PATH variable. The MongoDB binaries are in the bin/ directory of the archive. To ensure that the binaries are in your PATH, you can modify your PATH.

For example, you can add the following line to your shell’s rc file (e.g. ~/.bashrc):

export PATH=<mongodb-install-directory>/bin:$PATH

Replace <mongodb-install-directory> with the path to the extracted MongoDB archive. Install for 32-bit Linux

Note: Starting in MongoDB 3.2, 32-bit binaries are deprecated and will be unavailable in future releases.

curl -O https://fastdl.mongodb.org/linux/mongodb-linux-i686-3.2.3.tgz

tar -zxvf mongodb-linux-i686-3.2.3.tgz

mkdir -p mongodb

(30)

Replace <mongodb-install-directory> with the path to the extracted MongoDB archive.

Step 1: Create the data directory. Before you start MongoDB for the first time, create the directory to which the mongod process will write data. By default, the mongod process uses the /data/db directory. If you create a directory other than this one, you must specify that directory in the dbpath option when starting the mongod process later in this procedure.

The following example command creates the default /data/db directory:

mkdir -p /data/db

Step 2: Set permissions for the data directory. Before running mongod for the first time, ensure that the user account running mongod has read and write permissions for the directory.

Step 3: Run MongoDB. To run MongoDB, run the mongod process at the system prompt. If necessary, specify the path of the mongod or the data directory. See the following examples.

Run without specifying paths If your system PATH variable includes the location of the mongod binary and if you use the default data directory (i.e., /data/db), simply enter mongod at the system prompt:

mongod

Specify the path of the mongod If your PATH does not include the location of the mongod binary, enter the full path to the mongod binary at the system prompt:

<path to binary>/mongod

Specify the path of the data directory If you do not use the default data directory (i.e., /data/db), specify the path to the data directory using the --dbpath option:

mongod --dbpath <path to data directory>

(31)

Install MongoDB Community Edition on OS X

On this page

• Overview(page 26)

• Install MongoDB Community Edition(page 26) • Run MongoDB(page 27)

Overview Use this tutorial to install MongoDB Community Edition on OS X systems. Platform Support

Starting in version 3.0, MongoDB only supports OS X versions 10.7 (Lion) and later on Intel x86-64.

MongoDB Community Edition is available through the popular OS X package managerHomebrew12_{or through the}

MongoDB Download site13_.

You can install MongoDB Community Edition withHomebrew15_{or manually. This section describes both methods.}

Install MongoDB Community Edition with Homebrew Homebrew16installs binary packages based on published “formulae.” This section describes how to update brew to the latest packages and install MongoDB Community Edition. Homebrew requires some initial setup and configuration, which is beyond the scope of this document.

Step 1: Update Homebrew’s package database. In a system shell, issue the following command:

brew update

Step 2: Install MongoDB. You can install MongoDB via brew with several different options. Use one of the following operations:

Install the MongoDB Binaries To install the MongoDB binaries, issue the following command in a system shell:

brew install mongodb

Build MongoDB from Source with TLS/SSL Support To build MongoDB from the source files and include TLS/SSL support, issue the following from a system shell:

brew install mongodb --with-openssl

12_{http://brew.sh/}

13_{http://www.mongodb.org/downloads}

14_{https://docs.mongodb.org/v3.0/tutorial/install-mongodb-on-os-x/} 15_{http://brew.sh/}

(32)

Install the Latest Development Release of MongoDB To install the latest development release for use in testing and development, issue the following command in a system shell:

brew install mongodb --devel

Install MongoDB Community Edition Manually Only install MongoDB Community Edition using this procedure if you cannot usehomebrew(page 26).

curl -O https://fastdl.mongodb.org/osx/mongodb-osx-x86_64-3.2.3.tgz

tar -zxvf mongodb-osx-x86_64-3.2.3.tgz

mkdir -p mongodb

cp -R -n mongodb-osx-x86_64-3.2.3/ mongodb

Replace <mongodb-install-directory> with the path to the extracted MongoDB archive.

Run MongoDB

Step 1: Create the data directory. Before you start MongoDB for the first time, create the directory to which the mongod process will write data. By default, the mongod process uses the /data/db directory. If you create a directory other than this one, you must specify that directory in the dbpath option when starting the mongod process later in this procedure.

The following example command creates the default /data/db directory:

mkdir -p /data/db

Step 2: Set permissions for the data directory. Before running mongod for the first time, ensure that the user account running mongod has read and write permissions for the directory.

Step 3: Run MongoDB. To run MongoDB, run the mongod process at the system prompt. If necessary, specify the path of the mongod or the data directory. See the following examples.

(33)

Run without specifying paths If your system PATH variable includes the location of the mongod binary and if you use the default data directory (i.e., /data/db), simply enter mongod at the system prompt:

mongod

Specify the path of the mongod If your PATH does not include the location of the mongod binary, enter the full path to the mongod binary at the system prompt:

<path to binary>/mongod

Specify the path of the data directory If you do not use the default data directory (i.e., /data/db), specify the path to the data directory using the --dbpath option:

mongod --dbpath <path to data directory>

Install MongoDB Community Edition on Windows

On this page

• Overview(page 28) • Requirements(page 28)

• Get MongoDB Community Edition(page 29) • Install MongoDB Community Edition(page 29) • Run MongoDB Community Edition(page 30)

• Configure a Windows Service for MongoDB Community Edition(page 31) • Manually Create a Windows Service for MongoDB Community Edition(page 32) • Additional Resources(page 33)

Overview Use this tutorial to install MongoDB Community Edition on Windows systems. Platform Support

Starting in version 2.2, MongoDB does not support Windows XP. Please use a more recent version of Windows to use more recent releases of MongoDB.

Important: If you are running any edition of Windows Server 2008 R2 or Windows 7, please installa hotfix to resolve an issue with memory mapped files on Windows17.

Requirements MongoDB Community Edition requires Windows Server 2008 R2, Windows Vista, or later. The .msiinstaller includes all other software dependencies and will automatically upgrade any older version of MongoDB installed using an .msi file.

(34)

Get MongoDB Community Edition

Step 1: Determine which MongoDB build you need. There are three builds of MongoDB for Windows:

MongoDB for Windows 64-bit runs only on Windows Server 2008 R2, Windows 7 64-bit, and newer versions of Windows. This build takes advantage of recent enhancements to the Windows Platform and cannot operate on older versions of Windows.

MongoDB for Windows 32-bit runs on any 32-bit version of Windows newer than Windows Vista. 32-bit versions of MongoDB are only intended for older systems and for use in testing and development systems. 32-bit versions of MongoDB only support databases smaller than 2GB.

Note: Starting in MongoDB 3.2, 32-bit binaries are deprecated and will be unavailable in future releases.

MongoDB for Windows 64-bit Legacy runs on Windows Vista, Windows Server 2003, and Windows Server 2008 and does not include recent performance enhancements.

To find which version of Windows you are running, enter the following commands in the Command Prompt or Pow-ershell:

wmic os get caption

wmic os get osarchitecture

Step 2: Download MongoDB for Windows. Download the latest production release of MongoDB from the Mon-goDB downloads page19_{. Ensure you download the correct version of MongoDB for your Windows system. The} 64-bit versions of MongoDB do not work with 32-bit Windows.

Interactive Installation

Step 1: Install MongoDB for Windows. In Windows Explorer, locate the downloaded MongoDB .msi file, which typically is located in the default Downloads folder. Double-click the .msi file. A set of screens will appear to guide you through the installation process.

You may specify an installation directory if you choose the “Custom” installation option. Note: These instructions assume that you have installed MongoDB to C:\mongodb.

MongoDB is self-contained and does not have any other system dependencies. You can run MongoDB from any folder you choose. You may install MongoDB in any folder (e.g. D:\test\mongodb).

Unattended Installation You may install MongoDB Community unattended on Windows from the command line using msiexec.exe.

18_{https://docs.mongodb.org/v3.0/tutorial/install-mongodb-on-windows/} 19_{http://www.mongodb.org/downloads}

(35)

Step 1: Open an Administrator command prompt. Press the Win key, type cmd.exe, and press Ctrl + Shift + Enterto run the Command Prompt as Administrator.

Execute the remaining steps from the Administrator command prompt.

Step 2: Install MongoDB for Windows. Change to the directory containing the .msi installation binary of your choice and invoke:

msiexec.exe /q /i mongodb-win32-x86_64-2008plus-ssl-3.2.3-signed.msi ^ INSTALLLOCATION="C:\mongodb" ^

ADDLOCAL="all"

You can specify the installation location for the executable by modifying the INSTALLLOCATION value.

By default, this method installs all MongoDB binaries. To install specific MongoDB component sets, you can specify them in the ADDLOCAL argument using a comma-separated list including one or more of the following component sets:

Component Set Binaries

Server mongod.exe

Router mongos.exe

Client mongo.exe

MonitoringTools mongostat.exe, mongotop.exe

ImportExportTools mongodump.exe, mongorestore.exe, mongoexport.exe, mongoimport.exe

MiscellaneousTools bsondump.exe, mongofiles.exe, mongooplog.exe, mongoperf.exe For instance, to install only the MongoDB utilities, invoke:

msiexec.exe /q /i mongodb-win32-x86_64-2008plus-ssl-3.2.3-signed.msi ^ INSTALLLOCATION="C:\mongodb" ^

ADDLOCAL="MonitoringTools,ImportExportTools,MiscellaneousTools"

Warning: Do not make mongod.exe visible on public networks without running in “Secure Mode” with the authsetting. MongoDB is designed to be run in trusted environments, and the database does not enable “Secure Mode” by default.

Step 1: Set up the MongoDB environment. MongoDB requires a data directory to store all data. MongoDB’s default data directory path is \data\db. Create this folder using the following commands from a Command Prompt:

md \data\db

You can specify an alternate path for data files using the --dbpath option to mongod.exe, for example:

C:\mongodb\bin\mongod.exe --dbpath d:\test\mongodb\data

If your path includes spaces, enclose the entire path in double quotes, for example:

C:\mongodb\bin\mongod.exe --dbpath "d:\test\mongo db data"

You may also specify the dbpath in a configuration file.

(36)

C:\mongodb\bin\mongod.exe

This starts the main MongoDB database process. The waiting for connections message in the console output indicates that the mongod.exe process is running successfully.

Depending on the security level of your system, Windows may pop up a Security Alert dialog box about blocking “some features” of C:\mongodb\bin\mongod.exe from communicating on networks. All users should select Private Networks, such as my home or work networkand click Allow access. For additional information on security and MongoDB, please see theSecurity Documentation(page 315).

Step 3: Connect to MongoDB. To connect to MongoDB through the mongo.exe shell, open another Command Prompt.

C:\mongodb\bin\mongo.exe

If you want to develop applications using .NET, see the documentation ofC# and MongoDB20_{for more information.}

Configure a Windows Service for MongoDB Community Edition

Step 2: Create directories. Create directories for your database and log files:

mkdir c:\data\db mkdir c:\data\log

Step 3: Create a configuration file. Create a configuration file. The file must set systemLog.path. Include additional configuration options as appropriate.

For example, create a file at C:\mongodb\mongod.cfg that specifies both systemLog.path and storage.dbPath: systemLog: destination: file path: c:\data\log\mongod.log storage: dbPath: c:\data\db 20_{https://docs.mongodb.org/ecosystem/drivers/csharp}

(37)

Step 4: Install the MongoDB service.

Important: Run all of the following commands in Command Prompt with “Administrative Privileges”.

Install the MongoDB service by starting mongod.exe with the --install option and the -config option to specify the previously created configuration file.

"C:\mongodb\bin\mongod.exe" --config "C:\mongodb\mongod.cfg" --install

To use an alternate dbpath, specify the path in the configuration file (e.g. C:\mongodb\mongod.cfg) or on the command line with the --dbpath option.

If needed, you can install services for multiple instances of mongod.exe or mongos.exe. Install each service with a unique --serviceName and --serviceDisplayName. Use multiple instances only when sufficient system resources exist and your system design requires it.

Step 5: Start the MongoDB service.

net start MongoDB

Step 6: Stop or remove the MongoDB service as needed. To stop the MongoDB service use the following com-mand:

net stop MongoDB

To remove the MongoDB service use the following command: "C:\mongodb\bin\mongod.exe" --remove

Manually Create a Windows Service for MongoDB Community Edition You can set up the MongoDB server as a Windows Service that starts automatically at boot time.

The following procedure assumes you have installed MongoDB Community using the .msi installer with the path C:\mongodb\.

If you have installed in an alternative directory, you will need to adjust the paths as appropriate.

Step 2: Create directories. Create directories for your database and log files:

mkdir c:\data\db mkdir c:\data\log

Step 3: Create a configuration file. Create a configuration file. The file must set systemLog.path. Include additional configuration options as appropriate.

For example, create a file at C:\mongodb\mongod.cfg that specifies both systemLog.path and storage.dbPath:

(38)

systemLog:

destination: file

path: c:\data\log\mongod.log storage:

dbPath: c:\data\db

Step 4: Create the MongoDB service. Create the MongoDB service.

sc.exe create MongoDB binPath= "C:\mongodb\bin\mongod.exe --service --config=\"C:\mongodb\mongod.cfg\"" DisplayName= "MongoDB" start= "auto"

sc.exerequires a space between “=” and the configuration values (eg “binPath= ”), and a “\” to escape double quotes.

If successfully created, the following log message will display: [SC] CreateService SUCCESS

Step 5: Start the MongoDB service.

net start MongoDB

Step 6: Stop or remove the MongoDB service as needed. To stop the MongoDB service, use the following com-mand:

net stop MongoDB

To remove the MongoDB service, first stop the service and then run the following command:

sc.exe delete MongoDB

Additional Resources

• MongoDB for Developers Free Course21

• MongoDB for .NET Developers Free Online Course22

• MongoDB Architecture Guide23

Install MongoDB Enterprise

These documents provide instructions to install MongoDB Enterprise.

MongoDB Enterprise is available for MongoDB Enterprise subscribers and includes several additional features in-cluding support for SNMP monitoring, LDAP authentication, Kerberos authentication, and System Event Auditing. Install on Linux(page 34) Install the official builds of MongoDB Enterprise on Linux-based systems.

Install on OS X(page 51) Install the official build of MongoDB Enterprise on OS X

Install on Windows(page 52) Install MongoDB Enterprise on Windows using the .msi installer. 21_{https://university.mongodb.com/courses/M101P/about?jmp=docs}

22_{https://university.mongodb.com/courses/M101N/about?jmp=docs} 23_{https://www.mongodb.com/lp/white-paper/architecture-guide?jmp=docs}