From 39cd2a9c08772713f376c45123872a576b104d70 Mon Sep 17 00:00:00 2001 From: "Tim Slavin (MongoDB)" Date: Wed, 30 Jul 2014 16:29:59 -0400 Subject: [PATCH] DOCS-3018: Consolidate docs for replSetSyncFrom command --- .../fact-replSetSyncFrom-target-member.rst | 22 ++++++++ source/reference/command/replSetSyncFrom.txt | 56 ++----------------- source/reference/method/rs.syncFrom.txt | 3 + ...gure-replica-set-secondary-sync-target.txt | 47 +++++++++++++++- 4 files changed, 75 insertions(+), 53 deletions(-) create mode 100644 source/includes/fact-replSetSyncFrom-target-member.rst diff --git a/source/includes/fact-replSetSyncFrom-target-member.rst b/source/includes/fact-replSetSyncFrom-target-member.rst new file mode 100644 index 00000000000..51c2cd534dc --- /dev/null +++ b/source/includes/fact-replSetSyncFrom-target-member.rst @@ -0,0 +1,22 @@ +The member to sync from must be a valid source for data in the set. +To sync from a member, the member must: + +- Have data. It cannot be an arbiter, in startup or recovering mode, and + must be able to answer data queries. + +- Be accessible. + +- Be a member of the same set in the replica set configuration. + +- Build indexes with the + :data:`~local.system.replset.members[n].buildIndexes` setting. + +- A different member of the set, to prevent syncing from itself. + +If you attempt to replicate from a member that is more than 10 seconds +behind the current member, :program:`mongod` will log a warning but will +still replicate from the lagging member. + +If you run :dbcommand:`replSetSyncFrom` during initial sync, MongoDB +produces no error messages, but the sync target will not change until +after the initial sync operation. diff --git a/source/reference/command/replSetSyncFrom.txt b/source/reference/command/replSetSyncFrom.txt index 1c431825d08..ed5a10786a1 100644 --- a/source/reference/command/replSetSyncFrom.txt +++ b/source/reference/command/replSetSyncFrom.txt @@ -11,11 +11,10 @@ Description .. versionadded:: 2.2 - Explicitly configures - which host the current :program:`mongod` pulls :term:`oplog` - entries from. This operation is useful for testing different - patterns and in situations where a set member is not replicating from - the desired host. + Explicitly configures which host the current :program:`mongod` pulls + :term:`oplog` entries from. This operation is useful for testing + different patterns and in situations where a set member is not + replicating from the desired host. The :dbcommand:`replSetSyncFrom` command has the following form: @@ -27,48 +26,5 @@ Description .. include:: /reference/command/replSetSyncFrom-field.rst -The Target Member ------------------ - - The member to replicate from must be a valid source for data in the - set. The member cannot be: - - - The same as the :program:`mongod` on which you run - :dbcommand:`replSetSyncFrom`. In other words, a member cannot - replicate from itself. - - An arbiter, because arbiters do not hold data. - - A member that does not build indexes. - - An unreachable member. - - A :program:`mongod` instance that is not a member of the same - replica set. - - If you attempt to replicate from a member that is more than 10 seconds - behind the current member, :program:`mongod` will log a - warning but will still replicate from the lagging member. - - If you run :dbcommand:`replSetSyncFrom` during initial sync, MongoDB - produces no error messages, but the sync target will not change - until after the initial sync operation. - -Run from the ``mongo`` Shell ----------------------------- - - To run the command in the :program:`mongo` shell, use the following - invocation: - - .. code-block:: javascript - - db.adminCommand( { replSetSyncFrom: "hostname<:port>" } ) - - You may also use the :method:`rs.syncFrom()` helper in the - :program:`mongo` shell in an operation with the following form: - - .. code-block:: javascript - - rs.syncFrom("hostname<:port>") - - .. note:: - - .. include:: /includes/fact-replica-set-sync-from-is-temporary.rst - - .. slave-ok, admin-only + See :doc:`/tutorial/configure-replica-set-secondary-sync-target` for + more information on the use of :dbcommand:`replSetSyncFrom`. diff --git a/source/reference/method/rs.syncFrom.txt b/source/reference/method/rs.syncFrom.txt index 3c5643d9f9d..d496e64b8aa 100644 --- a/source/reference/method/rs.syncFrom.txt +++ b/source/reference/method/rs.syncFrom.txt @@ -14,3 +14,6 @@ rs.syncFrom() member you want to replicate from in the form of ``[hostname]:[port]``. See :dbcommand:`replSetSyncFrom` for more details. + + See :doc:`/tutorial/configure-replica-set-secondary-sync-target` for + details how to use this command. diff --git a/source/tutorial/configure-replica-set-secondary-sync-target.txt b/source/tutorial/configure-replica-set-secondary-sync-target.txt index 90a4204dd0f..65083f993b0 100644 --- a/source/tutorial/configure-replica-set-secondary-sync-target.txt +++ b/source/tutorial/configure-replica-set-secondary-sync-target.txt @@ -4,15 +4,34 @@ Configure a Secondary's Sync Target .. default-domain:: mongodb +Overview +-------- + +Secondaries capture data from the primary member to maintain an up to date +copy of the sets' data. However, by default secondaries may automatically +change their sync targets to secondary members based on changes in the +ping time between members and the state of other members’ replication. See +:doc:`/core/replica-set-sync` and +:doc:`/tutorial/manage-chained-replication` for more information. + +For some deployments, implementing a custom replication sync topology may +be more effective than the default sync target selection logic. MongoDB +provides the ability to specify a host to use as a sync target. + To override the default sync target selection logic, you may manually -configure a :term:`secondary` member's sync target for pulling -:term:`oplog` entries temporarily. The following operations provide -access to this functionality: +configure a :term:`secondary` member's sync target to temporarily pull +:term:`oplog` entries. The following provide access to this functionality: - :dbcommand:`replSetSyncFrom` command, or - :method:`rs.syncFrom()` helper in the :program:`mongo` shell +Considerations +-------------- + +Sync Logic +~~~~~~~~~~ + Only modify the default sync logic as needed, and always exercise caution. :method:`rs.syncFrom()` will not affect an in-progress initial sync operation. To affect the sync target for the initial sync, run @@ -25,3 +44,25 @@ after the initial sync operation. .. note:: .. include:: /includes/fact-replica-set-sync-from-is-temporary.rst + +The Sync Target +~~~~~~~~~~~~~~~ + +.. include:: /includes/fact-replSetSyncFrom-target-member.rst + +Procedure +--------- + +To use the :dbcommand:`replSetSyncFrom` command in the :program:`mongo` shell: + +.. code-block:: javascript + + db.adminCommand( { replSetSyncFrom: "hostname<:port>" } ) + +To use the :method:`rs.syncFrom()` helper in the :program:`mongo` shell: + +.. code-block:: javascript + + rs.syncFrom("hostname<:port>") + +.. slave-ok, admin-only