DOCS-508 force a member to be primary

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 <replica-set-tutorials-list>`.
+This section gives overview information on certain procedures. Most
+procedures, however, are found in the :ref:`replica set tutorials
+<replica-set-tutorials-list>`.
 
 .. _replica-set-admin-procedure-add-member:
 

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
 

source/tutorial/force-member-to-be-primary.txt

@@ -0,0 +1,147 @@
+================================
+Force a Member to Become Primary
+================================
+
+.. default-domain:: mongodb
+
+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 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 <replica-set-elections>` as
+primary. For more information, see
+: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 its Priority High
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. 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 <replica-set-reconfiguration-usage>`.
+
+This procedure assumes this 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. ``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:
+
+   .. 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})
+
+.. _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.