replSetInitiate (database command)

Definition

replSetInitiate

The replSetInitiate command initializes a new replica set.

Tip

In mongosh, this command can also be run through the rs.initiate() helper method.

Helper methods are convenient for mongosh users, but they may not return the same level of information as database commands. In cases where the convenience is not needed or the additional return fields are required, use the database command.

To run replSetInitiate, use the db.runCommand( { <command> } ) method.

Note

Run the command on only one of the mongod instances for the replica set.

Compatibility

This command is available in deployments hosted in the following environments:

MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

Important

This command is not supported in M0, M10+, and Flex clusters. For more information, see Unsupported Commands.

MongoDB Enterprise: The subscription-based, self-managed version of MongoDB
MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB

Syntax

The command has the following syntax:

db.runCommand(
 {
 replSetInitiate : <config_document>
 }
)

The <config_document> is a document that specifies the replica set's configuration. For instance, here's a config document for creating a simple 3-member replica set:

{
 _id : <setname>,
 members : [
 {_id : 0, host : <host0>},
 {_id : 1, host : <host1>},
 {_id : 2, host : <host2>},
 ]
}

Important

To avoid configuration updates due to IP address changes, use DNS hostnames instead of IP addresses. It is particularly important to use a DNS hostname instead of an IP address when configuring replica set members or sharded cluster members.

Use hostnames instead of IP addresses to configure clusters across a split network horizon. Starting in MongoDB 5.0, nodes that are only configured with an IP address fail startup validation and do not start.

IP Binding

Warning

Before you bind your instance to a publicly-accessible IP address, you must secure your cluster from unauthorized access. For a complete list of security recommendations, see Security Checklist for Self-Managed Deployments. At minimum, consider enabling authentication and hardening network infrastructure.

MongoDB binaries, mongod and mongos, bind to localhost by default. If the net.ipv6 configuration file setting or the --ipv6 command line option is set for the binary, the binary additionally binds to the localhost IPv6 address.

By default mongod and mongos that are bound to localhost only accept connections from clients that are running on the same computer. This binding behavior includes mongosh and other members of your replica set or sharded cluster. Remote clients cannot connect to binaries that are bound only to localhost.

To override the default binding and bind to other IP addresses, use the net.bindIp configuration file setting or the --bind_ip command-line option to specify a list of hostnames or IP addresses.

Warning

Starting in MongDB 5.0, split horizon DNS nodes that are only configured with an IP address fail startup validation and report an error. See disableSplitHorizonIPCheck.

For example, the following mongod instance binds to both the localhost and the hostname My-Example-Associated-Hostname, which is associated with the IP address 198.51.100.1:

mongod --bind_ip localhost,My-Example-Associated-Hostname

In order to connect to this instance, remote clients must specify the hostname or its associated IP address 198.51.100.1:

mongosh --host My-Example-Associated-Hostname
mongosh --host 198.51.100.1

Example

Assign a config document to a variable and then to pass the document to the rs.initiate() helper:

config = {
 _id : "my_replica_set",
 members : [
 {_id : 0, host : "rs1.example.net:27017"},
 {_id : 1, host : "rs2.example.net:27017"},
 {_id : 2, host : "rs3.example.net", arbiterOnly: true},
 ]
}
rs.initiate(config)

Important

Notice that omitting the port cause the host to use the default port of 27017. Notice also that you can specify other options in the config documents such as the arbiterOnly setting in this example.

Tip

Back

replSetGetStatus

replSetMaintenance