2.6.txt

:orphan:

========================================================
Release Notes for MongoDB 2.6 (Development Series 2.5.x)
========================================================

.. default-domain:: mongodb

MongoDB 2.6 is currently in development, as part of the 2.5
development release series. While 2.5-series releases are currently
available, these versions of MongoDB are for **testing only and
not for production use**.

This document will eventually contain the full release notes for
MongoDB 2.6; before its release this document covers the 2.5
development series as a work-in-progress.

.. contents:: See the :doc:`full index of this page <2.6-changes>` for
              a complete list of changes included in 2.6 (Development
              Series 2.5.x).
   :backlinks: none
   :local:
   :depth: 2

Downloading
-----------

You can download the current 2.5 development release on the `downloads
page`_ in the :guilabel:`Development Release (Unstable)`
section. There are no distribution packages for development releases,
but you can use the binaries provided for testing purposes. See
:doc:`/tutorial/install-mongodb-on-linux`,
:doc:`/tutorial/install-mongodb-on-windows`, or
:doc:`/tutorial/install-mongodb-on-os-x` for the basic installation
process.

.. _`downloads page`: http://www.mongodb.org/downloads

Compatibility Changes
---------------------

.. important:: The MongoDB 2.5-series, which will become MongoDB 2.6,
   is for testing and development **only**. All identifiers, names,
   interfaces are subject to change. Do **not** use a MongoDB 2.5
   release in production situations.

SNMP Enterprise Identifier Changed
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. DOCS-1696

In 2.5.1, the IANA enterprise identifier for MongoDB changed from
37601 to 34601. Users of SNMP monitoring must modify their SNMP
configuration (i.e. MIB) accordingly.

Default ``bind_ip`` for RPM and DEB Packages
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In the packages provided by 10gen for MongoDB in RPM (Red Hat, CentOS,
Fedora Linux, and derivatives) and DEB (Debian, Ubuntu, and
derivatives,) the default :setting:`bind_ip` value attaches MongoDB
components to the localhost interface *only*. These packages set this
default in the default configuration file
(i.e. ``/etc/mongodb.conf``.)

If you use one of these packages and have *not* modified the default
``/etc/mongodb.conf`` file, you will need to set :setting:`bind_ip`
before or during the upgrade.

There is no default ``bind_ip`` setting in any other 10gen distributions
of MongoDB.

``isMaster`` Comand includes Wire Protocol Versions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. versionadded:: 2.5.0

In order to support changes to the wire protocol both now and in the
future, the output of :dbcommand:`isMaster` now contains two new
fields that report the earliest version of the wire protocol that this
:program:`mongod` instance supports and the highest version of the
wire protocol that this :program:`mongo` instance supports. See
:data:`~isMaster.minWireVersion` and :data:`~isMaster.maxWireVersion`
for more information.

Replica Set Vote Configuration Validation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. versionadded:: 2.5.3

MongoDB now deprecates giving any :term:`replica set` member more than
a single vote. During configuration,
:data:`local.system.replset.members[n].votes` should only have a value
of 1 for voting members and 0 for non-voting members. MongoDB treats
values other than 1 or 0 as a value of 1 and produces a warning message.

.. _agg-helper-incompatibility:

Behavior of ``aggregate()`` Method in the ``mongo`` Shell
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. versionchanged:: 2.5.3

.. the text of this message will improve and become more clear before
   2.6 whenwe remove mention of 2.5-series releases.


The :method:`db.collection.aggregate()` helper now :ref:`returns a
cursor <rn-2.6-aggregation-cursor>`. As a result, you cannot use the
:method:`~db.collection.aggregate()` method from a 2.5.3 (or later)
version of the :program:`mongo` shell while connected to 2.4 (and
earlier) versions of MongoDB.

To perform aggregation on earlier versions of MongoDB, use either a
previous version of the :program:`mongo` shell or if using the 2.5.3
(or later) version of the :program:`mongo` shell, run the
:dbcommand:`aggregate` command, not the
:method:`db.collection.aggregate()` helper, without specifying the
``cursor`` option.

.. TODO DOCS-1948 Uncomment when this feature is complete

   MongoDB Refuses to Insert Documents that Cannot be Indexed
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   In 2.5.3, MongoDB will *not* insert documents into collections if
   the content of an indexed field exceeds the :limit:`Maximum Index
   Key Length <Index Key>` and return an error. In previous versions of
   MongoDB, such documents were inserted but not indexed.

.. _authentication-incompatibility:

Authentication and Authorization Incompatibility
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. important::
   For authentication/authorization, the 2.5.3 release does not
   offer an automatic upgrade process to go from version 2.4 model for
   user credentials and privileges to the 2.5.3 model. However, version
   2.5.4 **will** provide an automatic upgrade process.

MongoDB 2.5.3 does not offer an automatic upgrade process to go from
version 2.4 model :doc:`user privilege documents
</reference/privilege-documents>` to the :ref:`2.5.3. model
<user-defined-roles>`.

In order to *test* your existing database with the :ref:`MongoDB 2.5.3
authentication/authorization <user-defined-roles>`, you must remove all
the users from the ``system.users`` collection in the ``admin``
database and create new users with the new user privilege model. One
option is to delete all the users while running with
:option:`authorization <--auth>` disabled, and create the first user
with the role { role: "root", db: "admin" } using the
:method:`db.addUser` helper in the :program:`mongo` shell.

Version 2.5.3 is for testing and development **only**.

``$mod`` Query Operator Enforces Strict Syntax
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The :query:`$mod` operator now only accepts an array with exactly two
elements, and errors when passed an array with fewer or more elements.
In previous versions, if passed an array with one element, the
:query:`$mod` operator uses ``0`` as the second element, and if passed
an array with more than two elements, the :query:`$mod` ignores all but
the first two elements. Previous versions do return an error when
passed an empty array.

See :ref:`mod-not-enough-elements` and :ref:`mod-too-many-elements` for
details.

Changes
-------

.. important:: The MongoDB 2.5-series, which will become MongoDB 2.6,
   is for testing and development **only**. All identifiers, names,
   interfaces are subject to change. Do **not** use a MongoDB 2.5
   release in production situations.

Aggregation Pipeline Changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. _aggregation-method-change:

``db.collection.aggregation()`` Accepts Second Parameter
````````````````````````````````````````````````````````

In the 2.5.3 version of the :program:`mongo` shell, the
:method:`db.collection.aggregate()` helper can now accept as a second
parameter a document of options:

.. code-block:: javascript

   db.collection.aggregate( [ <pipeline> ], { options } )

The second parameter is *optional*.

The updated :method:`db.collection.aggregate()` helper supports legacy
syntax and accepts the pipeline stages as separate arguments. For
example,

.. code-block:: javascript

   db.collection.aggregate( { $match: ... }, { $group: ...} )

However, if you do not specify the ``<pipeline>`` in an array, you
cannot specify options.

.. seealso:: :ref:`agg-helper-incompatibility`

``$out`` Stage to Write Data to a Collection
````````````````````````````````````````````

.. versionadded:: 2.5.2

The aggregation pipeline adds a new stage named :pipeline:`$out` that
writes the result of the pipeline operation to an output collection and
returns an empty result set. In version 2.5.3 of the :program:`mongo`
shell, because the :method:`db.collection.aggregate()` method returns a
cursor, specifying an :pipeline:`$out` stage returns an empty cursor.

See the :doc:`$out documentation </reference/operator/aggregation/out>`
for more information.

.. _rn-2.6-aggregation-cursor:

Aggregation Operations Now Return Cursors
`````````````````````````````````````````

.. There's a few other edits in the content below to make our statements stronger.

.. DOCS-1835

The :method:`db.collection.aggregate()` helper in the :program:`mongo`
shell now returns a cursor. By returning a cursor,
aggregation pipelines can return result sets of any size. In previous
versions, the result of an aggregation operation could be no larger
than 16 megabytes.

To perform aggregation on older servers, use either a previous version
of the :program:`mongo` shell or if using the 2.5.3 :program:`mongo`
shell, run the :dbcommand:`aggregate` command, not the
:method:`db.collection.aggregate()` helper, without specifying the
``cursor`` option.

Cursors returned from aggregation only supports cursor methods that
operate on evaluated cursors (i.e. cursors whose first batch has been
retrieved), such as the following methods:

.. hlist::
   :columns: 2

   * :method:`cursor.hasNext()`
   * :method:`cursor.next()`
   * :method:`cursor.toArray()`
   * :method:`cursor.forEach()`
   * :method:`cursor.map()`
   * :method:`cursor.objsLeftInBatch()`
   * :method:`cursor.itcount()`
   * :method:`cursor.pretty()`

.. include:: /includes/important-uses-new-aggregate-helper.rst

The following example returns a cursor from the aggregation operation:

.. code-block:: javascript

   var results = db.records.aggregate(
                                       [
                                         { $project : { name: 1, email: 1, _id: 0 } },
                                         { $sort : { name: 1 } }
                                       ]
                                     )

Like the cursor returned from :method:`db.collection.find()`, in the
:program:`mongo` shell, if the cursor returned from the
:method:`db.collection.aggregate()` is not assigned to a variable using
the ``var`` keyword, then the cursor is automatically iterated up to 20
times. See :doc:`/core/cursors` for cursor behavior in the
:program:`mongo` shell and :doc:`/tutorial/iterate-a-cursor` for
handling cursors in the :program:`mongo` shell.

To specify an *initial* batch size for the cursor, set the option (e.g.
``cursor: { batchSize: <num> }``) in the :ref:`second parameter
<aggregation-method-change>` of the :method:`db.collection.aggregate()`
method. A ``batchSize`` of ``0`` means an empty first batch and is
useful if you want to quickly get back a cursor or a failure message
without doing significant server-side work, as in the following example:

.. code-block:: javascript

   var results = db.records.aggregate(
                                       [
                                         { $project : { name: 1, email: 1, _id: 0 } },
                                         { $sort : { name: 1 } }
                                       ],
                                       {
                                          cursor: { batchSize: 0 }
                                       }
                                     )

The :dbcommand:`aggregate` command may also return a cursor rather than
a result document. To return a cursor object, specify the ``cursor``
option. You can also specify an optional initial batch size to the
command. Using the :dbcommand:`aggregate` command to return a cursor is
a low-level operation, intended for authors of drivers. Most users
should use the :method:`db.collection.aggregate()` helper provided in
the :program:`mongo` shell or in their driver.

The following command returns a document that can be used to
instantiate an object.

.. code-block:: javascript

   db.runCommand(
      { aggregate: "records",
        pipeline: [
           { $project: { name: 1, email: 1, _id: 0 } },
           { $sort: { name: 1 } }
        ],
        cursor: { }
      }
   )

To specify an *initial* batch size, specify the ``batchSize`` in the
``cursor`` field, as in the following example:

.. code-block:: javascript

   db.runCommand(
      { aggregate: "records",
        pipeline: [
           { $project: { name: 1, email: 1, _id: 0 } },
           { $sort: { name: 1 } }
        ],
        cursor: { batchSize: 0 }
      }
   )

The ``{batchSize: 0 }`` document specifies the size of the *initial*
batch size only. Specify subsequent batch sizes to :ref:`OP_GET_MORE
<wire-op-get-more>` operations as with other MongoDB cursors. A
``batchSize`` of ``0`` means an empty first batch and is useful if you
want to quickly get back a cursor or failure message, without doing
significant server-side work.

Improved Sorting
````````````````

.. versionadded:: 2.5.2

The :pipeline:`$sort` and :pipeline:`$group` stages now use a more
efficient sorting system within the :program:`mongod` process. This
improves performance for sorting operations that cannot rely on an
index or that exceed the maximum memory use limit, see
:limit:`Aggregation Sort Operation` for more information.

For large sort operations these "external sort" operations can write
data to the ``_tmp`` sub-directory in the :setting:`dbpath` directory.

To enable external sort, specify the ``allowDiskUsage`` option as the
:ref:`second parameter <aggregation-method-change>` to the
:method:`db.collection.aggregate()` helper.

.. include:: /includes/important-uses-new-aggregate-helper.rst

.. code-block:: javascript

   var results = db.records.aggregate(
                                       [
                                          { $project : { name: 1, email: 1, _id: 0 } },
                                          { $sort : { name : 1 } }
                                       ],
                                       {
                                         allowDiskUsage: true
                                       }
                                     )

For the :dbcommand:`aggregate` command, add the new ``allowDiskUsage``
argument to the :dbcommand:`aggregate` command, as in the following
prototype:

.. code-block:: javascript

   {
     aggregate: "<collection>",
     pipeline: [<pipeline>],
     allowDiskUsage: <boolean>
   }


``$redact`` Stage to Provide Filtering for Field-Level Access Control
`````````````````````````````````````````````````````````````````````

.. include:: /includes/important-uses-new-aggregate-helper.rst

