Navigation
This version of the documentation is archived and no longer supported.

Deploy a Replica Set

This tutorial describes how to create a three-member replica set from three existing mongod instances. The tutorial provides two procedures: one for development and test systems; and a one for production systems.

To instead deploy a replica set from a single standalone MongoDB instance, see Convert a Standalone to a Replica Set. For additional information regarding replica set deployments, see Replica Set Fundamental Concepts and Replica Set Architectures and Deployment Patterns.

Overview

Three member replica sets provide enough redundancy to survive most network partitions and other system failures. Additionally, these sets have sufficient capacity for many distributed read operations. Most deployments require no additional members or configuration.

Requirements

Most replica sets consist of three or more mongod instances. [1] This tutorial describes a three member set. Production environments should have at least three distinct systems so that each system can run its own instance of mongod. For development systems you can run all three instances of the mongod process on a local system or within a virtual instance. For production environments, you should maintain as much separation between members as possible. For example, when using virtual machines for production deployments, each member should live on a separate host server, served by redundant power circuits and with redundant network paths.

[1]To ensure smooth elections always design replica sets with odd numbers of members. Use Arbiters to ensure the set has odd number of voting members and avoid tied elections.

Procedures

These procedures assume you already have instances of MongoDB installed on the systems you will add as members of your replica set. If you have not already installed MongoDB, see the installation tutorials.

Deploy a Development or Test Replica Set

The examples in this procedure create a new replica set named rs0.

  1. Before creating your replica set, verify that every member can successfully connect to every other member. The network configuration must allow all possible connections between any two members. To test connectivity, see Test Connections Between all Members.

  2. Start three instances of mongod as members of a replica set named rs0, as described in this step. For ephemeral tests and the purposes of this guide, you may run the mongod instances in separate windows of GNU Screen. OS X and most Linux distributions come with screen installed by default [2] systems.

    1. Create the necessary data directories by issuing a command similar to the following:

      mkdir -p /srv/mongodb/rs0-0 /srv/mongodb/rs0-1 /srv/mongodb/rs0-2
      
    2. Issue the following commands, each in a distinct screen window:

      mongod --port 27017 --dbpath /srv/mongodb/rs0-0 --replSet rs0
      mongod --port 27018 --dbpath /srv/mongodb/rs0-1 --replSet rs0
      mongod --port 27019 --dbpath /srv/mongodb/rs0-2 --replSet rs0
      

      This starts each instance as a member of a replica set named rs0, each running on a distinct port. If you are already using these ports, you can select different ports. See the documentation of the following options for more information: --port, --dbpath, and --replSet.

  3. Open a mongo shell and connect to the first mongod instance, with the following command:

    mongo --port 27017
    
  4. Create a replica set configuration object in the mongo shell environment to use to initiate the replica set with the following sequence of operations:

    rsconf = {
               _id: "rs0",
               members: [
                          {
                           _id: 0,
                           host: "<hostname>:27017"
                          }
                        ]
             }
    
  5. Use rs.initiate() to initiate a replica set consisting of the current member and using the default configuration:

    rs.initiate( rsconf )
    
  6. Display the current replica configuration:

    rs.conf()
    
  7. Add the second and third mongod instances to the replica set using the rs.add() method. Replace <hostname> with your system’s hostname in the following examples:

    rs.add("<hostname>:27018")
    rs.add("<hostname>:27019")
    

    After these commands return you have a fully functional replica set. New replica sets elect a primary within a few seconds.

  8. Check the status of your replica set at any time with the rs.status() operation.

See also

The documentation of the following shell functions for more information:

You may also consider the simple setup script as an example of a basic automatically configured replica set.

[2]GNU Screen is packaged as screen on Debian-based, Fedora/Red Hat-based, and Arch Linux.

Deploy a Production Replica Set

Production replica sets are very similar to the development or testing deployment described above, with the following differences:

  • Each member of the replica set resides on its own machine, and the MongoDB processes all bind to port 27017, which is the standard MongoDB port.

  • Each member of the replica set must be accessible by way of resolvable DNS or hostnames in the following scheme:

    • mongodb0.example.net
    • mongodb1.example.net
    • mongodb2.example.net

    Configure DNS names appropriately, or set up your systems’ /etc/hosts file to reflect this configuration.

  • You specify run-time configuration on each system in a configuration file stored in /etc/mongodb.conf or in a related location. You do not specify run-time configuration through command line options.

    For each MongoDB instance, use the following configuration. Set configuration values appropriate to your systems:

    port = 27017
    
    bind_ip = 10.8.0.10
    
    dbpath = /srv/mongodb/
    
    fork = true
    
    replSet = rs0
    

    You do not need to specify an interface with bind_ip. However, if you do not specify an interface, MongoDB listens for connections on all available IPv4 interfaces. Modify bind_ip to reflect a secure interface on your system that is able to access all other members of the set and on which all other members of the replica set can access the current member. The DNS or host names must point and resolve to this IP address. Configure network rules or a virtual private network (i.e. “VPN”) to permit this access.

    For more documentation on run time options used above and on additional configuration options, see Configuration File Options.

To deploy a production replica set:

  1. Before creating your replica set, verify that every member can successfully connect to every other member. The network configuration must allow all possible connections between any two members. To test connectivity, see Test Connections Between all Members.

  2. On each system start the mongod process by issuing a command similar to following:

    mongod --config /etc/mongodb.conf
    

    Note

    In production deployments you likely want to use and configure a control script to manage this process based on this command. Control scripts are beyond the scope of this document.

  3. Open a mongo shell connected to this host:

    mongo
    
  4. Use rs.initiate() to initiate a replica set consisting of the current member and using the default configuration:

    rs.initiate()
    
  5. Display the current replica configuration:

    rs.conf()
    
  6. Add two members to the replica set by issuing a sequence of commands similar to the following:

    rs.add("mongodb1.example.net")
    rs.add("mongodb2.example.net")
    

    After these commands return you have a fully functional replica set. New replica sets elect a primary within a few seconds.

  7. Check the status of your replica set at any time with the rs.status() operation.

See also

The documentation of the following shell functions for more information: