From 95e6e5e8add07cba9e6ebc65ee6cb42105852107 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Thu, 6 Mar 2014 20:17:02 -0500 Subject: [PATCH] DOCS-2671 macro tutorial: deploy replica set with auth --- ...dd-user-administrator-for-replica-set.yaml | 39 +++++++++++ .../steps-deploy-replica-set-with-auth.yaml | 63 ++++++++++++++++++ source/includes/steps-deploy-replica-set.yaml | 59 +++++++++-------- source/includes/steps-generate-key-file.yaml | 13 ++-- .../includes/toc-replica-set-deployment.yaml | 4 ++ ...oc-spec-replica-set-tutorials-landing.yaml | 2 + source/tutorial.txt | 1 + .../tutorial/deploy-replica-set-with-auth.txt | 65 +++++++++++++++++++ 8 files changed, 211 insertions(+), 35 deletions(-) create mode 100644 source/includes/steps-add-user-administrator-for-replica-set.yaml create mode 100644 source/includes/steps-deploy-replica-set-with-auth.yaml create mode 100644 source/tutorial/deploy-replica-set-with-auth.txt diff --git a/source/includes/steps-add-user-administrator-for-replica-set.yaml b/source/includes/steps-add-user-administrator-for-replica-set.yaml new file mode 100644 index 00000000000..cc3e47b10a7 --- /dev/null +++ b/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" + } + ] + } + ) +... diff --git a/source/includes/steps-deploy-replica-set-with-auth.yaml b/source/includes/steps-deploy-replica-set-with-auth.yaml new file mode 100644 index 00000000000..eef9278b21d --- /dev/null +++ b/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 `. +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 +... diff --git a/source/includes/steps-deploy-replica-set.yaml b/source/includes/steps-deploy-replica-set.yaml index fb2d64df930..ffe82fb48ba 100644 --- a/source/includes/steps-deploy-replica-set.yaml +++ b/source/includes/steps-deploy-replica-set.yaml @@ -1,24 +1,22 @@ -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 @@ -26,13 +24,13 @@ 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 `, issue: + Use :method:`rs.conf()` to display the :doc:`replica set configuration + object `: 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 - `. ... diff --git a/source/includes/steps-generate-key-file.yaml b/source/includes/steps-generate-key-file.yaml index 69c9cc790d5..8b69395457b 100644 --- a/source/includes/steps-generate-key-file.yaml +++ b/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. ... diff --git a/source/includes/toc-replica-set-deployment.yaml b/source/includes/toc-replica-set-deployment.yaml index 87b5efb1e9f..111751c00cd 100644 --- a/source/includes/toc-replica-set-deployment.yaml +++ b/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 diff --git a/source/includes/toc-spec-replica-set-tutorials-landing.yaml b/source/includes/toc-spec-replica-set-tutorials-landing.yaml index 87aef77bcc7..a131e1a071e 100644 --- a/source/includes/toc-spec-replica-set-tutorials-landing.yaml +++ b/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 diff --git a/source/tutorial.txt b/source/tutorial.txt index 8596751c80d..c7ad6148703 100644 --- a/source/tutorial.txt +++ b/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` diff --git a/source/tutorial/deploy-replica-set-with-auth.txt b/source/tutorial/deploy-replica-set-with-auth.txt new file mode 100644 index 00000000000..1d88cf23cdd --- /dev/null +++ b/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 ` uses +:doc:`authentication ` and :doc:`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 `. + +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`.