replica-configuration.txt

=========================
Replica Set Configuration
=========================

.. default-domain:: mongodb

The configuration for a replica set is stored as a document in the
:data:`system.replset <local.system.replset>` collection in the
:doc:`local database </reference/local-database>`.

.. _replica-set-configuration-document:

Replica Set Configuration Document
----------------------------------

The following document provides a representation of a replica set
configuration document. The configuration of your replica set may
include only a subset of these settings:

.. code-block:: none

   {
     _id: <string>,
     version: <int>,
     members: [
       {
         _id: <int>,
         host: <string>,
         arbiterOnly: <boolean>,
         buildIndexes: <boolean>,
         hidden: <boolean>,
         priority: <number>,
         tags: <document>,
         slaveDelay: <int>,
         votes: <number>
       },
       ...
     ],
     settings: {
       getLastErrorDefaults : <document>,
       chainingAllowed : <boolean>,
       getLastErrorModes : <document>,
       heartbeatTimeoutSecs: <int>
     }
   }

.. _replica-set-configuration-settings:

Configuration Settings
----------------------

.. data:: local.system.replset._id

   *Type*: string

   The name of the replica set. Once set, you cannot change the
   name of a replica set.

   .. see::
      :setting:`~replication.replSetName` or :option:`--replSet`
      for information on setting the replica set name.

.. data:: local.system.replset.version

   An incrementing number used to distinguish revisions of the replica
   set configuration object from previous iterations of the
   configuration.

``replset.members``
~~~~~~~~~~~~~~~~~~~

.. data:: local.system.replset.members

   *Type*: array

   An array of member configuration documents, one for each member
   of the replica set. The :data:`~local.system.replset.members` array
   is a zero-indexed array.

   Each member-specific configuration document can contain the following
   fields:

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

      *Type*: integer

      A numeric identifier of every member in the replica set. Once
      set, you cannot change the
      :data:`~local.system.replset.members[n]._id` of a member.

      .. note::

         .. include:: /includes/fact-rs-conf-array-index.rst

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

         :data:`~local.system.replset.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``.

   .. data:: local.system.replset.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
      :data:`~local.system.replset.members[n].arbiterOnly` to ``true``
      for the added member.

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

      *Optional*.

      *Type*: boolean

      *Default*: true

      A boolean that indicates whether the :program:`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
      :data:`~local.system.replset.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 :program:`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
        :program:`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
         :data:`~local.system.replset.members[n].buildIndexes` to
         ``false``, you must also set
         :data:`~local.system.replset.members[n].priority` to ``0``. If
         :data:`~local.system.replset.members[n].priority` is not
         ``0``, MongoDB will return an error when attempting to add a
         member with
         :data:`~local.system.replset.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
         :data:`~local.system.replset.members[n].buildIndexes` is
         false.

   .. data:: 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
      :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>`

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

      *Optional*.

      *Type*: Number, between 0 and 1000.

      *Default*: 1.0

      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. 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 :data:`~local.system.replset.members[n].priority` of ``0``
      makes it impossible for a member to become primary.

      .. seealso::
         :ref:`Replica Set Elections <replica-set-elections>`.

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

      *Optional*.

      *Type*: document

      *Default*: none

      A document that contains arbitrary field and value pairs for
      describing or *tagging* members in order to extend :doc:`write
      concern </reference/write-concern>` and :doc:`read preference
      </reference/read-preference>` and thereby allowing
      configurable data center awareness.

      Use :data:`~local.system.replicaset.members[n].tags` to
      configure write concerns in conjunction with
      :data:`~local.system.replset.settings.getLastErrorModes` and
      :data:`~local.system.replset.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`.

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

   .. data:: local.system.replset.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 can be either ``1`` or ``0``.

      A replica set can have up to 12 members, but can have at most
      only 7 *voting* members. If you need more than 7 members in one
      replica set, set :data:`~local.system.replset.members[n].votes`
      to ``0`` for the additional non-voting members.

      .. include:: /includes/members-used-to-allow-multiple-votes.rst

``replset.settings``
~~~~~~~~~~~~~~~~~~~~

.. data:: local.system.replset.settings

   *Optional*.

   *Type*: document

   A document that contains configuration options that apply to the
   whole replica set.

   The :data:`~local.system.replset.settings` document contain the
   following fields:

   .. data:: local.system.replset.settings.chainingAllowed

      .. versionadded:: 2.2.4

      *Optional*.

      *Type*: boolean

      *Default*: true

      When :data:`~local.system.replset.settings.chainingAllowed` is
      ``true``, the replica set allows :term:`secondary` members to
      replicate from other secondary members. When
      :data:`~local.system.replset.settings.chainingAllowed` is
      ``false``, secondaries can replicate only from the :term:`primary`.

      When you run :method:`rs.conf()` to view a replica set's
      configuration, the
      :data:`~local.system.replset.settings.chainingAllowed` field
      appears only when set to ``false``. If not set,
      :data:`~local.system.replset.settings.chainingAllowed` is ``true``.

      .. seealso:: :doc:`/tutorial/manage-chained-replication`

   .. data:: local.system.replset.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 :data:`~local.system.replset.settings.getLastErrorDefaults` is
      not set, the default write concern for the replica set only
      requires confirmation from the primary.

   .. data:: local.system.replset.settings.getLastErrorModes

      *Optional*.

      *Type*: document

      A document used to define an extended :term:`write concern`
      through the use of :data:`~local.system.replset.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.

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

View Replica Set Configuration
------------------------------

To view the current configuration for a replica set, use the
:method:`rs.conf()` method. See :method:`rs.conf()` for more
information.

Modify Replica Set Configuration
--------------------------------

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.