Docs4dev
Docs
mongodb / v3.6 / reference / reference-replica-configuration.html

Replica Set Configuration

On this page

You can access the configuration of a replica set using the rs.conf() method or the replSetGetConfig command.

To modify the configuration for a replica set, use the rs.reconfig() method, passing a configuration document to the method. See rs.reconfig() for more information.

Warning

Avoid reconfiguring replica sets that contain members of different MongoDB versions as validation rules may differ across MongoDB versions.

Replica Set Configuration Document Example

The following document provides a representation of a replica set configuration document. The configuration of your replica set may include only a subset of these settings:

{
  _id: <string>,
  version: <int>,
  protocolVersion: <number>,
  writeConcernMajorityJournalDefault: <boolean>,
  configsvr: <boolean>,
  members: [
    {
      _id: <int>,
      host: <string>,
      arbiterOnly: <boolean>,
      buildIndexes: <boolean>,
      hidden: <boolean>,
      priority: <number>,
      tags: <document>,
      slaveDelay: <int>,
      votes: <number>
    },
    ...
  ],
  settings: {
    chainingAllowed : <boolean>,
    heartbeatIntervalMillis : <int>,
    heartbeatTimeoutSecs: <int>,
    electionTimeoutMillis : <int>,
    catchUpTimeoutMillis : <int>,
    getLastErrorModes : <document>,
    getLastErrorDefaults : <document>,
    replicaSetId: <ObjectId>
  }
}

Replica Set Configuration Fields

_id

Type: string

The name of the replica set. Once set, you cannot change the name of a replica set.

_id must be identical to the replication.replSetName or the value of –replSet specified to mongod on the command line.

See

replSetName or --replSet for information on setting the replica set name.

version

Type: int

An incrementing number used to distinguish revisions of the replica set configuration object from previous iterations of the configuration.

configsvr

New in version 3.2.

Type: boolean

Default: false

Indicates whether the replica set is used for a sharded cluster’s config servers. Set to true if the replica set is for a sharded cluster’s config servers.

protocolVersion

New in version 3.2.

Type: number

Default: 1 for new replica sets

Version of the replica set election protocol.

Starting in MongoDB 3.2, new replica sets use protocolVersion: 1 by default. Previous versions of MongoDB use version 0 of the protocol and cannot run as members of a replica set configuration that specifies protocolVersion 1.

Before changing the protocol version, ensure that at least one oplog entry (generated from the current protocol version) has replicated from the primary to all secondaries. For details, see Modify Replica Set Protocol Version.

Note

MongoDB 3.6 deprecates the replica set protocol version 0.

writeConcernMajorityJournalDefault

New in version 3.2.6.

Type: boolean

Default: true if protocolVersion is 1 and false if protocolVersion is 0

Determines the behavior of { w: "majority" } write concern if the write concern does not explicitly specify the journal option j.

The following table lists the writeConcernMajorityJournalDefault values and the associated { w: "majority" } behavior:

Value { w: "majority" } Behavior
true

MongoDB acknowledges the write operation after a majority of the voting members have written to the on-disk journal.

Important

All voting members of the replica set must run with journaling when writeConcernMajorityJournalDefault is true.

If any voting member of a replica set runs without journaling and writeConcernMajorityJournalDefault is true, "majority" write operations may fail. These include operations that inherently use "majority" write concern, such as the replSetStepDown command, or various mongo shell methods that by default use "majority" write concern, such as user management methods and role management methods.

Starting in version 3.6.14, if a replica set member uses the in-memory storage engine (voting or non-voting) but the replica set has writeConcernMajorityJournalDefault set to true, the replica set member logs a startup warning.
false

MongoDB acknowledges the write operation after a majority of the voting members have applied the operation in memory.

Warning

If any voting member of a replica set runs without journaling (i.e. either runs an in-memory storage engine or runs with journaling disabled), you must set writeConcernMajorityJournalDefault to false.

