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

Add Members to a Replica Set

Overview

This tutorial explains how to add an additional member to an existing replica set.

Before adding a new member, see the Adding Members topic in the Replica Set Operation and Management document.

For background on replication deployment patterns, see the Replica Set Architectures and Deployment Patterns document.

Requirements

  1. An active replica set.
  2. A new MongoDB system capable of supporting your dataset, accessible by the active replica set through the network.

If neither of these conditions are satisfied, please use the MongoDB installation tutorial and the Deploy a Replica Set tutorial instead.

Procedures

The examples in this procedure use the following configuration:

  • The active replica set is rs0.
  • The new member to be added is mongodb3.example.net.
  • The mongod instance default port is 27017.
  • The mongodb.conf configuration file exists in the /etc directory and contains the following replica set information:
port = 27017

bind_ip = 10.8.0.10

dbpath = /srv/mongodb/db0

logpath = /var/log/mongodb.log

fork = true

replSet = rs0

For more information on configuration options, see Configuration File Options.

Add a Member to an Existing Replica Set

This procedure uses the above example configuration.

  1. Deploy a new mongod instance, specifying the name of the replica set. You can do this one of two ways:

    • Using the mongodb.conf file. On the primary, issue a command that resembles the following:

      mongod --config /etc/mongodb.conf
      
    • Using command line arguments. On the primary, issue command that resembles the following:

      mongod --dbpath /srv/mongodb/db0 --replSet rs0
      

    Replace /srv/mongodb/db0 with the path of your dbpath.

    Take note of the host name and port information for the new mongod instance.

  2. Open a mongo shell connected to the replica set’s primary:

    mongo
    

    Note

    The primary is the only member that can add or remove members from the replica set. If you do not know which member is the primary, log into any member of the replica set using mongo and issue the db.isMaster() command to determine which member is in the isMaster.primary field. For example, on the system shell:

    mongo mongodb0.example.net
    

    Then in the mongo shell:

    db.isMaster()
    

    If you are not connected to the primary, disconnect from the current client and reconnect to the primary.

  3. In the mongo shell, issue the following command to add the new member to the replica set.

    rs.add("mongodb3.example.net")
    

    Note

    You can also include the port number, depending on your setup:

    rs.add("mongodb3.example.net:27017")
    
  4. Verify that the member is now part of the replica set by calling the rs.conf() method, which displays the replica set configuration:

    rs.conf()
    

    You can use the rs.status() function to provide an overview of replica set status.

Add a Member to an Existing Replica Set (Alternate Procedure)

Alternately, you can add a member to a replica set by specifying an entire configuration document with some or all of the fields in a members sub-documents. For example:

rs.add({_id: 1, host: "mongodb3.example.net:27017", priority: 0, hidden: true})

This configures a hidden member that is accessible at mongodb3.example.net:27017. See host, priority, and hidden for more information about these settings. When you specify a full configuration object with rs.add(), you must declare the _id field, which is not automatically populated in this case.

Production Notes

  • In production deployments you likely want to use and configure a control script to manage this process based on this command.
  • A member can be removed from a set and re-added later. If the removed member’s data is still relatively fresh, it can recover and catch up from its old data set. See the rs.add() and rs.remove() helpers.
  • If you have a backup or snapshot of an existing member, you can move the data files (i.e. /data/db or dbpath) to a new system and use them to quickly initiate a new member. These files must be:
    • clean: the existing dataset must be from a consistent copy of the database from a member of the same replica set. See the Backup Strategies for MongoDB Systems document for more information.
    • recent: the copy must more recent than the oldest operation in the primary member’s oplog. The new secondary must be able to become current using operations from the primary’s oplog.
  • There is a maximum of seven voting members in any replica set. When adding more members to a replica set that already has seven votes, you must either: