OPTIONS

Replica Set Configuration

Synopsis

This reference provides an overview of replica set configuration options and settings.

Use rs.conf() in the mongo shell to retrieve this configuration. Note that default values are not explicitly displayed.

Example Configuration Document

The following document provides a representation of a replica set configuration document. Angle brackets (e.g. < and >) enclose all optional fields.

{
  _id : <setname>,
  version: <int>,
  members: [
    {
      _id : <ordinal>,
      host : hostname<:port>,
      <arbiterOnly : <boolean>,>
      <buildIndexes : <boolean>,>
      <hidden : <boolean>,>
      <priority: <priority>,>
      <tags: { <document> },>
      <slaveDelay : <number>,>
      <votes : <number>>
    }
    , ...
  ],
  <settings: {
    <getLastErrorDefaults : <lasterrdefaults>,>
    <chainingAllowed : <boolean>,>
    <getLastErrorModes : <modes>>
  }>
}

Configuration Variables

local.system.replset._id

Type: string

Value: <setname>

An _id field holding the name of the replica set. This reflects the set name configured with replSetName or mongod --replSet.

local.system.replset.members

Type: array

Contains an array holding an embedded document for each member of the replica set. The members document contains a number of fields that describe the configuration of each member of the replica set.

The members field in the replica set configuration document is a zero-indexed array.

local.system.replset.members[n]._id

Type: ordinal

Provides the zero-indexed identifier of every member in the replica set.

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 _id field in each document in the members array.

local.system.replset.members[n].host

Type: <hostname><:port>

Identifies the host name of the set member with a hostname and port number. This name must be resolvable for every host in the replica set.

Warning

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.

New in version 2.6: mongod installed from official .deb and .rpm packages have the bind_ip configuration set to 127.0.0.1 by default.

local.system.replset.members[n].arbiterOnly

Optional.

Type: boolean

Default: false

Identifies an arbiter. For arbiters, this value is true, and is automatically configured by rs.addArb()”.

local.system.replset.members[n].buildIndexes

Optional.

Type: boolean

Default: true

Determines whether the mongod builds indexes on this member. Do not set to false for instances that receive queries from clients.

Omitting index creation, and thus this setting, may be useful, if:

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

If set to false, secondaries configured with this option do build indexes on the _id field, to facilitate operations required for replication.

Warning

You may only set this value when adding a member to a replica set. You may not reconfigure a replica set to change the value of the buildIndexes field after adding the member to the set.

buildIndexes is only valid when priority is 0 to prevent these members from becoming primary. Make all instances that do not build indexes hidden.

Other secondaries cannot replicate from a members where buildIndexes is false.

local.system.replset.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.

local.system.replset.members[n].priority

Optional.

Type: Number, between 0 and 100.0 including decimals.

Default: 1

Specify higher values to make a member more eligible to become primary, and lower values to make the member less eligible to become primary. Priorities are only used in comparison to each other. Members of the set will veto election requests from members when another eligible member has a higher priority value. Changing the balance of priority in a replica set will trigger an election.

A priority of 0 makes it impossible for a member to become primary.

See also

priority and Replica Set Elections.

local.system.replset.members[n].tags

Optional.

Type: MongoDB Document

Default: none

Used to represent arbitrary values for describing or tagging members for the purposes of extending write concern to allow configurable data center awareness.

Use in conjunction with getLastErrorModes and getLastErrorDefaults and db.getLastError() (i.e. getLastError.)

For procedures on configuring tag sets, see Configure Replica Set Tag Sets.

Important

In tag sets, all tag values must be strings.

local.system.replset.members[n].slaveDelay

Optional.

Type: Integer. (seconds.)

Default: 0

Describes the number of seconds “behind” the primary that this replica set member should “lag.” Use this option to create delayed members, that maintain a copy of the data that reflects the state of the data set at some amount of time in the past, specified in seconds. Typically such delayed members help protect against human error, and provide some measure of insurance against the unforeseen consequences of changes and updates.

local.system.replset.members[n].votes

Optional.

Type: Integer

Default: 1

Controls the number of votes a server will cast in a replica set election. The number of votes each member has can be either 1 or 0.

If you need more than 7 members in one replica set, set votes to 0 for the additional non-voting members.

Note

Deprecated since version 2.6: votes values greater than 1.

Earlier versions of MongoDB allowed a member to have more than 1 vote by setting votes to a value greater than 1. Setting votes to value greater than 1 now produces a warning message.

local.system.replset.settings

Optional.

Type: MongoDB Document

The settings document configures options that apply to the whole replica set.

local.system.replset.settings.chainingAllowed

Optional.

Type: boolean

Default: true

New in version 2.2.4.

When chainingAllowed is true, the replica set allows secondary members to replicate from other secondary members. When chainingAllowed is false, secondaries can replicate only from the primary.

When you run rs.config() to view a replica set’s configuration, the chainingAllowed field appears only when set to false. If not set, chainingAllowed is true.

local.system.replset.settings.getLastErrorDefaults

Optional.

Type: MongoDB Document

Specify arguments to getLastError that members of this replica set will use when getLastError has no arguments. If you specify any arguments, getLastError, ignores these defaults.

local.system.replset.settings.getLastErrorModes

Optional.

Type: MongoDB Document

Defines the names and combination of members for use by the application layer to guarantee write concern to database using the getLastError command to provide data-center awareness.

Example Reconfiguration Operations

Most modifications of replica set configuration use the mongo shell. Consider the following reconfiguration operation:

Example

Given the following replica set configuration:

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

The following reconfiguration operation updates the priority of the replica set members:

cfg = rs.conf()
cfg.members[0].priority = 0.5
cfg.members[1].priority = 2
cfg.members[2].priority = 2
rs.reconfig(cfg)

First, this operation sets the local variable cfg to the current replica set configuration using the rs.conf() method. Then it adds priority values to the cfg document for the three sub-documents in the members array, accessing each replica set member with the array index and not the replica set member’s _id field. Finally, it calls the rs.reconfig() method with the argument of cfg to initialize this new configuration. The replica set configuration after this operation will resemble the following:

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

Using the “dot notation” demonstrated in the above example, you can modify any existing setting or specify any of optional replica set configuration variables. Until you run rs.reconfig(cfg) at the shell, no changes will take effect. You can issue cfg = rs.conf() at any time before using rs.reconfig() to undo your changes and start from the current configuration. If you issue cfg as an operation at any point, the mongo shell at any point will output the complete document with modifications for your review.

The rs.reconfig() operation has a “force” option, to make it possible to reconfigure a replica set if a majority of the replica set is not visible, and there is no primary member of the set. use the following form:

rs.reconfig(cfg, { force: true } )

Warning

Forcing a rs.reconfig() can lead to rollback situations and other difficult to recover from situations. Exercise caution when using this option.

Note

The rs.reconfig() shell method can force the current primary to step down and triggers an election in some situations. When the primary steps down, all clients will disconnect. This is by design. Since this typically takes 10-20 seconds, attempt to make such changes during scheduled maintenance periods.