Starting in version 3.6.14, if a replica set member uses the in-memory storage engine (voting or non-voting) but the replica set has writeConcernMajorityJournalDefault set to true, the replica set member logs a startup warning.

members

members

Type: array

An array of member configuration documents, one for each member of the replica set. The members array is a zero-indexed array.

Each member-specific configuration document can contain the following fields:

members[n]. _id

Type: integer

An integer identifier of every member in the replica set. Values must be between 0 and 255 inclusive. Each replica set member must have a unique _id. Once set, you cannot change the _id of a member.

Note

When updating the replica configuration object, access the replica set members in the members array with the array index. The array index begins with 0. Do not confuse this index value with the value of the members[n]._id field in each document in the members array.

members[n]. host

Type: string

The hostname and, if specified, the port number, of the set member.

The hostname name must be resolvable for every host in the replica set.

Warning

members[n].host cannot hold a value that resolves to localhost or the local interface unless all members of the set are on hosts that resolve to localhost.

members[n]. arbiterOnly

Optional.

Type: boolean

Default: false

A boolean that identifies an arbiter. A value of true indicates that the member is an arbiter.

When using the rs.addArb() method to add an arbiter, the method automatically sets members[n].arbiterOnly to true for the added member.

For the following MongoDB versions, pv1 increases the likelihood of w:1 rollbacks compared to pv0 for replica sets with arbiters:

  • MongoDB 3.4.1
  • MongoDB 3.4.0
  • MongoDB 3.2.11 or earlier

See Replica Set Protocol Versions.

members[n]. buildIndexes

Optional.

Type: boolean

Default: true

A boolean that indicates whether the mongod builds indexes on this member. You can only set this value when adding a member to a replica set. You cannot change members[n].buildIndexes field after the member has been added to the set. To add a member, see rs.add() and rs.reconfig().

Do not set to false for mongod instances that receive queries from clients.

Setting buildIndexes to false may be useful if all the following conditions are true:

  • you are only using this instance to perform backups using mongodump, and
  • this member will receive no queries, and
  • index creation and maintenance overburdens the host system.

Even if set to false, secondaries will build indexes on the _id field in order to facilitate operations required for replication.

Warning

If you set members[n].buildIndexes to false, you must also set members[n].priority to 0. If members[n].priority is not 0, MongoDB will return an error when attempting to add a member with members[n].buildIndexes equal to false.

To ensure the member receives no queries, you should make all instances that do not build indexes hidden.

Other secondaries cannot replicate from a member where members[n].buildIndexes is false.

members[n]. hidden

Optional.

Type: boolean

Default: false

When this value is true, the replica set hides this instance and does not include the member in the output of db.isMaster() or isMaster. This prevents read operations (i.e. queries) from ever reaching this host by way of secondary read preference.

Hidden members can acknowledge write operations issued with Write Concern. For write operations issued with "majority" write concern, the member must also be a voting member (i.e. votes is greater than 0).

members[n]. priority

Changed in version 3.6: Starting in MongoDB 3.6, arbiters have the priority 0. If an arbiter has a priority of 1, MongoDB 3.6 reconfigures the arbiter to have a priority of 0.

Optional.

Type: Number between 0 and 1000 for primary/secondary; 0 or 1 for arbiters.

Default: 1.0 for primary/secondary; 0 for arbiters.

A number that indicates the relative eligibility of a member to become a primary.

Specify higher values to make a member more eligible to become primary, and lower values to make the member less eligible. A member with a members[n].priority of 0 is ineligible to become primary.

Members with priority greater than 0 cannot have 0 votes.

Changing the balance of priority in a replica set will trigger one or more elections. If a lower priority secondary is elected over a higher priority secondary, replica set members will continue to call elections until the highest priority available member becomes primary.

Members with priority of 0 can acknowledge write operations issued with Write Concern. For write operations issued with "majority" write concern, the member must also be a voting member (i.e.