Permalink
Fetching contributors…
Cannot retrieve contributors at this time
581 lines (371 sloc) 16.9 KB
=========================
Replica Set Configuration
=========================
.. default-domain:: mongodb
.. contents:: On this page
:local:
:backlinks: none
:depth: 1
:class: singlecol
You can access the configuration of a :term:`replica set` using the
:method:`rs.conf()` method or the :dbcommand:`replSetGetConfig` command.
To modify the configuration for a replica set, use the
:method:`rs.reconfig()` method, passing a configuration document to the
method. See :method:`rs.reconfig()` for more information.
.. warning::
.. include:: /includes/warning-mixed-version-rs-config.rst
.. _replica-set-configuration-settings:
.. _replica-set-configuration-document:
Replica Set Configuration Document Example
------------------------------------------
.. include:: /includes/replica-set-conf-document-output.rst
.. _replSetGetConfig-output:
Replica Set Configuration Fields
--------------------------------
.. rsconf:: _id
*Type*: string
The name of the replica set. Once set, you cannot change the
name of a replica set.
:rsconf:`_id` *must* be identical to the
:setting:`replication.replSetName` or the value of `--replSet`
specified to :binary:`~bin.mongod` on the command line.
.. see::
:setting:`~replication.replSetName` or :option:`--replSet <mongod --replSet>`
for information on setting the replica set name.
.. rsconf:: version
*Type*: int
An incrementing number used to distinguish revisions of the replica
set configuration object from previous iterations of the
configuration.
.. rsconf:: configsvr
.. versionadded:: 3.2
*Type*: boolean
*Default*: false
Indicates whether the replica set is used for a sharded cluster's
config servers. Set to ``true`` if the replica set is for a sharded
cluster's config servers.
.. seealso:: :ref:`3.2-rel-notes-sharded-cluster`
.. rsconf:: protocolVersion
.. versionadded:: 3.2
*Type*: number
*Default*: 1 for new replica sets
Version of the :ref:`replica set election protocol
<3.2-rel-notes-rs-enhancements>`.
Starting in MongoDB 3.2, new replica sets use ``protocolVersion: 1`` by default.
Previous versions of MongoDB use version 0 of the protocol and
cannot run as members of a replica set configuration that specifies
``protocolVersion`` 1.
.. include:: /includes/note-pv0-deprecation.rst
.. seealso:: :doc:`/reference/replica-set-protocol-versions`
.. rsconf:: writeConcernMajorityJournalDefault
.. versionadded:: 3.2.6
*Type*: boolean
*Default*: true if ``protocolVersion`` is 1 and false if ``protocolVersion`` is 0
Determines the behavior of :writeconcern:`{ w: "majority" }
<"majority">` write concern if the write concern does not explicitly
specify the journal option :ref:`j <wc-j>`.
The following table lists the ``writeConcernMajorityJournalDefault``
values and the associated :writeconcern:`{ w: "majority" }
<"majority">` behavior:
.. list-table::
:header-rows: 1
:widths: 15 85
* - Value
- ``{ w: "majority" }`` Behavior
* - true
- MongoDB acknowledges the write operation after a majority of
the voting members have written to the on-disk journal.
.. important::
All voting members of the replica set must run with
journaling when ``writeConcernMajorityJournalDefault``
is ``true``.
.. include:: /includes/extracts/no-journaling-writeConcernMajorityJournalDefault-true.rst
* - false
- MongoDB acknowledges the write operation after a majority of
the voting members have applied the operation in
memory.
.. warning::
.. include:: /includes/extracts/no-journaling-writeConcernMajorityJournalDefault-false.rst
.. seealso:: :ref:`wc-ack-behavior`, :doc:`/reference/replica-set-protocol-versions`
``members``
~~~~~~~~~~~
.. rsconf:: members
*Type*: array
An array of member configuration documents, one for each member
of the replica set. The :rsconf:`members` array
is a zero-indexed array.
Each member-specific configuration document can contain the following
fields:
.. rsconf:: 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 member
must have a unique :rsconf:`_id<members[n]._id>`.
Once set, you cannot change the :rsconf:`_id<members[n]._id>` of a member.
.. note::
.. include:: /includes/fact-rs-conf-array-index.rst
.. rsconf:: members[n].host
*Type*: string
The hostname and, if specified, the port number, of the set
member.
The hostname name must be resolvable for every host in the
replica set.
.. warning::
:rsconf:`members[n].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``.
.. rsconf:: members[n].arbiterOnly
*Optional*.
*Type*: boolean
*Default*: false
A boolean that identifies an arbiter. A value of ``true``
indicates that the member is an arbiter.
When using the :method:`rs.addArb()` method to add an arbiter,
the method automatically sets
:rsconf:`members[n].arbiterOnly` to ``true``
for the added member.
.. include:: /includes/extracts/arbiters-and-pvs-with-reference.rst
.. rsconf:: members[n].buildIndexes
*Optional*.
*Type*: boolean
*Default*: true
A boolean that indicates whether the :binary:`~bin.mongod` builds
:term:`indexes <index>` on this member. You can only set this
value when adding a member to a replica set. You cannot change
:rsconf:`members[n].buildIndexes` field after
the member has been added to the set. To add a member, see
:method:`rs.add()` and :method:`rs.reconfig()`.
Do not set to ``false`` for :binary:`~bin.mongod` instances that receive
queries from clients.
Setting ``buildIndexes`` to ``false`` may be useful if **all**
the following conditions are true:
- you are only using this instance to perform backups using
:binary:`~bin.mongodump`, *and*
- this member will receive no queries, *and*
- index creation and maintenance overburdens the host
system.
Even if set to ``false``, secondaries *will* build indexes on the
``_id`` field in order to facilitate operations required for
replication.
.. warning::
If you set
:rsconf:`members[n].buildIndexes` to
``false``, you must also set
:rsconf:`members[n].priority` to ``0``. If
:rsconf:`members[n].priority` is not
``0``, MongoDB will return an error when attempting to add a
member with
:rsconf:`members[n].buildIndexes` equal to
``false``.
To ensure the member receives no queries, you should make all
instances that do not build indexes hidden.
Other secondaries cannot replicate from a member where
:rsconf:`members[n].buildIndexes` is
false.
.. rsconf:: 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
:method:`db.isMaster()` or :dbcommand:`isMaster`. This prevents
read operations (i.e. queries) from ever reaching this host by
way of secondary :term:`read preference`.
.. seealso::
:ref:`Hidden Replica Set Members <replica-set-hidden-members>`
.. rsconf:: members[n].priority
.. versionchanged:: 3.6
Starting in MongoDB 3.6, arbiters have the priority ``0``. If an
arbiter has a priority of ``1``, MongoDB 3.6 reconfigures the
arbiter 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 to
become a :term:`primary`.
Specify higher values to make a member *more* eligible to become
:term:`primary`, and lower values to make the member *less*
eligible. A member with a :rsconf:`members[n].priority` of ``0`` is
ineligible to become primary.
.. include:: /includes/fact-rs-nonzero-priority-vote-restriction.rst
Changing the balance of priority in a replica set will trigger
one or more elections. If a lower priority secondary is elected
over a higher priority secondary, replica set members will
continue to call elections until the highest priority available
member becomes primary.
.. seealso::
:ref:`Replica Set Elections <replica-set-elections>`.
.. rsconf:: members[n].tags
*Optional*.
*Type*: document
*Default*: none
.. include:: /includes/fact-tag-set-field.rst
Use :rsconf:`replicaset.members[n].tags` to
configure write concerns in conjunction with
:rsconf:`settings.getLastErrorModes` and
:rsconf:`settings.getLastErrorDefaults`.
.. include:: /includes/fact-tag-sets-must-be-strings.rst
For more information on configuring tag sets for read preference
and write concern, see
:doc:`/tutorial/configure-replica-set-tag-sets`.
.. rsconf:: members[n].slaveDelay
*Optional*.
*Type*: integer
*Default*: 0
The number of seconds "behind" the primary that this
replica set member should "lag".
Use this option to create :ref:`delayed members
<replica-set-delayed-members>`. Delayed members maintain a copy
of the data that reflects the state of the data at some time in
the past.
.. seealso::
:doc:`/core/replica-set-delayed-member`
.. rsconf:: members[n].votes
*Optional*.
*Type*: integer
*Default*: 1
The number of votes a server will cast in a :ref:`replica set
election <replica-set-elections>`. The number of votes each
member has is either ``1`` or ``0``, and :ref:`arbiters
<replica-set-arbiters>` always have exactly ``1`` vote.
.. include:: /includes/fact-rs-nonzero-priority-vote-restriction.rst
A replica set can have up to :limit:`50 members
<Number of Members of a Replica Set>` but only 7 voting members.
If you need more than 7 members in one replica set, set
:rsconf:`members[n].votes` to ``0`` for the
additional non-voting members.
.. versionchanged:: 3.2
.. include:: /includes/fact-rs-non-voting-priority-restriction.rst
.. include:: /includes/members-used-to-allow-multiple-votes.rst
``settings``
~~~~~~~~~~~~
.. rsconf:: settings
*Optional*.
*Type*: document
A document that contains configuration options that apply to the
whole replica set.
The :rsconf:`settings` document contain the
following fields:
.. rsconf:: settings.chainingAllowed
*Optional*.
*Type*: boolean
*Default*: true
When :rsconf:`settings.chainingAllowed` is
``true``, the replica set allows :term:`secondary` members to
replicate from other secondary members. When
:rsconf:`settings.chainingAllowed` is
``false``, secondaries can replicate only from the :term:`primary`.
.. seealso:: :doc:`/tutorial/manage-chained-replication`
.. rsconf:: settings.getLastErrorDefaults
*Optional*.
*Type*: document
A document that specifies the :doc:`write concern
</core/replica-set-write-concern>` for the replica set. The
replica set will use this write concern only when :ref:`write
operations <write-methods-incompatibility>` or
:dbcommand:`getLastError` specify no other write concern.
If :rsconf:`settings.getLastErrorDefaults` is
not set, the default write concern for the replica set only
requires confirmation from the primary.
.. rsconf:: settings.getLastErrorModes
*Optional*.
*Type*: document
A document used to define an extended :term:`write concern`
through the use of :rsconf:`members[n].tags`.
The extended :term:`write concern` can provide :term:`data-center
awareness`.
For example, the following document defines an extended write
concern named ``eastCoast`` and associates with a write to a
member that has the ``east`` tag.
.. code-block:: none
{ getLastErrorModes: { eastCoast: { "east": 1 } } }
Write operations to the replica set can use the extended write
concern, e.g. ``{ w: "eastCoast" }``.
See :doc:`/tutorial/configure-replica-set-tag-sets` for more
information and example.
.. rsconf:: settings.heartbeatTimeoutSecs
*Optional*.
*Type*: int
*Default*: 10
Number of seconds that the replica set members wait for a
successful heartbeat from each other. If a member does not
respond in time, other members mark the delinquent member as
inaccessible.
The setting only applies when using :rsconf:`protocolVersion: 0`.
.. include:: /includes/note-pv0-deprecation.rst
When using :rsconf:`protocolVersion: 1` the relevant setting is
:rsconf:`settings.electionTimeoutMillis`.
.. rsconf:: settings.electionTimeoutMillis
.. versionadded:: 3.2
*Optional*.
*Type*: int
*Default*: 10000 (10 seconds)
The time limit in milliseconds for detecting when a replica set's
primary is unreachable:
- Higher values result in slower failovers but decreased
sensitivity to primary node or network slowness or spottiness.
- Lower values result in faster failover, but increased
sensitivity to primary node or network slowness or spottiness.
The setting only applies when using :rsconf:`protocolVersion: 1`.
.. rsconf:: settings.catchUpTimeoutMillis
.. versionadded:: 3.4
*Optional*.
*Type*: int
.. versionchanged:: 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 more
recent writes. Infinite or high time limits may reduce the
amount of data that the other members would need to roll back
after an election but may increase the failover time.
The newly elected primary ends the catchup period early once it
is fully caught up with other members of the set. During the
catchup period, the newly elected primary is unavailable for
writes from clients. Use :dbcommand:`replSetAbortPrimaryCatchUp`
to abort the catchup then complete the transition to primary.
The setting only applies when using :rsconf:`protocolVersion: 1`.
.. note::
To downgrade a replica set initiated in version 3.6 to 3.4,
change ``catchUpTimeoutMillis`` from ``-1`` to a
positive number. Failure to change this value to a positive
number causes nodes running version 3.4 to neither restart nor
join the replica set.
.. _repl-conf-catchup-takeover-delay:
.. rsconf:: settings.catchUpTakeoverDelayMillis
.. versionadded:: 3.6
*Optional*.
*Type*: int
*Default*: 30000 (30 seconds)
Time in milliseconds a node waits to initiate a
*catchup takeover* after determining it is ahead of the current
:term:`primary`. During a catchup takeover, the node ahead of the
current primary initiates an :term:`election` to become the new
primary of the :term:`replica set`.
After the node initiating the takeover determines that it is
ahead of the current :term:`primary`, it waits the specified
number of milliseconds and then verifies the following:
1. It is still ahead of the current primary,
#. It is the most up-to-date node among all available nodes,
#. The current primary is currently catching up to it.
Once determining that all of these conditions are met, the node
initiating the takeover immediately runs for election.
For more information on Replica
Set Elections, see :doc:`/core/replica-set-elections/`.
.. note::
Setting ``catchUpTakeoverDelayMillis`` to ``-1`` disables
catchup takeover. Setting :rsconf:`catchUpTimeoutMillis` to
``0`` disables *primary catchup* and consequently also catchup
takeover.
.. rsconf:: settings.heartbeatIntervalMillis
.. versionadded:: 3.2
*Internal use only*.
The frequency in milliseconds of the heartbeats.
.. rsconf:: settings.replicaSetId
.. versionadded:: 3.2
*Type*: ObjectId
The ObjectId associated with the replica set and automatically
created during :method:`rs.initiate()` or
:dbcommand:`replSetInitate`. You cannot change the
:setting:`~settings.replicaSetId`.