From 137bdd6f2731b940cc933ae89d7a56922990044f Mon Sep 17 00:00:00 2001
From: Bob Grabar <bob.grabar@10gen.com>
Date: Tue, 5 Mar 2013 11:57:10 -0500
Subject: [PATCH] DOCS-1153 adduser

---
 source/reference/method/db.addUser.txt | 110 ++++++++++++++++++++++---
 1 file changed, 97 insertions(+), 13 deletions(-)

diff --git a/source/reference/method/db.addUser.txt b/source/reference/method/db.addUser.txt
index b7a75928185..2b749d02ba7 100644
--- a/source/reference/method/db.addUser.txt
+++ b/source/reference/method/db.addUser.txt
@@ -4,25 +4,109 @@ db.addUser()
 
 .. default-domain:: mongodb
 
-.. method:: db.addUser("username", "password" [, readOnly] )
+.. method:: db.addUser()
 
-   :param string username: Specifies a new username.
+   Use this method to create new database users by specifying a
+   username, password, and privileges.
 
-   :param string password: Specifies the corresponding password.
+   In MongoDB 2.4 you must pass :method:`db.addUser()` a document that
+   contains the user parameters. You cannot pass the parameters
+   directly. In MongoDB 2.2 and earlier you can pass the parameters
+   directly, or pass a document.
+
+   If you use MongoDB 2.4, the following parameters define users:
+
+   :param string user: Specifies a new username.
+
+   :param string pwd: Specifies the corresponding password.
+                      Specify either this parameter or the
+                      ``userSource`` parameter. The two fields are
+                      mutually exclusive. A single document cannot
+                      contain both.
+
+   :param array roles: This specifies one or more
+                       roles to the user. Each role provides the user
+                       with a set of privileges. For a list of roles,
+                       see :data:`system.users.roles <<database>.system.users.roles>`.
 
-   :param boolean readOnly: Optional. Restrict a user to
-                            read-privileges only. Defaults to false.
+   :param string userSource: This specifies
+                             the database that contains the user
+                             credentials. Specify either this parameter
+                             or the ``pwd`` parameter. The two fields
+                             are mutually exclusive. A single document
+                             cannot contain both.
 
-   Use this function to create new database users, by specifying a
-   username and password as arguments to the command. If you want to
-   restrict the user to have only read-only privileges, supply a true
-   third argument; however, this defaults to false.
+   :param document otherDBRoles: Optional. This
+                                 specifies the roles that an admin user
+                                 has on other databases. This field
+                                 applies only to a user added to the
+                                 ``admin`` database. For a list of
+                                 roles, see :data:`system.users.roles
+                                 <<database>.system.users.roles>`.
 
-   For example:
+   For MongoDB 2.4, use the syntax described here.
+
+   To specify the password:
 
    .. code-block:: javascript
 
-      db.addUser("user1" , "pass" , { readOnly : true } )
+      db.addUser( { user: "<user>", pwd: "<password>", roles: [<roles>] } )
+
+   To specify the database that contains the user credentials:
+
+   .. code-block:: javascript
+
+      db.addUser( { user: "<user>", userSource: "<database>", roles: [<roles>] } )
+
+   To give an admin user roles on other databases, include the following
+   field in the document passed to the :method:`db.addUser()` method:
+
+   .. code-block:: javascript
+
+      otherDBRoles: { <database1>: [<roles>], <database2>: [<roles>] }
+
+   .. example:: On MongoDB 2.4, the following creates a user named
+      "author" with ``readWrite`` and ``readAnyDatabase`` privileges:
+
+      .. code-block:: javascript
+
+         db.addUser( { user: "author", pwd: "pass", roles: [ "readWrite", "readAnyDatabase" ] } )
+
+   .. seealso::
+
+      - :doc:`/reference/user-privileges`
+
+      - :doc:`/reference/privilege-documents`
+
+   If you use MongoDB 2.2 or earlier, the following parameters define
+   users:
+
+   :param string user: Specifies a new username.
+
+   :param string password: Specifies the corresponding password.
+
+   :param boolean readOnly: Optional. If you use MongoDB 2.2 or earlier,
+                            this restricts a user to
+                            read privileges. This defaults to false.
+
+   Use the following syntax. The
+   ``readOnly`` field is optional and defaults to ``false``:
+
+   .. code-block:: javascript
+
+      db.addUser( "<username>", "<password>", { readOnly: <boolean> } )
+
+   .. example:: On MongoDB 2.2 and earlier, the following creates a user
+      named "guest" with ``readOnly`` privileges:
+
+      .. code-block:: javascript
+
+         db.addUser( "guest", "pass", { readOnly: true } )
+
+   .. note:: The :program:`mongo` shell excludes all
+     :method:`db.addUser()` operations from the saved history.
 
-   .. |operation-name| replace:: :method:`db.addUser()`
-   .. include:: /includes/note-auth-methods-excluded-from-shell-history.rst
+   .. deprecated:: 2.4
+      The ``roles`` parameter replaces the ``readOnly`` parameter for
+      :method:`db.addUser()`. Version 2.4 also adds the ``otherDBRoles``
+      and ``userSource`` parameters to :method:`db.addUser()`.