Replica Set Configuration

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

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

Warning

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

Replica Set Configuration Document Example

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

  1. {
  2.   _id: <string>,
  3.   version: <int>,
  4.   protocolVersion: <number>,
  5.   writeConcernMajorityJournalDefault: <boolean>,
  6.   configsvr: <boolean>,
  7.   members: [
  8.     {
  9.       _id: <int>,
  10.       host: <string>,
  11.       arbiterOnly: <boolean>,
  12.       buildIndexes: <boolean>,
  13.       hidden: <boolean>,
  14.       priority: <number>,
  15.       tags: <document>,
  16.       slaveDelay: <int>,
  17.       votes: <number>
  18.     },
  19.     ...
  20.   ],
  21.   settings: {
  22.     chainingAllowed : <boolean>,
  23.     heartbeatIntervalMillis : <int>,
  24.     heartbeatTimeoutSecs: <int>,
  25.     electionTimeoutMillis : <int>,
  26.     catchUpTimeoutMillis : <int>,
  27.     getLastErrorModes : <document>,
  28.     getLastErrorDefaults : <document>,
  29.     replicaSetId: <ObjectId>
  30.   }
  31. }

Replica Set Configuration Fields

  • _id
  • Type: string

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

_idmust be identical to thereplication.replSetName or the value of _–replSet_specified to mongod on the command line.

See

replSetName or —replSetfor information on setting the replica set name.

  • version
  • Type: int

An incrementing number used to distinguish revisions of the replicaset configuration object from previous iterations of theconfiguration.

  • configsvr

New in version 3.2.

Type: boolean

Default: false

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

See also

Sharded Cluster Enhancements

  • protocolVersion

New in version 3.2.

Type: number

Default: 1

Starting in 4.0, MongoDB only supports protocolVersion: 1 and nolonger supports protocolVersion: 0.

See also

Replica Set Protocol Version

  • writeConcernMajorityJournalDefault

New in version 3.2.6.

Type: boolean

Default: true

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

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

Value{ w: "majority" } BehaviortrueMongoDB acknowledges the write operation after a majority ofthe voting members have written to the on-disk journal.

Important

All voting members of the replica set must run withjournaling when writeConcernMajorityJournalDefaultis true.

If any voting member of a replica set uses the in-memorystorage engine, you must setwriteConcernMajorityJournalDefault to false.

If any voting member of a replica set uses the in-memorystorage engine andwriteConcernMajorityJournalDefault is true,"majority" write operations may fail. These includeoperations that inherently use "majority" writeconcern, such as the replSetStepDown command, orvarious mongo shell methods that by default use"majority" write concern, such as usermanagement methods androle management methods.

Starting in version 4.2 (and 4.0.13 and 3.6.14 ), if a replica setmember uses the in-memory storage engine(voting or non-voting) but the replica set haswriteConcernMajorityJournalDefault set to true, thereplica set member logs a startup warning.

falseMongoDB acknowledges the write operation after a majority ofthe voting members have applied the operation inmemory.

Warning

If any voting member of a replica set uses the in-memorystorage engine, you must setwriteConcernMajorityJournalDefault to false.

Starting in version 4.2 (and 4.0.13 and 3.6.14 ), if a replica setmember uses the in-memory storage engine(voting or non-voting) but the replica set haswriteConcernMajorityJournalDefault set to true, thereplica set member logs a startup warning.

You cannot run transactions on a sharded cluster that has a shardwith writeConcernMajorityJournalDefault set to false(such as a shard with a voting member that uses the in-memorystorage engine).

See also

Acknowledgment Behavior, Replica Set Protocol Version

members

  • members
  • Type: array

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

Each member-specific configuration document can contain the followingfields:

  • 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 membermust have a unique _id.Once set, you cannot change the _id of a member.

Note

When updating the replica configuration object, access the replica setmembers in the members array with thearray index. The array index begins with 0. Do not confusethis index value with the value of themembers[n]._id field in each document inthe members array.

  • members[n].host
  • Type: string

The hostname and, if specified, the port number, of the setmember.

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

Warning

members[n].host cannot hold avalue that resolves to localhost or the local interfaceunless all members of the set are on hosts that resolve tolocalhost.

  • members[n].arbiterOnly
  • Optional.

Type: boolean

Default: false

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

When using the rs.addArb() method to add an arbiter,the method automatically setsmembers[n].arbiterOnly to truefor the added member.

For the following MongoDB versions, pv1 increases the likelihoodof w:1 rollbacks compared to pv0(no longer supported in MongoDB 4.0+) for replica sets with arbiters:

  1. - MongoDB 3.4.1
  2. - MongoDB 3.4.0
  3. - MongoDB 3.2.11 or earlier

