• Replication >
• Replica Set Administration >
• Add Members to a Replica Set

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 to an existing replica set, do one of the following to prepare the new member’s data directory:

• Make sure the new member’s data directory does not contain data. The new member will copy the data from an existing member.

  If the new member is in a recovering state, it must exit and become a secondary before MongoDB can copy all data as part of the replication process. This process takes time but does not require administrator intervention.

• Manually copy the data directory from an existing member. The new member becomes a secondary member and will catch up to the current state of the replica set after a short interval. Copying the data over manually shortens the amount of time for the new member to become current.

  Ensure that you can copy the data directory to the new member and begin replication within the window allowed by the oplog. If the difference in the amount of time between the most recent operation and the most recent operation to the database exceeds the length of the oplog on the existing members, then the new instance will have to perform an initial sync, which completely resynchronizes the data, as described in Resync a Member of a Replica Set.

  Use db.printReplicationInfo() to check the current state of replica set members with regards to the oplog.

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() method to view replica set status. For a description of the status fields, see replSetGetStatus.

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:
  • add the new member as a non-voting members or,
  • remove votes from an existing member.

• <   Convert a Standalone to a Replica Set
• /\  Replication
• Remove Members from Replica Set  >