DOCS-536 added command-line options for starting an arbiter

source/administration/replica-sets.txt

@@ -249,13 +249,13 @@ participate in :ref:`elections <replica-set-elections>`.
 .. note::
 
    Because of their minimal system requirements, you may safely deploy an
-   arbiter on a system with another workload such as an application
+   arbiter on a system with another workload, such as an application
    server or monitoring member.
 
 .. warning::
 
    Do not run arbiter processes on a system that is an active
-   :term:`primary` or :term:`secondary` of its replica set.
+   :term:`primary` or :term:`secondary` of its :term:`replica set`.
 
 Arbiters never receive the contents of any collection but do have the
 following interactions with the rest of the replica set:
@@ -264,34 +264,17 @@ following interactions with the rest of the replica set:
   the replica set. All MongoDB processes within a replica set use
   keyfiles. These exchanges are encrypted.
 
-- The *only* cryptographically secure exchange is
-  authentication. Replica set configuration data and voting are not
-  encrypted.
+  The *only* cryptographically secure exchange is authentication.
+
+- Exchanges of replica set configuration data and of votes. These are
+  not encrypted.
 
 If your MongoDB deployment uses SSL, then all communications between
 arbiters and the other members of the replica set are secure. See the
-documentation for :doc:`/administration/ssl` for more information. Run
-all arbiters on secure networks, as with all MongoDB components.
-
-To start an arbiter, use the following command:
-
-.. code-block:: sh
-
-   mongod --replSet [setname]
-
-Replace ``[setname]`` with the name of the :term:`replica set` that the
-arbiter will join. Then in the :program:`mongo` shell, while connected
-to the *current* :term:`primary`, issue the following command:
-
-.. code-block:: javascript
-
-   rs.addArb("[hostname]:[port]")
+documentation for :doc:`/administration/ssl` for more information.
+As with all MongoDB components, run arbiters on secure networks.
 
-Replace the ``[hostname]:[port]`` string with the arbiter's
-hostname and the port.
-
-.. seealso:: :setting:`replSet`, :option:`--replSet <mongod --replSet>`,
-   and :method:`rs.addArb()`.
+To add an arbiter, see :ref:`replica-set-procedure-add-arbiter`.
 
 .. index:: replica set members; non-voting
 .. _replica-set-non-voting-members:
@@ -444,7 +427,7 @@ number. :method:`rs.reconfig()` will not change the value of
 .. _replica-set-member-priority-configuration:
 
 Adjusting Priority
-~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~
 
 To change the value of the :data:`members[n].priority` value in the
 replica set configuration, use the following sequence of commands in
