From f5d122b4d6d4a2ef4a7ea2e0d16dcead53e8bbbb Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Mon, 11 Feb 2013 15:03:10 -0500 Subject: [PATCH 1/4] DOCS-941 replication chaining --- source/administration/replica-sets.txt | 72 ++++++++++++++++++++++ source/reference/replica-configuration.txt | 40 +++++++++--- 2 files changed, 102 insertions(+), 10 deletions(-) diff --git a/source/administration/replica-sets.txt b/source/administration/replica-sets.txt index 3ae73453320..24bf6f7de5e 100644 --- a/source/administration/replica-sets.txt +++ b/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-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 ` +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 diff --git a/source/reference/replica-configuration.txt b/source/reference/replica-configuration.txt index 947cb78e797..6f532492dab 100644 --- a/source/reference/replica-configuration.txt +++ b/source/reference/replica-configuration.txt @@ -217,8 +217,27 @@ 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 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 : , host : hostname<:port>, - ,> - ,> - ,> - ,> - },> - ,> + >, + >, + >, + >, + } >, + >, > } , ... ], ,> - > + >, + >, + > }> } From 6fa4111029cbace6a522f46ead3ffec8cbb367f5 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Mon, 11 Feb 2013 16:23:58 -0500 Subject: [PATCH 2/4] DOCS-941 review edits --- source/administration/replica-sets.txt | 25 +++++++++++++++------- source/reference/replica-configuration.txt | 24 ++++++++++----------- 2 files changed, 29 insertions(+), 20 deletions(-) diff --git a/source/administration/replica-sets.txt b/source/administration/replica-sets.txt index 24bf6f7de5e..e02a7a5235a 100644 --- a/source/administration/replica-sets.txt +++ b/source/administration/replica-sets.txt @@ -349,10 +349,8 @@ 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. +Chained replication can reduce load on the primary. But depending on the network +topology, chained replication can also result in increased replication lag. .. versionadded:: 2.2.2 @@ -360,7 +358,7 @@ You can use the :data:`chainingAllowed ` setting in :doc:`/reference/replica-configuration` to disable chained replication -for situations where replication lag is an issue. For details, see +for situations where chained replication is causing lag. For details, see :ref:`replica-set-config-chained-replication`. Procedures @@ -631,7 +629,7 @@ You can use the following sequence of commands to set ``chainingAllowed`` to .. code-block:: javascript - cfg = rs.conf() + cfg = rs.config() #. Take note of whether the current configuration settings contain the ``settings`` sub-document. If they do, skip this step. @@ -655,8 +653,19 @@ You can use the following sequence of commands to set ``chainingAllowed`` to cfg.settings.chainingAllowed = false rs.reconfig(cfg) -To re-enable chained replication, use :dbcommand:`replSetSyncFrom` to -specify that each secondary replicates from the primary. +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 the primary. But that configuration will last only until the + secondary recalculates which member to sync from. .. _replica-set-procedure-change-oplog-size: diff --git a/source/reference/replica-configuration.txt b/source/reference/replica-configuration.txt index 6f532492dab..e2967c07e46 100644 --- a/source/reference/replica-configuration.txt +++ b/source/reference/replica-configuration.txt @@ -217,8 +217,8 @@ Configuration Variables **Type**: :term:`MongoDB Document ` - The settings document affects replication chaining and - available :term:`write concern` options. + The ``settings`` document configures options that apply to the whole + replica set. .. data:: local.system.replset.settings.chainingAllowed @@ -232,7 +232,7 @@ Configuration Variables 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 + 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. @@ -280,20 +280,20 @@ all optional fields. { _id : , host : hostname<:port>, - >, - >, - >, - >, - } >, - >, + ,> + ,> + ,> + ,> + },> + ,> > } , ... ], >, - >, - > + ,> + ,> + > }> } From c1e2daaa16981ecbdd27fb58dc8fbe3ea4310054 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Mon, 11 Feb 2013 19:39:42 -0500 Subject: [PATCH 3/4] DOCS-941 review edits II --- source/administration/replica-sets.txt | 8 ++++---- source/reference/replica-configuration.txt | 2 ++ 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/source/administration/replica-sets.txt b/source/administration/replica-sets.txt index e02a7a5235a..99c7a7a089c 100644 --- a/source/administration/replica-sets.txt +++ b/source/administration/replica-sets.txt @@ -344,6 +344,8 @@ the event of a network partition. 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 @@ -352,9 +354,7 @@ target based on ping time and if the closest member is another secondary. Chained replication can reduce load on the primary. But depending on the network topology, chained replication can also result in increased replication lag. -.. versionadded:: 2.2.2 - -You can use the +Beginning with version 2.2.2, you can use the :data:`chainingAllowed ` setting in :doc:`/reference/replica-configuration` to disable chained replication @@ -664,7 +664,7 @@ You can use the following sequence of commands: .. note:: If chained replication is disabled, you still can use :dbcommand:`replSetSyncFrom` to specify that a secondary replicates - from the primary. But that configuration will last only until the + from another secondary. But that configuration will last only until the secondary recalculates which member to sync from. .. _replica-set-procedure-change-oplog-size: diff --git a/source/reference/replica-configuration.txt b/source/reference/replica-configuration.txt index e2967c07e46..9b1739a47be 100644 --- a/source/reference/replica-configuration.txt +++ b/source/reference/replica-configuration.txt @@ -228,6 +228,8 @@ Configuration Variables **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`. From a1f08cede6f356cf5a0ff803e71abf377a92d6a1 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Tue, 12 Feb 2013 14:01:12 -0500 Subject: [PATCH 4/4] DOCS-941 review edits III --- source/administration/replica-sets.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/source/administration/replica-sets.txt b/source/administration/replica-sets.txt index 99c7a7a089c..ca842f9f99f 100644 --- a/source/administration/replica-sets.txt +++ b/source/administration/replica-sets.txt @@ -351,8 +351,9 @@ 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 depending on the network -topology, chained replication can also result in increased replication lag. +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 `