diff --git a/source/administration/replica-sets.txt b/source/administration/replica-sets.txt index 3ae73453320..ca842f9f99f 100644 --- a/source/administration/replica-sets.txt +++ b/source/administration/replica-sets.txt @@ -339,6 +339,29 @@ the event of a network partition. .. seealso:: :data:`~local.system.replset.settings.members[n].votes` and :ref:`Replica Set Reconfiguration `. +.. _replica-set-chained-replication: + +Chained Replication +~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 2.0 + +Chained replication occurs when a :term:`secondary` member replicates +from another secondary member instead of from the :term:`primary`. This +might be the case, for example, if a secondary selects its replication +target based on ping time and if the closest member is another secondary. + +Chained replication can reduce load on the primary. But chained +replication can also result in increased replication lag, depending on +the topology of the network. + +Beginning with version 2.2.2, you can use the +:data:`chainingAllowed ` +setting in +:doc:`/reference/replica-configuration` to disable chained replication +for situations where chained replication is causing lag. For details, see +:ref:`replica-set-config-chained-replication`. + Procedures ---------- @@ -586,6 +609,65 @@ after the initial sync operation. .. include:: /includes/fact-replica-set-sync-from-is-temporary.rst +.. _replica-set-config-chained-replication: + +Enable or Disable Chained Replication +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 2.2.2 + +:ref:`replica-set-chained-replication` is enabled by default. This +procedure describes how to disable it and how to re-enable it. + +To disable chained replication, set the +:data:`local.system.replset.settings.chainingAllowed` +field in :doc:`/reference/replica-configuration` to ``false``. + +You can use the following sequence of commands to set ``chainingAllowed`` to +``false``: + +1. Copy the configuration settings into the ``cfg`` object: + + .. code-block:: javascript + + cfg = rs.config() + +#. Take note of whether the current configuration settings contain the + ``settings`` sub-document. If they do, skip this step. + + .. warning:: To avoid data loss, skip this step if the configuration + settings contain the ``settings`` sub-document. + + If the current configuration settings **do not** contain the + ``settings`` sub-document, create the sub-document by issuing the + following command: + + .. code-block:: javascript + + cfg.settings = { } + +#. Issue the following sequence of commands to set ``chainingAllowed`` + to ``false``: + + .. code-block:: javascript + + cfg.settings.chainingAllowed = false + rs.reconfig(cfg) + +To re-enable chained replication, set ``chainingAllowed`` to ``true``. +You can use the following sequence of commands: + +.. code-block:: javascript + + cfg = rs.config() + cfg.settings.chainingAllowed = true + rs.reconfig(cfg) + +.. note:: If chained replication is disabled, you still can use + :dbcommand:`replSetSyncFrom` to specify that a secondary replicates + from another secondary. But that configuration will last only until the + secondary recalculates which member to sync from. + .. _replica-set-procedure-change-oplog-size: Changing Oplog Size diff --git a/source/reference/replica-configuration.txt b/source/reference/replica-configuration.txt index 947cb78e797..9b1739a47be 100644 --- a/source/reference/replica-configuration.txt +++ b/source/reference/replica-configuration.txt @@ -217,8 +217,29 @@ Configuration Variables **Type**: :term:`MongoDB Document ` - The setting document holds two optional fields, which affect the - available :term:`write concern` options and default configurations. + The ``settings`` document configures options that apply to the whole + replica set. + +.. data:: local.system.replset.settings.chainingAllowed + + *Optional*. + + **Type**: boolean + + **Default**: true + + .. versionadded:: 2.2.2 + + When this value is ``true``, the replica set allows :term:`secondary` + members to replicate from other secondary members. When this value is + ``false``, secondaries can replicate only from the :term:`primary`. + + When you run :method:`rs.config()` to view a replica set's + configuration, the ``chainingAllowed`` field appears only when it is + set to ``false``. If ``chainingAllowed`` is set to its default value + of ``true``, the field does not appear. + + .. seealso:: :ref:`replica-set-chained-replication` .. data:: local.system.replset.settings.getLastErrorDefaults @@ -272,6 +293,7 @@ all optional fields. , ... ], ,> ,> > }>