DOCS-2670 new steps format: enable auth in sharded and generate key file

source/includes/steps-enable-authentication-in-sharded-cluster.yaml

@@ -0,0 +1,38 @@
+stepnum: 1
+source:
+  file: steps-generate-key-file.yaml
+  ref: generate
+---
+title: Enable authentication on each component in the cluster.
+stepnum: 2
+ref: enable-auth
+pre: |
+  On each
+  :program:`mongos` and :program:`mongod` in the cluster, including each
+  config server and shard, specify the key file by doing one of the following:
+action:
+  - heading: Specify the key file in the configuration file.
+    pre: |
+      In the configuration file, set the :setting:`keyFile` option to the
+      key file's path and then start the component, as in the following
+      example:
+    language: cfg
+    code: |
+      keyFile = /srv/mongodb/keyfile
+  - heading: Specify the key file at runtime.
+    pre:
+      When starting the component, set the :option:`--keyFile <mongos --keyFile>`
+      option, which is an option for both :program:`mongos` instances and
+      :program:`mongod` instances. Set the :option:`--keyFile <mongos --keyFile>`
+      to the key file's path. The :setting:`keyFile` setting implies the
+      :setting:`auth` setting, which means in most cases you do not need
+      to set :setting:`auth` explicitly.
+---
+title: Add users.
+stepnum: 3
+ref: add-user
+action:
+  pre: |
+    Add the first administrative user and then add subsequent users. See
+    :doc:`/tutorial/add-user-administrator`.
+...

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

@@ -0,0 +1,19 @@
+title: Generate a key file to store authentication information.
+stepnum: 1
+ref: generate
+action:
+  pre: |
+    Use the following ``openssl`` command at the system shell to generate
+    a key file with pseudo-random content:
+  language: sh
+  code: |
+    openssl rand -base64 741
+---
+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
+    :setting:`keyFile` option.
+...

source/tutorial/enable-authentication-in-sharded-cluster.txt

@@ -7,46 +7,33 @@ Enable Authentication in a Sharded Cluster
 .. versionadded:: 2.0
    Support for authentication with sharded clusters.
 
-To control access to a sharded cluster, create key files and then set
-the :setting:`keyFile` option on *all* components of the sharded
-cluster, including all :program:`mongos` instances, all config server
-:program:`mongod` instances, and all shard :program:`mongod`
-instances. The content of the key file is arbitrary but must be the
-same on all cluster members.
-
-.. note:: For an overview of authentication, see
-   :doc:`/core/access-control`. For an overview of security, see
-   :doc:`/security`.
-
-Procedure
----------
+Overview
+--------
 
-To enable authentication, do the following:
+When authentication is enabled on a sharded cluster every client that
+accesses the cluster must provide credentials. This includes MongoDB
+instances that access each other within the cluster.
 
-1. Generate a key file to store authentication information, as described
-   in the :ref:`generate-key-file` section.
+To enable authentication on a sharded cluster, you must enable
+authentication individually on each component of the cluster. This means
+enabling authentication on each :program:`mongos` and each
+:program:`mongod`, including each config server and shard, and each member
+of a shard's replica set.
 
-#. On each component in the sharded cluster, enable authentication by
-   doing one of the following:
-
-   - In the configuration file, set the :setting:`keyFile` option to the
-     key file's path and then start the component, as in the following
-     example:
+Authentication requires an authentication mechanism and, in most cases, a
+:setting:`key file <keyFile>`. The content of the key file must be the
+same on all cluster members.
 
-     .. code-block:: cfg
+Procedure
+---------
 
-        keyFile = /srv/mongodb/keyfile
+.. include:: /includes/steps/enable-authentication-in-sharded-cluster.rst
 
-   - When starting the component, set :option:`--keyFile <mongos --keyFile>` option,
-     which is an option for both :program:`mongos` instances and
-     :program:`mongod` instances. Set the :option:`--keyFile <mongos --keyFile>`
-     to the key file's path.
+Related Documents
+-----------------
 
-   .. note::
+- :doc:`/core/authentication`
 
-      The :setting:`keyFile` setting implies :setting:`auth`, which
-      means in most cases you do not need to set :setting:`auth`
-      explicitly.
+- :doc:`/security`
 
-#. Add the first administrative user and then add subsequent users. See
-   :doc:`/tutorial/add-user-administrator`.
+- :doc:`/tutorial/configure-x509`

source/tutorial/generate-key-file.txt

@@ -6,6 +6,9 @@ Generate a Key File
 
 .. default-domain:: mongodb
 
+Overview
+--------
+
 This section describes how to generate a key file to store
 authentication information. After generating a key file, specify the key
 file using the :setting:`keyFile` option when starting a
@@ -16,24 +19,7 @@ characters in the base64 set. The key file must not have group or world
 permissions on UNIX systems. Key file permissions are not checked on
 Windows systems.
 
-Generate a Key File
--------------------
-
-Use the following ``openssl`` command at the system shell to generate
-pseudo-random content for a key file:
-
-.. code-block:: sh
-
-   openssl rand -base64 741
-
-.. note::
-
-   Key file permissions are not checked on Windows systems.
-
-Key File Properties
--------------------
-
-Be aware that MongoDB strips whitespace characters (e.g. ``x0d``,
+MongoDB strips whitespace characters (e.g. ``x0d``,
 ``x09``, and ``x20``) for cross-platform convenience. As a result,
 the following operations produce identical keys:
 
@@ -43,3 +29,8 @@ the following operations produce identical keys:
    echo -e "my secret key\n" > key2
    echo -e "my    secret    key" > key3
    echo -e "my\r\nsecret\r\nkey\r\n" > key4
+
+Procedure
+---------
+
+.. include:: /includes/steps/generate-key-file.rst