From 6a3104c62f7a10e4585dd325cd1bfcfe80f3f3ea Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Wed, 12 Mar 2014 13:22:57 -0400 Subject: [PATCH 01/11] DOCS-2671: new tutorial: deploy replica set and configure authentication and authorization Signed-off-by: Sam Kleinman --- source/includes/access-create-user.rst | 4 + .../considerations-deploying-replica-set.rst | 34 +++++ ...fact-prod-rs-deployment-considerations.rst | 74 ----------- source/includes/steps-add-admin-user.yaml | 6 +- .../steps-add-user-administrator.yaml | 6 +- .../includes/steps-add-user-to-database.yaml | 6 +- .../includes/steps-change-user-password.yaml | 6 +- .../steps-change-user-privileges.yaml | 36 +----- .../steps-connect-with-admin-privileges.yaml | 36 ++++++ source/includes/steps-define-roles.yaml | 6 +- .../steps-deploy-replica-set-with-auth.yaml | 116 ++++++++++++++++++ source/includes/steps-deploy-replica-set.yaml | 55 ++++----- 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 + source/tutorial/add-admin-user.txt | 10 -- source/tutorial/add-user-administrator.txt | 20 ++- source/tutorial/add-user-to-database.txt | 3 - ...geographically-distributed-replica-set.txt | 2 +- .../tutorial/deploy-replica-set-with-auth.txt | 44 +++++++ source/tutorial/deploy-replica-set.txt | 18 ++- 22 files changed, 312 insertions(+), 190 deletions(-) create mode 100644 source/includes/considerations-deploying-replica-set.rst delete mode 100644 source/includes/fact-prod-rs-deployment-considerations.rst create mode 100644 source/includes/steps-connect-with-admin-privileges.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/access-create-user.rst b/source/includes/access-create-user.rst index 7a6e8e9bcb9..9fe265edf68 100644 --- a/source/includes/access-create-user.rst +++ b/source/includes/access-create-user.rst @@ -5,3 +5,7 @@ database. You must have the :authaction:`grantRole` :ref:`action ` on a role's database to grant the role to another user. + +If you have the :authrole:`userAdmin` or :authrole:`userAdminAnyDatabase` +role, or if you are authenticated using the :ref:`localhost exception +`, you have those actions. diff --git a/source/includes/considerations-deploying-replica-set.rst b/source/includes/considerations-deploying-replica-set.rst new file mode 100644 index 00000000000..e3ba2074f15 --- /dev/null +++ b/source/includes/considerations-deploying-replica-set.rst @@ -0,0 +1,34 @@ +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 listen for connections +from applications on the configured address. + +Each member of a replica set must be 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. + +For a geographically distributed replica set, ensure that one system +resides in each secondary site, while the remaining systems are in the +primary site. + +Ensure that network traffic can pass between all members 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 authentication so that only servers and processes with + authentication can connect 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. + +Specify the run time configuration on each system in a :doc:`configuration +file ` 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`. diff --git a/source/includes/fact-prod-rs-deployment-considerations.rst b/source/includes/fact-prod-rs-deployment-considerations.rst deleted file mode 100644 index 4f983cac845..00000000000 --- a/source/includes/fact-prod-rs-deployment-considerations.rst +++ /dev/null @@ -1,74 +0,0 @@ -.. begin-nondist-dns - -- Each member of the replica set resides on its own machine and all of - the MongoDB processes bind to port ``27017`` (the - standard MongoDB port). - -- Each member of the replica set must be accessible by way of - resolvable DNS or hostnames, as in the following scheme: - - - ``mongodb0.example.net`` - - ``mongodb1.example.net`` - - ``mongodb2.example.net`` - - ``mongodbn.example.net`` - - You will need to *either* configure your DNS names appropriately, - *or* set up your systems' ``/etc/hosts`` file to reflect this configuration. - -.. end-nondist-dns - - For a geographically distributed replica set, you should ensure that - one system (e.g. ``mongodb2.example.net``) resides in each secondary - site (e.g. Site B), while the remaining systems are in Site A. - -.. begin-nondist-routing - -- Ensure that network traffic can pass between all members 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 authentication using :setting:`auth` and - :setting:`keyFile`, so that only servers and processes with - authentication can connect to the replica set. - - - Configure networking and firewall rules so that only traffic - (incoming and outgoing packets) on the default MongoDB port (e.g. - ``27017``) from *within* your deployment is permitted. - -- You must specify the run time configuration on each system in a - :doc:`configuration file ` stored - in ``/etc/mongodb.conf`` or a related location. *Do not* specify the - set's configuration in the :program:`mongo` shell. - - Use the following configuration for each of your MongoDB instances. - You should set values that are appropriate for your systems, as needed: - - .. code-block:: cfg - - port = 27017 - - bind_ip = 10.8.0.10 - - dbpath = /srv/mongodb/ - - fork = true - - replSet = rs0 - - The :setting:`dbpath` indicates where you want :program:`mongod` to - store data files. The :setting:`dbpath` must exist before you start - :program:`mongod`. If it does not exist, create the directory and - ensure :program:`mongod` has permission to read and write data to this - path. - - Modifying :setting:`bind_ip` ensures that :program:`mongod` will only - listen for connections from applications on the configured address. - - For more information about the run time options used above and other - configuration options, see - :doc:`/reference/configuration-options`. - -.. end-nondist-routing diff --git a/source/includes/steps-add-admin-user.yaml b/source/includes/steps-add-admin-user.yaml index 125fbedb751..e59e637f44e 100644 --- a/source/includes/steps-add-admin-user.yaml +++ b/source/includes/steps-add-admin-user.yaml @@ -1,14 +1,14 @@ stepnum: 1 source: - file: steps-change-user-privileges.yaml - ref: connect-with-appropriate-privileges + file: steps-connect-with-admin-privileges.yaml + ref: connect pre: | Connect to the :program:`mongod` or :program:`mongos` as a user with the privileges required in the :ref:`add-admin-prereq` section. --- stepnum: 2 source: - file: steps-change-user-privileges.yaml + file: steps-connect-with-admin-privileges.yaml ref: verify-privileges --- title: Create the administrative user. diff --git a/source/includes/steps-add-user-administrator.yaml b/source/includes/steps-add-user-administrator.yaml index fd7b5c8d114..dda4548a229 100644 --- a/source/includes/steps-add-user-administrator.yaml +++ b/source/includes/steps-add-user-administrator.yaml @@ -1,14 +1,14 @@ stepnum: 1 source: - file: steps-change-user-privileges.yaml - ref: connect-with-appropriate-privileges + file: steps-connect-with-admin-privileges.yaml + ref: connect pre: | Connect to the :program:`mongod` or :program:`mongos` as a user with the privileges required in the :ref:`add-user-admin-prereq` section. --- stepnum: 2 source: - file: steps-change-user-privileges.yaml + file: steps-connect-with-admin-privileges.yaml ref: verify-privileges --- title: Create the user administrator. diff --git a/source/includes/steps-add-user-to-database.yaml b/source/includes/steps-add-user-to-database.yaml index 85afcaf2ac4..71475cf4ab2 100644 --- a/source/includes/steps-add-user-to-database.yaml +++ b/source/includes/steps-add-user-to-database.yaml @@ -1,14 +1,14 @@ stepnum: 1 source: - file: steps-change-user-privileges.yaml - ref: connect-with-appropriate-privileges + file: steps-connect-with-admin-privileges.yaml + ref: connect pre: | Connect to the :program:`mongod` or :program:`mongos` with the privileges required in the :ref:`add-user-prereq` section. --- stepnum: 2 source: - file: steps-change-user-privileges.yaml + file: steps-connect-with-admin-privileges.yaml ref: verify-privileges --- title: Create the new user. diff --git a/source/includes/steps-change-user-password.yaml b/source/includes/steps-change-user-password.yaml index b6d7a1843bb..a60f86d3b47 100644 --- a/source/includes/steps-change-user-password.yaml +++ b/source/includes/steps-change-user-password.yaml @@ -1,14 +1,14 @@ stepnum: 1 source: - file: steps-change-user-privileges.yaml - ref: connect-with-appropriate-privileges + file: steps-connect-with-admin-privileges.yaml + ref: connect pre: | Connect to the :program:`mongod` or :program:`mongos` with the privileges required in the :ref:`change-password-prereq` section. --- stepnum: 2 source: - file: steps-change-user-privileges.yaml + file: steps-connect-with-admin-privileges.yaml ref: verify-privileges --- title: Change the password. diff --git a/source/includes/steps-change-user-privileges.yaml b/source/includes/steps-change-user-privileges.yaml index 7a1bf4535f9..28e51b7eff1 100644 --- a/source/includes/steps-change-user-privileges.yaml +++ b/source/includes/steps-change-user-privileges.yaml @@ -1,36 +1,12 @@ -title: Connect to MongoDB with the appropriate privileges. stepnum: 1 -ref: connect-with-appropriate-privileges -pre: | - Connect to the :program:`mongod` or :program:`mongos` either through the - :ref:`localhost exception ` or as a user with the - privileges required in the :ref:`change-user-privileges-prereq` section. -action: - pre: | - The following example operation connects to MongoDB as an authenticated - user named ``manager``: - language: javascript - code: | - mongo --port 27017 -u manager -p 12345678 --authenticationDatabase admin +source: + file: steps-connect-with-admin-privileges.yaml + ref: connect --- -title: Verify your privileges. stepnum: 2 -ref: verify-privileges -pre: | - Use the :dbcommand:`usersInfo` command with the ``showPrivileges`` option. -action: - pre: | - The following example operation checks privileges for a user connected as ``manager``: - language: javascript - code: | - db.runCommand( - { - usersInfo:"manager", - showPrivileges:true - } - ) -post: | - The resulting ``users`` document displays the privileges granted to ``manager``. +source: + file: steps-connect-with-admin-privileges.yaml + ref: verify-privileges --- title: Identify the user's roles and privileges. stepnum: 3 diff --git a/source/includes/steps-connect-with-admin-privileges.yaml b/source/includes/steps-connect-with-admin-privileges.yaml new file mode 100644 index 00000000000..bdf569d7140 --- /dev/null +++ b/source/includes/steps-connect-with-admin-privileges.yaml @@ -0,0 +1,36 @@ +# These two steps are borrowed by other tutorials but do *not* have a home tutorial. +# +title: Connect to MongoDB with the appropriate privileges. +stepnum: 1 +ref: connect +pre: | + Connect to the :program:`mongod` or :program:`mongos` either through the + :ref:`localhost exception ` or as a user with the + privileges required in the :ref:`change-user-privileges-prereq` section. +action: + pre: | + The following example operation connects to MongoDB as an authenticated + user named ``manager``: + language: javascript + code: | + mongo --port 27017 -u manager -p 12345678 --authenticationDatabase admin +--- +title: Verify your privileges. +stepnum: 2 +ref: verify-privileges +pre: | + Use the :dbcommand:`usersInfo` command with the ``showPrivileges`` option. +action: + pre: | + The following example operation checks privileges for a user connected as ``manager``: + language: javascript + code: | + db.runCommand( + { + usersInfo:"manager", + showPrivileges:true + } + ) +post: | + The resulting ``users`` document displays the privileges granted to ``manager``. +... diff --git a/source/includes/steps-define-roles.yaml b/source/includes/steps-define-roles.yaml index 9fbf2ec8eda..981b6552d7c 100644 --- a/source/includes/steps-define-roles.yaml +++ b/source/includes/steps-define-roles.yaml @@ -1,14 +1,14 @@ stepnum: 1 source: - file: steps-change-user-privileges.yaml - ref: connect-with-appropriate-privileges + file: steps-connect-with-admin-privileges.yaml + ref: connect pre: | Connect to the :program:`mongod` or :program:`mongos` with the privileges required in the :ref:`define-roles-prereq` section. --- stepnum: 2 source: - file: steps-change-user-privileges.yaml + file: steps-connect-with-admin-privileges.yaml ref: verify-privileges --- title: Define the privileges to grant to the role. 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..4b1360b2816 --- /dev/null +++ b/source/includes/steps-deploy-replica-set-with-auth.yaml @@ -0,0 +1,116 @@ +title: Create the key file to be used by each member of the replica set. +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. +action: + - pre: | + .. include:: /includes/important-unique-replica-set-names.rst + - 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 $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 one of the replica set members. +stepnum: 4 +pre: | + 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: verify-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 +--- +title: Connect to MongoDB with the privileges needed to create a user administrator. +stepnum: 9 +source: + file: steps-connect-with-admin-privileges.yaml + ref: connect +pre: | + Connect to the replica set :term:`primary`. +--- +stepnum: 10 +source: + file: steps-connect-with-admin-privileges.yaml + ref: verify-privileges +--- +stepnum: 11 +source: + file: steps-add-user-administrator.yaml + ref: create-user-admin +--- +title: Create additional users to meet your operational needs. +stepnum: 12 +ref: create-additional-users +pre: | + You can use :doc:`built-in roles ` to create + common types of database users, such as the :authrole:`dbAdmin` role to + create a database administrator, the :authrole:`readWrite` role to + create a user who can update data, or the :authrole:`read` role to + create user who can search data but no more. `. You + also can define :ref:`custom roles `. +action: + pre: | + For example, the following creates a database administrator for the + ``products`` database: + language: javascript + code: | + db.createUser( + { + user: "productsDBAdmin", + pwd: "password", + roles: + [ + { + role: "dbAdmin", + db: "products" + } + ] + } + ) +post: | + For an overview of roles and privileges, see :ref:`authorization`. For + more information on adding users, see + :doc:`/tutorial/add-user-to-database`. +... diff --git a/source/includes/steps-deploy-replica-set.yaml b/source/includes/steps-deploy-replica-set.yaml index fb2d64df930..b78c021c09b 100644 --- a/source/includes/steps-deploy-replica-set.yaml +++ b/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. 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 + 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: 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() @@ -75,18 +76,18 @@ action: 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 +98,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..4e16c9f5f4e 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: + To generate generate pseudo-random to use for a keyfile, use the + ``openssl`` command: 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. + 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 aaea474498e..d838c1154de 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/add-admin-user.txt b/source/tutorial/add-admin-user.txt index eaca8e6b39e..5f9c91ae4ca 100644 --- a/source/tutorial/add-admin-user.txt +++ b/source/tutorial/add-admin-user.txt @@ -38,16 +38,6 @@ Prerequisites .. include:: /includes/access-create-user.rst -The :authrole:`userAdmin` and :authrole:`userAdminAnyDatabase` roles -both grant the actions. - -A user that authenticated using the :ref:`localhost exception -` also has those actions on the ``admin`` database. The -localhost exception is available if there are no users on the ``admin`` database -and if a user connects to the :program:`mongod` or :program:`mongos` from a -client over the ``localhost`` interface. For more information, see -:ref:`localhost-exception`. - Procedure --------- diff --git a/source/tutorial/add-user-administrator.txt b/source/tutorial/add-user-administrator.txt index 317c43d4823..f66df12f540 100644 --- a/source/tutorial/add-user-administrator.txt +++ b/source/tutorial/add-user-administrator.txt @@ -33,22 +33,18 @@ Prerequisites .. include:: /includes/access-create-user.rst -A user with either the :authrole:`userAdmin` or -:authrole:`userAdminAnyDatabase` role, or authenticated using the -:ref:`localhost exception `, has those privileges. - Procedure --------- .. include:: /includes/steps/add-user-administrator.rst -Additional Information ----------------------- +Related Documents +----------------- + +- :doc:`/core/authentication` + +- :doc:`/core/security-introduction` -See the :doc:`/core/authentication` and -:doc:`/core/security-introduction` documents as well as the -:ref:`localhost-exception` section for more background information. +- :doc:`/tutorial/enable-authentication` -As you configure authentication you may also want to consider the -:doc:`/tutorial/enable-authentication` tutorial and the other -:doc:`/administration/security-access-control` tutorials. +- :doc:`/administration/security-access-control` diff --git a/source/tutorial/add-user-to-database.txt b/source/tutorial/add-user-to-database.txt index 122a9bf9183..ab54dd1a02b 100644 --- a/source/tutorial/add-user-to-database.txt +++ b/source/tutorial/add-user-to-database.txt @@ -59,9 +59,6 @@ user administrator, do so as described in .. include:: /includes/access-create-user.rst -The :authrole:`userAdmin` and :authrole:`userAdminAnyDatabase` roles both -provide those actions. - Procedures ---------- diff --git a/source/tutorial/deploy-geographically-distributed-replica-set.txt b/source/tutorial/deploy-geographically-distributed-replica-set.txt index 571d8be992f..29f52c97b1e 100644 --- a/source/tutorial/deploy-geographically-distributed-replica-set.txt +++ b/source/tutorial/deploy-geographically-distributed-replica-set.txt @@ -73,7 +73,7 @@ Procedures General Considerations ~~~~~~~~~~~~~~~~~~~~~~ -.. include:: /includes/fact-prod-rs-deployment-considerations.rst +.. include:: /includes/considerations-deploying-replica-set.rst .. _replica-set-deploy-distributed-three-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..a8d7388b719 --- /dev/null +++ b/source/tutorial/deploy-replica-set-with-auth.txt @@ -0,0 +1,44 @@ +================================================================= +Deploy Replica Set and Configure Authentication and Authorization +================================================================= + +.. default-domain:: mongodb + +Overview +-------- + +With authentication enabled, MongoDB will force all clients to +identify themselves before granting access to the +server. 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 runs +without authentication enabled. You can enable it at anytime, both during +initial deployment or after a system has been deployed. + +This tutorial provides a procedure for creating a MongoDB :doc:`replica +set ` that uses the challenge-and-response +authentication mechanism. The tutorial includes creation of a minimal +authorization system to support basic operations. + +Considerations +-------------- + +Authentication requires an authentication mechanism and in many cases a +:setting:`key file `. + +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/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 diff --git a/source/tutorial/deploy-replica-set.txt b/source/tutorial/deploy-replica-set.txt index 39649e06e43..acbba40641c 100644 --- a/source/tutorial/deploy-replica-set.txt +++ b/source/tutorial/deploy-replica-set.txt @@ -26,18 +26,14 @@ a successful replica set deployment, every member must be able to connect to every other member. For instructions on how to check your connection, see :ref:`replica-set-troubleshooting-check-connection`. -Procedure ---------- +.. _considerations-when-deploying-rs: + +Considerations When Deploying a Replica Set +------------------------------------------- -.. include:: /includes/fact-prod-rs-deployment-considerations.rst - :start-after: begin-nondist-dns - :end-before: end-nondist-dns - -.. include:: /includes/fact-prod-rs-deployment-considerations.rst - :start-after: begin-nondist-routing - :end-before: end-nondist-routing +.. include:: /includes/considerations-deploying-replica-set.rst -To deploy a production replica set: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Procedure +--------- .. include:: /includes/steps/deploy-replica-set.rst From b8258ea82f398495e591527576b2f89d67df480c Mon Sep 17 00:00:00 2001 From: Sam Kleinman Date: Fri, 21 Mar 2014 11:46:00 -0400 Subject: [PATCH 02/11] DOCS-2671: edits and structure for replica set tutorial --- .../administration/replica-set-deployment.txt | 3 ++ source/administration/security-deployment.txt | 12 ++++++++ source/core/replica-set-architectures.txt | 7 +++-- .../considerations-deploying-replica-set.rst | 20 ++++++++++--- .../fact-unique-replica-set-names.rst | 3 ++ .../important-unique-replica-set-names.rst | 5 ---- source/includes/options-mongod.yaml | 2 +- ...cally-distributed-replica-set-3member.yaml | 2 +- ...cally-distributed-replica-set-4member.yaml | 2 +- .../steps-deploy-replica-set-with-auth.yaml | 4 +-- source/includes/steps-deploy-replica-set.yaml | 4 +-- .../includes/toc-replica-set-deployment.yaml | 4 --- .../toc-security-tutorials-deployment.yaml | 4 +++ .../toc-security-tutorials-landing.yaml | 5 ++++ ...oc-spec-replica-set-tutorials-landing.yaml | 2 -- .../toc-spec-security-tutorials-landing.yaml | 2 ++ .../convert-standalone-to-replica-set.txt | 2 +- .../deploy-replica-set-for-testing.txt | 28 +++++++++++-------- .../tutorial/deploy-replica-set-with-auth.txt | 18 +++++++----- 19 files changed, 86 insertions(+), 43 deletions(-) create mode 100644 source/administration/security-deployment.txt create mode 100644 source/includes/fact-unique-replica-set-names.rst delete mode 100644 source/includes/important-unique-replica-set-names.rst create mode 100644 source/includes/toc-security-tutorials-deployment.yaml diff --git a/source/administration/replica-set-deployment.txt b/source/administration/replica-set-deployment.txt index 659ed9ee356..0a25752f911 100644 --- a/source/administration/replica-set-deployment.txt +++ b/source/administration/replica-set-deployment.txt @@ -6,6 +6,9 @@ Replica Set Deployment Tutorials The following tutorials provide information in deploying replica sets. +.. seealso:: :doc:`/administration/security-deployment` for additional + related tutorials. + .. include:: /includes/toc/dfn-list-replica-set-deployment.rst .. include:: /includes/toc/replica-set-deployment.rst diff --git a/source/administration/security-deployment.txt b/source/administration/security-deployment.txt new file mode 100644 index 00000000000..e29fc5be80e --- /dev/null +++ b/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-deployment.rst + +.. include:: /includes/toc/security-deployment.rst diff --git a/source/core/replica-set-architectures.txt b/source/core/replica-set-architectures.txt index 04b07077c62..25d10678f3f 100644 --- a/source/core/replica-set-architectures.txt +++ b/source/core/replica-set-architectures.txt @@ -16,8 +16,6 @@ three-member replica set. These sets provide redundancy and fault tolerance. Avoid complexity when possible, but let your application requirements dictate the architecture. -.. include:: /includes/important-unique-replica-set-names.rst - Strategies ---------- @@ -155,6 +153,11 @@ shutdowns, including power failures and unexpected reboots. All 64-bit versions of MongoDB after version 2.0 have journaling enabled by default. +Replica Set Naming +------------------ + +.. include:: /includes/fact-unique-replica-set-names.rst + Deployment Patterns ------------------- diff --git a/source/includes/considerations-deploying-replica-set.rst b/source/includes/considerations-deploying-replica-set.rst index e3ba2074f15..d9c3cdf87df 100644 --- a/source/includes/considerations-deploying-replica-set.rst +++ b/source/includes/considerations-deploying-replica-set.rst @@ -1,16 +1,20 @@ +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 listen for connections from applications on the configured address. -Each member of a replica set must be 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. - For a geographically distributed replica set, ensure that one system resides in each secondary site, while the remaining systems are in the primary site. +See :doc:`/core/replica-set-architectures` for more information. + +Connectivity +~~~~~~~~~~~~ + Ensure that network traffic can pass between all members in the network securely and efficiently. Consider the following: @@ -25,6 +29,14 @@ securely and efficiently. Consider the following: 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 ` stored in ``/etc/mongodb.conf`` or a related location. Create the directory where MongoDB stores data diff --git a/source/includes/fact-unique-replica-set-names.rst b/source/includes/fact-unique-replica-set-names.rst new file mode 100644 index 00000000000..cf2b682a1c4 --- /dev/null +++ b/source/includes/fact-unique-replica-set-names.rst @@ -0,0 +1,3 @@ +If your application connects to more than one replica set, each set +should have a distinct name. Some drivers group replica set +connections by replica set name. diff --git a/source/includes/important-unique-replica-set-names.rst b/source/includes/important-unique-replica-set-names.rst deleted file mode 100644 index 51eb5763a0b..00000000000 --- a/source/includes/important-unique-replica-set-names.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. important:: - - If your application connects to more than one replica set, each set - should have a distinct name. Some drivers group replica set - connections by replica set name. diff --git a/source/includes/options-mongod.yaml b/source/includes/options-mongod.yaml index 7334c2706fd..0479d2b411b 100644 --- a/source/includes/options-mongod.yaml +++ b/source/includes/options-mongod.yaml @@ -746,7 +746,7 @@ description: | Configures replication. Specify a replica set name as an argument to this set. All hosts in the replica set must have the same set name. - .. include:: /includes/important-unique-replica-set-names.rst + .. include:: /includes/fact-unique-replica-set-names.rst optional: true --- program: mongod diff --git a/source/includes/steps-deploy-geographically-distributed-replica-set-3member.yaml b/source/includes/steps-deploy-geographically-distributed-replica-set-3member.yaml index 43c2d649fe4..6ebf7d5d3bb 100644 --- a/source/includes/steps-deploy-geographically-distributed-replica-set-3member.yaml +++ b/source/includes/steps-deploy-geographically-distributed-replica-set-3member.yaml @@ -16,7 +16,7 @@ source: stepnum: 4 source: file: steps-deploy-replica-set.yaml - ref: display-rsconf + ref: verify-rsconf --- stepnum: 5 source: diff --git a/source/includes/steps-deploy-geographically-distributed-replica-set-4member.yaml b/source/includes/steps-deploy-geographically-distributed-replica-set-4member.yaml index d41b5fde9db..ab93cb188dc 100644 --- a/source/includes/steps-deploy-geographically-distributed-replica-set-4member.yaml +++ b/source/includes/steps-deploy-geographically-distributed-replica-set-4member.yaml @@ -16,7 +16,7 @@ source: stepnum: 4 source: file: steps-deploy-replica-set.yaml - ref: display-rsconf + ref: verify-rsconf --- title: Add the remaining members to the replica set. stepnum: 5 diff --git a/source/includes/steps-deploy-replica-set-with-auth.yaml b/source/includes/steps-deploy-replica-set-with-auth.yaml index 4b1360b2816..bd874ceb94f 100644 --- a/source/includes/steps-deploy-replica-set-with-auth.yaml +++ b/source/includes/steps-deploy-replica-set-with-auth.yaml @@ -16,9 +16,9 @@ pre: | 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: | - .. include:: /includes/important-unique-replica-set-names.rst - pre: | The following example specifies parameters through the :option:`--keyFile` and :option:`--replSet` command-line options: diff --git a/source/includes/steps-deploy-replica-set.yaml b/source/includes/steps-deploy-replica-set.yaml index b78c021c09b..629567c476b 100644 --- a/source/includes/steps-deploy-replica-set.yaml +++ b/source/includes/steps-deploy-replica-set.yaml @@ -6,9 +6,9 @@ pre: | 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. + + .. include:: /includes/fact-unique-replica-set-names.rst action: - - pre: | - .. include:: /includes/important-unique-replica-set-names.rst - pre: | The following example specifies the replica set name through the :option:`--replSet` command-line option: diff --git a/source/includes/toc-replica-set-deployment.yaml b/source/includes/toc-replica-set-deployment.yaml index 111751c00cd..87b5efb1e9f 100644 --- a/source/includes/toc-replica-set-deployment.yaml +++ b/source/includes/toc-replica-set-deployment.yaml @@ -3,10 +3,6 @@ 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-security-tutorials-deployment.yaml b/source/includes/toc-security-tutorials-deployment.yaml new file mode 100644 index 00000000000..e4ffca3fb7f --- /dev/null +++ b/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. +... diff --git a/source/includes/toc-security-tutorials-landing.yaml b/source/includes/toc-security-tutorials-landing.yaml index 065e995e0cb..90aa3fb4f4f 100644 --- a/source/includes/toc-security-tutorials-landing.yaml +++ b/source/includes/toc-security-tutorials-landing.yaml @@ -11,6 +11,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: | These tutorials describe procedures relevant for the configuration, diff --git a/source/includes/toc-spec-replica-set-tutorials-landing.yaml b/source/includes/toc-spec-replica-set-tutorials-landing.yaml index a131e1a071e..87aef77bcc7 100644 --- a/source/includes/toc-spec-replica-set-tutorials-landing.yaml +++ b/source/includes/toc-spec-replica-set-tutorials-landing.yaml @@ -8,8 +8,6 @@ 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/includes/toc-spec-security-tutorials-landing.yaml b/source/includes/toc-spec-security-tutorials-landing.yaml index 5d5636fff88..4f484382647 100644 --- a/source/includes/toc-spec-security-tutorials-landing.yaml +++ b/source/includes/toc-spec-security-tutorials-landing.yaml @@ -17,6 +17,8 @@ files: - text: "Continue reading from :doc:`/administration/security-network` for more information on running MongoDB in secure environments." level: 2 + - file: /administration/security-deployment + level: 1 - file: /administration/security-access-control level: 1 diff --git a/source/tutorial/convert-standalone-to-replica-set.txt b/source/tutorial/convert-standalone-to-replica-set.txt index 88076c7a94e..6cdb7b8c263 100644 --- a/source/tutorial/convert-standalone-to-replica-set.txt +++ b/source/tutorial/convert-standalone-to-replica-set.txt @@ -30,7 +30,7 @@ Procedure mongod --port 27017 --dbpath /srv/mongodb/db0 --replSet rs0 - .. include:: /includes/important-unique-replica-set-names.rst + .. include:: /includes/fact-unique-replica-set-names.rst For more information on configuration options, see :doc:`/reference/configuration-options` and the :program:`mongod` diff --git a/source/tutorial/deploy-replica-set-for-testing.txt b/source/tutorial/deploy-replica-set-for-testing.txt index f62ff1c148e..5b8f0700cf5 100644 --- a/source/tutorial/deploy-replica-set-for-testing.txt +++ b/source/tutorial/deploy-replica-set-for-testing.txt @@ -4,10 +4,9 @@ Deploy a Replica Set for Testing and Development .. default-domain:: mongodb -.. note:: This tutorial provides instructions for deploying a replica - set in a development or test environment. For a production - deployment, refer to the :doc:`/tutorial/deploy-replica-set` - tutorial. +This procedure describes deploying a replica set in a development or +test environment. For a production deployment, refer to the +:doc:`/tutorial/deploy-replica-set` tutorial. .. include:: /includes/introduction-deploy-replica-set.rst @@ -27,19 +26,26 @@ a successful replica set deployment, every member must be able to connect to every other member. For instructions on how to check your connection, see :ref:`replica-set-troubleshooting-check-connection`. -Procedure ---------- +Considerations +-------------- + +Replica Set Naming +~~~~~~~~~~~~~~~~~~ .. important:: These instructions should only be used for test or development deployments. The examples in this procedure create a new replica set named ``rs0``. - .. include:: /includes/important-unique-replica-set-names.rst +.. include:: /includes/fact-unique-replica-set-names.rst You will begin by starting three :program:`mongod` instances as members of a replica set named ``rs0``. + +Procedure +--------- + 1. Create the necessary data directories for each member by issuing a command similar to the following: @@ -54,19 +60,19 @@ members of a replica set named ``rs0``. commands: First member: - + .. code-block:: sh mongod --port 27017 --dbpath /srv/mongodb/rs0-0 --replSet rs0 --smallfiles --oplogSize 128 Second member: - + .. code-block:: sh mongod --port 27018 --dbpath /srv/mongodb/rs0-1 --replSet rs0 --smallfiles --oplogSize 128 Third member: - + .. code-block:: sh mongod --port 27019 --dbpath /srv/mongodb/rs0-2 --replSet rs0 --smallfiles --oplogSize 128 @@ -112,7 +118,7 @@ members of a replica set named ``rs0``. replacing ```` with your system's hostname, and then pass the ``rsconf`` file to :method:`rs.initiate()` as follows: - + .. code-block:: javascript rs.initiate( rsconf ) diff --git a/source/tutorial/deploy-replica-set-with-auth.txt b/source/tutorial/deploy-replica-set-with-auth.txt index a8d7388b719..2b2e2da58e8 100644 --- a/source/tutorial/deploy-replica-set-with-auth.txt +++ b/source/tutorial/deploy-replica-set-with-auth.txt @@ -7,12 +7,12 @@ Deploy Replica Set and Configure Authentication and Authorization Overview -------- -With authentication enabled, MongoDB will force all clients to -identify themselves before granting access to the -server. 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. +With :doc:`authentication ` enabled, MongoDB +forces all clients to identify themselves before granting access to +the server. :doc:`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 runs without authentication enabled. You can enable it at anytime, both during @@ -26,12 +26,16 @@ authorization system to support basic operations. Considerations -------------- +Authentication +~~~~~~~~~~~~~~ + Authentication requires an authentication mechanism and in many cases a :setting:`key file `. 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. +deployment. In the source of this procedure, you will create one user +with this role. .. include:: /includes/considerations-deploying-replica-set.rst From aa1328a394eb02117b1da4d1e4f2bf0f058318fc Mon Sep 17 00:00:00 2001 From: Sam Kleinman Date: Fri, 21 Mar 2014 12:00:39 -0400 Subject: [PATCH 03/11] DOCS-2671: redirect and edit --- config/htaccess-next.yaml | 16 ++++++++++++++++ source/administration/security-deployment.txt | 6 +++--- 2 files changed, 19 insertions(+), 3 deletions(-) diff --git a/config/htaccess-next.yaml b/config/htaccess-next.yaml index cbfb056424e..2d83f3bc417 100644 --- a/config/htaccess-next.yaml +++ b/config/htaccess-next.yaml @@ -1263,6 +1263,22 @@ redirect-path: '/tutorial/perform-maintence-on-replica-set-members' url-base: '/administration/replica-set-maintenance' type: 'redirect' code: 303 +outputs: + - 'manual' + - 'before-v2.4' +--- +redirect-path: '/administration/security-deployment' +url-base: '/' +type: 'redirect' +code: 303 +outputs: + - 'manual' + - 'before-v2.4' +--- +redirect-path: '/tutorial/deploy-replica-set-with-auth' +url-base: '/tutorial/deploy-replica-set' +type: 'redirect' +code: 303 outputs: - 'manual' - 'before-v2.4' diff --git a/source/administration/security-deployment.txt b/source/administration/security-deployment.txt index e29fc5be80e..8b83000c671 100644 --- a/source/administration/security-deployment.txt +++ b/source/administration/security-deployment.txt @@ -5,8 +5,8 @@ Security Deployment Tutorials .. default-domain:: mongodb The following tutorials provide information in deploying MongoDB using -authentication and authorization.. +authentication and authorization. -.. include:: /includes/toc/dfn-list-security-deployment.rst +.. include:: /includes/toc/dfn-list-security-tutorials-deployment.rst -.. include:: /includes/toc/security-deployment.rst +.. include:: /includes/toc/security-tutorials-deployment.rst From c7fd8944dd5dff7749e87cd630210651a430cb15 Mon Sep 17 00:00:00 2001 From: Sam Kleinman Date: Tue, 25 Mar 2014 12:43:31 -0400 Subject: [PATCH 04/11] DOCS-2671: edits to deploy replica set with auth document in response to spencer's feedback --- .../considerations-deploying-replica-set.rst | 15 ++++---- .../steps-add-user-administrator.yaml | 35 ++++++++++++++++--- ...eate-admin-then-enable-authentication.yaml | 2 +- .../steps-deploy-replica-set-with-auth.yaml | 27 ++++---------- .../includes/steps-enable-authentication.yaml | 2 +- source/includes/steps-generate-key-file.yaml | 4 +-- .../tutorial/deploy-replica-set-with-auth.txt | 24 +++++++------ 7 files changed, 64 insertions(+), 45 deletions(-) diff --git a/source/includes/considerations-deploying-replica-set.rst b/source/includes/considerations-deploying-replica-set.rst index d9c3cdf87df..695e7d16173 100644 --- a/source/includes/considerations-deploying-replica-set.rst +++ b/source/includes/considerations-deploying-replica-set.rst @@ -3,27 +3,28 @@ 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 listen for connections +:setting:`bind_ip` option to ensure that MongoDB listens for connections from applications on the configured address. For a geographically distributed replica set, ensure that one system -resides in each secondary site, while the remaining systems are in the -primary site. +resides in each secondary site, while the remaining :program:`mongod` +instances are in the primary site. See :doc:`/core/replica-set-architectures` for more information. Connectivity ~~~~~~~~~~~~ -Ensure that network traffic can pass between all members in the network -securely and efficiently. Consider the following: +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 authentication so that only servers and processes with - authentication can connect to the replica set. +- Configure authentication 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 diff --git a/source/includes/steps-add-user-administrator.yaml b/source/includes/steps-add-user-administrator.yaml index dda4548a229..52f828c9ca9 100644 --- a/source/includes/steps-add-user-administrator.yaml +++ b/source/includes/steps-add-user-administrator.yaml @@ -11,12 +11,39 @@ source: file: steps-connect-with-admin-privileges.yaml ref: verify-privileges --- -title: Create the user administrator. +title: Create the system user administrator. stepnum: 3 -ref: create-user-admin +ref: create-site-user-admin pre: | - Add the user and assign the :authrole:`userAdmin` role or - :authrole:`userAdminAnyDatabase` role, and only that role. + Add the user with the :authrole:`userAdminAnyDatabase` role, and + only that role. +action: + pre: | + The following example creates the user ``siteUserAdmin`` user on the + ``admin`` database: + language: javascript + code: | + db.createUser( + { + user: "siteUserAdmin", + pwd: "password", + roles: + [ + { + role: "userAdminAnyDatabase", + db: "admin" + } + ] + } + ) +--- +title: Create a user administrator for a single database. +stepnum: 4 +ref: create-db-user-admin +pre: | + Optionally, you may want to create user administrators that only + have access to administer users in a specific database by way of the + :authrole:`userAdmin` role. action: pre: | The following example creates the user ``recordsUserAdmin`` on the diff --git a/source/includes/steps-create-admin-then-enable-authentication.yaml b/source/includes/steps-create-admin-then-enable-authentication.yaml index 9dd28a0d446..37223f99320 100644 --- a/source/includes/steps-create-admin-then-enable-authentication.yaml +++ b/source/includes/steps-create-admin-then-enable-authentication.yaml @@ -16,7 +16,7 @@ post: | stepnum: 2 source: file: steps-add-user-administrator.yaml - ref: create-user-admin + ref: create-site-user-admin --- title: Re-start the MongoDB instance with authentication enabled. stepnum: 3 diff --git a/source/includes/steps-deploy-replica-set-with-auth.yaml b/source/includes/steps-deploy-replica-set-with-auth.yaml index bd874ceb94f..e7d18eea08c 100644 --- a/source/includes/steps-deploy-replica-set-with-auth.yaml +++ b/source/includes/steps-deploy-replica-set-with-auth.yaml @@ -62,34 +62,21 @@ source: file: steps-deploy-replica-set.yaml ref: check-status --- -title: Connect to MongoDB with the privileges needed to create a user administrator. stepnum: 9 -source: - file: steps-connect-with-admin-privileges.yaml - ref: connect -pre: | - Connect to the replica set :term:`primary`. ---- -stepnum: 10 -source: - file: steps-connect-with-admin-privileges.yaml - ref: verify-privileges ---- -stepnum: 11 source: file: steps-add-user-administrator.yaml - ref: create-user-admin + ref: create-site-user-admin --- -title: Create additional users to meet your operational needs. -stepnum: 12 +title: Create additional users to address operational requirements. +stepnum: 10 ref: create-additional-users pre: | You can use :doc:`built-in roles ` to create - common types of database users, such as the :authrole:`dbAdmin` role to + common types of database users, such as the :authrole:`dbOwner` role to create a database administrator, the :authrole:`readWrite` role to create a user who can update data, or the :authrole:`read` role to - create user who can search data but no more. `. You - also can define :ref:`custom roles `. + create user who can search data but no more. You also can define + :ref:`custom roles `. action: pre: | For example, the following creates a database administrator for the @@ -103,7 +90,7 @@ action: roles: [ { - role: "dbAdmin", + role: "dbOwner", db: "products" } ] diff --git a/source/includes/steps-enable-authentication.yaml b/source/includes/steps-enable-authentication.yaml index 5f07deb981f..374cd31b03e 100644 --- a/source/includes/steps-enable-authentication.yaml +++ b/source/includes/steps-enable-authentication.yaml @@ -31,7 +31,7 @@ action: stepnum: 3 source: file: steps-add-user-administrator.yaml - ref: create-user-admin + ref: create-site-user-admin post: | After you create the user administrator, the :ref:`localhost exception ` is no longer diff --git a/source/includes/steps-generate-key-file.yaml b/source/includes/steps-generate-key-file.yaml index 4e16c9f5f4e..69737998428 100644 --- a/source/includes/steps-generate-key-file.yaml +++ b/source/includes/steps-generate-key-file.yaml @@ -6,8 +6,8 @@ pre: | servers to each other. action: pre: | - To generate generate pseudo-random to use for a keyfile, use the - ``openssl`` command: + To generate generate pseudo-random data to use for a + :setting`keyfile`, issue the following ``openssl`` command: language: sh code: | openssl rand -base64 741 diff --git a/source/tutorial/deploy-replica-set-with-auth.txt b/source/tutorial/deploy-replica-set-with-auth.txt index 2b2e2da58e8..d0d0edac8f5 100644 --- a/source/tutorial/deploy-replica-set-with-auth.txt +++ b/source/tutorial/deploy-replica-set-with-auth.txt @@ -14,12 +14,13 @@ 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 runs -without authentication enabled. You can enable it at anytime, both during -initial deployment or after a system has been deployed. +All MongoDB deployments support authentication. By default, MongoDB +runs without authentication enabled. You can enable when deploying +MongoDB, or enable authentication after deploying; however, you cannot +enable authentication on a running deployment without downtime. This tutorial provides a procedure for creating a MongoDB :doc:`replica -set ` that uses the challenge-and-response +set ` that uses the challenge-response authentication mechanism. The tutorial includes creation of a minimal authorization system to support basic operations. @@ -29,13 +30,16 @@ Considerations Authentication ~~~~~~~~~~~~~~ -Authentication requires an authentication mechanism and in many cases a -:setting:`key file `. +Authentication requires an authentication mechanism, which defaults to +``MONGODB-CR``. To support :ref:`inter-process authentication +` with ``MONGODB-CR`` MongoDB uses a +:setting:`keyFile` to authentication communication between members of +a deployment. -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. In the source of this procedure, you will create one user -with this role. +To ensure that you can continue to the deployment and have access to +create administrative users, before enabling authentication you should +have a user administrator. During this procedure you will create a +user administrator that you will use to administer this deployment. .. include:: /includes/considerations-deploying-replica-set.rst From 22f826c58bf14dcb02b2e669c2915373f9b9695c Mon Sep 17 00:00:00 2001 From: Sam Kleinman Date: Tue, 25 Mar 2014 16:23:30 -0400 Subject: [PATCH 05/11] DOCS-2671: additional clarifications for deploy repl-set auth tutorial --- .../considerations-deploying-replica-set.rst | 8 ++++---- .../includes/steps-add-user-administrator.yaml | 2 ++ .../steps-deploy-replica-set-with-auth.yaml | 9 ++++++++- source/includes/steps-generate-key-file.yaml | 8 ++++++-- source/tutorial/deploy-replica-set-with-auth.txt | 16 +++++++++------- 5 files changed, 29 insertions(+), 14 deletions(-) diff --git a/source/includes/considerations-deploying-replica-set.rst b/source/includes/considerations-deploying-replica-set.rst index 695e7d16173..250d5a28c77 100644 --- a/source/includes/considerations-deploying-replica-set.rst +++ b/source/includes/considerations-deploying-replica-set.rst @@ -6,9 +6,9 @@ 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 the configured address. -For a geographically distributed replica set, ensure that one system -resides in each secondary site, while the remaining :program:`mongod` -instances are in the primary site. +For a geographically distributed replica set, ensure that one +:program:`mongod` instance resides in each secondary site, while the +:program:`mongod` instances are in the primary site. See :doc:`/core/replica-set-architectures` for more information. @@ -23,7 +23,7 @@ following: routes all traffic between members within a single site over the local area network. -- Configure authentication to prevent connections from unknown clients +- Configure access control to prevent connections from unknown clients to the replica set. - Configure networking and firewall rules so that incoming and outgoing diff --git a/source/includes/steps-add-user-administrator.yaml b/source/includes/steps-add-user-administrator.yaml index 52f828c9ca9..8dfc44d047a 100644 --- a/source/includes/steps-add-user-administrator.yaml +++ b/source/includes/steps-add-user-administrator.yaml @@ -23,6 +23,7 @@ action: ``admin`` database: language: javascript code: | + use admin db.createUser( { user: "siteUserAdmin", @@ -50,6 +51,7 @@ action: ``records`` database: language: javascript code: | + use products db.createUser( { user: "recordsUserAdmin", diff --git a/source/includes/steps-deploy-replica-set-with-auth.yaml b/source/includes/steps-deploy-replica-set-with-auth.yaml index e7d18eea08c..bdc1841344c 100644 --- a/source/includes/steps-deploy-replica-set-with-auth.yaml +++ b/source/includes/steps-deploy-replica-set-with-auth.yaml @@ -37,7 +37,8 @@ post: | title: Connect to one of the replica set members. stepnum: 4 pre: | - Connect through the :ref:`localhost exception `. + Connect to one of the instances using the :ref:`localhost exception + `. source: file: steps-deploy-replica-set.yaml ref: open-shell @@ -66,6 +67,12 @@ stepnum: 9 source: file: steps-add-user-administrator.yaml ref: create-site-user-admin +pre: | + Add the user administrator with the :authrole:`userAdminAnyDatabase` role, and + only that role. + + You must issue the following operation while connected using the + :ref:`localhost exception `. --- title: Create additional users to address operational requirements. stepnum: 10 diff --git a/source/includes/steps-generate-key-file.yaml b/source/includes/steps-generate-key-file.yaml index 69737998428..10eefb37259 100644 --- a/source/includes/steps-generate-key-file.yaml +++ b/source/includes/steps-generate-key-file.yaml @@ -10,8 +10,12 @@ action: :setting`keyfile`, issue the following ``openssl`` command: language: sh code: | - openssl rand -base64 741 - + openssl rand -base64 741 > mongodb-keyfile + chmod 600 mongodb-keyfile +post: | + Copy the ``mongodb-keyfile`` to all hosts where components of a + MongoDB deployment run. Set the permissions of these files to + ``600``. --- title: Specify the key file when starting a MongoDB instance. stepnum: 2 diff --git a/source/tutorial/deploy-replica-set-with-auth.txt b/source/tutorial/deploy-replica-set-with-auth.txt index d0d0edac8f5..469ba2232f1 100644 --- a/source/tutorial/deploy-replica-set-with-auth.txt +++ b/source/tutorial/deploy-replica-set-with-auth.txt @@ -33,13 +33,15 @@ Authentication Authentication requires an authentication mechanism, which defaults to ``MONGODB-CR``. To support :ref:`inter-process authentication ` with ``MONGODB-CR`` MongoDB uses a -:setting:`keyFile` to authentication communication between members of -a deployment. - -To ensure that you can continue to the deployment and have access to -create administrative users, before enabling authentication you should -have a user administrator. During this procedure you will create a -user administrator that you will use to administer this deployment. +:setting:`keyFile` to authenticate communication between members of a +deployment. The content of the key file is the shared secret used for +all internal authentication. + +To ensure that you can continue to use the deployment and have access +to create users, you should have a user administrator. Create this +user before enabling authorization checking. During this procedure you +will create a user administrator that you will use to administer this +deployment. .. include:: /includes/considerations-deploying-replica-set.rst From 208be092fe78548dd14333ac5e5abe62344c9991 Mon Sep 17 00:00:00 2001 From: Sam Kleinman Date: Tue, 25 Mar 2014 19:39:07 -0400 Subject: [PATCH 06/11] DOCS-2671: syntax fixes --- source/includes/steps-generate-key-file.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/includes/steps-generate-key-file.yaml b/source/includes/steps-generate-key-file.yaml index 10eefb37259..52c90578e22 100644 --- a/source/includes/steps-generate-key-file.yaml +++ b/source/includes/steps-generate-key-file.yaml @@ -6,8 +6,8 @@ pre: | servers to each other. action: pre: | - To generate generate pseudo-random data to use for a - :setting`keyfile`, issue the following ``openssl`` command: + 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 From fcdf2925fcc8133a9f523ba0e10956b77b77e6b3 Mon Sep 17 00:00:00 2001 From: Sam Kleinman Date: Tue, 25 Mar 2014 19:40:54 -0400 Subject: [PATCH 07/11] DOCS-2671: fixing logical error in steps sequence --- source/includes/steps-deploy-replica-set-with-auth.yaml | 4 ++++ source/includes/steps-generate-key-file.yaml | 6 ++---- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/source/includes/steps-deploy-replica-set-with-auth.yaml b/source/includes/steps-deploy-replica-set-with-auth.yaml index bdc1841344c..9ce931c5c18 100644 --- a/source/includes/steps-deploy-replica-set-with-auth.yaml +++ b/source/includes/steps-deploy-replica-set-with-auth.yaml @@ -7,6 +7,10 @@ source: title: Copy the key file to each member of the replica set. stepnum: 2 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``. --- title: Start each member of the replica set with the appropriate options. stepnum: 3 diff --git a/source/includes/steps-generate-key-file.yaml b/source/includes/steps-generate-key-file.yaml index 52c90578e22..0635353fcd8 100644 --- a/source/includes/steps-generate-key-file.yaml +++ b/source/includes/steps-generate-key-file.yaml @@ -12,10 +12,8 @@ action: code: | openssl rand -base64 741 > mongodb-keyfile chmod 600 mongodb-keyfile -post: | - Copy the ``mongodb-keyfile`` to all hosts where components of a - MongoDB deployment run. Set the permissions of these files to - ``600``. +# 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 From a93263451469e0402ae3d512b2d2bcf454f1e09d Mon Sep 17 00:00:00 2001 From: Sam Kleinman Date: Wed, 26 Mar 2014 15:22:19 -0400 Subject: [PATCH 08/11] DOCS-2671: deploy replica set steps --- source/includes/considerations-deploying-replica-set.rst | 2 +- source/includes/steps-deploy-replica-set-with-auth.yaml | 7 ++++--- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/source/includes/considerations-deploying-replica-set.rst b/source/includes/considerations-deploying-replica-set.rst index 250d5a28c77..301e573baa9 100644 --- a/source/includes/considerations-deploying-replica-set.rst +++ b/source/includes/considerations-deploying-replica-set.rst @@ -7,7 +7,7 @@ and if possible bind to the standard MongoDB port of ``27017``. Use the from applications on the configured address. For a geographically distributed replica set, ensure that one -:program:`mongod` instance resides in each secondary site, while the +:program:`mongod` instance resides in each secondary site, while the remaining :program:`mongod` instances are in the primary site. See :doc:`/core/replica-set-architectures` for more information. diff --git a/source/includes/steps-deploy-replica-set-with-auth.yaml b/source/includes/steps-deploy-replica-set-with-auth.yaml index 9ce931c5c18..900a3c94dcf 100644 --- a/source/includes/steps-deploy-replica-set-with-auth.yaml +++ b/source/includes/steps-deploy-replica-set-with-auth.yaml @@ -75,12 +75,12 @@ pre: | Add the user administrator with the :authrole:`userAdminAnyDatabase` role, and only that role. - You must issue the following operation while connected using the - :ref:`localhost exception `. + You must issue the following operation while connected to the + :term:`primary` using the :ref:`localhost exception `. --- title: Create additional users to address operational requirements. stepnum: 10 -ref: create-additional-users +ref: create-records-db-owner pre: | You can use :doc:`built-in roles ` to create common types of database users, such as the :authrole:`dbOwner` role to @@ -94,6 +94,7 @@ action: ``products`` database: language: javascript code: | + use products db.createUser( { user: "productsDBAdmin", From 5a3fb4744c9a2be155bc0480b651c3f017258914 Mon Sep 17 00:00:00 2001 From: Sam Kleinman Date: Wed, 26 Mar 2014 16:46:38 -0400 Subject: [PATCH 09/11] DOCS-2671: improvements to the introduction of the repl-set-with-auth tutorial --- source/tutorial/deploy-replica-set-with-auth.txt | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/source/tutorial/deploy-replica-set-with-auth.txt b/source/tutorial/deploy-replica-set-with-auth.txt index 469ba2232f1..474fdbb33a0 100644 --- a/source/tutorial/deploy-replica-set-with-auth.txt +++ b/source/tutorial/deploy-replica-set-with-auth.txt @@ -15,9 +15,10 @@ 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 -runs without authentication enabled. You can enable when deploying -MongoDB, or enable authentication after deploying; however, you cannot -enable authentication on a running deployment without downtime. +does not require authorization checking. You can enforce authorization +checking when deploying MongoDB, or on an existing deploying; however, +you cannot enable authorization checking on a running deployment +without downtime. This tutorial provides a procedure for creating a MongoDB :doc:`replica set ` that uses the challenge-response From b4b26d47e005f9ad03cf0f899bcb9f84873b289e Mon Sep 17 00:00:00 2001 From: Sam Kleinman Date: Tue, 1 Apr 2014 14:25:05 -0400 Subject: [PATCH 10/11] DOCS-2671: changing langauge in tutorials and introductory materials --- .../considerations-deploying-replica-set.rst | 8 +++---- .../steps-deploy-replica-set-with-auth.yaml | 6 ++++-- source/includes/steps-generate-key-file.yaml | 7 ++++++- .../tutorial/deploy-replica-set-with-auth.txt | 21 +++++++++---------- 4 files changed, 24 insertions(+), 18 deletions(-) diff --git a/source/includes/considerations-deploying-replica-set.rst b/source/includes/considerations-deploying-replica-set.rst index 301e573baa9..1b4a49b42cb 100644 --- a/source/includes/considerations-deploying-replica-set.rst +++ b/source/includes/considerations-deploying-replica-set.rst @@ -4,11 +4,11 @@ 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 the configured address. +from applications on configured addresses. -For a geographically distributed replica set, ensure that one -:program:`mongod` instance resides in each secondary site, while the remaining -:program:`mongod` instances are in the primary site. +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. diff --git a/source/includes/steps-deploy-replica-set-with-auth.yaml b/source/includes/steps-deploy-replica-set-with-auth.yaml index 900a3c94dcf..e0bd8da2633 100644 --- a/source/includes/steps-deploy-replica-set-with-auth.yaml +++ b/source/includes/steps-deploy-replica-set-with-auth.yaml @@ -10,7 +10,9 @@ 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``. + ``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: 3 @@ -73,7 +75,7 @@ source: ref: create-site-user-admin pre: | Add the user administrator with the :authrole:`userAdminAnyDatabase` role, and - only that role. + only that role. You must issue the following operation while connected to the :term:`primary` using the :ref:`localhost exception `. diff --git a/source/includes/steps-generate-key-file.yaml b/source/includes/steps-generate-key-file.yaml index 0635353fcd8..c77e5690e25 100644 --- a/source/includes/steps-generate-key-file.yaml +++ b/source/includes/steps-generate-key-file.yaml @@ -12,8 +12,13 @@ action: 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. +# steps-deploy-replica-set-with-auth.yaml and friends. --- title: Specify the key file when starting a MongoDB instance. stepnum: 2 diff --git a/source/tutorial/deploy-replica-set-with-auth.txt b/source/tutorial/deploy-replica-set-with-auth.txt index 474fdbb33a0..a7fcaafb2ba 100644 --- a/source/tutorial/deploy-replica-set-with-auth.txt +++ b/source/tutorial/deploy-replica-set-with-auth.txt @@ -31,17 +31,16 @@ Considerations Authentication ~~~~~~~~~~~~~~ -Authentication requires an authentication mechanism, which defaults to -``MONGODB-CR``. To support :ref:`inter-process authentication -` with ``MONGODB-CR`` MongoDB uses a -:setting:`keyFile` to authenticate communication between members of a -deployment. The content of the key file is the shared secret used for -all internal authentication. - -To ensure that you can continue to use the deployment and have access -to create users, you should have a user administrator. Create this -user before enabling authorization checking. During this procedure you -will create a user administrator that you will use to administer this +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 `. 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 From 557c420580744822e6e7beaa99756d32c6df9fe8 Mon Sep 17 00:00:00 2001 From: Sam Kleinman Date: Tue, 1 Apr 2014 14:34:47 -0400 Subject: [PATCH 11/11] DOCS-2671: edits to avoid the localhost auth bypass --- .../steps-deploy-replica-set-with-auth.yaml | 52 ++++++++++++++++--- 1 file changed, 45 insertions(+), 7 deletions(-) diff --git a/source/includes/steps-deploy-replica-set-with-auth.yaml b/source/includes/steps-deploy-replica-set-with-auth.yaml index e0bd8da2633..3e275236a3b 100644 --- a/source/includes/steps-deploy-replica-set-with-auth.yaml +++ b/source/includes/steps-deploy-replica-set-with-auth.yaml @@ -1,5 +1,39 @@ +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.createUser( { + user: "siteUserAdmin", + pwd: "", + roles: [ { role: "userAdminAnyDatabase", db: "admin" } ] + }); + db.createUser( { + user: "siteRootAdmin", + pwd: "", + roles: [ { role: "root", db: "admin" } ] + }); +--- +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: 1 +ref: generate-keyfile source: file: steps-generate-key-file.yaml ref: generate @@ -40,14 +74,18 @@ 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. +title: "Connect to the member of the replica set where you created the administrative users." stepnum: 4 +ref: connect-and-auth pre: | - Connect to one of the instances using the :ref:`localhost exception - `. -source: - file: steps-deploy-replica-set.yaml - ref: open-shell + 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", ""); --- stepnum: 5 source: @@ -78,7 +116,7 @@ pre: | only that role. You must issue the following operation while connected to the - :term:`primary` using the :ref:`localhost exception `. + :term:`primary` as the ``siteRootAdmin`` user. --- title: Create additional users to address operational requirements. stepnum: 10