Replica Set Configuration

Command Line
Initial Setup
The Replica Set Config Object

Minimum Config - Required Arguments
Advanced Config - Optional Arguments

Member options
Set options

Shell Example 1
Shell Example 2
See Also

Command Line

Each mongod participating in the set should have a --replSet parameter on its command line. The syntax is

mongod --replSet setname --rest

setname is the logical name of the set.

Use the --rest command line parameter when using replica sets, as the web admin interface of mongod (normally at port 28017) shows status information on the set. See Replica Set Admin UI for more information.

Initial Setup

We use the replSetInitiate command for initial configuration of a replica set. Send the initiate command to a single server to christen the set. The member being initiated may have initial data; the other servers in the set should be empty.

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

A shorthand way to type the above is via a helper method in the shell:

> rs.initiate(<config_object>)

A quick way to initiate a set is to leave out the config object parameter. The initial set will then consist of the member to which the shell is communicating, along with all the seeds that member knows of. However, see the configuration object details below for more options.

> rs.initiate()

The Replica Set Config Object

The local.system.replset collection holds a singleton object which contains the replica set configuration. The config object automatically propagates among members of the set. The object is not directly manipulated, but rather changed via commands (such as replSetInitiate).

Minimum Config - Required Arguments

At its simplest, the config object contains the name of the replica set and a list of its members:

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

Every replica set configuration must contain an _id field and a members field with one or more hosts listed.

Setting	Description
`_id`	The set name. This must match command line setting. Set names are usually alphanumeric and, in particular, cannot contain the '/' character.
`members`	An array of servers in the set. For simpler configs, one can often simply set `_id` and `host` fields only – all the rest are optional. `_id` - Each member has an _id ordinal, typically beginning with zero and numbered in increasing order. When a node is retired (removed from the config), its `_id` should not be reused. `host` - Host name and optionally the port for the member

Advanced Config - Optional Arguments

There are many optional settings that can also be configured using the config object. The full set is:

{
  _id : <setname>,
  members: [
    {
      _id : <ordinal>,
      host : <hostname[:port]>
      [, arbiterOnly : true]
      [, buildIndexes : <bool>]
      [, hidden : true]
      [, priority: <priority>]
      [, tags: {loc1 : desc1, loc2 : desc2, ..., locN : descN}]
      [, slaveDelay : <n>]
      [, votes : <n>]
    }
    , ...
  ],
  [settings: {
    [getLastErrorDefaults: <lasterrdefaults>]
    [, getLastErrorModes : <modes>]
  }]
}

Member options

Each member can be configured to have any of the following options.

Command	Default	Description	Min Version
`arbiterOnly`	`false`	If `true`, this member will participate in vote but receive no data.	1.6
`buildIndexes`	`true`	When `false`, prevent secondary indexes from being created on this member. This is typically used on machines that are pure "backup" machines that are never queried. By not having the secondary indexes, the member performs less works on writes and requires less ram. Note the _id index is still created. Can only be set to `false` if `priority:0`. It is rare to use this option.	1.6
`hidden`	`false`	If `true`, do not advertise the member's existence to clients in `isMaster` command responses. Hidden replicas makes sense for replicas of data which have very different use patterns (reporting, integration, backup, etc.) than the main set of replicas; this option allows you to keep from sending normal non-primary queries to the node.	1.7
`priority`	1.0	Priority of the server for elections. Higher priority servers will be preferred as primary. (more information)	1.6, 1.9
`tags`	{}	An document representing the location of this server. Tags can be used for location-aware write guarantees and read locality, see Data Center Awareness	1.9.1
`slaveDelay`	0	Number of seconds to remain behind the primary. A value of 0 implies "as up-to-date as possible". Used to recover from human errors (e.g.: accidentally dropping a database). Can only be set on members with priority 0. Slave delay members are a great way to keep a rolling backup from a certain amount of time in the past.	1.6.3
`votes`	1	Number of votes this member has in an election. Generally you should not change this. (more information)	1.6

Set options

The final optional argument, settings, can be used to set options on the set as a whole. Often one can leave out settings completely from the config as the defaults are reasonable.

Setting	Description	Min Version
`getLastErrorDefaults`	Specifies defaults for the `getlasterror` command. If the client calls `getLastError` with no parameters then the defaults specified here are used.	1.6.2
`getLastErrorModes`	Define and name combinations of tags that can be used by the application to guarantee writes to certain servers, racks, data centers, etc. See Data Center Awareness.	1.9.1

Shell Example 1

> // all at once method
> cfg = {
... _id : "acme_a",
... members : [
... { _id : 0, host : "sf1.acme.com" },
... { _id : 1, host : "sf2.acme.com" },
... { _id : 2, host : "sf3.acme.com" } ] }
> rs.initiate(cfg)
> rs.status()

Shell Example 2

$ # incremental configuration method
$ mongo sf1.acme.com/admin
> rs.initiate();
> rs.add("sf2.acme.com");
> rs.add("sf3.acme.com");
> rs.status();