DOCS-4831 - 2.4 replset with auth

source/administration/security-deployment.txt

@@ -0,0 +1,12 @@
+=============================
+Security Deployment Tutorials
+=============================
+
+.. default-domain:: mongodb
+
+The following tutorials provide information in deploying MongoDB using
+authentication and authorization.
+
+.. include:: /includes/toc/dfn-list-security-tutorials-deployment.rst
+
+.. include:: /includes/toc/security-tutorials-deployment.rst

source/includes/considerations-deploying-replica-set.rst

@@ -0,0 +1,47 @@
+Architecture
+~~~~~~~~~~~~
+
+In a production, deploy each member of the replica set to its own machine
+and if possible bind to the standard MongoDB port of ``27017``. Use the
+:setting:`bind_ip` option to ensure that MongoDB listens for connections
+from applications on configured addresses.
+
+For a geographically distributed replica sets, ensure that the
+majority of the set's :program:`mongod` instances reside in the
+primary site.
+
+See :doc:`/core/replica-set-architectures` for more information.
+
+Connectivity
+~~~~~~~~~~~~
+
+Ensure that network traffic can pass between all members of the set
+and all clients in the network securely and efficiently. Consider the
+following:
+
+- Establish a virtual private network. Ensure that your network topology
+  routes all traffic between members within a single site over the local
+  area network.
+
+- Configure access control to prevent connections from unknown clients
+  to the replica set.
+
+- Configure networking and firewall rules so that incoming and outgoing
+  packets are permitted only on the default MongoDB port and only from
+  within your deployment.
+
+Finally ensure that each member of a replica set is accessible by
+way of resolvable DNS or hostnames. You should either configure your
+DNS names appropriately or set up your systems' ``/etc/hosts`` file to
+reflect this configuration.
+
+Configuration
+~~~~~~~~~~~~~
+
+Specify the run time configuration on each system in a :doc:`configuration
+file </reference/configuration-options>` stored in ``/etc/mongodb.conf``
+or a related location. Create the directory where MongoDB stores data
+files before deploying MongoDB.
+
+For more information about the run time options used above and other
+configuration options, see :doc:`/reference/configuration-options`.

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

@@ -0,0 +1,112 @@
+title: Start one member of the replica set.
+stepnum: 1
+ref: start-first-replica-set-member
+content: |
+  This :program:`mongod`  should *not* enable :setting:`auth`.
+---
+title: Create administrative users.
+stepnum: 2
+ref: create-administrative-users
+pre: |
+  The following operations will create two users: a user administrator
+  that will be able to create and modify users (``siteUserAdmin``),
+  and a :authrole:`root` user (``siteRootAdmin``) that you will use to
+  complete the remainder of the tutorial:
+action:
+  language: javascript
+  code: |
+    use admin
+    db.addUser( {
+        user: "siteUserAdmin",
+        pwd: "<password>",
+        roles: [ "userAdminAnyDatabase" ]
+      });
+    db.addUser( {
+        user: "siteRootAdmin",
+        pwd: "<password>",
+        roles: [ "userAdminAnyDatabase",
+                 "readWriteAnyDatabase",
+                 "dbAdminAnyDatabase",
+                 "clusterAdmin" ]
+      });
+---
+title: Stop the ``mongod`` instance.
+stepnum: 3
+ref: stop-first-replica-set-member
+---
+title: Create the key file to be used by each member of the replica set.
+stepnum: 4
+ref: generate-keyfile
+source:
+  file: steps-generate-key-file.yaml
+  ref: generate
+---
+title: Copy the key file to each member of the replica set.
+stepnum: 5
+ref: copy-key-file
+content: |
+  Copy the ``mongodb-keyfile`` to all hosts where components of a
+  MongoDB deployment run. Set the permissions of these files to
+  ``600`` so that only the *owner* of the file can read or write this
+  file to prevent other users on the system from accessing the shared
+  secret.
+---
+title: Start each member of the replica set with the appropriate options.
+stepnum: 6
+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.
+
+  .. include:: /includes/fact-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/mongodb-keyfile --replSet "rs0"
+  - pre: |
+      The following example specifies parameters through a configuration file:
+    language: javascript
+    code: |
+      mongod --config $HOME/.mongodb/config
+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 the member of the replica set where you created the administrative users."
+stepnum: 7
+ref: connect-and-auth
+pre: |
+  Connect to the replica set member you started and authenticate as
+  the ``siteRootAdmin`` user. From the :program:`mongo` shell, use the
+  following operation to authenticate:
+action:
+  language: javascript
+  code: |
+    use admin
+    db.auth("siteRootAdmin", "<password>");
+---
+stepnum: 8
+source:
+  file: steps-deploy-replica-set.yaml
+  ref: initiate-rs
+---
+stepnum: 9
+source:
+  file: steps-deploy-replica-set.yaml
+  ref: verify-rsconf
+---
+stepnum: 10
+source:
+  file: steps-deploy-replica-set.yaml
+  ref: add-remaining-members
+---
+stepnum: 11
+source:
+  file: steps-deploy-replica-set.yaml
+  ref: check-status
+...

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

