DOCS-2671 macro tutorial: deploy replica set with auth

source/includes/steps-add-user-administrator-for-replica-set.yaml

@@ -0,0 +1,39 @@
+stepnum: 1
+source:
+  file: steps-change-user-privileges.yaml
+  ref: connect-with-appropriate-privileges
+pre: |
+  Connect to the replica set :term:`primary` as a user with the
+  privileges required in the :ref:`add-user-admin-prereq` section.
+---
+stepnum: 2
+source:
+  file: steps-change-user-privileges.yaml
+  ref: verify-privileges
+---
+title: Create the user administrator.
+stepnum: 3
+ref: create-user-admin
+pre: |
+  Add the user and assign the :authrole:`userAdmin` role or
+  :authrole:`userAdminAnyDatabase` role, and only that role.
+action:
+  pre: |
+    The following example creates the user ``recordsUserAdmin`` on the
+    ``records`` database:
+  language: javascript
+  code: |
+    db.createUser(
+      {
+        user: "recordsUserAdmin",
+        pwd: "password",
+        roles:
+        [
+          {
+            role: "userAdmin",
+            db: "records"
+          }
+        ]
+      }
+    )
+...

source/includes/steps-deploy-replica-set-with-auth.yaml

@@ -0,0 +1,63 @@
+stepnum: 1
+source:
+  file: steps-generate-key-file.yaml
+  ref: generate
+---
+title: Copy the key file to each member of the replica set.
+stepnum: 2
+ref: copy-key-file
+---
+title: Start each member of the replica set with the appropriate options.
+stepnum: 3
+ref: start-mongod
+pre: |
+  For each member, start a :program:`mongod` and specify the key file and
+  the name of the replica set. Also specify other parameters as needed for
+  your deployment. For replication-specific parameters, see
+  :ref:`cli-mongod-replica-set` required by your deployment.
+pre: |
+  .. include:: /includes/important-unique-replica-set-names.rst
+action:
+  - pre: |
+      The following example specifies parameters through the :option:`--keyFile`
+      and :option:`--replSet` command-line options:
+    language: javascript
+    code: |
+      mongod --keyFile /mysecretdirectory/keyfile --replSet "rs0"
+  - pre: |
+      The following example specifies parameters through a configuration file:
+    language: javascript
+    code: |
+      mongod --config /etc/mongodb.conf
+post: |
+  In production deployments, you can configure a :term:`control script` to
+  manage this process. Control scripts are beyond the scope of this document.
+---
+title: Connect to one of the replica set members.
+stepnum: 4
+port: |
+  Connect through the :ref:`localhost exception <localhost-exception>`.
+source:
+  file: steps-deploy-replica-set.yaml
+  ref: open-shell
+---
+stepnum: 5
+source:
+  file: steps-deploy-replica-set.yaml
+  ref: initiate-rs
+---
+stepnum: 6
+source:
+  file: steps-deploy-replica-set.yaml
+  ref: display-rsconf
+---
+stepnum: 7
+source:
+  file: steps-deploy-replica-set.yaml
+  ref: add-remaining-members
+---
+stepnum: 8
+source:
+  file: steps-deploy-replica-set.yaml
+  ref: check-status
+...

source/includes/steps-deploy-replica-set.yaml

@@ -1,38 +1,36 @@
-title: Start a :program:`mongod` on each system to be part of the replica set.
+title: Start each member of the replica set with the appropriate options.
 stepnum: 1
 ref: start-mongod
 pre: |
-  Specify the same replica set name on each instance.
+  For each member, start a :program:`mongod` and specify the replica set
+  name through the :setting:`replSet` option. Specify any other parameters
+  specific to your deployment. For replication-specific parameters, see
+  :ref:`cli-mongod-replica-set` required by your deployment.
+pre: |
+  .. include:: /includes/important-unique-replica-set-names.rst
 action:
   - pre: |
-      .. include:: /includes/important-unique-replica-set-names.rst
-  - pre: |
-      To specify the replica set name from the command-line, start a
-      :program:`mongod` instance with the :option:`--replSet` option. For
-      additional replica-set options, see :ref:`cli-mongod-replica-set`.
-      The following example specifies a replica set named ``rs0``:
+      The following example specifies the replica set name through the
+      :option:`--replSet` command-line option:
     language: javascript
     code: |
-      mongod --dbpath /srv/mongodb/ --port 27017 --replSet "rs0"
+      mongod --replSet "rs0"
   - pre: |
-      To instead use a configuration file, start each
-      :program:`mongod` instance with a command that resembles the
-      following. Change ``/etc/mongodb.conf`` to the location of your
-      configuration file:
+      The following example specifies the name through a configuration file:
     language: javascript
     code: |
       mongod --config /etc/mongodb.conf
 post: |
   In production deployments, you can configure a :term:`control script` to
   manage this process. Control scripts are beyond the scope of this document.
 ---
-title: Open a :program:`mongo` shell and connect to one of the hosts.
+title: Open a :program:`mongo` shell and connect to one of the replica set members.
 stepnum: 2
 ref: open-shell
 action:
   pre: |
-    For example, to connect to the :program:`mongod` running on the default
-    port ``27017`` on the localhost, simply issue:
+    For example, to connect to a :program:`mongod` running on localhost on
+    the default port of ``27017``, simply issue:
   language: javascript
   code: |
     mongo
@@ -42,18 +40,21 @@ stepnum: 3
 ref: initiate-rs
 action:
   pre: |
-    Use :method:`rs.initiate()` to initiate a replica set that consists of
-    the current member and that uses the default configuration:
+    Use :method:`rs.initiate()`:
   language: javascript
   code: |
     rs.initiate()
