adding the createUser() method

source/includes/access-create-user.rst

@@ -0,0 +1,5 @@
+To run |local-cmd-name|, a user must have access
+that includes the :authaction:`createUser` action on the database.
+
+To grant a role to a new user, the user granting the role must have access
+that includes the :authaction:`grantRole` action on the role's database.

source/includes/ref-toc-method-user-management.yaml

@@ -1,8 +1,8 @@
-# name: :method:`db.createUser()`
-# file: /reference/method/db.createUser
-# description: |
-#   Creates a new user.
-# ---
+name: :method:`db.createUser()`
+file: /reference/method/db.createUser
+description: |
+  Creates a new user.
+---
 # name: :method:`db.updateUser()`
 # file: /reference/method/db.updateUser
 # description: |

source/reference/command/createUser-field.yaml

@@ -1,4 +1,5 @@
 #content from this page is included in /reference/method/db.addUser-param.yaml
+#content from this page is included in /reference/method/db.createUser-param.yaml
 object:
   name: createUser
   type: dbcommand
@@ -24,7 +25,7 @@ description: |
   The user's password. The ``pwd`` field is not
   required if you run |local-cmd-name| on the ``$external``
   database to create users who have credentials stored externally to
-  MongoDB. See :ref:`createUser-pwd-field-consideration`.
+  MongoDB.
 ---
 object:
   name: createUser

source/reference/command/createUser.txt

@@ -9,6 +9,8 @@ Definition
 
 .. dbcommand:: createUser
 
+   .. |local-cmd-name| replace:: :dbcommand:`createUser`
+
    Creates a new user on the database where you run the command. The
    :dbcommand:`createUser` command returns a *duplicate user* error if the
    user exists.
@@ -28,7 +30,6 @@ Definition
 
    :dbcommand:`createUser` has the following fields:
 
-   .. |local-cmd-name| replace:: :dbcommand:`createUser`
    .. include:: /reference/command/createUser-field.rst
 
    .. include:: /includes/fact-roles-array-contents.rst
@@ -52,23 +53,19 @@ Enterprise installations that use Kerberos
 Required Access
 ---------------
 
-To run the :dbcommand:`createUser` command, a user must have access
-that includes the :authaction:`createUser` action on the database.
-
-To grant a role to the new user, the user granting the role must have access
-that includes the :authaction:`grantRole` action on the role's database.
+.. include:: /includes/access-create-user.rst
 
 Example
 -------
 
-The following :dbcommand:`createUser` command creates a user ``Carlos`` on the
-``products`` database. The command gives ``Carlos`` the
+The following :dbcommand:`createUser` command creates a user ``accountAdmin01`` on the
+``products`` database. The command gives ``accountAdmin01`` the
 ``clusterAdmin`` and ``readAnyDatabase`` roles on the ``admin`` database
 and the ``readWrite`` role on the ``products`` database:
 
 .. code-block:: javascript
 
-   db.getSiblingDB("products").runCommand( { createUser: "Carlos",
+   db.getSiblingDB("products").runCommand( { createUser: "accountAdmin01",
                                              pwd: "cleartext password",
                                              customData: { employeeId: 12345 },
                                              roles: [

source/reference/method/db.createUser-param.yaml

@@ -0,0 +1,24 @@
+object:
+  name: db.createUser()
+  type: method
+field:
+  optional: false
+  type: field
+name: user
+type: string
+position: 1
+description: |
+  The name of the new user.
+---
+file: /reference/command/createUser-field.yaml
+name: pwd
+position: 2
+---
+file: /reference/command/createUser-field.yaml
+name: customData
+position: 3
+---
+file: /reference/command/createUser-field.yaml
+name: roles
+position: 4
+...

source/reference/method/db.createUser.txt

@@ -0,0 +1,94 @@
+===============
+db.createUser()
+===============
+
+.. default-domain:: mongodb
+
+Definition
+----------
+
+.. method:: db.createUser ( user, writeConcern )
+
+   .. Defines a |local-cmd-name| replacement:
+   .. |local-cmd-name| replace:: :method:`db.createUser()`
+
+   Creates a new user on the database where you run the method. The method
+   returns a *duplicate user* error if the user already exists on the database.
+
+   The :method:`db.createUser()` method takes a ``user`` document and, optionally,
+   a ``writeConcern`` document as its arguments.
+
+   The ``user`` document defines the user and has the following form:
+
+   .. code-block:: javascript
+
+      { user: "<name>",
+        pwd: "<cleartext password>",
+        customData: { <any information> },
+        roles: [
+          { role: "<role>", db: "<database>" } | "<role>",
+          ...
+        ]
+      }
+
+   The ``user`` document has the following fields:
+
+   .. include:: /reference/method/db.createUser-param.rst
+
+   The ``writeConcern`` document is optional and determines the level of
+   :doc:`write concern </reference/write-concern>` for the
+   :method:`db.createUser()` operation. The ``writeConcern`` document takes
+   the same fields as the :dbcommand:`getLastError` command.
+
+   The :method:`db.createUser()` method wraps the :dbcommand:`createUser`
+   command.
+
+Considerations
+--------------
+
+``pwd`` Field
+~~~~~~~~~~~~~
+
+:method:`db.createUser()` sends password to the MongoDB instance in
+cleartext. To encrypt the password in transit, use :doc:`SSL
+</tutorial/configure-ssl>`.
+
+Users created on the ``$external`` database should have credentials
+stored externally to MongoDB, as, for example, with :doc:`MongoDB
+Enterprise installations that use Kerberos
+</tutorial/control-access-to-mongodb-with-kerberos-authentication>`.
+
+``roles`` Field
+~~~~~~~~~~~~~~~
+
+.. include:: /includes/fact-roles-array-contents.rst
+
+Required Access
+---------------
+
+.. include:: /includes/access-create-user.rst
+
+Example
+-------
+
+The following :method:`db.createUser()` operation creates the
+``accountAdmin01`` user on the ``products`` database.
+
+.. code-block:: javascript
+
+   use products
+   db.createUser( { "user" : "accountAdmin01",
+                    "pwd": "cleartext password",
+                    "customData" : { employeeId: 12345 },
+                    "roles" : [ { role: "clusterAdmin", db: "admin" },
+                                { role: "readAnyDatabase", db: "admin" },
+                                "readWrite"
+                                ] },
+                  { w: "majority" , wtimeout: 5000 } )
+
+The operation gives ``accountAdmin01`` the following roles:
+
+- the ``clusterAdmin`` and ``readAnyDatabase`` roles on the ``admin``
+  database
+
+- the ``readWrite`` role on the ``products`` database