@@ -0,0 +1,119 @@
+# This file ref'd in steps-convert-replica-set-shard-deploy-test-data.yaml
+# This file is tweaked to work with the other step file, as well.
+#
+title: 
+  text: Start each member of the replica set with the appropriate options.
+  character: "`"
+stepnum: 1
+ref: start-mongod
+pre: |
+  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`.
+
+  .. include:: /includes/fact-unique-replica-set-names.rst
+action:
+  - pre: |
+      The following example specifies the replica set name through the
+      :option:`--replSet` command-line option:
+    language: javascript
+    code: |
+      mongod --replSet "rs0"
+  - pre: |
+      You can also specify the :setting:`replica set name <replication>` in
+      the :doc:`configuration file </reference/configuration-options>`.
+      To start :program:`mongod` with a configuration file, specify the
+      file with the :option:`--config <mongod --config>` option:
+    language: javascript
+    code: |
+      mongod --config $HOME/.mongodb/config
+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: 
+  text: Connect a :program:`mongo` shell to a replica set member.
+  character: "`"
+stepnum: 2
+ref: open-shell
+pre: |
+  For example, to connect to a :program:`mongod` running on localhost on
+  the default port of ``27017``, simply issue:
+action:
+  language: javascript
+  code: |
+    mongo
+---
+title: 
+  text: Initiate the replica set.
+  character: "`"
+stepnum: 3
+ref: initiate-rs
+pre: |
+  Use :method:`rs.initiate()` on the replica set member:
+action:
+  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: 
+  text: Verify the initial replica set configuration.
+  character: "`"
+stepnum: 4
+ref: verify-rsconf
+action:
+  - pre: |
+      Use :method:`rs.conf()` to display the :doc:`replica set configuration
+      object </reference/replica-configuration>`:
+    language: javascript
+    code: |
+      rs.conf()
+  - pre: |
+      The replica set configuration object resembles the following:
+    language: javascript
+    code: |
+      {
+         "_id" : "rs0",
+         "version" : 1,
+         "members" : [
+            {
+               "_id" : 1,
+               "host" : "mongodb0.example.net:27017"
+            }
+         ]
+      }
+---
+title: 
+  text: Add the remaining members to the replica set.
+  character: "`"
+stepnum: 5
+ref: add-remaining-members
+pre: |
+  Add the remaining members with the :method:`rs.add()` method.
+action:
+  pre: |
+    The following example adds two members:
+  language: javascript
+  code: |
+      rs.add("mongodb1.example.net")
+      rs.add("mongodb2.example.net")
+post: |
+  When complete, you have a fully functional replica set. The new replica
+  set will elect a :term:`primary`.
+---
+title: 
+  text: Check the status of the replica set.
+  character: "`"
+stepnum: 6
+ref: check-status
+action:
+  pre: |
+    Use the :method:`rs.status()` operation:
+  language: javascript
+  code: |
+    rs.status()
+...

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

@@ -0,0 +1,29 @@
+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: |
+    To generate pseudo-random data to use for a
+    :setting:`keyfile`, issue the following ``openssl`` command:
+  language: sh
+  code: |
+    openssl rand -base64 741 > mongodb-keyfile
+    chmod 600 mongodb-keyfile
+post: |
+  You may generate a key file using any method you choose. Always
+  ensure that the password stored in the key file is both long and
+  contains a high amount of entropy. Using ``openssl`` in this manner
+  helps generate such a key.
+# the name of this file is referenced later on
+# steps-deploy-replica-set-with-auth.yaml and friends.
+---
+title: Specify the key file when starting a MongoDB instance.
+stepnum: 2
+ref: specify
+action:
+  pre: |
+    Specify the path to the key file with the :setting:`~security.keyFile` option.
+...

source/includes/toc-security-tutorials-deployment.yaml

@@ -0,0 +1,4 @@
+file: /tutorial/deploy-replica-set-with-auth
+description: |
+  Configure a replica set that has authentication enabled.
+...

source/includes/toc-security-tutorials-landing.yaml

@@ -4,6 +4,11 @@ description: |
   operating environment for MongoDB deployments, and appropriately
   limits access to MongoDB deployments.
 ---
+file: /administration/security-deployment
+description: |
+  These tutorials describe procedures for deploying MongoDB using
+  authentication and authorization.
+---
 file: /administration/security-access-control
 description: |
   MongoDB's access control system provides role-based access control

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

@@ -0,0 +1,54 @@
+=================================================================
+Deploy Replica Set and Configure Authentication and Authorization
+=================================================================
+
+.. default-domain:: mongodb
+
+Overview
+--------
+
+With :doc:`authentication </core/authentication>` enabled, MongoDB
+forces all clients to identify themselves before granting access to
+the server. :doc:`Authorization </core/authorization>`, in turn,
+allows administrators to define and limit the resources and operations
+that a user can access. Using authentication and authorization is a
+key part of a complete security strategy.
+
+All MongoDB deployments support authentication. By default, MongoDB
+does not require authorization checking. You can enforce authorization
+checking when deploying MongoDB, or on an existing deployment; however,
+you cannot enable authorization checking on a running deployment
+without downtime.
+
+This tutorial provides a procedure for creating a MongoDB :doc:`replica
+set </core/replication-introduction>` that uses the challenge-response
+authentication mechanism. The tutorial includes creation of a minimal
+authorization system to support basic operations.
+
+Considerations
+--------------
+
+Authentication
+~~~~~~~~~~~~~~
+
+In this procedure, you will configure MongoDB using the default
+challenge-response authentication mechanism, using the
+:setting:`keyFile` to supply the password for :ref:`inter-process
+authentication <replica-set-security>`. The content of the key
+file is the shared secret used for all internal authentication.
+
+All deployments that enforce authorization checking should have one
+*user administrator* user that can create new users and modify
+existing users. During this procedure you will create a user
+administrator that you will use to administer this
+deployment.
+
+.. include:: /includes/considerations-deploying-replica-set.rst
+
+Procedure
+---------
+
+This procedure deploys a replica set in which all members use the same key
+file.
+
+.. include:: /includes/steps/deploy-replica-set-with-auth.rst