diff --git a/source/includes/steps-3.0-upgrade-mongodb-cr-to-scram.yaml b/source/includes/steps-3.0-upgrade-mongodb-cr-to-scram.yaml index 42df62146c2..49a4ae72f96 100644 --- a/source/includes/steps-3.0-upgrade-mongodb-cr-to-scram.yaml +++ b/source/includes/steps-3.0-upgrade-mongodb-cr-to-scram.yaml @@ -1,6 +1,4 @@ -title: - text: Connect to the MongoDB instance. - character: '`' +title: Connect to the MongoDB instance. stepnum: 1 ref: connect content: | @@ -11,28 +9,23 @@ content: | --- title: text: Upgrade authentication schema. - character: '`' ref: upgrade-auth-schema stepnum: 2 pre: | Use the :dbcommand:`authSchemaUpgrade` command in the ``admin`` database to update the user data using the :program:`mongo` shell. action: - - heading: - text: Run ``authSchemaUpgrade`` command. - character: "'" + - heading: Run ``authSchemaUpgrade`` command. language: javascript code: | db.adminCommand({authSchemaUpgrade: 1}); post: | In case of error, you may safely rerun the :dbcommand:`authSchemaUpgrade` command. - - heading: - text: Sharded cluster ``authSchemaUpgrade`` consideration. - character: "'" + - heading: Sharded cluster ``authSchemaUpgrade`` consideration. pre: | For a sharded cluster *without* :ref:`shard local users - <_sharding-security>`, :dbcommand:`authSchemaUpgrade` will, by + `, :dbcommand:`authSchemaUpgrade` will, by default, upgrade the authorization data of the shards as well, completing the upgrade. diff --git a/source/release-notes/3.0-scram.txt b/source/release-notes/3.0-scram.txt index b4c3c00b55c..9f47fcb3f83 100644 --- a/source/release-notes/3.0-scram.txt +++ b/source/release-notes/3.0-scram.txt @@ -6,9 +6,12 @@ MongoDB 3.0 and SCRAM-SHA-1 .. default-domain:: mongodb +Overview +-------- + MongoDB 3.0 includes support for the :ref:`SCRAM-SHA-1 ` challenge-response user authentication -mechanism. This changes how user credentials are stored and used. If +mechanism. This changes how MongoDB uses and stores user credentials. If your deployment uses authentication and authorization, you must upgrade the authentication schema in addition to upgrading MongoDB processes if you wish to make use of ``SCRAM-SHA-1``. @@ -18,19 +21,23 @@ challenge-response mechanism and skip this upgrade. See the :ref:`SCRAM-SHA-1 ` documentation for further information on its advantages. -.. note:: +Recommendation +~~~~~~~~~~~~~~ + +``SCRAM-SHA-1`` represents a significant improvement in security +over ``MONGODB-CR``, the previous default authentication mechanism: +you are strongly urged to upgrade. The next major version of +MongoDB is likely to remove all support for ``MONGODB-CR``. - ``SCRAM-SHA-1`` represents a significant improvement in security - over ``MONGODB-CR``, the previous default authentication mechanism, - and you are strongly urged to upgrade. The next major version of - MongoDB is likely to remove support for ``MONGODB-CR`` entirely. +Upgrade Scenarios +~~~~~~~~~~~~~~~~~ The following scenarios are possible when upgrading from 2.6 to 3.0: - If you are starting with a new 3.0 installation without any users or upgrading from a 2.6 database that has no users and wish to use ``SCRAM-SHA-1``, **no action is required**. All new users created in - this situation will be created using the appropriate format for + will have the correct format for ``SCRAM-SHA-1``. - If you are upgrading from a 2.6 database with existing data, @@ -44,30 +51,24 @@ The following scenarios are possible when upgrading from 2.6 to 3.0: follow the steps under the heading :ref:`Upgrade a 2.6 Database to Use SCRAM-SHA-1 on 3.0 <2.8-upgrade-mongodb-cr-to-scram>`. -Upgrade a 2.6 Database to Use ``SCRAM-SHA-1`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. important:: - - This procedure **discards** the ``MONGODB-CR`` credentials used by - 2.6, and therefore is irreversible short of restoring from - backups. - - This procedure disables ``MONGODB-CR`` as an authentication - mechanism. - Considerations -`````````````` +-------------- Before upgrading the authentication model, you should first upgrade MongoDB binaries to 3.0. For sharded clusters, ensure that **all** cluster components are 3.0. +Requirements +~~~~~~~~~~~~ + +To upgrade the authentication model, you must have a user in the +``admin`` database with the role :authrole:`userAdminAnyDatabase`. + Timing -`````` +~~~~~~ Because downgrades are more difficult after you upgrade the user -authentication model, once you upgrade the MongoDB binaries to +authentication model, after upgrading the MongoDB binaries to version 3.0, allow your MongoDB deployment to run for a day or two before following this procedure. @@ -83,22 +84,22 @@ after upgrading the sharded clusters to run the authentication upgrade command. Replica Sets -```````````` +~~~~~~~~~~~~ For a replica set, it is only necessary to run the upgrade process on the :term:`primary` as the changes will automatically replicate to the secondaries. Sharded Clusters -```````````````` +~~~~~~~~~~~~~~~~ -For a sharded cluster, connect to a :program:`mongos` and run the +For a sharded cluster, connect to one :program:`mongos` instance and run the upgrade procedure to upgrade the cluster's authentication data. By default, the procedure will upgrade the authentication data of the shards as well. -To override this behavior, run the upgrade command with the -additional parameter ``upgradeShards: false``. If you choose to +To override this behavior, run the upgrade operation (i.e. :dbcommand:`authSchemaUpgrade`) with the +parameter ``upgradeShards: false``. If you choose to override, you must run the upgrade procedure on the :program:`mongos` first, and then run the procedure on the :term:`primary` members of each shard. @@ -109,19 +110,22 @@ against the :doc:`config servers process using one :program:`mongos` instance to interact with the config database. -Requirements -```````````` +Procedure: Upgrade a 2.6 Database to Use ``SCRAM-SHA-1`` +-------------------------------------------------------- -To upgrade the authentication model, you must have a user in the -``admin`` database with the role :authrole:`userAdminAnyDatabase`. +.. important:: -Procedure -````````` + This procedure **discards** the ``MONGODB-CR`` credentials used by + 2.6, and therefore is irreversible short of restoring from + backups. + + This procedure disables ``MONGODB-CR`` as an authentication + mechanism. -.. include:: /includes/steps/2.8-upgrade-mongodb-cr-to-scram.rst +.. include:: /includes/steps/3.0-upgrade-mongodb-cr-to-scram.rst Result -`````` +------ After this procedure is complete, all users in the database will have ``SCRAM-SHA-1``-style credentials, and any subsequently-created users diff --git a/source/release-notes/3.0-upgrade.txt b/source/release-notes/3.0-upgrade.txt index 6b4a84fa378..baa94f4a1d8 100644 --- a/source/release-notes/3.0-upgrade.txt +++ b/source/release-notes/3.0-upgrade.txt @@ -269,6 +269,7 @@ WiredTiger. Upgrade Authentication Schema to Enable ``SCRAM-SHA-1`` ``````````````````````````````````````````````````````` + See :ref:`2.8-scram` for details on ``SCRAM-SHA-1`` upgrade scenarios. .. include:: /includes/2.6-3.0-upgrade-downgrade-procedure.rst diff --git a/source/release-notes/3.0.txt b/source/release-notes/3.0.txt index e9870d673fe..f208aab567c 100644 --- a/source/release-notes/3.0.txt +++ b/source/release-notes/3.0.txt @@ -67,7 +67,7 @@ engine, see :setting:`storage.wiredTiger` configuration options. You can set :ref:`WiredTiger options on the command line `. -.. seealso:: +.. seealso:: :ref:`storage-wiredtiger` section in the :doc:`/core/storage` documentation @@ -75,7 +75,7 @@ WiredTiger Concurrency and Compression `````````````````````````````````````` The 3.0 WiredTiger storage engine provides document-level locking and -compression. +compression. By default, WiredTiger compresses collection data using the :term:`snappy` compression library. WiredTiger uses :term:`prefix @@ -380,6 +380,7 @@ Upgrade Process .. toctree:: /release-notes/3.0-upgrade + /release-notes/3.0-scram /release-notes/3.0-downgrade See :doc:`/release-notes/3.0-upgrade` for full upgrade instructions.