- Reference >
- Replica Set Configuration
Replica Set Configuration¶
On this page
Synopsis¶
This reference provides an overview of all possible 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.
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 withreplSet
ormongod --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, address all members of the set using the index value in the array. The array index begins with
0
. Do not confuse this index value with the value of the_id
field in each document in themembers
array.The
_id
rarely corresponds to the array index.
-
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 tolocalhost
or the local interface unless all members of the set are on hosts that resolve to localhost.
-
local.system.replset.members[n].
arbiterOnly
¶ Optional.
Type: boolean
Default: false
Identifies an arbiter. For arbiters, this value is
true
, and is automatically configured byrs.addArb()
”.
-
local.system.replset.members[n].
buildIndexes
¶ Optional.
Type: boolean
Default: true
Determines whether the
mongod
builds indexes on this member. Do not set tofalse
if a replica set can become a primary, or if any clients ever issue queries against this instance.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.Other secondaries cannot replicate from a members where
buildIndexes
is false.- You are only using this instance to perform backups using
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 ofdb.isMaster()
orisMaster
. This prevents read operations (i.e. queries) from ever reaching this host by way of secondary read preference.See also
-
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 elections from members when another eligible member has a higher absolute priority value. Changing the balance of priority in a replica set will cause an election.
A
priority
of0
makes it impossible for a member to become primary.See also
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
andgetLastErrorDefaults
anddb.getLastError()
(i.e.getLastError
.)
-
local.system.replset.members[n].
slaveDelay
¶ Optional.
Type: Integer. (seconds.)
Default: 0
Describes the number of seconds “behind” the master 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 some amount of time (specified in seconds.) Typically these 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 has in a replica set election. The number of votes each member has can be any non-negative integer, but it is highly recommended each member has 1 or 0 votes.
If you need more than 7 members, use this setting to add additional non-voting members with a
votes
value of0
.For most deployments and most members, use the default value,
1
, forvotes
.
-
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.2.
When
chainingAllowed
istrue
, the replica set allows secondary members to replicate from other secondary members. WhenchainingAllowed
isfalse
, secondaries can replicate only from the primary.When you run
rs.config()
to view a replica set’s configuration, thechainingAllowed
field appears only when set tofalse
. If not set,chainingAllowed
istrue
.See also
-
local.system.replset.settings.
getLastErrorDefaults
¶ Optional.
Type: MongoDB Document
Specify arguments to the
getLastError
that members of this replica set will use when no arguments togetLastError
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 thegetLastError
command to provide data-center awareness.
Example Document¶
The following document provides a representation of a replica set
configuration document. Angle brackets (e.g. <
and >
) enclose
all optional fields.
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:
And the following reconfiguration operation:
This operation begins by saving the current replica set
configuration to the local variable cfg
using the
rs.conf()
method. Then it adds priority values to the
cfg
document where for the first three sub-documents in
the members
array. 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:
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:
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 causes an election in some
situations. When the primary steps down, all clients will
disconnect. This is by design. While this typically takes 10-20
seconds, attempt to make these changes during scheduled maintenance
periods.
Tag Sets¶
Tag sets provide custom and configurable write concern and read preferences for a replica set. This section outlines the process for specifying tags for a replica set, for more information see the full documentation of the behavior of tags sets for write concern and tag sets for read preference.
Important
Custom read preferences and write concerns evaluate tags sets in different ways.
Read preferences consider the value of a tag when selecting a member to read from.
Write concerns do not utilize the value of a tag to select a member except to consider whether or not the value is unique.
Configure tag sets by adding fields and values to the document stored
in the tags
. Consider the
following examples:
Configure Tag Sets¶
Given the following replica set configuration:
You could add the tag sets, to the members of this replica set,
with the following command sequence in the mongo
shell:
After this operation the output of rs.conf()
, would
resemble the following:
Configure Tag Sets for Custom Multi-Data Center Write Concern Mode¶
Given a five member replica set with members in two data centers:
- a facility
VA
taggeddc.va
- a facility
GTO
taggeddc.gto
Create a custom write concern to require confirmation from two
data centers using replica set tags, using the following sequence
of operations in the mongo
shell:
Create the replica set configuration object
conf
:Add tags to the replica set members reflecting their locations:
Create a custom
getLastErrorModes
setting to ensure that the write operation will propagate to at least one member of each facility:Reconfigure the replica set using the new
conf
configuration object:
To ensure that a write operation propagators to at least one member of
the set in both facilities, then use the MultipleDC
write concern
mode, as follows:
Alternatively, if you want to ensure that each write operation
propagates to at least 2 racks in each facility, reconfigure the
replica set as follows in the mongo
shell:
Create the replica set configuration object
conf
:Redefine the
getLastErrorModes
value to require two different values of bothdc.va
anddc.gto
:Reconfigure the replica set using the new
conf
configuration object:
Now, the following write concern operation will only return after the write operation propagates to at least two different racks in the each facility:
Configure Tag Sets for Functional Segregation of Read and Write Operations¶
Given a replica set with tag sets that reflect:
- data center facility,
- physical rack location of instance, and
- storage system (i.e. disk) type.
Where each member of the set has a tag set that resembles one of the following: [1]
To target a read operation to a member of the replica set with an
disk type of ssd
, you could use the following tag set:
However, to create comparable write concern modes, you would specify a
different set of
getLastErrorModes
configuration. Consider the the following sequence of operations in
the mongo
shell:
Create the replica set configuration object
conf
:Redefine the
getLastErrorModes
value to configure two write concern modes:Reconfigure the replica set using the new
conf
configuration object:
Now, you can specify the MultipleDC
write concern mode, as in the
following operation, to ensure that a write operation propagates to
each data center.
Additionally, you can specify the ssd
write concern mode, as in
the following operation, to ensure that a write operation propagates
to at least one instance with an SSD.
[1] | Since read preferences and write concerns use the value of fields in tag sets differently, larger deployments will have some redundancy. |