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/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..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/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/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..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/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/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-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..8dfc44d047a 100644 --- a/source/includes/steps-add-user-administrator.yaml +++ b/source/includes/steps-add-user-administrator.yaml @@ -1,28 +1,57 @@ 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. +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: | + use admin + 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 ``records`` database: language: javascript code: | + use products db.createUser( { user: "recordsUserAdmin", 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-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-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-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 new file mode 100644 index 00000000000..3e275236a3b --- /dev/null +++ b/source/includes/steps-deploy-replica-set-with-auth.yaml @@ -0,0 +1,155 @@ +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 +--- +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`` 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 +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/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: 4 +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: 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 +--- +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 to the + :term:`primary` as the ``siteRootAdmin`` user. +--- +title: Create additional users to address operational requirements. +stepnum: 10 +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 + 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: | + use products + db.createUser( + { + user: "productsDBAdmin", + pwd: "password", + roles: + [ + { + role: "dbOwner", + 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..629567c476b 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. + + .. include:: /includes/fact-unique-replica-set-names.rst action: - pre: | - .. include:: /includes/important-unique-replica-set-names.rst - - pre: | - To specify the replica set name from the command-line, start a - :program:`mongod` instance with the :option:`--replSet` option. For - additional replica-set options, see :ref:`cli-mongod-replica-set`. - The following example specifies a replica set named ``rs0``: + The following example specifies the replica set name through the + :option:`--replSet` command-line option: language: javascript code: | - mongod --dbpath /srv/mongodb/ --port 27017 --replSet "rs0" + mongod --replSet "rs0" - pre: | - To instead use a configuration file, start each - :program:`mongod` instance with a command that resembles the - following. Change ``/etc/mongodb.conf`` to the location of your - configuration file: + The following example specifies the name through a configuration file: language: javascript code: | - mongod --config /etc/mongodb.conf + 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-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 69c9cc790d5..c77e5690e25 100644 --- a/source/includes/steps-generate-key-file.yaml +++ b/source/includes/steps-generate-key-file.yaml @@ -1,19 +1,29 @@ -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 pseudo-random data to use for a + :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: | + 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: | - 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-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-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.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/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-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-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 new file mode 100644 index 00000000000..a7fcaafb2ba --- /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 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 +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 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