• Replication >
• Change Hostnames in a Replica Set

Change Hostnames in a Replica Set

Overview

For most replica sets the hostnames [1] in the host field never change. However, in some cases you must migrate some or all host names in a replica set as organizational needs change. This document presents two possible procedures for changing the hostnames in the host field. Depending on your environments availability requirements, you may:

1. Make the configuration change without disrupting the availability of the replica set. While this ensures that your application will always be able to read and write data to the replica set, this procedure can take a long time and may incur downtime at the application layer. [2]

   For this procedure, see Changing Hostnames while Maintaining the Replica Set’s Availability.

2. Stop all members of the replica set at once running on the “old” hostnames or interfaces, make the configuration changes, and then start the members at the new hostnames or interfaces. While the set will be totally unavailable during the operation, the total maintenance window is often shorter.

   For this procedure, see Changing All Hostnames in Replica Set at Once.

See also

• Replica Set Configuration
• Replica Set Reconfiguration Process
• rs.conf() and rs.reconfig()

And the following tutorials:

• Deploy a Replica Set
• Add Members to a Replica Set

[1]	Always use resolvable hostnames for the value of the host field in the replica set configuration to avoid confusion and complexity.

[2]

You will have to configure your applications so that they can connect to the replica set at both the old and new locations. This often requires a restart and reconfiguration at the application layer, which may affect the availability of your applications. This re-configuration is beyond the scope of this document and makes the second option preferable when you must change the hostnames of all members of the replica set at once.

Procedures

Given a replica set with three members:

• database0.example.com:27017 (the primary)
• database1.example.com:27017
• database2.example.com:27017

And with the following rs.conf() output:

copy

{
    "_id" : "rs",
    "version" : 3,
    "members" : [
        {
            "_id" : 0,
            "host" : "database0.example.com:27017"
        },
        {
            "_id" : 1,
            "host" : "database1.example.com:27017"
        },
        {
            "_id" : 2,
            "host" : "database2.example.com:27017"
        }
    ]
}

The following procedures change the members’ hostnames as follows:

• mongodb0.example.net:27017 (the primary)
• mongodb1.example.net:27017
• mongodb2.example.net:27017

Use the most appropriate procedure for your deployment.

Changing Hostnames while Maintaining the Replica Set’s Availability

This procedure uses the above assumptions.

1. For each secondary in the replica set, perform the following sequence of operations:

   1. Stop the secondary.

   2. Restart the secondary at the new location.

   3. Open a mongo shell connected to the replica set’s primary. In our example, the primary runs on port 27017 so you would issue the following command:

      copy

      mongo --port 27017
      

   4. Run the following reconfigure option, for the host value where n is 1:

      copy

      cfg = rs.conf()
      
      cfg.members[1].host = "mongodb1.example.net:27017"
      
      rs.reconfig(cfg)
      

      See Replica Set Configuration for more information.

   5. Make sure your client applications are able to access the set at the new location and that the secondary has a chance to catch up with the other members of the set.

      Repeat the above steps for each non-primary member of the set.

2. Open a mongo shell connected to the primary and step down the primary using replSetStepDown. In the mongo shell, use the rs.stepDown() wrapper, as follows:

   copy

   rs.stepDown()
   

3. When the step down succeeds, shut down the primary.

4. To make the final configuration change, connect to the new primary in the mongo shell and reconfigure the host value where n is 0:

   copy

   cfg = rs.conf()
   
   cfg.members[0].host = "mongodb0.example.net:27017"
   
   rs.reconfig(cfg)
   

5. Start the original primary.

6. Open a mongo shell connected to the primary.

7. To confirm the new configuration, call rs.conf() in the mongo shell.

   Your output should resemble:

   copy

   {
       "_id" : "rs",
       "version" : 4,
       "members" : [
           {
               "_id" : 0,
               "host" : "mongodb0.example.net:27017"
           },
           {
               "_id" : 1,
               "host" : "mongodb1.example.net:27017"
           },
           {
               "_id" : 2,
               "host" : "mongodb2.example.net:27017"
           }
       ]
   }
   

Changing All Hostnames in Replica Set at Once

This procedure uses the above assumptions.

1. Stop all members in the replica set.

2. Restart each member on a different port and without using the --replSet run-time option. Changing the port number during maintenance prevents clients from connecting to this host while you perform maintenance. Use the member’s usual --dbpath, which in this example is /data/db1. Use a command that resembles the following:

   copy

   mongod --dbpath /data/db1/ --port 37017
   

3. For each member of the replica set, perform the following sequence of operations:

   1. Open a mongo shell connected to the mongod running on the new, temporary port. For example, for a member running on a temporary port of 37017, you would issue this command:

      copy

      mongo --port 37017
      

   2. Edit the replica set configuration manually. The replica set configuration is the only document in the system.replset collection in the local database. Edit the replica set configuration with the new hostnames and correct ports for all the members of the replica set. Consider the following sequence of commands to change the hostnames in a three-member set:

      copy

      use local
      
      cfg = db.system.replset.findOne( { "_id": "rs" } )
      
      cfg.members[0].host = "mongodb0.example.net:27017"
      
      cfg.members[1].host = "mongodb1.example.net:27017"
      
      cfg.members[2].host = "mongodb2.example.net:27017"
      
      db.system.replset.update( { "_id": "rs" } , cfg )
      

   3. Stop the mongod process on the member.

4. After re-configuring all members of the set, start each mongod instance in the normal way: use the usual port number and use the --replSet option. For example:

   copy

   mongod --dbpath /data/db1/ --port 27017 --replSet rs
   

5. Connect to one of the mongod instances using the mongo shell. For example:

   copy

   mongo --port 27017
   

6. To confirm the new configuration, call rs.conf() in the mongo shell.

   Your output should resemble:

   copy

   {
       "_id" : "rs",
       "version" : 4,
       "members" : [
           {
               "_id" : 0,
               "host" : "mongodb0.example.net:27017"
           },
           {
               "_id" : 1,
               "host" : "mongodb1.example.net:27017"
           },
           {
               "_id" : 2,
               "host" : "mongodb2.example.net:27017"
           }
       ]
   }
   

←   Force a Member to Become Primary Convert a Secondary to an Arbiter  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.