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.

If you wish to deploy a replica set from a single MongoDB instance, see Convert a Standalone to a Replica Set. For more information on replica set deployments, see the Replication and Replica Set Deployment Architectures documentation.

Overview

Three member replica sets provide enough redundancy to survive most network partitions and other system failures. These sets also have sufficient capacity for many distributed read operations. Replica sets should always have an odd number of members. This ensures that elections will proceed smoothly. For more about designing replica sets, see the Replication overview.

The basic procedure is to start the mongod instances that will become members of the replica set, configure the replica set itself, and then add the mongod instances to it.

Requirements

For production deployments, you should maintain as much separation between members as possible by hosting the mongod instances on separate machines. When using virtual machines for production deployments, you should place each mongod instance on a separate host server serviced by redundant power circuits and redundant network paths.

Before you can deploy a replica set, you must install MongoDB on each system that will be part of your replica set. If you have not already installed MongoDB, see the installation tutorials.

Before creating your replica set, you should verify that your network configuration allows communication among all members; i.e. each member must be able to connect to every other member. For instructions on how to check your connection, see Test Connections Between all Members.

Procedure

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

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

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

    You will need to either configure your DNS names appropriately, or set up your systems’ /etc/hosts file to reflect this configuration.

  • Ensure that network traffic can pass between all members in the network securely and efficiently. Consider the following:

    • Establish a virtual private network. Ensure that your network topology routes all traffic between members within a single site over the local area network.
    • Configure authentication using auth and keyFile, so that only servers and processes with authentication can connect to the replica set.
    • Configure networking and firewall rules so that only traffic (incoming and outgoing packets) on the default MongoDB port (e.g. 27017) from within your deployment is permitted.

    For more information on security and firewalls, see Inter-Process Authentication.

  • You must specify the run time configuration on each system in a configuration file stored in /etc/mongodb.conf or a related location. Do not specify the set’s configuration in the mongo shell.

    Use the following configuration for each of your MongoDB instances. You should set values that are appropriate for your systems, as needed:

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

    The dbpath indicates where you want mongod to store data files. The dbpath must exist before you start mongod. If it does not exist, create the directory and ensure mongod has permission to read and write data to this path. For more information on permissions, see the security operations documentation.

    Modifying bind_ip ensures that mongod will only listen for connections from applications on the configured address.

    For more information about the run time options used above and other configuration options, see Configuration File Options.

To deploy a production replica set:

  1. Start a mongod instance on each system that will be part of your replica set. Specify the same replica set name on each instance. For additional mongod configuration options specific to replica sets, see Replication Options.

    Important

    If your application connects to more than one replica set, each set should have a distinct name. Some drivers group replica set connections by replica set name.

    If you use a configuration file, then start each mongod instance with a command that resembles the following:

    mongod --config /etc/mongodb.conf
    

    Change /etc/mongodb.conf to the location of your configuration file.

    Note

    You will likely want to use and configure a control script to manage this process in production deployments. Control scripts are beyond the scope of this document.

  2. Open a mongo shell connected to one of the hosts by issuing the following command:

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

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

    rs.conf()
    

    The replica set configuration object resembles the following

    {
       "_id" : "rs0",
       "version" : 4,
       "members" : [
          {
             "_id" : 1,
             "host" : "mongodb0.example.net:27017"
          }
       ]
    }
    
  1. In the mongo shell connected to the primary, add the remaining members to the replica set using rs.add() in the mongo shell on the current primary (in this example, mongodb0.example.net). The commands should resemble the following:

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

    When complete, you should have a fully functional replica set. The new replica set will elect a primary.

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:

Refer to Replica Set Read and Write Semantics for a detailed explanation of read and write semantics in MongoDB.