create role, create user

source/administration/configuration.txt

@@ -69,7 +69,7 @@ following explanation:
 
   .. |mongodb-package| replace:: :program:`mongod`
 
-  .. include:: /includes/note-deb-and-rpm-default-to-localhost
+  .. include:: /includes/note-deb-and-rpm-default-to-localhost.rst
 
 - :setting:`port` is ``27017``, which is the default
   MongoDB port for database instances. MongoDB can bind to any

source/core/sharded-cluster-security.txt

@@ -86,5 +86,4 @@ remote host address, sharded clusters will not function correctly.
 
 .. |mongodb-package| replace:: :program:`mongos`
 
-.. include:: /includes/note-deb-and-rpm-default-to-localhost
-
+.. include:: /includes/note-deb-and-rpm-default-to-localhost.rst

source/includes/note-deb-and-rpm-default-to-localhost.rst

@@ -5,8 +5,8 @@
 
    .. versionadded:: 2.5.3
       |mongodb-package| installed from official :doc:`.deb
-      <install-mongodb-on-debian>` and :doc:`.rpm
-      <install-mongodb-on-red-hat-centos-or-fedora-linux>` packages
+      </tutorial/install-mongodb-on-debian>` and :doc:`.rpm
+      </tutorial/install-mongodb-on-red-hat-centos-or-fedora-linux>` packages
       have the :setting:`bind_ip` configuration set to ``127.0.0.1`` by
       default.
 

source/includes/toc-security-tutorials-access-control.yaml

@@ -14,6 +14,14 @@ description: |
   Create non-administrator users using MongoDB's role-based
   authentication system.
 ---
+file: /tutorial/create-a-role
+description: |
+  Create custom role.
+---
+file: /tutorial/view-roles
+description: |
+  View a role's privileges.
+---
 file: /tutorial/change-user-password
 description: |
   Only user administrators can edit credentials. This tutorial

source/includes/toc-spec-security-tutorials-landing.yaml

@@ -19,6 +19,10 @@ files:
     level: 2
   - file: /tutorial/add-user-to-database
     level: 2
+  - file: /tutorial/create-a-role
+    level: 2
+  - file: /tutorial/view-roles
+    level: 2
   - file: /tutorial/control-access-to-mongodb-with-kerberos-authentication
     level: 2
   - file: /tutorial/configure-auditing

source/reference/configuration-options.txt

@@ -276,9 +276,9 @@ Settings
 
    .. versionadded:: 2.4.6
       Allows users to override the default :doc:`Kerberos
-      <tutorial/control-access-to-mongodb-with-kerberos-authentication>`
+      </tutorial/control-access-to-mongodb-with-kerberos-authentication>`
       service name component of the :doc:`Kerberos
-      <tutorial/control-access-to-mongodb-with-kerberos-authentication>`
+      </tutorial/control-access-to-mongodb-with-kerberos-authentication>`
       principal name, on a per-instance basis. If unspecified, the
       default value is ``mongodb``.
 

source/reference/method/sh.addShard.txt

@@ -42,7 +42,7 @@ Definition
 
       .. |mongodb-package| replace:: :program:`mongos`
 
-      .. include:: /includes/note-deb-and-rpm-default-to-localhost
+      .. include:: /includes/note-deb-and-rpm-default-to-localhost.rst
 
 The :method:`sh.addShard()` method is a helper for the
 :dbcommand:`addShard` command.

source/reference/program/mongod.txt

@@ -183,7 +183,7 @@ Core Options
 
    .. |mongodb-package| replace:: :program:`mongod`
 
-   .. include:: /includes/note-deb-and-rpm-default-to-localhost
+   .. include:: /includes/note-deb-and-rpm-default-to-localhost.rst
 
 .. option:: --unixSocketPrefix <path>
 
@@ -217,9 +217,9 @@ Core Options
 
    .. versionadded:: 2.4.6
       Allows users to override the default :doc:`Kerberos
-      <tutorial/control-access-to-mongodb-with-kerberos-authentication>`
+      </tutorial/control-access-to-mongodb-with-kerberos-authentication>`
       service name component of the :doc:`Kerberos
-      <tutorial/control-access-to-mongodb-with-kerberos-authentication>`
+      </tutorial/control-access-to-mongodb-with-kerberos-authentication>`
       principal name, on a per-instance basis. If unspecified, the
       default value is ``mongodb``.
 

source/reference/program/mongos.txt

@@ -177,7 +177,7 @@ Options
 
    .. |mongodb-package| replace:: :program:`mongos`
 
-   .. include:: /includes/note-deb-and-rpm-default-to-localhost
+   .. include:: /includes/note-deb-and-rpm-default-to-localhost.rst
 
 .. option:: --unixSocketPrefix <path>
 
@@ -199,9 +199,9 @@ Options
 
    .. versionadded:: 2.4.6
       Overrides the default :doc:`Kerberos
-      <tutorial/control-access-to-mongodb-with-kerberos-authentication>`
+      </tutorial/control-access-to-mongodb-with-kerberos-authentication>`
       service name component of the :doc:`Kerberos
-      <tutorial/control-access-to-mongodb-with-kerberos-authentication>`
+      </tutorial/control-access-to-mongodb-with-kerberos-authentication>`
       principal name, on a per-instance basis.
 
       Only available on :doc:`MongoDB Enterprise

source/reference/replica-configuration.txt

@@ -102,7 +102,7 @@ Configuration Variables
 
    .. |mongodb-package| replace:: :program:`mongod`
 
-   .. include:: /includes/note-deb-and-rpm-default-to-localhost
+   .. include:: /includes/note-deb-and-rpm-default-to-localhost.rst
 
 .. data:: local.system.replset.members[n].arbiterOnly
 