@@ -499,6 +482,50 @@ of the member with the highest :data:`members[n].priority` setting.
    <replica-set-reconfiguration-usage>` example revolves around
    changing the priorities of the :data:`members` of a replica set.
 
+.. _replica-set-procedure-add-arbiter:
+
+Adding an Arbiter
+~~~~~~~~~~~~~~~~~
+
+For a description of :term:`arbiters <arbiter>` and their purpose in
+:term:`replica sets <replica set>`, see :ref:`replica-set-arbiters`.
+
+To prevent tied :term:`elections <election>`, do not add an arbiter to a
+set if the set already has an odd number of voting members.
+
+Because arbiters do not hold a copies of collection data, they have minimal
+resource requirements and do not require dedicated hardware.
+
+1. Create a data directory for the arbiter. The directory is used for
+   configuration information. It *will not* hold database collection data.
+   The following example creates the ``/data/arb`` data directory:
+
+   .. code-block:: sh
+
+      mkdir /data/arb
+
+#. Start the arbiter, making sure to specify the replica set and the
+   data directory. Consider the following example:
+
+   .. code-block:: sh
+
+      mongod --port 30000 --dbpath /data/arb --replSet rs
+
+#. In a :program:`mongo` shell connected to the :term:`primary`, add the
+   arbiter to the replica set by issuing the :method:`rs.addArb()`
+   method, which uses the following syntax:
+
+   .. code-block:: javascript
+
+      rs.addArb("<hostname>:<port>")
+
+   For example, if the arbiter runs on example.net:30000, you would
+   issue this command:
+
+   .. code-block:: javascript
+
+      rs.addArb("example.net:30000")
+
 .. _replica-set-procedure-change-oplog-size:
 
 Changing Oplog Size
@@ -512,8 +539,8 @@ the oplog. For a detailed procedure, see
 
 .. _replica-set-security:
 
-Security
---------
+Replica Set Security
+--------------------
 
 In most cases, the most effective ways to control access and to secure
 the connection between members of a :term:`replica set` depend on

source/administration/replication-architectures.txt

@@ -11,8 +11,9 @@ commonly used deployment patterns for replica sets. The descriptions
 are necessarily not mutually exclusive, and you can combine features
 of each architecture in your own deployment.
 
-.. seealso:: :doc:`/administration/replica-sets` and
-   :doc:`/reference/replica-configuration`.
+For a list of best practices when designing your replication architecture,
+see the :ref:`replica-set-architecture` topic in the :doc:`/core/replication`
+document.
 
 .. _replica-set-three-members:
 
@@ -242,24 +243,12 @@ primary *and* a quorum of voting members in the main facility.
 Arbiters
 --------
 
-You can deploy an :term:`arbiter` to ensure that a replica set will have
+You deploy an :term:`arbiter` to ensure that a replica set will have
 a sufficient number of members to elect a :term:`primary`. While having
 replica sets with 2 members is not recommended for production
-environments, in these circumstances, and *any replica set with an even
+environments, if you have just two members, deploy an arbiter.
+Also, for *any replica set with an even
 number of members*, deploy an arbiter.
 
-To add an arbiter, while connected to the *current primary* in the
-:program:`mongo` shell, issue the following command:
-
-.. code-block:: javascript
-
-   rs.addArb("[hostname]:[port]")
-
-Because arbiters do not hold a copy of the data, they have minimal
-resource requirements and do not require dedicated hardware. Do not add
-an arbiter to a set if you have an odd number of voting members that hold
-data, to prevent tied :term:`elections <election>`.
-
-.. seealso:: :ref:`Arbiters <replica-set-arbiters>`,
-   :setting:`replSet`, :option:`mongod --replSet`, and
-   :method:`rs.addArb()`.
+To deploy an arbiter, see the :ref:`replica-set-arbiters` topic in the
+:doc:`/administration/replica-sets` document.

source/core/replication.txt

@@ -32,10 +32,8 @@ A replica set can have up to 12 members, but only 7 members can have
 votes. For information regarding non-voting members, see
 :ref:`non-voting members <replica-set-non-voting-members>`
 
-.. seealso:: :ref:`Replica Set Implementation Details
-   <replica-set-implementation>` and the :doc:`/replication` index for a
-   list of all documents in this manual that contain information related
-   to the operation and use of MongoDB's replica sets.
+.. seealso:: The :doc:`/replication` index for a list of the documents in
+   this manual that describe the operation and use of replica sets.
 
 .. [#master-slave] MongoDB also provides conventional master/slave
    replication. Master/slave replication operates by way of the same
@@ -52,11 +50,7 @@ Member Configurations
 
 All replica sets at most use a single :term:`primary` and one or more
 :term:`secondary` members. You can configure secondary members in a
-variety of ways, as listed here. For details, see
-:ref:`replica-set-member-configurations` in the
-:doc:`/administration/replica-sets` document.
-
-You can configure a member as any of the following:
+variety of ways, as listed here:
 
 - **Secondary-Only**: These members cannot become primary. See
   :ref:`replica-set-secondary-only-members`.
@@ -73,6 +67,10 @@ You can configure a member as any of the following:
 - **Non-Voting**: These members cannot vote in elections. See
   :ref:`replica-set-non-voting-members`.
 
+For detailed explanations of each member type, see the
+:ref:`replica-set-member-configurations` section in the
+:doc:`/administration/replica-sets` document.
+
 .. _replica-set-failover:
 
 Failover
@@ -81,7 +79,11 @@ Failover
 Replica sets feature automated failover. If the :term:`primary`
 goes offline or becomes unresponsive and a majority of the original
 set members can still connect to each other, the set will elect a new
-primary. For details, see :ref:`replica-set-failover-administration`.
+primary.
+
+For a detailed explanation of failover, see the
+:ref:`replica-set-failover-administration` section in the
+:doc:`/administration/replica-sets` document.
 
 .. index:: replica set; elections
 .. index:: failover; elections
@@ -116,10 +118,13 @@ remain a secondary.
    view of the :term:`replica set` and helps prevent :term:`rollbacks
    <rollback>`.
 
-.. seealso:: The :ref:`replica-set-election-internals` section in the
-   :doc:`/core/replication-internals` document, as well as the
-   :ref:`replica-set-failover-administration` section in the
-   :doc:`/administration/replica-sets` document.
+For more information on elections and failover, see:
+
+- The :ref:`replica-set-failover-administration` section in the
+  :doc:`/administration/replica-sets` document.
+
+- The :ref:`replica-set-election-internals` section in the
+  :doc:`/core/replication-internals` document
 
 .. index:: replica set; priority
 .. _replica-set-node-priority:
@@ -141,16 +146,22 @@ have a single vote in elections.
    :data:`members[n].votes` except to permit more than 7 secondary
    members.
 
-.. seealso:: :ref:`Member Priority Configuration <replica-set-node-priority-configuration>`
+For more information on member priorities, see the
+:ref:`replica-set-node-priority-configuration` section in the
+:doc:`/administration/replica-sets` document.
 
 .. index:: pair: replica set; consistency
 .. _replica-set-consistency:
 
 Consistency
 -----------
 
+This section provides an overview of the concepts that underpin
+database consistency and the MongoDB mechanisms to ensure that users
+have access to consistent data.
+
 In MongoDB, all read operations issued to the primary of a
-replica set are :term:`consistent <strict consistency>`, with the last
+replica set are :term:`consistent <strict consistency>` with the last
 write operation.
 
 If clients configure the :term:`read preference` to permit allow secondary reads,
@@ -168,10 +179,6 @@ members,* except by configuring the :term:`client` and :term:`driver` to
 ensure that write operations succeed on all members before completing
 successfully.
 
-This section provides an overview of the concepts that underpin
-database consistency and the MongoDB mechanisms to ensure that users
-have access to consistent data.
-
 .. index:: rollbacks
    single: replica set; rollbacks
    single: consistency; rollbacks
@@ -212,6 +219,13 @@ that might create rollbacks.
    megabytes of data. If your system needs to rollback more than 300
    MB, you will need to manually intervene to recover this data.
 
+For more information on failover, see:
+
+- The :ref:`replica-set-failover` section in this document.
+
+- The :ref:`replica-set-failover-administration` section in the
+  :doc:`/administration/replica-sets` document.
+
 Application Concerns
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -245,19 +259,18 @@ working with replica sets:
 :term:`Read preference` and :term:`write concern` have particular
 :ref:`consistency <replica-set-consistency>` implications.
 
-.. seealso:: :doc:`/applications/replication`,
-   :ref:`replica-set-write-concern`, and
-   :ref:`replica-set-read-preference`.
+For a more detailed discussion of application concerns, see :doc:`/applications/replication`.
 
 Administration and Operations
 -----------------------------
 
-This section provides a brief overview of relevant concerns for
-administrators of replica set deployments.
+This section provides a brief overview of concerns relevant to
+administrators of :term:`replica set` deployments.
 
-.. seealso::
+For more detailed explanations of replica set administration, see:
 
    - :doc:`/administration/replica-sets`
+
    - :doc:`/administration/replication-architectures`
 
 .. index:: replica set; oplog
@@ -333,11 +346,12 @@ activity of your MongoDB-based application are reads and you are
 writing a small amount of data, you may find that you need a much
 smaller oplog.
 
-.. seealso:: The :ref:`replica-set-oplog` topic in
-   the :doc:`/core/replication-internals` document.
+For a further understanding of oplog behavior, see the
+:ref:`replica-set-oplog` topic in the :doc:`/core/replication-internals`
+document.
 
-Deployment
-~~~~~~~~~~
+Replica Set Deployment
+~~~~~~~~~~~~~~~~~~~~~~
 
 Without replication, a standalone MongoDB instance represents a single
 point of failure and any disruption of the MongoDB system will render
@@ -349,7 +363,7 @@ operations, (i.e. "read heavy") replica sets can greatly increase the
 capability of the database system.
 
 The minimum requirements for a replica set include two members with
-data, for a :term:`primary` and a :term:`secondary`, and an :ref:`arbiters
+data, for a :term:`primary` and a secondary, and an :ref:`arbiters
 <replica-set-arbiters>`. In most circumstances, however, you will want
 to deploy three data members.
 
@@ -408,15 +422,16 @@ that:
   infrastructure, ensure that you configure a
   :setting:`keyFile` on all members to permit authentication.
 
-.. seealso:: :ref:`Replica Set Security <replica-set-security>`
+For more information, see the :ref:`replica-set-security` section in the
+:doc:`/administration/replica-sets` document.
 
 .. _replica-set-deployment-overview:
 .. _replica-set-architecture:
 
 Architectures
 ~~~~~~~~~~~~~
 
-The architecture and design of the replica set deployment can have a
+The architecture and design of the :term:`replica set` deployment can have a
 great impact on the set's capacity and capability. This section
 provides a general overview of best practices for replica set
 architectures.
@@ -436,13 +451,13 @@ Consider the following factors when developing an architecture for
 your replica set:
 
 - Ensure that the members of the replica set will always be able to
-  elect a primary. Run an odd number of members or run an arbiter
+  elect a :term:`primary`. Run an odd number of members or run an :term:`arbiter`
   on one of your application servers if you have an even number of
   members.
 
 - With geographically distributed members, be aware of where the
-  "quorum" of members will be in case of likely network partitions,
-  attempt to ensure that the set can elect a primary among the members in
+  "quorum" of members will be in case of likely network partitions.
+  Attempt to ensure that the set can elect a primary among the members in
   the primary data center.
 
 - Consider including a :ref:`hidden <replica-set-hidden-members>`
@@ -453,7 +468,7 @@ your replica set:
 - Consider keeping one or two members of the set in an off-site data
   center, but make sure to configure the :ref:`priority
   <replica-set-node-priority>` to prevent it from
-  becoming :term:`primary`.
+  becoming primary.
 
-.. seealso:: :doc:`/administration/replication-architectures` for
-   more information regarding replica set architectures.
+For detailed descriptions of replica set configurations see
+:doc:`/administration/replication-architectures`.