.. pipeline:: $redact

   .. versionadded:: 2.5.2

   Provides a method to restrict the content of a returned document on
   a per-field level.

   .. example::

      Given a collection with the following document in a ``test``
      collection:

      .. code-block:: javascript

         { a: {
                level: 1,
                b: {
                    level: 5,
                    c: {
                        level: 1,
                        message: "Hello"
                    }
                },
                d: "World."
             }
         }

      Consider the following aggregation operation:

      .. code-block:: javascript

         db.test.aggregate(
            { $match: {} },
            { $redact: { $cond: { if: { $lt: [ '$level', 3 ] },
                                  then: "$$DESCEND",
                                  else: "$$PRUNE" }
                       }
            }
         )

      This operation evaluates every object-typed field at every level for all
      documents in the ``test`` collection, and uses the
      :expression:`$cond` expression and the variables ``$$DESCEND``
      and ``$$PRUNE`` to specify the redaction of document parts in the
      aggregation pipeline.

      Specifically, if the field ``level`` is less than 3, (i.e. ``{
      $lt: [ '$level', 3' ] }``) :pipeline:`$redact` continues (i.e.
      ``$$DESCEND``) evaluating the fields and sub-documents at this
      level of the input document. If the value of ``level`` is greater
      than ``3``, then :pipeline:`$redact` removes all data at this
      level of the document.

      The result of this aggregation operation is as follows:

      .. code-block:: javascript

         { a: {
                level: 1,
                d: "World."
         }    }

      You may also specify ``$$KEEP`` as a variable to
      :expression:`$cond`, which returns the entire sub-document
      without traversing, as ``$$DESCEND``.

      .. see:: :expression:`$cond`.

Set Expression Operations in ``$project``
`````````````````````````````````````````

In 2.5.2, the :pipeline:`$project` aggregation pipeline stage now
supports the following set expressions:

.. important:: Set operators take arrays as their arguments and treat
   these arrays as sets. The set operators ignore duplicate entries in
   an input array and produce arrays containing unique entries.

.. expression:: $setIsSubset

   Takes two arrays and returns ``true`` when the first array is a
   subset of the second and ``false`` otherwise.

.. expression:: $setEquals

   Takes two arrays and returns ``true`` when they contain the same
   elements, and ``false`` otherwise.

.. expression:: $setDifference

   Takes two arrays and returns an array containing the elements that
   only exist in the first array.

.. expression:: $setIntersection

   Takes any number of arrays and returns an array that contains the
   elements that appear in every input array.

.. expression:: $setUnion

   Takes any number of arrays and returns an array that containing the
   elements that appear in any input array.

.. expression:: $allElementsTrue

   Takes a single expression that returns an array and returns ``true``
   if all its values are ``true`` and ``false`` otherwise. An empty
   array returns ``true``.

   :expression:`$anyElementsTrue` was ``$all`` in versions of 2.5
   before 2.5.3.

.. expression:: $anyElementTrue

   Takes a single expression that returns an array and returns ``true``
   if any of its values are ``true`` and ``false`` otherwise. An empty
   array returns ``false``.

   :expression:`$anyElementTrue` was ``$any`` in versions of 2.5 before
   2.5.3.

``$map`` and ``$let`` Expressions in Aggregation Pipeline Stages
````````````````````````````````````````````````````````````````

.. tip:: For :expression:`$let` and :expression:`$map`, the
   aggregation framework introduces variables. To specify a variable,
   use the name of the variable prefixed by **2** dollar signs
   (i.e. ``$$``) as in: ``$$<name>``.

The :expression:`$let` and :expression:`$map` make it possible to
declare and manipulate variables within an aggregation pipeline
stages, specifically the :pipeline:`$project`, :pipeline:`$group`, and
:pipeline:`$redact` stages. See: :doc:`/reference/operator/aggregation/let` and
:doc:`/reference/operator/aggregation/map` for more information.

.. expression:: $let

   :expression:`$let` binds variables for use in sub-expressions. For
   example:

   .. code-block:: javascript

      { $project: { remaining: { $let: {
                                         vars: { tally: 75, count: 50 },
                                         in: { $subtract: [ "$$tally", "$$count" ] }
                                        }
                                }
                  }
      }

   Would return a document with the following:

   .. code-block:: javascript

      { remaining: 25 }

   :expression:`$let` is available in the :pipeline:`$project`,
   :pipeline:`$group`, and :pipeline:`$redact` pipeline stages.

.. expression:: $map

   :expression:`$map` applies a sub-expression to each item in an
   array and returns an array with the result of the sub-expression

   :expression:`$map` is available in the :pipeline:`$project`,
   :pipeline:`$group`, and :pipeline:`$redact` pipeline stages.

   Given an input document that resembles the following:

   .. code-block:: javascript

      { skews: [ 1, 1, 2, 3, 5, 8 ] }

   And the following :pipeline:`$project` statement:

   .. code-block:: javascript

      { $project: { adjustments: { $map: { input: "$skews",
                                           as: "adj",
                                           in: { $add: [ "$$adj", 100 ] } } } } }

   The :expression:`$map` would transform the input document into the
   following output document:

   .. code-block:: javascript

      { adjustments: [ 101, 101, 102, 103, 105, 108 ] }

``$literal`` Expression for Aggregation Pipeline Stages
```````````````````````````````````````````````````````

The new :expression:`$literal` operator allows users to explicitly
specify documents in aggregation operations that the pipeline stage
would otherwise interpret directly. See
:doc:`/reference/operator/aggregation/literal` for more information.

``explain`` Option for the Aggregation Pipeline
```````````````````````````````````````````````

The new ``explain`` option for aggregation provides information about
how the command processes the pipeline. The returned document contains
information on each stage of the pipeline.

The intended readers of the ``explain`` output document are humans, and
not machines, and the output format is subject to change between
releases.

To use ``explain``, specify ``explain: true`` as the :ref:`second
parameter <aggregation-method-change>` to the
:method:`db.collection.aggregate()` helper:

.. include:: /includes/important-uses-new-aggregate-helper.rst

.. code-block:: javascript

   db.collection.aggregate( [ <pipeline operations> ],
                            {explain: true }
                          )

.. example::

   In the :program:`mongo` shell, given the following aggregation

   .. code-block:: javascript

      db.records.aggregate(
                            [ { $sort: { name : -1 } },
                              { $limit: 5 }
                            ],
                            { explain: true }
                          )

   The returned document provides information on how
   :dbcommand:`aggregate` processed the pipeline. For this example, the
   returned document may show, among other details, which index, if
   any, the operation used. If the operation did not use an index and
   since the :pipeline:`$sort` immediately precedes the
   :pipeline:`$limit`, the output would show the :pipeline:`$sort`
   operation only maintaining the top 5 results as it progresses rather
   than sorting all input documents. If the ``record`` collection is a
   sharded collection, the output also shows the division of labor
   between the shards and the merge,, and for targeted queries, shows
   the targeted shards.

For the :dbcommand:`aggregate` command, add the ``explain: true`` to the
command, as shown:

.. code-block:: javascript

   db.runCommand( { aggregate: "<collection>",
                    explain: true,
                    pipeline: [ <pipeline operations> ] } )


``$cond`` Accepts Objects as Arguments
``````````````````````````````````````

.. versionadded:: 2.5.3

The ternary :expression:`$cond` expression can now take either an object
or an array. Previously :expression:`$cond` always took an array. See
:doc:`/reference/operator/aggregation/cond` for more information.

New ``$size`` Operator for the Aggregation Pipeline
```````````````````````````````````````````````````

.. include:: /includes/important-uses-new-aggregate-helper.rst

.. versionadded:: 2.5.3

The new :expression:`$size` operator for the :doc:`aggregation
pipeline </core/aggregation-pipeline>` returns the size of a specified
array. See :doc:`/reference/operator/aggregation/size` for more
information.

Write Operation Improvements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. versionadded 2.5.3

MongoDB has updated the wire protocol to include new ``insert``,
``update``, and ``delete`` commands for batch operations. You may
specify a single write concern for each batch of writes. The new
commands support a number of other configuration options including
the ability to proceed if any individual write fails.

MongoDB also introduces new changes to the update language:

``$mul`` Update Operator
````````````````````````

The new :update:`$mul` operator allows you to multiply the value of a
field by the specified amount. See :update:`$mul` for details.

``xor`` operation for ``$bit`` Operator
```````````````````````````````````````

The :update:`$bit` operator now supports bitwise updates using a logical
``xor`` operation. See the documentation of :update:`$bit` for more
information on bitwise updates. Consider the following operation:

``$min`` Update Operator
````````````````````````

The new :update:`$min` operator updates the value of the field to a
specified value *if* the specified value is **less than** the current
value of the field. See :update:`$min` for details.

``$max`` Update Operator
````````````````````````

The new :update:`$max` operator updates the value of the field to a
specified value *if* the specified value is **greater than** the
current value of the field. See :update:`$max` for details.

``$currentDate`` Update Operator
````````````````````````````````

The :update:`$currentDate` operator sets the value of a field to the
current date, either as a :ref:`Date <document-bson-type-date>` or a
:ref:`timestamp <document-bson-type-timestamp>`. See
:update:`$currentDate` for details.

Enhanced Modifiers for ``$push`` Update Operator
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. versionchanged:: 2.5.3

The :update:`$push` operator has enhanced support for the
:update:`$sort`, :update:`$slice`, and :update:`$each` modifiers
to increase functionality and usability. MongoDB also provides a new
:update:`$position` modifier for the :update:`$push` operator.

``$each`` Modifier Changes
``````````````````````````

When used in conjunction with the :update:`$sort`, the
:update:`$slice`, and the :update:`$position` modifiers, the
:update:`$each` modifier no longer needs to be the first modifier for
the :update:`$push`.

``$sort`` Modifier Enhancements
```````````````````````````````

The :update:`$sort` modifier can sort the array elements as a whole.
This change means that the :update:`$sort` modifier can now sort
array elements that are not documents. Or, if the array elements are
documents, the modifier can sort by the whole documents, and not just
by the field in the documents. The :update:`$sort` no longer requires
the :update:`$slice` modifier. See :update:`$sort` for details.

``$slice`` Modifier Enhancements
````````````````````````````````

The :update:`$slice` modifier can accept positive numbers to slice
from the front of the array. See :update:`$slice` for details.

``$position`` Modifier
``````````````````````

The :update:`$position` modifier specifies the insert position for
the :update:`$push` operator. See :update:`$position`.

Sharding Improvements
~~~~~~~~~~~~~~~~~~~~~

Support for Removing Orphan Data From Shards
````````````````````````````````````````````

.. versionadded:: 2.5.2

The new :dbcommand:`cleanupOrphaned` is available to remove orphaned
data from a sharded cluster. Orphaned data are those documents in a
collection that exist on shards that belong to another shard in the
cluster. Orphaned data are the result of failed migrations or incomplete
migration cleanup due to abnormal shutdown.

.. dbcommand:: cleanupOrphaned

   :dbcommand:`cleanupOrphaned` removes documents from *one* orphaned
   chunk range on shard and runs directly on the shard's
   :program:`mongod` instance, and requires the
   :authrole:`clusterAdmin` for systems running with :setting:`auth`.
   You do **not** need to disable the :term:`balancer` to run
   :dbcommand:`cleanupOrphaned`.

   In the common case, :dbcommand:`cleanupOrphaned` takes the
   following form:

   .. code-block:: javascript

      { cleanupOrphaned: <namespace>, startingFromKey: { } }

   The ``startingFromKey`` field specifies the lowest value of the
   :term:`shard key` to begin searching for orphaned data. The empty
   document (i.e. ``{ }``) is equivalent to the minimum value for the
   shard key (i.e. ``$minValue``).

   The :dbcommand:`cleanupOrphaned` command returns a document that
   contains a field named ``stoppedAtKey`` that you can use to
   construct a loop, as in the following example in the
   :program:`mongo` shell:

   .. code-block:: javascript

      db = db.getSiblingDB("admin")

      var nextKey = {};

      while (
         nextKey = db.runCommand( { cleanupOrphaned : "test.user", startingFromKey : nextKey } ).stoppedAtKey
         ) { printjson(nextKey); }

   This loop removes all orphaned data on the shard.

Ability to Merge Co-located Contiguous Chunks
`````````````````````````````````````````````

.. versionadded:: 2.5.2

The :dbcommand:`mergeChunks` provides the ability for users to combine
contiguous chunks located on a single shard. This makes it possible to
combine chunks in situations where document removal leaves a sharded
collection with too many empty chunks.

.. dbcommand:: mergeChunks

   Combines two contiguous chunks located on the same shard. The
   :dbcommand:`mergeChunks` takes the following form:

   .. code-block:: javascript

      { mergeChunks: <namespace>, bounds: [ <minKey>, <maxKey> ] }

   The ``bounds`` option specified to :dbcommand:`mergeChunks` *must*
   be the boundaries of existing chunks in the collections. See the
   output of :method:`sh.status()` to see the current shard
   boundaries.

   .. important:: Both chunks **must** reside on the same shard.

   .. tip:: In 2.5.2, :dbcommand:`mergeChunks` has the following
      restrictions, which are subject to change in future releases:

      - :dbcommand:`mergeChunks` will only merge two chunks.

      - one chunk **must** not hold any documents (i.e. an "empty
        chunk").

.. _collection-level-access-control:

Collection-Level Access Control
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

MongoDB 2.5.3 provides the ability to specify user privileges at a
collection-level granularity. To specify collection-level access
control, create a custom role that pairs its actions to a particular
collection in a specific database in the :ref:`resource document
<resource-document>`. The MongoDB :doc:`built-in roles
</reference/user-privileges>` grant privileges at a database-level
only, and thus cannot be used to control privileges at the
collection-level.

See :ref:`user-defined-roles` for more information.

.. _user-defined-roles:

User Defined Roles
~~~~~~~~~~~~~~~~~~

.. important:: For authentication/authorization, the 2.5.3 release does not
   offer an automatic upgrade process to go from version 2.4 model for
   user credentials and privileges to the 2.5.3 model. See
   :ref:`authentication-incompatibility`.

In version 2.5.3, MongoDB 2.5.3 provides the ability to create custom
:ref:`user roles <custom-user-roles>` in addition to the roles provided by
MongoDB. In addition, MongoDB now provides global user management,
storing all user and user-defined role data in the ``admin`` database
and providing a new set of commands for managing users and roles.

MongoDB uses a role-based approach to authorization. A role grants
privileges to act on various :ref:`resources <resource-document>` to
the user with that role. To create a role is to define its privileges
by pairing resources (e.g. database, collection) with actions (e.g.
``insert``, ``find``), and/or by specifying other roles from which
the role inherits privileges. MongoDB stores the user-defined roles
information in the :ref:`system.roles <admin-system-roles-collection>`
collection of the ``admin`` database.

Both the user-defined roles and roles provided by MongoDB are available
for assignments to users. Assigning roles to a user authorizes the user
to have only the privileges granted by the roles.

User data includes the user's authentication credentials as well as any
roles assigned to the user. MongoDB stores the user data in the
:ref:`system.users <admin-system-users-collection>` collection of the
``admin`` database.

.. _resource-document:

Resource Document
`````````````````

The resource document specifies the resources upon which the
``actions`` for that privilege(s) are permitted.

The resource document can specify a database and a collection:

.. code-block:: javascript

   { db: <database>, collection: <collection> }

If both the ``db`` field and the ``collection`` field are specified,
the resource is the specified collection in the specified database,
providing :ref:`collection-level access control
<collection-level-access-control>`.

If the ``db`` field is an empty string ``""``, the resource is all
collections with the specified name across databases.

If the ``collection`` field is an empty string ``""``, then the
resource is the whole database, excluding the system collections.

If both the ``db`` field and the ``collection`` field are empty strings
``""``, then the resource is all collections, excluding the system
collections, in all the databases.

.. _exclude-system-collections:

.. note:: When you grant access to a full database, the system
   collections are excluded, unless you name them explicitly. System
   collections include but are not limited to the following:

   - :data:`<database>.system.profile`
   - :data:`<database>.system.namespaces`
   - :data:`<database>.system.indexes`
   - :data:`<database>.system.js`
   - :data:`local.system.replset`
   - :ref:`admin.system.users <admin-system-users-collection>`
   - :ref:`admin.system.roles <admin-system-roles-collection>`

Or, the resource document can specify the cluster, as in:

.. code-block:: javascript

   { cluster : true }

Use the ``cluster`` resource for actions that affect the state of the
system rather than act on specific set of databases and/or collections.
Examples of such actions are ``shutdown``, ``replSetReconfig``, and
``enableSharding``. For example, the following privilege document
grants the action ``shutdown`` on the ``cluster``.

.. code-block:: javascript

   { resource: { cluster : true }, actions: [ "shutdown" ] }

New Schema for User and Role Data
`````````````````````````````````

MongoDB stores all user and role information for a system in a single
database, the ``admin`` database, and no longer stores information
separately in each database. The :doc:`system.users
</reference/privilege-documents>` collections in non-``admin``
databases are deprecated, and you can no longer manage users and roles
through updates to these collections. In the ``admin`` database,
MongoDB stores the user-defined roles information in the
:ref:`system.roles <admin-system-roles-collection>` collection and the
users information in the :ref:`system.users
<admin-system-users-collection>` collection.

To manage users and roles, use the new :ref:`user management commands
<user-management-commands>` and :ref:`role-management commands
<role-management-commands>`.

.. todo: Add this to the RNs when the command is ready:

   For upgrades, MongoDB provides the ``upgradeUsers`` command to
   migrate data from the deprecated collections.

.. todo: When we write the upgrade document, use this info from Andy
   as appropriate:

   Upgrade all of the nodes to 2.6 (including the config servers), and
   then run the upgradeUsers command. When that command returns ok: 1,
   the upgrade is complete. If that command fails to return or returns
   some other value, it is always safe to run again.

   To upgrade a single node, run upgradeUsers on that node. For a
   replicaset, run it on the primary. For a sharded cluster, run it on
   *one* mongos, and then run it on the primary of each shard. In this
   last case, the upgrades are independent. If one fails, you only have
   to rerun that one, not all of them.

.. _admin-system-roles-collection:

``system.roles`` Schema
^^^^^^^^^^^^^^^^^^^^^^^

MongoDB stores the user-defined roles information globally in the
``system.roles`` collection of the ``admin`` database and provides
access through the :ref:`role-management commands
<role-management-commands>`.

The ``system.roles`` collection stores roles information in documents
with the following schema:

.. code-block:: javascript

   {
     _id: <system defined id>,
     role: "<role name>",
     db: "<database>",
     privileges: [ { resource: { db: "<database>", collection: "<collection>" },
                     actions: [ "<action>", "<action>", ... ]
                   },
                   ...
                 ]
     roles: [ { role: "<role name>", db: "<role db>" },
              ...
            ]
   }

The ``privileges`` array contains the privileges defined for that role.
Each privilege document specifies a ``resource`` and the ``actions``
(see :ref:`security-user-actions`) permitted on the ``resource``. See
:ref:`resource-document` for details on specifying the ``resource``.

.. todo: from Spencer: clarify the differnce between a server and a cluster, how the
   cluster is used, and what actions need to be granted to the cluster
   resource vs which get granted to a database or collection. In our list
   of grantable actions we'll need to make that really clear.

A role can inherit privileges from other roles. The ``roles`` array
lists other roles from which this role inherits privileges.

The ``privileges`` and ``roles`` arrays can be empty.

.. example:: ``appUser`` role

   The following document in the ``system.roles`` collection shows that
   the ``appUser`` role specifies five privileges in the ``privileges``
   array. As indicated by the empty ``roles`` array, ``appUser``
   inherits no additional privileges from other roles.

   .. code-block:: javascript

      {
        _id: "admin.appUser",
        role: "appUser",
        db: "myApp",
        privileges: [
             { resource: { db: "myApp" , collection: "" },
               actions: [ "find", "createCollection", "dbStats", "collStats" ] },
             { resource: { db: "myApp", collection: "logs" },
               actions: [ "insert" ] },
             { resource: { db: "myApp", collection: "data" },
               actions: [ "insert", "update", "remove", "compact" ] },
             { resource: { db: "myApp", collection: "system.indexes" },
               actions: [ "find" ] },
             { resource: { db: "myApp", collection: "system.namespaces" },
               actions: [ "find" ] },
        ],
        roles: []
      }

   The five privilege documents listed for the ``appUser`` role show
   that the ``appUser`` role has privileges with actions permitted on
   the ``myApp`` database:

   - The first privilege permits its actions ( ``"find"``,
     ``"createCollection"``, ``"dbStats"``, ``"collStats"``) on all the
     collections in the ``myApp`` database *excluding* its system
     collections. See exclude-system-collections_.

   - The next two privileges permits *additional* actions on specific
     collections, ``logs`` and ``data``, in the ``myApp`` database.

   - The last two privileges permits actions on two system collections.
     While the first privilege gives database-wide permission for the
     ``find`` action, the action does not apply to ``myApp``'s system
     collections. To give access to the system collections, privileges
     must specify those collections explicitly. See
     :ref:`resource-document` for more information.

.. example:: ``appAdmin`` role

   The following document shows that the ``appAdmin`` role specifies
   privileges as as well as inherits privileges from other roles. The
   privilege to perform the ``shutdown`` action applies to the
   ``cluster`` resource:

   .. code-block:: javascript

      {
        _id: "myApp.appAdmin",
        role: "appAdmin",
        db: "myApp",
        privileges: [
                 { resource: { db: "myApp", collection: "" },
                   actions: [ "insert", "dbStats", "collStats", "compact", "repairDatabase" ] },
                 { resource: { cluster : true },
                   actions: [ "shutdown" ] }
        ],
        roles: [ { role: "replAdmin", db: "admin" },
                 { role: "appUser", db: "myApp" }
        ]
      }

.. _admin-system-users-collection:

``system.users`` Schema
^^^^^^^^^^^^^^^^^^^^^^^

MongoDB stores users globally in the ``system.users`` collection of the
``admin`` database and provides access through the :ref:`user
management commands <user-management-commands>`.

The ``system.users`` collection stores user information in documents
with the following schema:

.. code-block:: javascript

   {
     _id: <system defined id>,
     user: "<name>",
     db: "<database>",
     credentials: { <authentication credentials> },
     roles: [ { role: "<role>", db: "<database>" },
              ...
            ],
     customData: < custom information >
    }

The ``db`` field specifies the database associated with the user. The
user may, however, have roles in other databases. The ``credentials``
field contains the user's authentication information. [#external]_

The ``roles`` array contains the roles granted to that user. Each
:ref:`role document <role-document>` contains a ``role`` field, which
specifies the name of the role, and a ``db`` field, which specifies the
database the role is defined on.

The ``customData`` field is optional and contains any custom information.

.. [#external] For users with externally stored authentication
   credentials, such as users that use Kerberos or x.509 certificates
   for authentication, the ``systems.users`` document for that user
   does not contain the ``credentials`` field.

.. example::

   The following document in the ``system.users`` collection shows that
   a user ``Kari``, defined in the ``home`` database, has a ``read``
   role in the ``home`` database as well as a ``readWrite`` role in the
   ``test`` database and a ``appUser`` role in the ``myApp`` databases.

   .. code-block:: javascript

      {
        _id: "home.Kari",
        user: "Kari",
        db: "home",
        credentials: { "MONGODB-CR" :"<hashed password>" },
        roles : [
                  { role: "read", db: "home" },
                  { role : "readWrite", db: "test" },
                  { role: "appUser", db: "myApp" }
                 ],
        customData: { zipCode: 64157 }
      }

.. _user-management-commands:

User Management Commands
````````````````````````

MongoDB provides the following new commands for managing users and user
roles. You no longer manage users through direct updates to the
:doc:`system.users </reference/privilege-documents>` collection but
instead manage users through the following commands.

.. dbcommand:: createUser

   Creates a new user in the database where the command is run. To
   grant a role, you must have the :authrole:`grantAnyRole` action on
   the role's database. The :dbcommand:`createUser` command returns a
   duplicate-user error if the user exists.

   The following is an example of the :dbcommand:`createUser` command:

   .. code-block:: javascript

      { createUser: "Carlos",
        pwd: "cleartext password",
        customData: { employeeId: 12345 },
        roles: [
          { role: "clusterAdmin", db: "admin" },
          { role: "readAnyDatabase", db: "admin" },
          "readWrite"
        ],
        writeConcern: { w: "majority" , wtimeout: 5000 }
      }

   The ``pwd`` field's password is sent to the server in cleartext. To
   encrypt the password in transit, use SSL. The ``pwd`` field is
   required, *unless* you run :dbcommand:`createUser` on the
   ``$external`` database. Users created on ``$external`` are assumed
   to have credentials stored externally to MongoDB, as with
   :doc:`MongoDB Enterprise installations that use Kerberos
   </tutorial/control-access-to-mongodb-with-kerberos-authentication>`.

   The ``customData`` field is optional and contains any arbitrary
   information.

   For details on specifying roles in the ``roles`` array, see
   :ref:`role-document`. The :dbcommand:`createUser` document *must*
   have a ``roles`` array. If you specify an empty ``roles`` array, the
   user starts with no roles.

.. dbcommand:: updateUser

   Updates the user's profile on the database on which you run the
   command. An update to the user's ``roles`` array overrides the
   previous array's values.

   To update a user, you must specify ``updateUser`` field and
   at least one other field, other than ``writeConcern``.

   The following is an example of the :dbcommand:`updateUser` command:

   .. code-block:: javascript

      { updateUser: "Carlos",
        pwd: "cleartext password",
        customData: { employeeId: 54321 },
        roles: [
          { role: "assetsReader", db: "assets" }
        ],
        writeConcern: { w: "majority" , wtimeout: 5000 }
      }

   For details on specifying roles in the ``roles`` array, see
   :ref:`role-document`.

   .. important::

      To update the ``roles`` array, you must have the
      :authrole:`revokeAnyRole` action on all databases. When you update
      the ``roles`` array, you completely replace the previous array's
      values. To add roles in an update, you must have the
      :authrole:`grantAnyRole` action on the database of the role.

      To change your password or custom data, you must have the
      :authrole:`changeOwnPassword` action or
      :authrole:`changeOwnCustomData` action on the ``cluster``
      resource.

      To change another user's password or custom data, you must have
      the :authrole:`changeAnyPassword` action or
      :authrole:`changeAnyCustomData` action on that user's database.

.. dbcommand:: dropUser

   Removes the user from the database on which you run the command. To
   run this command you must have the :authrole:`dropUser` action on the
   database the user is from.

   The following is an example of the :dbcommand:`dropUser` command:

   .. code-block:: javascript

      {
        dropUser: "Carlos",
        writeConcern: { w: "majority" , wtimeout: 5000 }
      }

.. dbcommand:: dropUsersFromDatabase

   Deletes all users from the database on which you run the command.

   The following is an example of the :dbcommand:`dropUsersFromDatabase` command:

   .. code-block:: javascript

      { dropUsersFromDatabase: 1,
        writeConcern: { w: "majority" , wtimeout: 5000 }
      }

.. dbcommand:: grantRolesToUser

   Grants a role and its privileges to a user. To grant a given role,
   you must have the :authrole:`grantAnyRole` action on the role's
   database.

   The :dbcommand:`grantRolesToUser` command takes the following form:

   .. code-block:: javascript

      { grantRolesToUser: "<user>",
        roles: <roles array>,
        writeConcern: <write concern document>
      }

   For details on specifying roles in the ``roles`` array, see
   :ref:`role-document`.

   .. example:: Grant roles to a user

      The following :dbcommand:`grantRolesToUser` command runs on the
      ``products`` database and updates the user ``Erin`` on that
      database. The command's ``roles`` array grants ``Erin`` two
      ``assetsReader`` roles, one from the ``assets`` database and the
      other from the ``products`` database, on which the command is run:

      .. code-block:: javascript

         { grantRolesToUser: "Erin",
           roles: [
             { role: "assetsReader", db: "assets"},
             "assetsReader"
           ],
           writeConcern: { w: "majority" , wtimeout: 5000 }
         }

.. dbcommand:: revokeRolesFromUser

   Removes a role from a user. To remove a role, you must have the
   :authrole:`revokeAnyRole` action on the role's database.

   The following is an example of the :dbcommand:`revokeRolesFromUser` command:

   .. code-block:: javascript

      { revokeRolesFromUser: "Dan",
        roles: [
          { role: "assetsReader", db: "assets"},
          "assetsReader"
        ],
        writeConcern: { w: "majority" , wtimeout: 5000 }
      }

   For details on specifying roles in the ``roles`` array, see
   :ref:`role-document`.

.. dbcommand:: usersInfo

   Returns information about the specified users. You can always view
   your own information. To view another user's information, you must
   have the :authrole:`viewUser` action on the user's database.

   To match a single user on the database, use the following form:

   .. code-block:: javascript

      { usersInfo: { user: <name>, db: <db> },
        showCredentials: <Boolean>,
        showPrivileges: <Boolean>
      }

   The ``showCredentials`` field is optional. Set the field to ``true``
   to display the user's password hash. By default, this field is
   ``false``.

   The ``showPrivileges`` field is optional. Set the field to ``true``
   to show the user's full set of privileges, including expanded
   information for all child roles taken from the
   :ref:`admin.system.roles <admin-system-roles-collection>`
   collection. By default, this field is ``false``.

   For example, to see information and privileges, but not the
   credentials, for the user ``"Kari"`` defined in ``"home"`` database,
   run the following command:

   .. code-block:: javascript

      {
        usersInfo:  { user: "Kari", db: "home" },
        showPrivileges: true
      }

   To view a user that exists in the database on which the command is
   run, you can specify the user by name only. For example, if you are
   in the ``home`` database and a user named ``"Kari"`` exists in the
   ``home`` database, you can run the following command:

   .. code-block:: javascript

      {
        usersInfo:  "Kari",
        showPrivileges: true
      }

   To view info for several users, use an array, with or
   without the optional fields. For example:

   .. code-block:: javascript

      { usersInfo: [ { user: "Kari", db: "home" }, { user: "Li", db: "myApp" } ],
        showPrivileges: true
      }

   To view all users on the database the command is run, set
   ``userInfo`` to 1:

   .. code-block:: javascript

      { usersInfo: 1 }

   When viewing all users, you can specify the ``showCredentials``
   field but not the ``showPrivileges`` field.

.. _custom-user-roles:

Role Creation
`````````````

MongoDB 2.5.3 provides the ability to create custom user roles in
addition to the MongoDB :doc:`built-in roles
</reference/user-privileges>`.

To create a role, define its privileges by pairing resources (e.g.
database, collection) with actions (e.g. ``find``, ``insert``). To
inherit privileges from other roles, specify the roles from which to
inherit.

MongoDB scopes each role to the database in which it is created and
uniquely identifies each role by the pairing of its name and its
database. When assigned a role, a user receives all the privileges of
that role.

.. _role-management-commands:

Role Management Commands
````````````````````````

MongoDB provides the following commands for creating and managing roles.

.. dbcommand:: createRole

   Creates a role and specifies its privileges. The role applies to the
   database on which you run the command. The :dbcommand:`createRole`
   command returns a duplicate role error if the role already exists in the
   database.

   To create a role, you must have the :authrole:`createRole` action on
   the database. In addition:

   - To specify a privilege to the role, you must have the
     :authrole:`grantAnyRole` action on the database the privilege
     targets. If the privilege targets multiple databases or the
     ``cluster`` resource , you must have the :authrole:`grantAnyRole`
     action on the ``admin`` database. [#target-databases]_

   - To grant a child role to the role, you must have the
     :authrole:`grantAnyRole` action on the child role's database.

   The :dbcommand:`createRole` command takes the following form:

   .. code-block:: javascript

      { createRole: "<new role>",
        privileges: [
          { resource: <resource document>, actions: [ "<action>", ... ] },
          { resource: <resource document>, actions: [ "<action>", ... ]},
          ...
        ],
        roles: [
          { role: "<role>", db: "<database>" },
          { role: "<role>", db: "<database>" },
          ...
        ],
        writeConcern: <write concern document>
      }

   The ``privileges`` array specifies :ref:`resources
   <resource-document>` and permitted :ref:`actions
   <security-user-actions>`. The ``roles`` array specifies roles from
   which this role inherits privileges.

   Both the ``privileges`` and ``roles`` fields must be present. If you
   choose not to specify privileges or roles, you must provide an empty
   array for that field.

   The following is an example of the :dbcommand:`createRole` command:

   .. code-block:: javascript

      { createRole: "myClusterwideAdmin",
        privileges: [
          { resource: { cluster: true }, actions: [ "addShard" ] },
          { resource: { db: "config", collection: "" }, actions: [ "find", "update", "insert", "remove" ] },
          { resource: { db: "users", collection: "usersCollection" }, actions: [ "update", "insert", "remove" ] },
          { resource: { db: "", collection: "" }, actions: [ "find" ] }
        ],
        roles: [
          { role: "read", db: "admin" }
        ],
        writeConcern: { w: "majority" , wtimeout: 5000 }
      }

.. dbcommand:: updateRole

   Updates the role on the database on which you run the command. The
   :dbcommand:`updateRole` command takes the following form:

   .. code-block:: javascript

      { updateRole: "<existing role>",
        privileges: [
          { resource: < resource document >, actions: [ "<action>", ... ] },
          { resource: < resource document >, actions: [ "<action>", ... ] },
          ...
        ],
        roles: [
          { role: "<role>", db: "<database>" },
          { role: "<role>", db: "<database>" },
          ...
        ],
        writeConcern: <write concern document>
      }

   The ``privileges`` array specifies :ref:`resources
   <resource-document>` and permitted :ref:`actions
   <security-user-actions>`. The ``roles`` array specifies roles from
   which this role inherits privileges.

   You must provide at least one of the two arrays to make changes.

   .. important:: The :dbcommand:`updateRole` command overrides the
      existing ``privileges`` and/or ``roles`` with the specified
      ``privileges`` and/or ``roles`` respectively.

   To run the :dbcommand:`updateRole` command, you must have the
   :authrole:`revokeAnyRole` action on all databases, as well as the
   action permissions described below:

   - If you update the ``roles`` array, you must have
     :authrole:`grantAnyRole` on the database for every role in the
     updated array.

   - If you update the ``privileges`` array, you must have
     :authrole:`grantAnyRole` on the database for each privilege in the
     updated array. If the resource for the privilege is a collection
     in all databases, or all collections and all database, or the
     ``cluster`` resource, you must have :authrole:`grantAnyRole` on
     the ``admin`` database. [#target-databases]_

   The following is an example of the :dbcommand:`updateRole` command. All
   fields are optional, but you must provide at least one:

   .. code-block:: javascript

      { updateRole: "myClusterwideAdmin",
        privileges: [
          { resource: { db: "", collection: "" },
            actions: [ "find" , "update", "insert", "remove" ] }
        ],
        roles: [
          { role: "dbAdminAnyDatabase", db: "admin" }
        ],
        writeConcern: { w: "majority" , wtimeout: 5000 }
      }

.. dbcommand:: dropRole

   Deletes the role from the database on which you run the command. To
   run this command you must have the :authrole:`dropRole` action on the
   database. The :dbcommand:`dropRole` command takes the following form:

   .. code-block:: javascript

      {
        dropRole: "<role>",
        writeConcern: <write concern document>
      }

   For example:

   .. code-block:: javascript

      { dropRole: "myReadOnlyRole",
        writeConcern: { w: "majority" , wtimeout: 5000 }
      }

.. dbcommand:: dropRolesFromDatabase

   Deletes all roles from the database on which you run the command. To
   run this command you must have the :authrole:`dropRole` action on
   the database. The :dbcommand:`dropRolesFromDatabase` command takes
   the following form:

   .. code-block:: javascript

      { dropRolesFromDatabase: 1,
        writeConcern: <write concern document>
      }

.. dbcommand:: grantPrivilegesToRole

   Assigns privileges to a role. To grant a privilege, you must have
   the :authrole:`grantAnyRole` action on the database the privilege
   targets. If the privilege targets multiple databases or the
   ``cluster`` resource, you must have the :authrole:`grantAnyRole`
   action on the ``admin`` database. [#target-databases]_

   The command takes the following form:

   .. code-block:: javascript

      { grantPrivilegesToRole: "<role>",
        privileges: [
          { resource: { <resource> }, actions: [ "<action>", ... ] },
          ...
        ],
        writeConcern: <write concern document>
      }

   See :ref:`resource-document` for details on specifying resources and
   :ref:`security-user-actions` for the list of available actions.

   The following is an example of the
   :dbcommand:`grantPrivilegesToRole`:

   .. code-block:: javascript

      { grantPrivilegesToRole: "myRole",
        privileges: [
          { resource: { db: "A", collection: "" }, actions: [ "find" ] },
          { resource: { db: "", collection: "system.indexes" }, actions: [ "find" ] }
        ],
        writeConcern: { w: "majority" , wtimeout: 5000 }
      }

.. dbcommand:: revokePrivilegesFromRole

   Removes the specified privileges from the role. The command applies
   to the database on which you run the command. To revoke a privilege
   you must have the :authrole:`revokeAnyRole` action on the database
   the privilege targets. If the privilege targets multiple databases
   or the ``cluster`` resource, you must have the
   :authrole:`revokeAnyRole` action on the ``admin`` database.
   [#target-databases]_

   The command takes the following form:

   .. code-block:: javascript

      { revokePrivilegesFromRole: "<role>",
        privileges: [
          { resource: { <resource> }, actions: [ "<action>", ... ] },
          ...
        ],
        writeConcern: <write concern document>
      }

   See :ref:`resource-document` for details on specifying resources
   and :ref:`security-user-actions` for the list of available actions.

   To remove a privilege from a role you must match the resource
   pattern of an existing privilege being revoked, as explained in the
   following example.

   .. example:: Resource patterns must match

      Consider a role ``myRole`` with the following privilege:

      .. code-block:: javascript

         { resource: { db: "products", collection: "" }, actions: [ "find",  "update" ] }

      You cannot revoke ``find`` from just one collection in the
      ``products`` database. Trying to remove the following would result in
      no change:

      .. code-block:: javascript

         db.runCommand ( {
                           revokePrivilegesFromRole: "myRole",
                           privileges: [
                                        { resource: { db: "products", collection: "gadgets" }, actions: [ "find" ] }
                                       ],
                           writeConcern: { w: "majority" , wtimeout: 5000 }
                       } )

      To revoke ``find`` from the role ``myRole``, you must match the
      resource exactly:

      .. code-block:: javascript

         db.runCommand ( { revokePrivilegesFromRole: "myRole",
                           privileges: [
                                         { resource: { db: "products", collection: "" }, actions: [ "find" ] }
                                       ],
                           writeConcern: { w: "majority" , wtimeout: 5000 }
                       } )

   .. example:: ``revokePrivilegesFromRole`` command

      The following example of :dbcommand:`revokePrivilegesFromRole`
      removes ``find`` from the ``products`` database as well as from
      the ``system.indexes`` collections in all databases:

      .. code-block:: javascript

         { revokePrivilegesFromRole: "associate",
           privileges: [
             { resource: { db: "products", collection: "" }, actions: [ "find" ] },
             { resource: { db: "", collection: "system.indexes" }, actions: [ "find" ] }
           ],
           writeConcern: { w: "majority" , wtimeout: 5000 }
         }

.. dbcommand:: grantRolesToRole

   Specifies roles from which this role inherits privileges. The command
   applies to the role from database on which you run the command. To
   grant a given role, you must have the :authrole:`grantAnyRole` action
   on the role's database.

   Specify the child roles in the ``grantedRoles`` array, using the
   format for ``role`` documents described in the
   ref:`admin-system-roles-collection` section:

   .. code-block:: javascript

      { grantRolesToRole: "productsReaderWriter",
        grantedRoles: [
          { role: "productsReader", db: "products"}
        ],
        writeConcern: { w: "majority" , wtimeout: 5000 }
      }

.. dbcommand:: revokeRolesFromRole

   Removes child roles from this role. To remove a given role, you must
   have the :authrole:`revokeAnyRole` action on the role's database.

   The command takes the form described here. Specify the roles to
   remove using the format for ``role`` documents described in the
   ref:`admin-system-roles-collection` section:

   .. code-block:: javascript

      { revokeRolesFromRole: "productsReaderWriter",
        revokedRoles: [
          { role: "productsReader", db: "products"}
        ],
        writeConcern: { w: "majority" , wtimeout: 5000 }
      }

   .. note:: If the role does not have any of the roles being revoked,
      MongoDB does *not* give an error message.

.. dbcommand:: rolesInfo

   Lists the privileges and child roles that a role contains. To
   view role information you must have the :authrole:`viewRole` action
   on the role's database or be authenticated as a user explicitly
   granted the role.

   To match a single role on a specific database, use the following
   form, where ``<database>`` is the role's database.

   .. code-block:: javascript

      { rolesInfo: { role: "<role>", db: "<database>" } }

   To view info for several roles, use an array, as in the following
   example that specifies the roles and their databases:

   .. code-block:: javascript

      { rolesInfo: [
           { role: "associate", db: "products" },
           { role: "manager", db: "resources" },
        ]
      }

   To match a role that exists in the database on which the command is
   run, you can specify the role by its name only. See
   :ref:`role-document`.

   .. code-block:: javascript

      { rolesInfo: "<role>" }

.. [#target-databases] Privileges whose ``resource`` documents specify
   a database (e.g. ``{ db: "test", collection: "" }``) or specify a
   particular collection in a specific database ( e.g. ``{ db:
   "records", collection: "users" }``) target a single database.

   Privileges whose ``resource`` documents specify an empty string ``""``
   for the ``db`` field (e.g. ``{ db: "", collection: "" }`` or ``{ db: "",
   collection: <collection> }`` ) or specify ``{ cluster:true }`` target
   multiple databases.

.. _role-document:

Identify a Role
```````````````

For use with :ref:`role-management-commands` or
:ref:`user-management-commands`, identify a role with a document of the
following form:

.. code-block:: javascript

   { role: "<role>", db: "<database>" }

In general, specify the role with a document when used with
:ref:`role-management-commands` or :ref:`user-management-commands`.
However, to refer to a role that exists in the same database the
command is run, you can specify the role either with a role document
(e.g. ``{ role: "readWrite", db: "sameDB" }`` ) or with just the role
name (e.g. ``"readWrite"``).

.. _security-user-actions:

User Actions
````````````

This section lists the actions you can specify when defining a privilege
in a role.

New User Actions
^^^^^^^^^^^^^^^^

MongoDB adds the following new user actions. The actions apply to the
database in which they are assigned, unless otherwise noted:

.. authrole:: createUser

   The user can create new users in the given database.

.. authrole:: createRole

   The user can create new roles in the given database.

.. authrole:: dropUser

   The user can remove any user from the given database.

.. authrole:: dropRole

   The user can delete any role from the given database.

.. authrole:: grantAnyRole

   The user can grant any role in the database to any user from any
   database in the system.

.. authrole:: revokeAnyRole

   The user can remove any role from any user from any database in the
   system.

.. authrole:: changeOwnPassword

   Users with this action can change their own passwords. This action
   should be granted on the ``cluster`` resource.

.. authrole:: changeAnyPassword

   The user can change the password of any user in the given database.

.. authrole:: changeOwnCustomData

   Users with this action can change their own custom information, as
   stored in the ``customData`` field of the ``admin.system.users``
   collection. This action should be granted on the ``cluster``
   resource.

.. authrole:: changeAnyCustomData

   The user can change the custom information of any user in the given
   database. Custom information is stored in the ``customData`` field of
   the ``admin.system.users`` collection.

.. authrole:: viewUser

   The user can view the information of any user in the given database.

.. authrole:: viewRole

   The user can view information about any role in the given database.

Existing Actions
^^^^^^^^^^^^^^^^

.. todo: update for the final 2.6 code, which is expected to have fewer
   actions than those listed here

.. todo: for each action, indicate the types of resources it acts on.

In addition to the actions new in version 2.6, MongoDB provides the
following user actions:

.. hlist::
   :columns: 3

   * ``_migrateClone``
   * ``_recvChunkAbort``
   * ``_recvChunkCommit``
   * ``_recvChunkStart``
   * ``_recvChunkStatus``
   * ``_transferMods``
   * ``addShard``
   * ``captrunc``
   * ``clean``
   * ``clone``
   * ``cloneCollectionLocalSource``
   * ``cloneCollectionTarget``
   * ``closeAllDatabases``
   * ``collMod``
   * ``collStats``
   * ``compact``
   * ``connPoolStats``
   * ``connPoolSync``
   * ``convertToCapped``
   * ``cpuProfiler``
   * ``createCollection``
   * ``cursorInfo``
   * ``dbHash``
   * ``dbStats``
   * ``delete``
   * ``diagLogging``
   * ``dropCollection``
   * ``dropDatabase``
   * ``enableSharding``
   * ``find``
   * ``flushRouterConfig``
   * ``fsync``
   * ``getCmdLineOpts``
   * ``getLog``
   * ``getParameter``
   * ``getShardMap``
   * ``getShardVersion``
   * ``handshake``
   * ``hostInfo``
   * ``indexStats``
   * ``inprog``
   * ``insert``
   * ``killCursors``
   * ``killop``
   * ``listDatabases``
   * ``listShards``
   * ``logRotate``
   * ``moveChunk``
   * ``movePrimary``
   * ``netstat``
   * ``profileEnable``
   * ``reIndex``
   * ``removeShard``
   * ``repairDatabase``
   * ``replSetElect``
   * ``replSetFreeze``
   * ``replSetFresh``
   * ``replSetGetRBID``
   * ``replSetGetStatus``
   * ``replSetHeartbeat``
   * ``replSetInitiate``
   * ``replSetMaintenance``
   * ``replSetReconfig``
   * ``replSetStepDown``
   * ``replSetSyncFrom``
   * ``resync``
   * ``serverStatus``
   * ``setParameter``
   * ``setShardVersion``
   * ``shardCollection``
   * ``shardingState``
   * ``shutdown``
   * ``split``
   * ``splitChunk``
   * ``splitVector``
   * ``storageDetails``
   * ``top``
   * ``touch``
   * ``unlock``
   * ``unsetSharding``
   * ``update``
   * ``userAdmin``
   * ``validate``
   * ``writeBacksQueued``
   * ``writebacklisten``

SSL Improvements
~~~~~~~~~~~~~~~~

Optionally Prompt for SSL Certificate Passphrases at Server Startup
```````````````````````````````````````````````````````````````````

In MongoDB 2.6, a :program:`mongod` or :program:`mongos` can now
interactively prompt the user at startup to enter the passphrase for the
locally encrypted SSL key. This provides an alternative to providing a
cleartext passphrase on the command line or in a configuration file.

The passphrase prompt option is available if you run the MongoDB instance in the
foreground with a connected terminal. The prompt will not work if you run the
process in a non-interactive session (e.g. without a terminal or as a
service on Windows).

To receive the passphrase prompt, start the MongoDB instance with the
``.pem`` file that contains the SSL certificate and key but *do not*
specify the passphrase. MongoDB interactively prompts
for a passphrase.

You can use the passphrase prompt with both the :setting:`sslPEMKeyFile`
option and the new :setting:`sslClusterFile` option (see
:ref:`rn26-x509-authentication`).

For the :setting:`sslPEMKeyFile` option, specify the encrypted SSL
private key/certificate ``.pem`` file with :setting:`sslPEMKeyFile` but
do not specify an :setting:`sslPEMKeyPassword`.

For the :setting:`sslClusterFile` option, specify an x.509 certificate-and-key
``.pem`` file with :setting:`sslClusterFile` but do not specify an
:setting:`sslClusterPassword`.

For instructions on configuring SSL see :doc:`/tutorial/configure-ssl`.

Tools Now Support SSL
`````````````````````

.. versionadded:: 2.5.3

MongoDB programs add support for connecting to :program:`mongod` and
:program:`mongos` instances using SSL connection. See
:doc:`/tutorial/configure-ssl` for more information
Tools with SSL support include:

- :program:`mongodump`
- :program:`mongoexport`
- :program:`mongofiles`
- :program:`mongoimport`
- :program:`mongooplog`
- :program:`mongorestore`
- :program:`mongostat`
- :program:`mongotop`

.. tip:: To use SSL connections with these tools, use the same
   SSL options as the :program:`mongo` shell.

MongoDB Allows Only Strong SSL Ciphers
``````````````````````````````````````

.. DOCS-1921

MongoDB's SSL encryption only allows use of strong SSL ciphers, with a minimum
of 128-bit key length for all connections.

The strong-cipher requirement prevents an old or malicious client from forcing
use of a weak cipher.

Support for SSL and non-SSL Connections on the Same Port
````````````````````````````````````````````````````````

.. merge this under the new ~~~ header created by DOCS-1921

.. DOCS-1941

.. draft, waiting for feature complete before sending to technical review

MongoDB supports mixed SSL and non-SSL connections on the same port to
allow upgrades to SSL without forcing downtime. MongoDB provides
a new command-line option and server command that configure a server
port to allow unencrypted internal connections while maintaining
encrypted external connections.

To use such mixed SSL modes on a port, you must restrict access at the
network level. You cannot at this time restrict encryption based on
MongoDB user or role. Outgoing connections from the MongoDB server
cannot choose encryption based on connection target.

You can only increase security level on a server. Changing a server's
listening behavior does not require a restart of the server.

The --sslMode Command-Line Option
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

MongoDB provides the following new server command-line option to handle
mixed SSL mode:

.. code-block:: sh

   --sslMode <parameter>

The value of ``<parameter>`` is one of the following:

- ``noSSL``. The server does not use SSL.

- ``sslOnly``. The server uses only SSL.

- ``acceptSSL``. Outgoing connections do not use SSL. For incoming
  connections, the server accepts both SSL and non-SSL.

- ``sendAcceptSSL``. Outgoing connections use SSL. For incoming
  connections, the server accepts both SSL and non-SSL.

Upgrade a Cluster to Use SSL
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To upgrade from a MongoDB cluster using no SSL encryption to one using
*only* SSL encryption, do the following:

1. Perform a rolling upgrade to MongoDB 2.6 on all nodes, and activate
   mixed-mode SSL by using the ``--sslMode`` command-line option
   set to ``acceptSSL``:

  .. code-block:: javascript

     --sslMode=acceptSSL

2. Switch all clients to use SSL.

3. Switch all outgoing server connections to use SSL by restarting each server
   with the ``--sslMode`` option set to ``sendAcceptSSL``.

   At this point, all connections should be using SSL.

4. Switch all servers to accept only SSL connections by restarting each server
   with the ``--sslMode`` option set to ``sslOnly`` parameter on each server.

.. _rn26-x509-authentication:

x.509 Authentication
````````````````````

MongoDB introduces :doc:`x.509 certificate authentication
</tutorial/configure-x509>` for use with a secure :doc:`SSL connection
</tutorial/configure-ssl>`.

.. important:: To use SSL, you must either use MongoDB Enterprise or
   build MongoDB locally using ``scons`` with the ``--ssl`` option.

The x.509 authentication allows clients to authenticate to servers with
certificates instead of with username and password. The x.509
authentication also allows sharded cluster members and replica set
members to use x.509 certificates to verify their membership to the
cluster or the replica set instead of using key files. The membership
authentication is an internal process.

The change for x.509 authentication introduces a new ``MONGODB-X509``
protocol. For internal authentication for membership, the change also
introduces the :option:`--clusterAuthMode`, :option:`--sslClusterFile` and the
:option:`--sslClusterPassword` options.

For details on x.509 certificate authentication, see
:doc:`/tutorial/configure-x509`.

Index Building Improvements
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Background Index Builds Replicate to Secondaries
````````````````````````````````````````````````

Starting in MongoDB 2.5.0, if you initiate a :ref:`background index
build <index-creation-background>` on a :term:`primary`, the
secondaries will replicate the index build in the background.
In previous versions of MongoDB, secondaries built all indexes in the
foreground, even if the primary built an index in the background.

For all index builds, secondaries will not begin building indexes
until the primary has successfully completed the index build.

``mongod`` Automatically Continues in Progress Index Builds Following Restart
`````````````````````````````````````````````````````````````````````````````

If your :program:`mongod` instance was building an index when it
shutdown or terminated, :program:`mongod` will now continue building
the index when the :program:`mongod` restarts. Previously, the index
build *had* to finish building before :program:`mongod` shutdown.

To disable this behavior the 2.5 series adds a new run time option,
:setting:`noIndexBuildRetry` (or via, ``--noIndexBuildRetry`` on the
command line,) for :program:`mongod`. :setting:`noIndexBuildRetry`
prevents :program:`mongod` from continuing rebuilding indexes that did
not finished building when the :program:`mongod` last shut down.

Tool Improvements
~~~~~~~~~~~~~~~~~

Global ``mongorc.js`` File
``````````````````````````

If the file :file:`mongorc.js` exists in the :file:`/etc` directory (or
:file:`%ProgramData%\\MongoDB` directory on Windows), the
:program:`mongo` shell evaluates the contents of this file on start-up.
Then, the :program:`mongo` shell evaluates the user's
:file:`.mongorc.js` file if the file exists in the user's :envvar:`HOME
directory`.

The :option:`--norc` option for :program:`mongo` suppresses only the
user's :file:`.mongorc.js` file.

.. important::
   The :file:`mongorc.js` in :file:`/etc` directory must have read
   permission for the user running the shell.

Support for ``--quiet`` Option for all Tools
````````````````````````````````````````````

.. versionadded:: 2.5.0

All MongoDB :doc:`executable files </reference/program>` now support
the ``--quiet`` option. This option suppresses all logging output
except for error messages.

``mongoimport`` Uses Filename If Collection Name Is Not Specified
`````````````````````````````````````````````````````````````````

.. versionadded:: 2.5.3

When invoked without the ``-c`` or ``--collection`` command-line argument,
the :program:`mongoimport` tool uses the input filename as the name
of the collection. MongoDB omits the extension of the file from the
collection name if the input file has an extension.

.. example::

   The following command imports data from the ``contacts.csv`` file
   into the ``contacts`` collection:

   .. code-block:: none

      mongoimport --db users --type csv --file /opt/backups/contacts.csv

   To specify the collection to import, use the ``-c`` or
   ``--collection`` option:

   .. code-block:: none

      mongoimport --db users --collection contacts --type csv --file /opt/backups/contacts.csv

``mongostat`` Can Support ``--rowcount`` Option with ``--discover`` Option
``````````````````````````````````````````````````````````````````````````

.. versionadded:: 2.5.3

The :program:`mongostat` program now produces the specified
number of lines of output when using :option:`--rowcount` (:option:`-n`)
with the :option:`--discover` option. In earlier versions of
:program:`mongostat`, the :option:`--discover` option would override
:option:`--rowcount`, and would continue to produce output until the
user terminated the program.

Limit for ``maxConns`` Removed
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Starting in MongoDB 2.5.0, there is no longer any upward limit for the
:setting:`maxConns`, or :program:`mongod --maxConns` and
:program:`mongos --maxConns` options. Previous versions capped the
maximum possible :setting:`maxConns` setting at ``20,000``
connections.

See :setting:`maxConns`.

Geospatial Enhancements
~~~~~~~~~~~~~~~~~~~~~~~

.. versionadded:: 2.5.2

MongoDB added support for the following `GeoJSON
<http://geojson.org/geojson-spec.html>`_ object types for use with
:doc:`2dsphere indexes </core/2dsphere>`:

- `MultiPoint <http://geojson.org/geojson-spec.html#id5>`_

- `MultiLineString <http://geojson.org/geojson-spec.html#id6>`_

- `MultiPolygon <http://geojson.org/geojson-spec.html#id7>`_

- `GeometryCollection <http://geojson.org/geojson-spec.html#geometrycollection>`_

C++ Driver Enhancement
~~~~~~~~~~~~~~~~~~~~~~

.. versionadded:: 2.5.0

The C++ driver now monitors :term:`replica set` health with the
:dbcommand:`isMaster` command instead of :dbcommand:`replSetGetStatus`.
This allows the C++ driver to support systems that have access control
enabled.

MSI Package for MongoDB Available for Windows
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. versionadded:: 2.5.3

MongoDB now distributes MSI packages for Microsoft Windows. This is the
recommended method for MongoDB installation under Windows.

New Replica Set Status Methods
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

MongoDB provides two additional methods to provide information
regarding the status of a :term:`replica set`:
:method:`rs.printReplicationInfo()` and
:method:`rs.printSlaveReplicationInfo()`.

The :method:`rs.printReplicationInfo()` method provides a formatted
report of the status of a :term:`replica set` from the perspective of
the primary set member. The output is identical to that of the
:method:`db.printReplicationInfo()` method.

The :method:`rs.printSlaveReplicationInfo()` method provides a
formatted report of the status of a :term:`replica set` from the
perspective of a secondary set member. The output is identical to that
of the :method:`db.printSlaveReplicationInfo()` method.

MongoDB Enterprise Features
---------------------------

Support for Auditing
~~~~~~~~~~~~~~~~~~~~

.. versionadded:: 2.5.3

.. important:: Auditing, like all new features in 2.5.3, is in ongoing
   development. Specifically, the interface, output format, audited
   events and the structure of audited events will change
   significantly in the 2.5 series before the release of 2.6.

MongoDB Enterprise adds features to audit server and client activity
for :program:`mongod` and :program:`mongos` instances. See
:ref:`auditing` for details.

MongoDB Enterprise for Windows
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. versionadded:: 2.5.3

MongoDB Enterprise for Windows is now available. It includes advanced
Kerberos security, SSL, and SNMP support.

.. include:: /includes/admonition-mongodb-enterprise-windows-ldap.rst

SASL Library Change
~~~~~~~~~~~~~~~~~~~

MongoDB Enterprise uses Cyrus SASL instead of GNU SASL (``libgsasl``).
This change has the following SASL2 and Cyrus SASL library and GSSAPI
plugin dependencies:

For Debian or Ubuntu, install the following:

.. code-block:: sh

   sudo apt-get install cyrus-sasl2-dbg cyrus-sasl2-mit-dbg libsasl2-2 libsasl2-dev libsasl2-modules libsasl2-modules-gssapi-mit

For CentOS, Red Hat Enterprise Linux, and Amazon AMI, install the
following:

.. code-block:: sh

   sudo yum install cyrus-sasl cyrus-sasl-lib cyrus-sasl-devel cyrus-sasl-gssapi

For SUSE, install the following:

.. code-block:: sh

   sudo zypper install cyrus-sasl cyrus-sasl-devel cyrus-sasl-gssapi

LDAP Support for Authentication
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

MongoDB Enterprise provides support for proxy authentication of users.  This
change allows administrators to configure a MongoDB cluster to authenticate
users via Linux PAM or by proxying authentication requests to a specified LDAP
service.

.. include:: /includes/admonition-mongodb-enterprise-windows-ldap.rst

.. warning::

   Because this change uses ``SASL PLAIN`` mechanism to transmit the
   user password to the MongoDB server, you should, in general, use
   only on a trusted channel (VPN, SSL, trusted wired network).

Configuration
`````````````

LDAP support for user authentication requires proper configuration of
the ``saslauthd`` daemon process as well as introduces a new server
parameter, ``saslauthdPath``. ``saslauthdPath`` is the path to the Unix
Domain Socket of the ``saslauthd`` instance to use for proxy
authentication.

``saslauthd`` Configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^

On systems that configure ``saslauthd`` with a
``/etc/sysconfig/saslauthd`` file, such as Red Hat Enterprise Linux,
Fedora, CentOS, Amazon Linux AMI, set the mechanism ``MECH`` to
``ldap``:

.. code-block:: none

   MECH=ldap

On systems that configure ``saslauthd`` with a
``/etc/default/saslauthd`` file, set the mechanisms option to
``ldap``:

.. code-block:: none

   MECHANISMS="ldap"

To use with *ActiveDirectory*, start ``saslauthd`` with the following
configuration options:

.. code-block:: none

   ldap_servers: <ldap uri, e.g. ldaps://ad.example.net>
   ldap_use_sasl: yes
   ldap_mech: DIGEST-MD5
   ldap_auth_method: fastbind

To connect to an OpenLDAP server, use ``saslauthd.conf`` with
the following content:

.. code-block:: none

   ldap_servers: <ldap uri, e.g. ldaps://ad.example.net>
   ldap_search_base: <search base, e.g. ou=Users,dc=example,dc=com>
   ldap_filter: <filter, e.g. (uid=%u)>

For example, a sample ``saslauthd.conf`` may have the following content:

.. code-block:: none

   ldap_servers: ldaps://ad.example.net
   ldap_search_base: ou=Users,dc=example,dc=com
   ldap_filter: (uid=%u)

The values for these fields should correspond to values specific for
your test. For example, to filter on email, specify ``ldap_filter:
(email:%u)``.

.. tip:: For OpenLDAP installed on the local machine, you can specify for
   ``ldap_servers`` the value ``ldap://localhost:389``.

To use this sample OpenLDAP configuration which specifies
``ldap_search_base: ou=Users,dc=example,dc=com``, create users with a
``uid`` attribute (login name) and place under the ``Users``
organizational unit (``ou``).

To test the ``saslauthd`` configuration, use ``testsaslauthd`` utility,
as in the following example:

.. code-block:: sh

   testsaslauthd -u testuser -p testpassword -s mongod -f /var/run/saslauthd/mux

In the example, the ``-s mongod`` is optional to verify the
``saslauthd`` configuration.

For more information on ``saslauthd`` configuration, see
`<http://www.openldap.org/doc/admin24/guide.html#Configuring saslauthd>`_.

MongoDB Server Configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Configure the MongoDB server with the ``authenticationMechanisms``
parameter and the ``saslauthdPath`` parameters using either the command
line option :option:`--setParameter <mongod --setParameter>` or the
:doc:`configuration file </reference/configuration-options>`:

- If ``saslauthd`` has a socket path of ``/<some>/<path>/saslauthd``,
  set the ``saslauthdPath`` parameter to
  ``/<some>/<path>/saslauthd/mux`` and the ``authenticationMechanisms``
  parameter to ``PLAIN``, as in the following command line example:

  .. code-block:: sh

     mongod --setParameter saslauthdPath=/<some>/<path>/saslauthd/mux --setParameter authenticationMechanisms=PLAIN --auth

  Or to set the configuration in the :doc:`configuration file
  </reference/configuration-options>`, add the parameters:

  .. code-block:: sh

     setParameter=saslauthdPath=/<some>/<path>/saslauthd/mux
     setParameter=authenticationMechanisms=PLAIN
     auth=true

- Otherwise, set the ``saslauthdPath`` to the empty string ``""`` to use
  the library's default value and the ``authenticationMechanisms``
  parameter to ``PLAIN``, as in the following command line example:

  .. code-block:: sh

     mongod --setParameter saslauthdPath="" --setParameter authenticationMechanisms=PLAIN --auth

  Or to set the configuration in the :doc:`configuration file
  </reference/configuration-options>`, add the parameters:

  .. code-block:: sh

     setParameter=saslauthdPath=""
     setParameter=authenticationMechanisms=PLAIN
     auth=true

Authenticate in the ``mongo`` Shell
```````````````````````````````````

To use this authentication mechanism in the :program:`mongo` shell, you
**must** pass ``digestPassword: false`` to :method:`db.auth()` when
authenticating on the ``$external`` database, since the server must
receive an undigested password to forward on to ``saslauthd``, as in
the following example:

.. code-block:: javascript

   use $external
   db.auth(
            {
              mechanism: "PLAIN",
              user: "application/reporting@EXAMPLE.NET",
              pwd: "some1nterestingPwd",
              digestPassword: false
            }
          )

Expanded SNMP Support
~~~~~~~~~~~~~~~~~~~~~

.. versionadded:: 2.5.3

MongoDB Enterprise has greatly expanded its SNMP support. Enterprise
clients who need fine-grained server statistics now have SNMP access to
nearly the full range of metrics provided by
:dbcommand:`db.serverStatus()`.