+post: |
+  MongoDB initiates a set that consists of the current member and that
+  uses the default replica set configuration.
 ---
-title: Display the current replica set configuration.
+title: Verify the initial replica set configuration.
 stepnum: 4
-ref: display-rsconf
+ref: verify-rsconf
 action:
   - pre: |
-      To display the :doc:`replica configuration </reference/replica-configuration>`, issue:
+      Use :method:`rs.conf()` to display the :doc:`replica set configuration
+      object </reference/replica-configuration>`:
     language: javascript
     code: |
       rs.conf()
@@ -71,22 +72,24 @@ action:
             }
          ]
       }
+post: |
+
 ---
 title: Add the remaining members to the replica set.
 stepnum: 5
 ref: add-remaining-members
+pre: |
+  Add the remaining members with the :method:`rs.add()` method.
 action:
   pre: |
-    In the :program:`mongo` shell connected to the :term:`primary`, add
-    the remaining members with the :method:`rs.add()` method. The
-    commands should resemble the following:
+    The following example adds two members:
   language: javascript
   code: |
       rs.add("mongodb1.example.net")
       rs.add("mongodb2.example.net")
 post: |
-  When complete, you should have a fully functional replica set.
-  The new replica set will elect a :term:`primary`.
+  When complete, you have a fully functional replica set. The new replica
+  set will elect a :term:`primary`.
 ---
 title: Check the status of the replica set.
 stepnum: 6
@@ -97,8 +100,4 @@ action:
   language: javascript
   code: |
     rs.status()
-post: |
-  For a detailed explanation of read and write semantics in MongoDB, refer
-  to :doc:`Replica Set Read and Write Semantics
-  </applications/replication>`.
 ...

source/includes/steps-generate-key-file.yaml

@@ -1,19 +1,22 @@
-title: Generate a key file to store authentication information.
+title: Create a key file.
 stepnum: 1
 ref: generate
+pre: |
+   Create the key file your deployment will use to authenticate
+   servers to each other.
 action:
   pre: |
-    Use the following ``openssl`` command at the system shell to generate
-    a key file with pseudo-random content:
+    For example, issue the ``openssl`` command to generate pseudo-random
+    content and save it as a new key file:
   language: sh
   code: |
-    openssl rand -base64 741
+    openssl rand -base64 741 > /mysecretdirectory/keyfile
 ---
 title: Specify the key file when starting a MongoDB instance.
 stepnum: 2
 ref: specify
 action:
   pre: |
-    When starting your MongoDB instance, specify the key file using the
+    When starting a MongoDB instance, specify the key file through the
     :setting:`keyFile` option.
 ...

source/includes/toc-replica-set-deployment.yaml

@@ -3,6 +3,10 @@ description: |
   Configure a three-member replica set for either a
   production system.
 ---
+file: /tutorial/deploy-replica-set-with-auth
+description: |
+  Configure a replica set that has authentication enabled.
+---
 file: /tutorial/deploy-replica-set-for-testing
 description: |
   Configure a three-member replica set for either a

source/includes/toc-spec-replica-set-tutorials-landing.yaml

@@ -8,6 +8,8 @@ files:
     level: 1
   - file: /tutorial/deploy-replica-set
     level: 2
+  - file: /tutorial/deploy-replica-set-with-auth
+    level: 2
   - file: /tutorial/convert-standalone-to-replica-set
     level: 2
   - file: /tutorial/expand-replica-set

source/tutorial.txt

@@ -37,6 +37,7 @@ Replica Sets
 ~~~~~~~~~~~~
 
 - :doc:`/tutorial/deploy-replica-set`
+- :doc:`/tutorial/deploy-replica-set-with-auth`
 - :doc:`/tutorial/convert-standalone-to-replica-set`
 - :doc:`/tutorial/expand-replica-set`
 - :doc:`/tutorial/remove-replica-set-member`

source/tutorial/deploy-replica-set-with-auth.txt

@@ -0,0 +1,65 @@
+=================================================================
+Deploy Replica Set and Configure Authentication and Authorization
+=================================================================
+
+.. default-domain:: mongodb
+
+Overview
+--------
+
+When a :doc:`replica set </core/replication-introduction>` uses
+:doc:`authentication </core/authentication>` and :doc:`authorization
+</core/authorization>`, clients must provide credentials to access the
+replica set's data. A client's privileges define the client's level of
+access.
+
+Replication keeps your data available in the event of a hardware or other
+failure. Deploying a replica set involves setting up a :term:`primary`
+MongoDB instance and two or more additional instances that replicate the
+primary's data. All members in a replica set hold the same data.
+
+Enabling authentication requires an authentication mechanism. This
+tutorial uses a challenge-response mechanism, which uses a key file.
+
+.. Authorization ...
+
+.. When you complete the tutorial ...
+
+Considerations
+--------------
+
+Authentication requires an authentication mechanism and in many cases a
+:setting:`key file <keyFile>`.
+
+Prerequisites
+-------------
+
+.. todo
+
+Procedures
+----------
+
+Use following procedures in sequence.
+
+Deploy the Replica Set and Enable Authentication
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This procedure deploys all members of the set, each with a copy of the
+same key file.
+
+
+.. include:: /includes/steps/deploy-replica-set-with-auth.rst
+
+Create a User Administrator
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Running with authentication requires that a user administrator exists who
+can create any type of user with any level of access required by your
+deployment.
+
+.. include:: /includes/steps/add-user-administrator-for-replica-set.rst
+
+Create Additional Users
+~~~~~~~~~~~~~~~~~~~~~~~
+
+To add a user to a database, see :doc:`/tutorial/add-user-to-database`.