From 748a74f936450377116187a043d009c3478769c8 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Fri, 21 Sep 2012 12:29:43 -0400 Subject: [PATCH 1/3] DOCS-508 early edits --- source/administration/replica-sets.txt | 12 ++++++---- source/replication.txt | 4 ++++ .../tutorial/force-member-to-be-primary.txt | 24 +++++++++++++++++++ 3 files changed, 36 insertions(+), 4 deletions(-) create mode 100644 source/tutorial/force-member-to-be-primary.txt diff --git a/source/administration/replica-sets.txt b/source/administration/replica-sets.txt index b036ab07932..eebb99814e2 100644 --- a/source/administration/replica-sets.txt +++ b/source/administration/replica-sets.txt @@ -21,11 +21,15 @@ suggestions for administers of replica sets. The following tutorials provide task-oriented instructions for specific administrative tasks related to replica set operation. +.. Updates to this tutorial list should also be made in + source/replication.txt + - :doc:`/tutorial/deploy-replica-set` + - :doc:`/tutorial/convert-standalone-to-replica-set` - :doc:`/tutorial/expand-replica-set` - :doc:`/tutorial/deploy-geographically-distributed-replica-set` - :doc:`/tutorial/change-oplog-size` - - :doc:`/tutorial/convert-replica-set-to-replicated-shard-cluster` + - :doc:`/tutorial/force-member-to-be-primary` - :doc:`/tutorial/change-hostnames-in-a-replica-set` - :doc:`/tutorial/convert-secondary-into-arbiter` @@ -333,9 +337,9 @@ the event of a network partition. Procedures ---------- -For procedures on deploying replica sets, see the -:doc:`/administration/replication-architectures` document and the -:ref:`list of replica set tutorials `. +This section gives overview information on certain procedures. Most +procedures, however, are found in the :ref:`replica set tutorials +`. .. _replica-set-admin-procedure-add-member: diff --git a/source/replication.txt b/source/replication.txt index e4b33043c5e..f84cff74ac4 100644 --- a/source/replication.txt +++ b/source/replication.txt @@ -38,6 +38,9 @@ Tutorials The following tutorials describe certain replica set maintenance operations in detail: +.. Updates to this tutorial list should also be made in + source/administration/replica-sets.txt + .. toctree:: :maxdepth: 1 @@ -46,6 +49,7 @@ operations in detail: tutorial/expand-replica-set tutorial/deploy-geographically-distributed-replica-set tutorial/change-oplog-size + tutorial/force-member-to-be-primary` tutorial/change-hostnames-in-a-replica-set tutorial/convert-secondary-into-arbiter diff --git a/source/tutorial/force-member-to-be-primary.txt b/source/tutorial/force-member-to-be-primary.txt new file mode 100644 index 00000000000..0be8bfe23f6 --- /dev/null +++ b/source/tutorial/force-member-to-be-primary.txt @@ -0,0 +1,24 @@ +========================== +For a Member to be Primary +========================== + +.. default-domain:: mongodb + +Synopsis +-------- + +You can force a member to be :term:`primary` by giving it a higher +:data:`members[n].priority` value than any other member in the +:term:`replica set`. You can also force :term:`secondary` members never +to become primary by setting their :data:`members[n].priority` values to +``0``, which means they can never seek :ref:`election +` as primary. For more information on priority +levels, see :ref:`replica-set-node-priority`. + +Procedures +---------- + +.. _replica-set-force-member-to-be-primary-via-priority-setting: + +Force a Member to be Primary by Setting it Priority High +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From e39c748a7589f3f5e2671ee91b15db67e627ca1a Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Fri, 21 Sep 2012 15:36:01 -0400 Subject: [PATCH 2/3] DOCS-508 new procedure --- source/replication.txt | 2 +- .../tutorial/force-member-to-be-primary.txt | 102 +++++++++++++++--- 2 files changed, 91 insertions(+), 13 deletions(-) diff --git a/source/replication.txt b/source/replication.txt index f84cff74ac4..38ffc134252 100644 --- a/source/replication.txt +++ b/source/replication.txt @@ -49,7 +49,7 @@ operations in detail: tutorial/expand-replica-set tutorial/deploy-geographically-distributed-replica-set tutorial/change-oplog-size - tutorial/force-member-to-be-primary` + tutorial/force-member-to-be-primary tutorial/change-hostnames-in-a-replica-set tutorial/convert-secondary-into-arbiter diff --git a/source/tutorial/force-member-to-be-primary.txt b/source/tutorial/force-member-to-be-primary.txt index 0be8bfe23f6..42c2e2f6f03 100644 --- a/source/tutorial/force-member-to-be-primary.txt +++ b/source/tutorial/force-member-to-be-primary.txt @@ -1,24 +1,102 @@ -========================== -For a Member to be Primary -========================== +================================ +Force a Member to Become Primary +================================ .. default-domain:: mongodb Synopsis -------- -You can force a member to be :term:`primary` by giving it a higher -:data:`members[n].priority` value than any other member in the -:term:`replica set`. You can also force :term:`secondary` members never -to become primary by setting their :data:`members[n].priority` values to -``0``, which means they can never seek :ref:`election -` as primary. For more information on priority -levels, see :ref:`replica-set-node-priority`. +You can force a :term:`replica set` member to become :term:`primary` by +giving it a higher :data:`members[n].priority` value than any other +member in the set. Optionally, you also can force all :term:`secondary` +members never to become primaries by setting their +:data:`members[n].priority` values to ``0``, which means they can never +seek :ref:`election ` as primary. Or, as +different approach, you can instead set all secondary members to be +secondary-only, as described in +:ref:`replica-set-secondary-only-members`. Procedures ---------- .. _replica-set-force-member-to-be-primary-via-priority-setting: -Force a Member to be Primary by Setting it Priority High -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Force a Member to be Primary by Setting its Priority High +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For this procedure, assume your current :term:`primary` is +``m1.example.net`` and you'd like to force ``m3.example.net`` to be +primary. Also assume you have a three-member :term:`replica set` with the +following configuration: + +.. code-block:: javascript + + { + "_id" : "rs", + "version" : 7, + "members" : [ + { + "_id" : 0, + "host" : "m1.example.net:27017" + }, + { + "_id" : 1, + "host" : "m2.example.net:27017" + }, + { + "_id" : 2, + "host" : "m3.example.net:27017" + } + ] + } + +1. In the :program:`mongo` shell, use the following sequence of operations + to make ``m3.example.net`` the primary: + + .. code-block:: javascript + + cfg = rs.conf() + cfg.members[0].priority = 0.5 + cfg.members[1].priority = 0.5 + cfg.members[2].priority = 1 + rs.reconfig(cfg) + + This sets ``m3.example.net`` to have a higher + :data:`members[n].priority` value than the other :program:`mongod` + instances. + + The following sequence of events occur: + + - ``m3.example.net`` and ``m2.example.net`` sync with + ``m1.example.net`` (typically within 10 seconds). + + - ``m1.example.net`` sees that it no longer has highest priority and, + in most cases, steps down. If ``m3.example.net`` is far behind + ``m1.example.net``, ``m1.example.net`` does not step down until + ``m3.example.net`` is within 10 seconds of it's :ref:`optime + `. This minimizes the amount of time with no + primary on failover. + + - The step down forces on election in which ``m3.example.net`` + becomes primary based on its :data:`members[n].priority` value. + +#. Optionally, if ``m3.example.net`` is more than 10 seconds behind + ``m1.example.net``'s optime, and if you don't need to have a primary + designated within 10 seconds, you can force ``m1.example.net`` to step down by running: + + .. code-block:: javascript + + db.adminCommand({replSetStepDown:1000000, force:1}) + + This prevents ``m1.example.net`` from being primary for 1,000,000 + seconds, even if there is no other member that can become primary. + When ``m3.example.net`` catches up with ``m1.example.net`` it syncs + and becomes primary. + + If you change your mind and would like to make ``m1.example.net`` primary again while it waits for + ``m3.example.net`` to catch up, issue the following command to make ``m1.example.net`` seek election again: + + .. code-block:: javascript + + db.adminCommand({replSetFreeze:0}) From 2ec288ff5c4e9e4d0fb70c7756238367d4843263 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Fri, 21 Sep 2012 17:04:41 -0400 Subject: [PATCH 3/3] DOCS-508 added tutorial to force primary --- source/administration/replica-sets.txt | 4 +- .../tutorial/force-member-to-be-primary.txt | 81 ++++++++++++++----- 2 files changed, 65 insertions(+), 20 deletions(-) diff --git a/source/administration/replica-sets.txt b/source/administration/replica-sets.txt index eebb99814e2..0bccf42c5bc 100644 --- a/source/administration/replica-sets.txt +++ b/source/administration/replica-sets.txt @@ -21,8 +21,8 @@ suggestions for administers of replica sets. The following tutorials provide task-oriented instructions for specific administrative tasks related to replica set operation. -.. Updates to this tutorial list should also be made in - source/replication.txt + .. Updates to this tutorial list should also be made in + source/replication.txt - :doc:`/tutorial/deploy-replica-set` - :doc:`/tutorial/convert-standalone-to-replica-set` diff --git a/source/tutorial/force-member-to-be-primary.txt b/source/tutorial/force-member-to-be-primary.txt index 42c2e2f6f03..7e20411d850 100644 --- a/source/tutorial/force-member-to-be-primary.txt +++ b/source/tutorial/force-member-to-be-primary.txt @@ -9,12 +9,12 @@ Synopsis You can force a :term:`replica set` member to become :term:`primary` by giving it a higher :data:`members[n].priority` value than any other -member in the set. Optionally, you also can force all :term:`secondary` -members never to become primaries by setting their -:data:`members[n].priority` values to ``0``, which means they can never -seek :ref:`election ` as primary. Or, as -different approach, you can instead set all secondary members to be -secondary-only, as described in +member in the set. + +Optionally, you also can force a member never to become primary by +setting its :data:`members[n].priority` value to ``0``, which means the +member can never seek :ref:`election ` as +primary. For more information, see :ref:`replica-set-secondary-only-members`. Procedures @@ -25,10 +25,17 @@ Procedures Force a Member to be Primary by Setting its Priority High ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For this procedure, assume your current :term:`primary` is -``m1.example.net`` and you'd like to force ``m3.example.net`` to be -primary. Also assume you have a three-member :term:`replica set` with the -following configuration: +.. versionchanged:: 2.0 + +For more information on priorities, see :ref:`replica-set-node-priority`. + +This procedure assumes your current :term:`primary` is +``m1.example.net`` and that you'd like to instead make ``m3.example.net`` primary. +The procedure also assumes you have a three-member :term:`replica set` with the +configuration below. For more information on configurations, see :ref:`Replica Set +Configuration Use `. + +This procedure assumes this configuration: .. code-block:: javascript @@ -72,18 +79,19 @@ following configuration: ``m1.example.net`` (typically within 10 seconds). - ``m1.example.net`` sees that it no longer has highest priority and, - in most cases, steps down. If ``m3.example.net`` is far behind - ``m1.example.net``, ``m1.example.net`` does not step down until - ``m3.example.net`` is within 10 seconds of it's :ref:`optime - `. This minimizes the amount of time with no - primary on failover. + in most cases, steps down. ``m1.example.net`` *does not* step down + if ``m3.example.net``'s sync is far behind. In that case, + ``m1.example.net`` waits until ``m3.example.net`` is within 10 + seconds of its optime and then steps down. This minimizes the + amount of time with no primary on failover. - The step down forces on election in which ``m3.example.net`` becomes primary based on its :data:`members[n].priority` value. #. Optionally, if ``m3.example.net`` is more than 10 seconds behind ``m1.example.net``'s optime, and if you don't need to have a primary - designated within 10 seconds, you can force ``m1.example.net`` to step down by running: + designated within 10 seconds, you can force ``m1.example.net`` to + step down by running: .. code-block:: javascript @@ -94,9 +102,46 @@ following configuration: When ``m3.example.net`` catches up with ``m1.example.net`` it syncs and becomes primary. - If you change your mind and would like to make ``m1.example.net`` primary again while it waits for - ``m3.example.net`` to catch up, issue the following command to make ``m1.example.net`` seek election again: + If you change your mind and would like to make ``m1.example.net`` + primary again while it waits for ``m3.example.net`` to catch up, + issue the following command to make ``m1.example.net`` seek election + again: .. code-block:: javascript db.adminCommand({replSetFreeze:0}) + +.. _replica-set-force-member-to-be-primary-via-dbcommands: + +Force a Member to be Primary Using Database Commands +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionchanged:: 1.8 + +For this procedure, assume you have a :term:`replica set` with members +``A``, ``B``, and ``C``. ``A`` is current :term:`primary`, and you want +``B`` to become primary. To do so you use :method:`rs.freeze()` and +:method:`rs.stepDown()`, which are wrappers for the +:dbcommand:`replSetFreeze` and :dbcommand:`replSetStepDown` commands. + +1. In a :program:`mongo` shell, run :method:`rs.status()` to ensure your replica + set is running as expected. + +#. In a :program:`mongo` shell connected to ``C``, freeze ``C`` so that it does + not attempt to become primary for 120 seconds. + + .. code-block:: javascript + + rs.freeze(120) + +#. In a :program:`mongo` shell connected to ``A``, step down ``A`` so that it is not + eligible to become primary for 120 seconds: + + .. code-block:: javascript + + rs.stepDown(120) + + ``B`` becomes primary. + + .. note:: During the transition, there is a short window when no member + is primary.