DOCS-508 new procedure

Author: Bob Grabar

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
 

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
-<replica-set-elections>` 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 <replica-set-elections>` 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
+     <members.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})