From ac1e8fdc8bf20b2a9740a46734abb948b6fbffd9 Mon Sep 17 00:00:00 2001 From: ravind Date: Fri, 30 Dec 2016 10:26:46 -0500 Subject: [PATCH 1/3] DOCS-8616: no-downtime security sharded cluster --- .../core/security-internal-authentication.txt | 3 +- source/includes/extracts-keyfile-info.yaml | 25 +- ...n-shardcluster-nodowntime-auth-config.yaml | 31 ++ ...n-shardcluster-nodowntime-auth-mongos.yaml | 55 ++++ ...in-shardcluster-nodowntime-auth-shard.yaml | 24 ++ ...dcluster-nodowntime-transition-config.yaml | 94 ++++++ ...dcluster-nodowntime-transition-mongos.yaml | 79 +++++ ...dcluster-nodowntime-transition-shards.yaml | 18 ++ ...cation-in-shardcluster-nodowntime-uac.yaml | 113 +++++++ ...n-existing-sharded-cluster-no-downtime.txt | 297 ++++++++++++++++++ 10 files changed, 731 insertions(+), 8 deletions(-) create mode 100644 source/includes/steps-enable-authentication-in-shardcluster-nodowntime-auth-config.yaml create mode 100644 source/includes/steps-enable-authentication-in-shardcluster-nodowntime-auth-mongos.yaml create mode 100644 source/includes/steps-enable-authentication-in-shardcluster-nodowntime-auth-shard.yaml create mode 100644 source/includes/steps-enable-authentication-in-shardcluster-nodowntime-transition-config.yaml create mode 100644 source/includes/steps-enable-authentication-in-shardcluster-nodowntime-transition-mongos.yaml create mode 100644 source/includes/steps-enable-authentication-in-shardcluster-nodowntime-transition-shards.yaml create mode 100644 source/includes/steps-enable-authentication-in-shardcluster-nodowntime-uac.yaml create mode 100644 source/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime.txt diff --git a/source/core/security-internal-authentication.txt b/source/core/security-internal-authentication.txt index 3a17e2f6260..46c5d3fa84b 100644 --- a/source/core/security-internal-authentication.txt +++ b/source/core/security-internal-authentication.txt @@ -95,6 +95,7 @@ see :doc:`/tutorial/upgrade-keyfile-to-x509`. /tutorial/enforce-keyfile-access-control-in-existing-replica-set-without-downtime /tutorial/deploy-replica-set-with-keyfile-access-control /tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster - /tutorial/deploy-sharded-cluster-with-keyfile-access-control + /tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime + /tutorial/deploy-sharded-cluster-with-keyfile-access-control /tutorial/configure-x509-member-authentication /tutorial/upgrade-keyfile-to-x509 diff --git a/source/includes/extracts-keyfile-info.yaml b/source/includes/extracts-keyfile-info.yaml index 3ac47e8b8e3..6757418c270 100644 --- a/source/includes/extracts-keyfile-info.yaml +++ b/source/includes/extracts-keyfile-info.yaml @@ -1,9 +1,12 @@ ref: _keyfile-intro content: | - The contents of the :ref:`keyfile ` serves as - the shared password for the members of the {{deployment}}. The - content of the keyfile must be the same for all members of the + With :ref:`keyfile ` authentication, the + {{components}} in the {{deployment}} use the contents of the keyfile as the + shared password for authenticating other members in the deployment. Only + {{components}} with the correct keyfile can join the {{deployment}}. + + The content of the keyfile must be the same for all members of the {{deployment}}. You can generate a keyfile using any method you choose. The contents @@ -24,6 +27,7 @@ source: ref: _keyfile-intro replacement: deployment: replica set + components: :program:`mongod` instances --- ref: keyfile-intro-sharded-cluster source: @@ -31,15 +35,22 @@ source: ref: _keyfile-intro replacement: deployment: sharded cluster + components: :program:`mongod` or :program:`mongos` instances --- ref: _keyfile-distribution content: | - Copy the keyfile to each server hosting the {{deployment}} members. Use a - consistent location for each server. + + Copy the keyfile to each server hosting the {{deployment}} members. For + simplicity in configuration and maintenance, save the keyfile to a + consistent location for each server, such as the file path specified in + the {{programs}} :setting:`storage.dbPath` setting. .. important:: - Do not use shared network locations or storage mediums such as USB - drives for storing the keyfile. + + If the {{programs}} cannot access the keyfile, they cannot communicate + with the {{deployment}}. Avoid storing the keyfile on storage mediums + that can be easily disconnected from the hardware hosting the + {{programs}}, such as a USB drive or a network attached storage device. Ensure that the user running the {{programs}} can access the keyfile. --- diff --git a/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-auth-config.yaml b/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-auth-config.yaml new file mode 100644 index 00000000000..0676ecf7a5d --- /dev/null +++ b/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-auth-config.yaml @@ -0,0 +1,31 @@ +stepnum: 1 +level: 4 +title: "Remove ``transitionToAuth`` from the ``mongod`` configuration file." +ref: modify-config-files +pre: | + + Remove the :setting:`security.transitionToAuth` key and its value from the + configuration file created during this tutorial. + + .. code-block:: yaml + + security: + keyFile: +--- +stepnum: 2 +level: 4 +ref: restart-mongod +title: "Restart the ``mongod`` with the updated configuration file." +source: + file: steps-enable-authentication-in-shardcluster-nodowntime-transition-config.yaml + ref: restart-mongod +post: | + + At the end of this section, the config server replica set should be up and + running fully enforcing authentication. + + Users and client applications *must* specify authentiation credentials when + connecting to the config server replica set. +replacement: + status: "updated" +... \ No newline at end of file diff --git a/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-auth-mongos.yaml b/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-auth-mongos.yaml new file mode 100644 index 00000000000..b32bc5f0419 --- /dev/null +++ b/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-auth-mongos.yaml @@ -0,0 +1,55 @@ +stepnum: 1 +level: 4 +title: "Remove ``transitionToAuth`` from the ``mongos`` configuration file" +ref: modify-config-files +pre: | + + Remove the :setting:`security.transitionToAuth` key and its value from the + configuration file created during this tutorial. + + .. code-block:: yaml + + security: + keyFile: + +--- +stepnum: 2 +level: 4 +ref: restart-mongos +title: "Restart the ``mongos`` with the updated configuration file." +pre: | + + Connect to the :program:`mongos` and use the :method:`db.shutdownServer()` + method against the ``admin`` database to safely shut down the + :program:`mongos`. + + Restart one :program:`mongos` at a time to ensure that clients + can connect to the sharded cluster. If your cluster has only one + :program:`mongos`, this step results in downtime while the :program:`mongos` + is offline. + + .. code-block:: javascript + + db.getSiblingDB("admin").shutdownServer() + + You can then start the :program:`mongos` specifying the updated + configuration file, specifying the path to the config file using + :option:`--config`.. This configuration file no longer contains the + :setting:`security.transitionToAuth` setting, but retains the + :setting:`security.keyFile` setting. + + .. example:: + + The following operation starts the :program:`mongos` specifying + the updated configuration file, here named ``mongos-secure.conf``. + The ```` represents the system path to the folder containing + the configuration file. + + .. code-block:: shell + + mongos --config /mongos-secure.conf + + .. note:: + + MongoDB deployments running on :abbr:`Windows (Microsoft Windows)` use + the ``.cfg`` file extension instead of ``.conf``. diff --git a/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-auth-shard.yaml b/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-auth-shard.yaml new file mode 100644 index 00000000000..43a0ce1b05f --- /dev/null +++ b/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-auth-shard.yaml @@ -0,0 +1,24 @@ +stepnum: 1 +level: 4 +title: "Remove ``transitionToAuth`` from the ``mongod`` configuration file" +ref: modify-configuration +source: + file: steps-enable-authentication-in-shardcluster-nodowntime-auth-config.yaml + ref: modify-config-files +--- +stepnum: 2 +level: 4 +title: "Restart the ``mongod`` with the new configuration file." +ref: restart-mongod +source: + file: steps-enable-authentication-in-shardcluster-nodowntime-transition-config.yaml + ref: restart-mongod +post: | + + At the end of this section, the shard replica set should be up and + running fully enforcing authentication. + + Users and client applications *must* specify authentiation credentials when + connecting to the shard replica set. +replacement: + status: "updated" diff --git a/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-transition-config.yaml b/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-transition-config.yaml new file mode 100644 index 00000000000..47902f0e653 --- /dev/null +++ b/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-transition-config.yaml @@ -0,0 +1,94 @@ +stepnum: 1 +level: 4 +title: "Add ``transitionToAuth: true`` to the ``mongod`` configuration file." +ref: modify-config-files +pre: | + + Copy the existing {{program}} configuration file and name the copy to + distinguish it, for example, by adding ``-secure`` to the filename. You will + use this new configuration file to transition the {{program}} to enforce + authentication in the sharded cluster. Retain the original configuration + file for backup purposes. + + Add the following settings to the new configuration file. + + .. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Setting + - Value + + * - :setting:`security.transitionToAuth` + - ``true`` + + * - :setting:`security.keyFile` + - Path to the keyfile. + + If using a different internal authentication mechanism, specify that + mechanism instead of :setting:`security.keyFile`. + + The new configuration file should contain all of the configuration settings + previously used by the {{program}}, as well as the new security + settings. + + .. code-block:: yaml + + security: + transitionToAuth: true + keyFile: +replacement: + program: :program:`mongod` +--- +stepnum: 2 +level: 4 +ref: restart-mongod +title: "Restart the ``mongod`` with the new configuration file." +pre: | + + Connect to the :program:`mongod` and use the :method:`db.shutdownServer()` + method against the ``admin`` database to safely shut down the + :program:`mongod`. + + .. code-block:: javascript + + db.getSiblingDB("admin").shutdownServer() + + If you are performing this step on the :term:`primary`, you must first use + the :method:`rs.stepDown()` method against the ``admin`` database to step + down the primary and trigger an election. You can use the + :method:`rs.status()` method to ensure the replica set elected a new primary. + + Once you step down the primary, you can then shut it down using the + :method:`db.shutdownServer()` method against the ``admin`` database. + + .. code-block:: javascript + + db.getSiblingDB("admin").rs.stepDown() + db.getSiblingDB("admin").shutdownServer() + + You can then restart the :program:`mongod` with the {{status}} configuration + file, specifying the path to the config file using :option:`--config`. + + .. example:: + + The following operation starts the replica set member specifying + the {{status}} configuration file, here named ``mongod-secure.conf``. + The ```` represents the system path to the folder containing + the configuration file. + + .. code-block:: shell + + mongod --config /mongod-secure.conf + + .. note:: + + MongoDB deployments running on :abbr:`Windows (Microsoft Windows)` use + the ``.cfg`` file extension instead of ``.conf``. +replacement: + status: "new" +post: | + + Include additional settings as appropriate to your deployment. Refer to + the :ref:`configuration-options` documentation for a complete list of + configuration file options. diff --git a/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-transition-mongos.yaml b/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-transition-mongos.yaml new file mode 100644 index 00000000000..97ffc7a1aa9 --- /dev/null +++ b/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-transition-mongos.yaml @@ -0,0 +1,79 @@ +stepnum: 1 +level: 4 +title: "Add ``transitionToAuth: true`` to the ``mongos`` configuration file" +ref: modify-config-files +pre: | + + Copy the existing {{program}} configuration file and name the copy to + distinguish it, for example, by adding ``-secure`` to the filename. You will + use this new configuration file to transition the {{program}} to enforce + authentication in the sharded cluster. Retain the original configuration + file for backup purposes. + + Add the following settings to the new configuration file. + + .. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Setting + - Value + + * - :setting:`security.transitionToAuth` + - ``true`` + + * - :setting:`security.keyFile` + - Path to the keyfile. + + If using a different internal authentication mechanism, specify that + mechanism instead of :setting:`security.keyFile`. + + The new configuration file should contain all of the configuration settings + previously used by the {{program}}, as well as the new security + settings. + + .. code-block:: yaml + + security: + transitionToAuth: true + keyFile: +replacement: + program: :program:`mongos` +--- +stepnum: 2 +level: 4 +ref: restart-mongos +title: "Restart the ``mongos`` with the new configuration file." +pre: | + + Connect to the :program:`mongos` and use the :method:`db.shutdownServer()` + method against the ``admin`` database to safely shut down the + :program:`mongos`. + + Restart one :program:`mongos` at a time to ensure that clients + can connect to the sharded cluster. If your cluster has only one + :program:`mongos`, this step results in downtime while the :program:`mongos` + is offline. + + .. code-block:: javascript + + db.getSiblingDB("admin").shutdownServer() + + You can then start the :program:`mongos` with the new configuration + file, specifying the path to the config file using :option:`--config`. + + .. example:: + + The following operation starts the :program:`mongos` specifying + the updated configuration file, here named ``mongos-secure.conf``. + The ```` represents the system path to the folder containing + the configuration file. + + .. code-block:: shell + + mongos --config /mongos-secure.conf + + .. note:: + + MongoDB deployments running on :abbr:`Windows (Microsoft Windows)` use + the ``.cfg`` file extension instead of ``.conf``. diff --git a/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-transition-shards.yaml b/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-transition-shards.yaml new file mode 100644 index 00000000000..5933f7af052 --- /dev/null +++ b/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-transition-shards.yaml @@ -0,0 +1,18 @@ +stepnum: 1 +level: 4 +title: "Add ``transitionToAuth: true`` to the ``mongod`` configuration file." +ref: modify-configuration +source: + file: steps-enable-authentication-in-shardcluster-nodowntime-transition-config.yaml + ref: modify-config-files +--- +stepnum: 2 +level: 4 +title: "Restart the ``mongod`` with the new configuration file." +ref: restart-mongod +source: + file: steps-enable-authentication-in-shardcluster-nodowntime-transition-config.yaml + ref: restart-mongod +replacement: + status: "new" +... \ No newline at end of file diff --git a/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-uac.yaml b/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-uac.yaml new file mode 100644 index 00000000000..639087dc812 --- /dev/null +++ b/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-uac.yaml @@ -0,0 +1,113 @@ +stepnum: 1 +title: Create the adminstrator user. +level: 4 +ref: add-user-useradmin +pre: | + + Clients performing maintenance operations or user administrative + operations on the {{CLUSTER}} must authenticate as this user + at the completion of this tutorial. Create this user now to ensure + that you have seamless access to the cluster after enforcing authentication. + + Create a user with the :method:`db.createUser()` method and assign it the + following roles: + + - :authrole:`clusterAdmin` on the ``admin`` database + - :authrole:`userAdmin` roles on the ``admin`` database + +action: + language: javascript + code: | + admin = db.getSiblingDB("admin") + admin.createUser( + { + user: "admin", + pwd: "", + roles: [ + { role: "clusterAdmin", db: "admin" }, + { role: "userAdmin", db: "admin" } + ] + } + ) + +post: | + + .. important:: + + Passwords should be random, long, and complex to ensure system security + and to prevent or delay malicious access. + + While this tutorial uses a single administrative user, you should + consider applying the `principle of least privilege + `_ + when configuring MongoDB users in your deployment. + +replacement: + CLUSTER: "sharded cluster" +--- +stepnum: 2 +title: "Create users for client applications to authenticate with." +optional: true +pre: | + + You can create users for your client applications to authenticate with prior + to enforcing authentication in the sharded cluster. This ensures + seamless access to the sharded cluster once you fully enforce authentication. + + .. example:: + + The following operation creates the user ``joe`` on the ``analytics`` + database, assigning it the :authrole:`readWrite` :ref:`built-in role + `. + + .. code-block:: javascript + + db.getSiblingDB("marketing").createUser( + { + "user": "joe", + "pwd": "", + "roles": [ { "role" : "readWrite", "db" : "analytics" } ] + } + ) + + Clients authenticating as this user can perform read and write operations + on the ``analytics`` database. + +post: | + See :ref:`database-user-roles` for basic built-in roles to use + in creating users for client applications to authenticate as. + + See the :ref:`Add Users ` tutorial for more information on + adding users. Consider :ref:`security best practices + ` when adding new users. +level: 4 +ref: shardcluster-add-clientuser +--- +stepnum: 3 +title: "Update client applications to specify authentication credentials." +optional: true +ref: update-client-apps +pre: | + + While the sharded cluster does not currently enforce authentication, you can + still update client applications to specify authentication credentials when + connecting to the sharded cluster. This may prevent loss of connectivity at + the completion of this tutorial. + + .. example:: + + The following operation connects to the sharded cluster using the + :program:`mongo` shell, authenticating as the user ``joe`` on the + ``marketing`` database. + + .. code-block:: javascript + + mongo --username "joe" --password "" \ + --authenticationDatabase "marketing" --host mongos1.example.net:27017 + + If your application uses a MongoDB driver, see the associated + :ecosystem:`driver ` documentation for instructions on creating + an authenticated connection. + +level: 4 +... \ No newline at end of file diff --git a/source/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime.txt b/source/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime.txt new file mode 100644 index 00000000000..7a4f3fed9a0 --- /dev/null +++ b/source/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime.txt @@ -0,0 +1,297 @@ +========================================================================== +Enable mandatory user authentication in a sharded cluster without downtime +========================================================================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Overview +-------- + +.. important:: + + MongoDB 3.2 and earlier do not support a no-downtime upgrade to enforce + authentication in sharded clusters and cannot perform the procedure + described in this tutorial. + + Refer to the + :doc:`/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster` + tutorial for a procedure for enforcing access control in a sharded cluster + running MongoDB 3.2 or prior. + +To secure against unauthorized access, enforce :ref:`authentication +` in :term:`sharded cluster` deployments. + +A MongoDB sharded cluster can enforce :ref:`user authentication +` as well as :ref:`internal +authentication ` among the sharded cluster +:program:`mongod` and :program:`mongos` components. + +This tutorial describes a correct procedure for using +:setting:`security.transitionToAuth` to enable access control in an existing +MongoDB sharded cluster without incurring downtime. + +Before you attempt this tutorial, please familiarize yourself with the +contents of this document. + +Considerations +~~~~~~~~~~~~~~ + +Cloud Manager and Ops Manager +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you are using Cloud Manager or Ops Manager to manage your deployment, +refer to *Configure Access Control for MongoDB Deployments* +in the :mms-docs:`Cloud Manager manual +` +or :opsmgr:`Ops Manager manual +` to enforce authentication. + +Internal and Client Authentication Mechanisms +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This tutorial configures authentication using :ref:`SCRAM-SHA-1 +` for client authentication and a :ref:`keyfile +` for internal authentication. + +Refer to the :ref:`authentication` documentation for a complete list of +available client and internal authentication mechanisms, as well as tutorials +on implementation. + +Architecture +~~~~~~~~~~~~ + +This tutorial assumes that each shard replica set, as well as the config +server replica set, can elect a new :term:`primary` after stepping down its +existing primary. + +A replica set can elect a primary only if both of the following conditions are +true: + +- A majority of voting replica set members are available after stepping down + the :term:`primary`. + +- There is at least one available :term:`secondary` member that is not + :ref:`delayed `, :ref:`hidden + `, or :ref:`Priority 0 + `. + +Minimum number of ``mongos`` instances +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This tutorial requires restarting each :program:`mongos` in the cluster. If +your cluster only has one available :program:`mongos` instance, this results +in downtime during the period that the :program:`mongos` is offline. To avoid +this, ensure your sharded cluster has at least *two* :program:`mongos` +instances available. + +.. _security-shardcluster-nodowntime-enable-access-control: + +Enforce Keyfile Access Control on an Existing Sharded Cluster +------------------------------------------------------------- + +Create and Distribute the Keyfile +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/extracts/keyfile-intro-sharded-cluster.rst + +.. code-block:: shell + + openssl rand -base64 755 > + chmod 400 + + +.. include:: /includes/extracts/keyfile-distribution-sharded-cluster.rst + +For more information on using keyfiles for internal authentication, refer to +:ref:`internal-auth-keyfile`. + +.. _security-shardcluster-nodowntime-adminusers-clientusers: + +Configure Sharded Cluster Admin User and Client Users +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You must connect to a :program:`mongos` to complete these steps. The users +created in these steps are cluster-level users and cannot be used for +accessing individual shard replica sets. + +.. include:: /includes/steps/enable-authentication-in-shardcluster-nodowntime-uac.rst + +Restart Each ``mongos`` Instance with ``transitionToAuth`` set to ``true`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Repeat these steps for each :program:`mongos` in the sharded cluster, +working on one :program:`mongos` at a time. + +.. include:: /includes/steps/enable-authentication-in-shardcluster-nodowntime-transition-mongos.rst + +At the end of this section, all :program:`mongos` instances in the sharded +cluster are running with :setting:`security.transitionToAuth` and +:setting:`security.keyFile` internal authentication. + +Restart Each Config Server Replica Set Member with ``transitionToAuth`` set to ``true`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Repeat these steps for each :program:`mongod` in the config server replica +set, one member at a time. Work on the :term:`secondary` or :term:`arbiter` +members *first*, and the :term:`primary` *last*. + +.. include:: /includes/steps/enable-authentication-in-shardcluster-nodowntime-transition-config.rst + +At the end of this section, all :program:`mongod` instances in the config +server replica set is running with :setting:`security.transitionToAuth` and +:setting:`security.keyFile` internal authentication. + +Restart Each Member of Each Shard Replica Set with ``transitionToAuth`` set to ``true`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Create the shard-local administrator +++++++++++++++++++++++++++++++++++++ + +Each shard replica set in a sharded cluster that enforces authentication +should have its own shard-local administrator. You cannot use a shard-local +administrator for one shard to access another shard or the sharded cluster. + +At the completion of this tutorial, if you want to connect to the shard for +performing maintenance operations on the shard replica set, you must +authenticate as the shard-local administrator. + +Connect to the :term:`primary` member of the shard replica set and create a +user with the :method:`db.createUser()` method, assigning it the following +roles: + +- :authrole:`clusterAdmin` on the ``admin`` database +- :authrole:`userAdmin` roles on the ``admin`` database + +.. code-block:: javascript + + admin = db.getSiblingDB("admin") + admin.createUser( + { + user: "admin", + pwd: "", + roles: [ + { role: "clusterAdmin", db: "admin" }, + { role: "userAdmin", db: "admin" } + ] + } + ) + +.. note:: + + Only connect to individual shard replica sets for performing + maintenance operations. Connect to a :program:`mongos` for + performing queries or cluster-level maintenance operations. + +Procedure ++++++++++ + +Repeat these steps for each shard replica set in the sharded cluster. + +Perform these steps on one shard replica set at a time, and one member in the +shard replica set at a time. Work on the :term:`secondary` or :term:`arbiter` +members *first*, and the :term:`primary` *last*. + +.. include:: /includes/steps/enable-authentication-in-shardcluster-nodowntime-transition-shards.rst + +At this point in the tutorial, every component of the sharded cluster is +running with :option:`--transitionToAuth` and :setting:`security.keyFile` +internal authentication. The sharded cluster has at least one administrative +user, and each shard replica set has a shard-local administrative user. + +The following sections involve taking the sharded cluster out of the +transition state to fully enforce authentication. + +Restart Each ``mongos`` Instance without ``transitionToAuth`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. important:: + + At the end of this section, clients must specify authentication + credentials to connect to the sharded cluster. Update clients to specify + authentication credentials *before* completing this section to avoid loss of + connectivity. + +To complete the transition to fully enforcing authentication in the +sharded cluster, you must restart each :program:`mongos` instance without +the :setting:`security.transitionToAuth` setting. + +Perform these steps for each :program:`mongos` in the sharded cluster, +working on one :program:`mongos` at a time. + +.. include:: /includes/steps/enable-authentication-in-shardcluster-nodowntime-auth-mongos.rst + +At the end of this section, all :program:`mongos` instances enforce client +authentication and :setting:`security.keyFile` internal authentication. + +Restart Each Config Server Replica Set Member without ``transitionToAuth`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. important:: + + At the end of this step, clients must specify authentication credentials to + connect to the config server replica set. Update clients to specify + authentication credentials *before* completing this section to avoid loss of + connectivity. + +To complete the transition to fully enforcing authentication in the +sharded cluster, you must restart each :program:`mongod` instance without +the :setting:`security.transitionToAuth` setting. + +Perform these steps for each :program:`mongod` in the config server replica +set, one member at a time. Work on the :term:`secondary` or +:term:`arbiter` members *first*, and the :term:`primary` *last*. + +.. include:: /includes/steps/enable-authentication-in-shardcluster-nodowntime-auth-config.rst + +At the end of this section, all :program:`mongod` instances in the config +server replica set enforce client authentication and +:setting:`security.keyFile` internal authentication. + +Restart Each Member in Each Shard Replica Set without ``transitionToAuth`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. important:: + + At the end of this step, clients must specify authentication credentials to + connect to the shard replica set. Update clients to specify authentication + credentials *before* completing this section to avoid loss of connectivity. + +To complete the transition to fully enforcing authentication in the sharded +cluster, you must restart every member of every shard replica set in the +sharded cluster without the :setting:`security.transitionToAuth` setting. + +Repeat these steps for each shard replica set in the sharded cluster. + +Perform these steps on one shard replica set at a time, and one member in the +shard replica set at a time. Work on the :term:`secondary` or :term:`arbiter` +members *first*, and the :term:`primary` *last*. + +.. include:: /includes/steps/enable-authentication-in-shardcluster-nodowntime-auth-shard.rst + +At the end of this section, all :program:`mongos` and :program:`mongod` +instances in the sharded cluster enforce client authentication and +:setting:`security.keyFile` internal authentication. Clients can only connect +to the sharded cluster by using the configured client authentication mechanism. +Additional components can only join the cluster by specifying the correct +keyfile. + +x.509 Certificate Internal Authentication +----------------------------------------- + +MongoDB supports x.509 certificate authentication for use with a secure TLS/SSL +connection. Sharded cluster members and replica set members can use x.509 +certificates to verify their membership to the cluster or the replica set +instead of using :ref:`internal-auth-keyfile`. + +For details on using x.509 certificates for internal authentication, see +:doc:`/tutorial/configure-x509-member-authentication`. + +:doc:`/tutorial/upgrade-keyfile-to-x509` describes how to upgrade a +deployment's internal auth mechanism from keyfile-based authentication to x.509 +certificate-based auth. From b9bfc452a9fbdd2d0066e20564963c597f1757dd Mon Sep 17 00:00:00 2001 From: ravind Date: Fri, 10 Feb 2017 14:43:42 -0500 Subject: [PATCH 2/3] DOCS-8616: Kay CR --- ...n-shardcluster-nodowntime-auth-config.yaml | 4 +-- ...n-shardcluster-nodowntime-auth-mongos.yaml | 12 ++++---- ...dcluster-nodowntime-transition-config.yaml | 19 ++++++------ ...dcluster-nodowntime-transition-mongos.yaml | 30 +++++++++++-------- ...cation-in-shardcluster-nodowntime-uac.yaml | 19 +++++------- ...n-existing-sharded-cluster-no-downtime.txt | 12 ++++---- 6 files changed, 47 insertions(+), 49 deletions(-) diff --git a/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-auth-config.yaml b/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-auth-config.yaml index 0676ecf7a5d..0c5d1518988 100644 --- a/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-auth-config.yaml +++ b/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-auth-config.yaml @@ -21,8 +21,8 @@ source: ref: restart-mongod post: | - At the end of this section, the config server replica set should be up and - running fully enforcing authentication. + At the end of this section the config server replica set should be up and + running, fully enforcing authentication. Users and client applications *must* specify authentiation credentials when connecting to the config server replica set. diff --git a/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-auth-mongos.yaml b/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-auth-mongos.yaml index b32bc5f0419..f9653cd8269 100644 --- a/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-auth-mongos.yaml +++ b/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-auth-mongos.yaml @@ -32,15 +32,12 @@ pre: | db.getSiblingDB("admin").shutdownServer() - You can then start the :program:`mongos` specifying the updated - configuration file, specifying the path to the config file using - :option:`--config`.. This configuration file no longer contains the - :setting:`security.transitionToAuth` setting, but retains the - :setting:`security.keyFile` setting. + You can then restart the :program:`mongos specifying the path to the updated + config file using :option:`--config`. .. example:: - The following operation starts the :program:`mongos` specifying + The following operation restarts the :program:`mongos` specifying the updated configuration file, here named ``mongos-secure.conf``. The ```` represents the system path to the folder containing the configuration file. @@ -52,4 +49,5 @@ pre: | .. note:: MongoDB deployments running on :abbr:`Windows (Microsoft Windows)` use - the ``.cfg`` file extension instead of ``.conf``. + the ``.cfg`` file extension instead of ``.conf``, and + :program:`mongos.exe` instead of :program:`mongos`. diff --git a/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-transition-config.yaml b/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-transition-config.yaml index 47902f0e653..b8332262721 100644 --- a/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-transition-config.yaml +++ b/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-transition-config.yaml @@ -4,11 +4,12 @@ title: "Add ``transitionToAuth: true`` to the ``mongod`` configuration file." ref: modify-config-files pre: | - Copy the existing {{program}} configuration file and name the copy to - distinguish it, for example, by adding ``-secure`` to the filename. You will - use this new configuration file to transition the {{program}} to enforce - authentication in the sharded cluster. Retain the original configuration - file for backup purposes. + Copy the existing {{program}} configuration file, giving it a distinct + name such as ``-secure``. + + You will use this new configuration file to transition the {{program}} to + enforce authentication in the sharded cluster. Retain the original + configuration file for backup purposes. Add the following settings to the new configuration file. @@ -25,8 +26,8 @@ pre: | * - :setting:`security.keyFile` - Path to the keyfile. - If using a different internal authentication mechanism, specify that - mechanism instead of :setting:`security.keyFile`. + If using a different internal authentication mechanism, specify + settings appropriate for the mechanism. The new configuration file should contain all of the configuration settings previously used by the {{program}}, as well as the new security @@ -59,7 +60,7 @@ pre: | down the primary and trigger an election. You can use the :method:`rs.status()` method to ensure the replica set elected a new primary. - Once you step down the primary, you can then shut it down using the + Once you step down the primary, you shut it down using the :method:`db.shutdownServer()` method against the ``admin`` database. .. code-block:: javascript @@ -67,7 +68,7 @@ pre: | db.getSiblingDB("admin").rs.stepDown() db.getSiblingDB("admin").shutdownServer() - You can then restart the :program:`mongod` with the {{status}} configuration + Restart the :program:`mongod` with the {{status}} configuration file, specifying the path to the config file using :option:`--config`. .. example:: diff --git a/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-transition-mongos.yaml b/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-transition-mongos.yaml index 97ffc7a1aa9..1d8dcf11640 100644 --- a/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-transition-mongos.yaml +++ b/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-transition-mongos.yaml @@ -4,11 +4,12 @@ title: "Add ``transitionToAuth: true`` to the ``mongos`` configuration file" ref: modify-config-files pre: | - Copy the existing {{program}} configuration file and name the copy to - distinguish it, for example, by adding ``-secure`` to the filename. You will - use this new configuration file to transition the {{program}} to enforce - authentication in the sharded cluster. Retain the original configuration - file for backup purposes. + Copy the existing {{program}} configuration file, giving it a distinct + name such as ``-secure``. + + You will use this new configuration file to transition the {{program}} to + enforce authentication in the sharded cluster. Retain the original + configuration file for backup purposes. Add the following settings to the new configuration file. @@ -25,8 +26,8 @@ pre: | * - :setting:`security.keyFile` - Path to the keyfile. - If using a different internal authentication mechanism, specify that - mechanism instead of :setting:`security.keyFile`. + If using a different internal authentication mechanism, specify + settings appropriate for the mechanism. The new configuration file should contain all of the configuration settings previously used by the {{program}}, as well as the new security @@ -50,17 +51,20 @@ pre: | method against the ``admin`` database to safely shut down the :program:`mongos`. - Restart one :program:`mongos` at a time to ensure that clients - can connect to the sharded cluster. If your cluster has only one - :program:`mongos`, this step results in downtime while the :program:`mongos` - is offline. + Restart one :program:`mongos` at a time to ensure that clients can connect + to the sharded cluster. If your cluster has only one :program:`mongos`, this + step results in downtime while the :program:`mongos` is offline. + + Connect to the :program:`mongos` and use the :method:`db.shutdownServer()` + method against the ``admin`` database to safely shut down the + :program:`mongos`. .. code-block:: javascript db.getSiblingDB("admin").shutdownServer() - You can then start the :program:`mongos` with the new configuration - file, specifying the path to the config file using :option:`--config`. + Restart :program:`mongos` with the new configuration file, specifying the + path to the config file using :option:`--config`. .. example:: diff --git a/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-uac.yaml b/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-uac.yaml index 639087dc812..91cb79e6a50 100644 --- a/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-uac.yaml +++ b/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-uac.yaml @@ -7,7 +7,7 @@ pre: | Clients performing maintenance operations or user administrative operations on the {{CLUSTER}} must authenticate as this user at the completion of this tutorial. Create this user now to ensure - that you have seamless access to the cluster after enforcing authentication. + that you have access to the cluster after enforcing authentication. Create a user with the :method:`db.createUser()` method and assign it the following roles: @@ -35,12 +35,7 @@ post: | .. important:: Passwords should be random, long, and complex to ensure system security - and to prevent or delay malicious access. - - While this tutorial uses a single administrative user, you should - consider applying the `principle of least privilege - `_ - when configuring MongoDB users in your deployment. + and to prevent or hinder malicious access. replacement: CLUSTER: "sharded cluster" @@ -50,15 +45,15 @@ title: "Create users for client applications to authenticate with." optional: true pre: | - You can create users for your client applications to authenticate with prior + You can create users for your client applications to authenticate prior to enforcing authentication in the sharded cluster. This ensures - seamless access to the sharded cluster once you fully enforce authentication. + access to the sharded cluster once you fully enforce authentication. .. example:: - The following operation creates the user ``joe`` on the ``analytics`` + The following operation creates the user ``joe`` on the ``marketing`` database, assigning it the :authrole:`readWrite` :ref:`built-in role - `. + ` on the ``marketing`` database`. .. code-block:: javascript @@ -66,7 +61,7 @@ pre: | { "user": "joe", "pwd": "", - "roles": [ { "role" : "readWrite", "db" : "analytics" } ] + "roles": [ { "role" : "readWrite", "db" : "marketing" } ] } ) diff --git a/source/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime.txt b/source/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime.txt index 7a4f3fed9a0..3b792cf5003 100644 --- a/source/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime.txt +++ b/source/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime.txt @@ -1,5 +1,5 @@ ========================================================================== -Enable mandatory user authentication in a sharded cluster without downtime +Enable Mandatory User Authentication in a Sharded Cluster Without Downtime ========================================================================== .. default-domain:: mongodb @@ -32,7 +32,7 @@ A MongoDB sharded cluster can enforce :ref:`user authentication authentication ` among the sharded cluster :program:`mongod` and :program:`mongos` components. -This tutorial describes a correct procedure for using +This tutorial describes a procedure for using :setting:`security.transitionToAuth` to enable access control in an existing MongoDB sharded cluster without incurring downtime. @@ -194,7 +194,7 @@ Procedure Repeat these steps for each shard replica set in the sharded cluster. Perform these steps on one shard replica set at a time, and one member in the -shard replica set at a time. Work on the :term:`secondary` or :term:`arbiter` +shard replica set at a time. Work on the :term:`secondary` members *first*, and the :term:`primary` *last*. .. include:: /includes/steps/enable-authentication-in-shardcluster-nodowntime-transition-shards.rst @@ -244,8 +244,8 @@ sharded cluster, you must restart each :program:`mongod` instance without the :setting:`security.transitionToAuth` setting. Perform these steps for each :program:`mongod` in the config server replica -set, one member at a time. Work on the :term:`secondary` or -:term:`arbiter` members *first*, and the :term:`primary` *last*. +set, one member at a time. Work on the :term:`secondary` or members *first*, +and the :term:`primary` *last*. .. include:: /includes/steps/enable-authentication-in-shardcluster-nodowntime-auth-config.rst @@ -269,7 +269,7 @@ sharded cluster without the :setting:`security.transitionToAuth` setting. Repeat these steps for each shard replica set in the sharded cluster. Perform these steps on one shard replica set at a time, and one member in the -shard replica set at a time. Work on the :term:`secondary` or :term:`arbiter` +shard replica set at a time. Work on the :term:`secondary` members *first*, and the :term:`primary` *last*. .. include:: /includes/steps/enable-authentication-in-shardcluster-nodowntime-auth-shard.rst From e8f16ff4d8197fb3cde30258bdada0e94e75b292 Mon Sep 17 00:00:00 2001 From: ravind Date: Thu, 16 Feb 2017 15:56:28 -0500 Subject: [PATCH 3/3] DOCS-8616: More CR Changes --- ...ication-in-shardcluster-nodowntime-auth-mongos.yaml | 2 +- ...n-in-shardcluster-nodowntime-transition-config.yaml | 10 +++++----- ...n-in-shardcluster-nodowntime-transition-mongos.yaml | 4 ---- ...control-in-existing-sharded-cluster-no-downtime.txt | 6 +++--- 4 files changed, 9 insertions(+), 13 deletions(-) diff --git a/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-auth-mongos.yaml b/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-auth-mongos.yaml index f9653cd8269..fc0b98dde99 100644 --- a/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-auth-mongos.yaml +++ b/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-auth-mongos.yaml @@ -32,7 +32,7 @@ pre: | db.getSiblingDB("admin").shutdownServer() - You can then restart the :program:`mongos specifying the path to the updated + You can then restart the :program:`mongos` specifying the path to the updated config file using :option:`--config`. .. example:: diff --git a/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-transition-config.yaml b/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-transition-config.yaml index b8332262721..4841b3c0fda 100644 --- a/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-transition-config.yaml +++ b/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-transition-config.yaml @@ -47,20 +47,20 @@ ref: restart-mongod title: "Restart the ``mongod`` with the new configuration file." pre: | - Connect to the :program:`mongod` and use the :method:`db.shutdownServer()` - method against the ``admin`` database to safely shut down the - :program:`mongod`. + If upgrading the a :term:`secondary`, connect to the :program:`mongod` and + use the :method:`db.shutdownServer()` method against the ``admin`` database + to safely shut down the :program:`mongod`. .. code-block:: javascript db.getSiblingDB("admin").shutdownServer() - If you are performing this step on the :term:`primary`, you must first use + If upgrading the :term:`primary`, connect to the :program:`mongod` and use the :method:`rs.stepDown()` method against the ``admin`` database to step down the primary and trigger an election. You can use the :method:`rs.status()` method to ensure the replica set elected a new primary. - Once you step down the primary, you shut it down using the + Once you step down the primary, shut it down using the :method:`db.shutdownServer()` method against the ``admin`` database. .. code-block:: javascript diff --git a/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-transition-mongos.yaml b/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-transition-mongos.yaml index 1d8dcf11640..7d8dc29686b 100644 --- a/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-transition-mongos.yaml +++ b/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-transition-mongos.yaml @@ -47,10 +47,6 @@ ref: restart-mongos title: "Restart the ``mongos`` with the new configuration file." pre: | - Connect to the :program:`mongos` and use the :method:`db.shutdownServer()` - method against the ``admin`` database to safely shut down the - :program:`mongos`. - Restart one :program:`mongos` at a time to ensure that clients can connect to the sharded cluster. If your cluster has only one :program:`mongos`, this step results in downtime while the :program:`mongos` is offline. diff --git a/source/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime.txt b/source/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime.txt index 3b792cf5003..a11aa041ba6 100644 --- a/source/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime.txt +++ b/source/tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime.txt @@ -244,8 +244,8 @@ sharded cluster, you must restart each :program:`mongod` instance without the :setting:`security.transitionToAuth` setting. Perform these steps for each :program:`mongod` in the config server replica -set, one member at a time. Work on the :term:`secondary` or members *first*, -and the :term:`primary` *last*. +set, one member at a time. Start with the :term:`secondary` members +*first*, and the :term:`primary` *last*. .. include:: /includes/steps/enable-authentication-in-shardcluster-nodowntime-auth-config.rst @@ -269,7 +269,7 @@ sharded cluster without the :setting:`security.transitionToAuth` setting. Repeat these steps for each shard replica set in the sharded cluster. Perform these steps on one shard replica set at a time, and one member in the -shard replica set at a time. Work on the :term:`secondary` +shard replica set at a time. Start with the :term:`secondary` members *first*, and the :term:`primary` *last*. .. include:: /includes/steps/enable-authentication-in-shardcluster-nodowntime-auth-shard.rst