See Replica Set Protocol Version.

  • members[n].buildIndexes
  • Optional.

Type: boolean

Default: true

A boolean that indicates whether the mongod buildsindexes on this member. You can only set thisvalue when adding a member to a replica set. You cannot changemembers[n].buildIndexes field afterthe member has been added to the set. To add a member, seers.add() and rs.reconfig().

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

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

  1. - you are only using this instance to perform backups using[<code>mongodump</code>]($22489dff0ca974e1.md#bin.mongodump), _and_
  2. - this member will receive no queries, _and_
  3. - index creation and maintenance overburdens the hostsystem.

Even if set to false, secondaries will build indexes on the_id field in order to facilitate operations required forreplication.

Warning

If you setmembers[n].buildIndexes tofalse, you must also setmembers[n].priority to 0. Ifmembers[n].priority is not0, MongoDB will return an error when attempting to add amember withmembers[n].buildIndexes equal tofalse.

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

Other secondaries cannot replicate from a member wheremembers[n].buildIndexes isfalse.

  • members[n].hidden
  • Optional.

Type: boolean

Default: false

When this value is true, the replica set hides this instanceand does not include the member in the output ofdb.isMaster() or isMaster. This preventsread operations (i.e. queries) from ever reaching this host byway of secondary read preference.

Hidden members can acknowledge write operationsissued with Write Concern. For write operations issuedwith "majority" write concern, the member mustalso be a voting member (i.e. votes isgreater than 0).

See also

Hidden Replica Set Members

  • members[n].priority

Changed in version 3.6: Starting in MongoDB 3.6, arbiters have the priority 0. If anarbiter has a priority of 1, MongoDB 3.6 reconfigures thearbiter 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 tobecome a primary.

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

Members with priority greater than 0 cannot have0 votes.

Changing the balance of priority in a replica set will triggerone or more elections. If a lower priority secondary is electedover a higher priority secondary, replica set members willcontinue to call elections until the highest priority availablemember becomes primary.

Members with priority of 0 canacknowledge write operations issued with Write Concern.For write operations issued with "majority" writeconcern, the member must also be a voting member (i.e.votes is greater than 0).

See also

Replica Set Elections.

  • members[n].tags
  • Optional.

Type: document

Default: none

A tags document contains user-defined tag field and value pairs forthe replica set member.

  1. { "<tag1>": "<string1>", "<tag2>": "<string2>",... }
  1. - For read operations, you can specify a tag set in the [readpreference]($fa2fb125500af441.md#replica-set-read-preference-tag-sets) to direct theoperations to replica set member(s) with the specified tag(s).
  2. - For write operations, you can create a customize [write concern]($d526a6502b9a8116.md) using[<code>settings.getLastErrorModes</code>]($364b66b683f71e1a.md#rsconf.settings.getLastErrorModes) and[<code>settings.getLastErrorDefaults</code>]($364b66b683f71e1a.md#rsconf.settings.getLastErrorDefaults).

For more information, seeConfigure Replica Set Tag Sets.

  • members[n].slaveDelay
  • Optional.

Type: integer

Default: 0

The number of seconds “behind” the primary that thisreplica set member should “lag”.

Use this option to create delayed members. Delayed members maintain a copyof the data that reflects the state of the data at some time inthe past.

Delayed members can contribute to acknowledging writeoperations issued with Write Concern. However,they return write acknowledgment no earlier than the configureddelay value. For write operations issued with"majority" write concern, the member must also bea voting member (i.e. votes is greater than0).

See also

Delayed Replica Set Members

  • members[n].votes
  • Optional.

Type: integer

Default: 1

The number of votes a server will cast in a replica setelection. The number of votes eachmember has is either 1 or 0, and arbiters always have exactly 1 vote.

Members with priority greater than 0 cannot have0 votes.

A replica set can have up to 50 members but only 7 voting members.If you need more than 7 members in one replica set, setmembers[n].votes to 0 for theadditional non-voting members.

Changed in version 3.2: Non-voting members must have priority of 0.

Changed in version 3.0.0: Members cannot have members[n].votesgreater than 1. For details, seeReplica Set Configuration Validation.

Members with 0 votes cannot acknowledge write operationsissued with a Write Concern of majority.

settings

  • settings
  • Optional.

Type: document

A document that contains configuration options that apply to thewhole replica set.

The settings document contain thefollowing fields:

  • settings.chainingAllowed
  • Optional.

Type: boolean

Default: true

When settings.chainingAllowed istrue, the replica set allows secondary members toreplicate from other secondary members. Whensettings.chainingAllowed isfalse, secondaries can replicate only from the primary.

See also

Manage Chained Replication

  • settings.getLastErrorDefaults
  • Optional.

Type: document

A document that specifies the write concern for the replica set. Thereplica set will use this write concern only when writeoperations orgetLastError specify no other write concern.

If settings.getLastErrorDefaults isnot set, the default write concern for the replica set onlyrequires confirmation from the primary.

  • settings.getLastErrorModes
  • Optional.

Type: document

A document used to define a custom write concern through the use of members[n].tags.The custom write concern can provide data-centerawareness.

  1. { getLastErrorModes: {
  2.    <name of write concern> : { <tag1>: <number>, .... },
  3.    ...
  4. } }

The <number> refers to the number of different tag valuesrequired to satisfy the write concern. For example, the followingsettings.getLastErrorModes defines a write concernnamed datacenter that requires the write to propagate to twomembers whose dc tag values differ.

  1. { getLastErrorModes: { datacenter: { "dc": 2 } } }

To use the custom write concern, pass in the write concern nameto the w Option, e.g.

  1. { w: "datacenter" }

See Configure Replica Set Tag Sets for moreinformation and example.

  • settings.heartbeatTimeoutSecs
  • Optional.

Type: int

Default: 10

Number of seconds that the replica set members wait for asuccessful heartbeat from each other. If a member does notrespond in time, other members mark the delinquent member asinaccessible.

Note

For pv1,settings.electionTimeoutMillis has a greaterinfluence on whether the secondary members call for anelection than the settings.heartbeatTimeoutSecs.

  • settings.electionTimeoutMillis

New in version 3.2.

Optional.

Type: int

Default: 10000 (10 seconds)

The time limit in milliseconds for detecting when a replica set’sprimary is unreachable:

  1. - Higher values result in slower failovers but decreasedsensitivity to primary node or network slowness or spottiness.
  2. - Lower values result in faster failover, but increasedsensitivity to primary node or network slowness or spottiness.

The setting only applies when using protocolVersion: 1.

Note

Changed in version 4.0.2: If the parameter enableElectionHandoff is true(default), when a primary steps down from rs.stepDown()(or the replSetStepDown command without the force:true), the stepped-down primary nominates an eligible secondaryto call an election immediately. Otherwise, secondaries can waitup to settings.electionTimeoutMillis before calling anelection. The stepped down primary does not wait for the effectsof the handoff. For more information, seeenableElectionHandoff.

  • settings.catchUpTimeoutMillis

New in version 3.4.

Optional.

Type: int

Changed in version 3.6:

Default: -1, infinite catchup time.

Time limit in milliseconds for a newly elected primary to sync(catch up) with the other replica set members that may have morerecent writes. Infinite or high time limits may reduce theamount of data that the other members would need to roll backafter an election but may increase the failover time.

The newly elected primary ends the catchup period early once itis fully caught up with other members of the set. During thecatchup period, the newly elected primary is unavailable forwrites from clients. Use replSetAbortPrimaryCatchUpto abort the catchup then complete the transition to primary.

The setting only applies when using protocolVersion: 1.

Note

To downgrade a replica set initiated in version 3.6 to 3.4,change catchUpTimeoutMillis from -1 to apositive number. Failure to change this value to a positivenumber causes nodes running version 3.4 to neither restart norjoin the replica set.

  • settings.catchUpTakeoverDelayMillis

New in version 3.6.

Optional.

Type: int

Default: 30000 (30 seconds)

Time in milliseconds a node waits to initiate acatchup takeover after determining it is ahead of the currentprimary. During a catchup takeover, the node ahead of thecurrent primary initiates an election to become the newprimary of the replica set.

After the node initiating the takeover determines that it isahead of the current primary, it waits the specifiednumber of milliseconds and then verifies the following:

  1. - It is still ahead of the current primary,
  2. - It is the most up-to-date node among all available nodes,
  3. - The current primary is currently catching up to it.

Once determining that all of these conditions are met, the nodeinitiating the takeover immediately runs for election.

For more information on ReplicaSet Elections, see Replica Set Elections.

Note

Setting catchUpTakeoverDelayMillis to -1 disablescatchup takeover. Setting catchUpTimeoutMillis to0 disables primary catchup and consequently also catchuptakeover.

  • settings.heartbeatIntervalMillis

New in version 3.2.

Internal use only.

The frequency in milliseconds of the heartbeats.

  • settings.replicaSetId

New in version 3.2.

Type: ObjectId

The ObjectId associated with the replica set and automaticallycreated during rs.initiate() orreplSetInitate. You cannot change thereplicaSetId.