source/tutorial.txt

@@ -103,6 +103,8 @@ Security
 - :doc:`/tutorial/enable-authentication`
 - :doc:`/tutorial/add-user-administrator`
 - :doc:`/tutorial/add-user-to-database`
+- :doc:`/tutorial/create-a-role`
+- :doc:`/tutorial/view-roles`
 - :doc:`/tutorial/generate-key-file`
 - :doc:`/tutorial/control-access-to-mongodb-with-kerberos-authentication`
 - :doc:`/tutorial/create-a-vulnerability-report`

source/tutorial/configure-ldap-sasl-authentication.txt

@@ -108,7 +108,7 @@ Socket of the ``saslauthd`` instance and the
 :parameter:`authenticationMechanisms` parameter to ``PLAIN``.
 
 Configure the MongoDB server using either the command line option
-:doc:`--setParameter <reference/parameters>` or the :doc:`configuration
+:doc:`--setParameter </reference/parameters>` or the :doc:`configuration
 file </reference/configuration-options>`:
 
 - If ``saslauthd`` has a socket path of ``/<some>/<path>/saslauthd``,

source/tutorial/create-a-role.txt

@@ -0,0 +1,82 @@
+===================
+Create Custom Roles
+===================
+
+.. default-domain:: mongodb
+
+MongoDB provides the ability to create custom roles in addition to the
+MongoDB :doc:`built-in roles </reference/user-privileges>`.
+
+.. _custom-roles:
+
+Custom Roles
+------------
+
+You can create custom roles to govern access a user or application has to
+collections and databases. A role contains privileges that define a
+specific set of actions that can be performed against specific resources.
+
+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 or client application receives all the
+privileges of that role.
+
+Required Authorization
+----------------------
+
+To create roles and privileges, you must have the appropriate
+authorization:
+
+- To create a role you must have the :authaction:`createRole` action on
+  the database.
+
+- To specify a privilege, you must have the :authaction:`grantAnyRole`
+  action on the database the privilege targets. If the privilege targets
+  multiple databases or the ``cluster`` resource, you must have the
+  :authaction:`grantAnyRole` action on the ``admin`` database.
+
+- To assign a member role, you must have the :authaction:`grantAnyRole`
+  action on the member role's database.
+
+Create a Role
+-------------
+
+To create a role, use the :dbcommand:`createRole` command and specify the
+privileges and the member roles that this role contains.
+
+A privilege pairs resources, such as databases and collections, with
+actions, such as ``find`` and ``insert``. MongoDB provides the actions
+described in :ref:`security-user-actions`. Specify each privilege in its
+own :ref:`resource document <resource-document>` in
+:data:`~admin.system.roles.privileges` array.
+
+A member role provides all its privileges to the new role. Specify each
+member role in its own document in the :data:`~admin.system.roles.roles`
+array. The documents in the :data:`~admin.system.roles.roles` array use the
+following syntax:
+
+.. code-block:: javascript
+
+   { role: "<role name>", db: "<role database>" }
+
+.. example::
+
+   The following command from the :program:`mongo` shell creates the
+   ``myClusterwideAdmin`` role with privileges defined in four
+   :ref:`resource documents <resource-document>` and privileges inherited
+   from the ``read`` role on the ``admin`` database.
+
+   .. code-block:: javascript
+
+      db.runCommand( { 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 }
+                   } )

source/tutorial/view-roles.txt

@@ -0,0 +1,76 @@
+===================
+View Existing Roles
+===================
+
+.. default-domain:: mongodb
+
+MongoDB stores roles in the :data:`admin.system.roles` collection in the
+``admin`` database. Each document in the collection contains the privileges
+granted by a specific role.
+
+To view a role you must have the :authaction:`viewRole` action on the
+role's database or be authenticated as a user explicitly granted the role.
+
+To view a role, use the :dbcommand:`rolesInfo` command:
+
+   .. code-block:: javascript
+
+      { rolesInfo: <role> }
+
+For example, to view the system :authrole:`readWrite` role issue the
+following command from the :program:`mongo` shell:
+
+   .. code-block:: javascript
+
+      db.runCommand({ rolesInfo: "readWrite" })
+
+View a Role in the Current Database
+-----------------------------------
+
+If the role is in the current database, specify the role in quotes, as above and as shown here
+for the custom role ``dataEntry``:
+
+   .. code-block:: javascript
+
+      db.runCommand({ rolesInfo: "dataEntry" })
+
+View a Role in a Different Database
+-----------------------------------
+
+If the role is in a different database, specify the role as a document.
+Use the following form:
+
+.. code-block:: javascript
+
+   { role: "<role name>", db: "<role db>" }
+
+For example, to view the custom ``appWriter`` role in the ``orders``
+database, issue the following command from the :program:`mongo` shell:
+
+.. code-block:: javascript
+
+   db.runCommand({ rolesInfo: { role: "appWriter", db: "orders" } })
+
+View Multiple Roles
+-------------------
+
+To view information for multiple roles, specify each role as a document or
+string in an array.
+
+For example, to view the custom ``appWriter`` and ``clientWriter`` roles
+in the ``orders`` database and to view the ``dataEntry`` role on the
+current database, issue the following command from the :program:`mongo`
+shell:
+
+.. code-block:: javascript
+
+   db.runCommand( { rolesInfo: [ { role: "appWriter", db: "orders" },
+                                 { role: "clientWriter", db: "orders" },
+                                 "dataEntry" ]
+                  } )
+
+View All Custom Roles
+---------------------
+
+To view the all custom roles, query :ref:`admin.system.roles
+<admin-system-roles-collection>` collection directly.