edits to privlege modification tutorials

Author: Sam Kleinman

bin/builddata/htaccess-next.yaml

@@ -338,6 +338,22 @@ redirect-path: '/reference/command/cleanupOrphaned'
 url-base: '/administration/sharded-clusters'
 type: 'redirect'
 code: 303
+outputs:
+  - 'manual'
+  - 'before-v2.4'
+---
+redirect-path: '/tutorial/define-roles'
+url-base: '/administration/security-access-control'
+type: 'redirect'
+code: 303
+outputs:
+  - 'manual'
+  - 'before-v2.4'
+---
+redirect-path: '/tutorial/view-roles'
+url-base: '/administration/security-access-control'
+type: 'redirect'
+code: 303
 outputs:
   - 'manual'
   - 'before-v2.4'

source/tutorial/define-privilege.txt renamed to source/tutorial/define-privilege.rst

@@ -1,3 +1,7 @@
+.. renamed as an rst file to prevent this from being published in case
+   this is a stub. If its not we should remove this as it seems
+   redundant.
+
 ==================
 Define a Privilege
 ==================

source/tutorial/define-roles.txt

@@ -1,16 +1,26 @@
-=============
-Create a Role
-=============
+===========================
+Define MongoDB Access Roles
+===========================
 
 .. default-domain:: mongodb
 
 .. todo:: Link 'role' below to the conceptual doc, when written
 
-Roles grant users access to MongoDB resources. Create roles to define
-access to resources according to your operational needs.
+Overview
+--------
 
-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.
+Roles grant users access to MongoDB resources. By default, MongoDB
+provides a number of roles that administrators may use to control
+access to a MongoDB system. However, if these roles cannot describe
+the proper limited subset of access that a user might require in a
+deployment, you can define a unique role to provide these access.
+
+Create new roles to define access to resources according to the
+operational needs of a deployment.
+
+MongoDB limits the scope of each role to the database where the role
+was created. The combination of database name and name of role
+uniquely defines a role in MongoDB.
 
 Prerequisites
 -------------
@@ -30,39 +40,37 @@ When creating the role, enter these resource-action pairings in
 :ref:`resource documents <resource-document>` in the
 :data:`~admin.system.roles.privileges` array.
 
-Identify Privileges from Other Roles
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Identify Privileges from Existing Roles
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If this role is to include all the privileges of an existing role, then instead
-of re-creating those privileges, you can add the existing role to this role.
-The contained role provides all its privileges to the new role.
+If this role must include *all* the privileges of an existing role,
+you can add the existing role to this role, rather than adding
+privileges individually. The member role provides all its privileges
+to the containing role.
 
 When creating the new role, specify each contained role in its own
 document in the :data:`~admin.system.roles.roles` array.
 
 Create the Role
 ~~~~~~~~~~~~~~~
 
-To create the role, use the :dbcommand:`createRole` command.
-
-.. 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 }
-                   } )
+To create the role, use the :dbcommand:`createRole` command. Consider
+the following example that 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

@@ -1,6 +1,6 @@
-===================
-View Existing Roles
-===================
+==========================
+View Existing Access Roles
+==========================
 
 .. default-domain:: mongodb
 
@@ -9,7 +9,8 @@ MongoDB stores roles in the :data:`admin.system.roles` collection in the
 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.
+role's database or have authenticated as a user explicitly granted the
+role.
 
 To view a role, use the :dbcommand:`rolesInfo` command:
 
@@ -24,18 +25,21 @@ following command from the :program:`mongo` shell:
 
       db.runCommand({ rolesInfo: "readWrite" })
 
+Procedures
+----------
+
 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``:
+If the role is in the current database, you can refer to the role
+by name, as for the role ``dataEntry`` on the current database:
 
-   .. code-block:: javascript
+.. code-block:: javascript
 
-      db.runCommand({ rolesInfo: "dataEntry" })
+   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:
@@ -44,22 +48,22 @@ Use the following form:
 
    { role: "<role name>", db: "<role db>" }
 
-For example, to view the custom ``appWriter`` role in the ``orders``
+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`
+To view the custom ``appWriter`` and ``clientWriter`` roles
+in the ``orders`` database, as well as the ``dataEntry`` role on the
+current database, use the following command from the :program:`mongo`
 shell:
 
 .. code-block:: javascript
@@ -70,7 +74,12 @@ shell:
                   } )
 
 View All Custom Roles
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 
 To view the all custom roles, query :ref:`admin.system.roles
-<admin-system-roles-collection>` collection directly.
+<admin-system-roles-collection>` collection directly, for example:
+
+.. code-block:: javascript
+
+   db = db.getSiblingDB('admin')
+   db.system.roles.find()