From 065692a0199dc079bed6e548727f66f11e4bf771 Mon Sep 17 00:00:00 2001 From: Michael Paik Date: Tue, 3 Mar 2015 21:36:27 -0500 Subject: [PATCH] DOCS-4831 - 2.4 replset with auth --- source/administration/security-deployment.txt | 12 ++ .../considerations-deploying-replica-set.rst | 47 +++++++ .../steps-deploy-replica-set-with-auth.yaml | 112 +++++++++++++++++ source/includes/steps-deploy-replica-set.yaml | 119 ++++++++++++++++++ source/includes/steps-generate-key-file.yaml | 29 +++++ .../toc-security-tutorials-deployment.yaml | 4 + .../toc-security-tutorials-landing.yaml | 5 + .../tutorial/deploy-replica-set-with-auth.txt | 54 ++++++++ 8 files changed, 382 insertions(+) create mode 100644 source/administration/security-deployment.txt create mode 100644 source/includes/considerations-deploying-replica-set.rst create mode 100644 source/includes/steps-deploy-replica-set-with-auth.yaml create mode 100644 source/includes/steps-deploy-replica-set.yaml create mode 100644 source/includes/steps-generate-key-file.yaml create mode 100644 source/includes/toc-security-tutorials-deployment.yaml create mode 100644 source/tutorial/deploy-replica-set-with-auth.txt diff --git a/source/administration/security-deployment.txt b/source/administration/security-deployment.txt new file mode 100644 index 00000000000..8b83000c671 --- /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-tutorials-deployment.rst + +.. include:: /includes/toc/security-tutorials-deployment.rst diff --git a/source/includes/considerations-deploying-replica-set.rst b/source/includes/considerations-deploying-replica-set.rst new file mode 100644 index 00000000000..1b4a49b42cb --- /dev/null +++ b/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 ` 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/steps-deploy-replica-set-with-auth.yaml b/source/includes/steps-deploy-replica-set-with-auth.yaml new file mode 100644 index 00000000000..565c560d4bc --- /dev/null +++ b/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: "", + roles: [ "userAdminAnyDatabase" ] + }); + db.addUser( { + user: "siteRootAdmin", + pwd: "", + 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", ""); +--- +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 +... diff --git a/source/includes/steps-deploy-replica-set.yaml b/source/includes/steps-deploy-replica-set.yaml new file mode 100644 index 00000000000..27b2b5bbed1 --- /dev/null +++ b/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 ` in + the :doc:`configuration file `. + To start :program:`mongod` with a configuration file, specify the + file with the :option:`--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 `: + 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() +... diff --git a/source/includes/steps-generate-key-file.yaml b/source/includes/steps-generate-key-file.yaml new file mode 100644 index 00000000000..1eb87fa33f2 --- /dev/null +++ b/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. +... 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 f5a41f08755..8b3638de18a 100644 --- a/source/includes/toc-security-tutorials-landing.yaml +++ b/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 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..ab28d155636 --- /dev/null +++ b/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 ` 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 +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 ` 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 `. 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