DOCS-941 chained replication

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-reconfiguration-usage>`.
 
+.. _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 <local.system.replset.settings.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

source/reference/replica-configuration.txt

@@ -217,8 +217,29 @@ Configuration Variables
 
    **Type**: :term:`MongoDB Document <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.
        , ...
      ],
      <settings: {
+       <chainingAllowed : <boolean>,>
        <getLastEerrorDefaults : <lasterrdefaults>,>
        <getLastErrorModes : <modes>>
      }>