DOCS-941 replication chaining

Author: Bob Grabar

source/administration/replica-sets.txt

@@ -339,6 +339,30 @@ 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
+~~~~~~~~~~~~~~~~~~~
+
+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 has the benefit of providing load balancing in cases
+where the primary is heavily loaded. But, depending on the network
+topology, replication chaining can also result in increased replication
+lag.
+
+.. versionadded:: 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 replication lag is an issue. For details, see
+:ref:`replica-set-config-chained-replication`.
+
 Procedures
 ----------
 
@@ -586,6 +610,54 @@ 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.conf()
+
+#. 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, use :dbcommand:`replSetSyncFrom` to
+specify that each secondary replicates from the primary.
+
 .. _replica-set-procedure-change-oplog-size:
 
 Changing Oplog Size

source/reference/replica-configuration.txt

@@ -217,8 +217,27 @@ 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 affects replication chaining and
+   available :term:`write concern` options.
+
+.. data:: local.system.replset.settings.chainingAllowed
+
+   *Optional*.
+
+   **Type**: boolean
+
+   **Default**: true
+
+   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.conf()` 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
 
@@ -261,19 +280,20 @@ all optional fields.
        {
          _id : <ordinal>,
          host : hostname<:port>,
-         <arbiterOnly : <boolean>,>
-         <buildIndexes : <boolean>,>
-         <hidden : <boolean>,>
-         <priority: <priority>,>
-         <tags: { <document> },>
-         <slaveDelay : <number>,>
+         <arbiterOnly : <boolean> >,
+         <buildIndexes : <boolean> >,
+         <hidden : <boolean> >,
+         <priority: <priority> >,
+         <tags: { <document> } >,
+         <slaveDelay : <number> >,
          <votes : <number>>
        }
        , ...
      ],
      <settings: {
-       <getLastEerrorDefaults : <lasterrdefaults>,>
-       <getLastErrorModes : <modes>>
+       <chainingAllowed : <boolean> >,
+       <getLastEerrorDefaults : <lasterrdefaults> >,
+       <getLastErrorModes : <modes> >
      }>
    }