- Replication >
- Replication Reference >
- Replica Set Configuration
Replica Set Configuration¶
On this page
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.
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.
-
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
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 is0
to prevent these members from becoming primary. Make all instances that do not build indexes hidden.Other secondaries cannot replicate from a member 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 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
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
.)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 any non-negative integer, but it is highly recommended each member has 1 or 0 votes.
If you need more than 7 members in one replica set, 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.4.
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
getLastError
that members of this replica set will use whengetLastError
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 Reconfiguration Operations¶
Most modifications of replica set configuration use the
mongo
shell. Consider the following reconfiguration
operation:
Example
Given the following replica set configuration:
The following reconfiguration operation updates the
priority
of the replica set
members:
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:
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 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.