DOCS-2423 roles info output

source/core/access-control.txt

@@ -135,7 +135,7 @@ the privileges granted by the roles. Roles always grant privileges and
 never limit access. For example, if a user has both :authrole:`read`
 *and* :authrole:`readWriteAnyDatabase` roles on a database, the greater
 access prevails. A user's role assignments can include
-:ref:`system-defined roles <system-user-roles>` provided by MongoDB or
+:ref:`built-in roles <built-in-roles>` provided by MongoDB or
 a :ref:`custom roles <user-defined-roles>` defined by the user.
 
 To assign roles to users, you must be a user with an administrative

source/includes/access-roles-info.rst

@@ -1,3 +1,3 @@
-A user must have the :authaction:`viewRole` :ref:`action
-<security-user-actions>` on a role's database to view the role's
-information.
+To view a role's information, a user must be explicitly granted the
+role or must have the :authaction:`viewRole` :ref:`action
+<security-user-actions>` on the role's database.

source/includes/fact-roles-array-contents.rst

@@ -1,7 +1,7 @@
 .. the including document should define a |local-cmd-name| replacement
 
 In the ``roles`` field, you can specify both
-:ref:`system-defined roles <system-user-roles>` and :ref:`user-defined
+:ref:`built-in roles <built-in-roles>` and :ref:`user-defined
 role <user-defined-roles>`. 
 
 To specify a role that exists in the same database where

source/reference/command/rolesInfo-field.yaml

@@ -12,7 +12,8 @@ type:
     - integer
 position: 1
 description: |
-  The role(s) to return information about.
+  The role(s) to return information about. For the syntax for specifying
+  roles, see :ref:`rolesinfo-behavior`.
 ---
 object:
   name: rolesInfo
@@ -24,7 +25,23 @@ name: showPrivileges
 type: Boolean
 position: 2
 description: |
-  Set the field to true to show the role's privileges. By default, this
-  field is ``false`` and the command returns only the role's
-  inheritance information.
+  Set the field to ``true`` to show role privileges, including both privileges
+  inherited from other roles and privileges defined directly. By default, the
+  command returns only the roles from which this role inherits privileges and
+  does not return specific privileges.
+---
+object:
+  name: rolesInfo
+  type: dbcommand
+field:
+  optional: true
+  type: field
+name: showBuiltinRoles
+type: Boolean
+position: 3
+description: |
+  When the ``rolesInfo`` field is set to ``1``, set ``showBuiltinRoles`` to
+  ``true`` to include :ref:`built-in roles <built-in-roles>` in the output.
+  By default this field is set to ``false``, and the output for ``rolesInfo:
+  1`` displays only :ref:`user-defined roles <user-defined-roles>`.
 ...

source/reference/command/rolesInfo.txt

@@ -9,50 +9,114 @@ Definition
 
 .. dbcommand:: rolesInfo
 
-   Returns information for the specified role(s).
+   Returns inheritance and privilege information for specified roles,
+   including both :ref:`user-defined roles <user-defined-roles>` and
+   :ref:`built-in roles <built-in-roles>`.
+
+   The :dbcommand:`rolesInfo` command can also retrieve all roles
+   scoped to a database.
 
    The command has the following fields:
 
    .. include:: /reference/command/rolesInfo-field.rst
 
-To specify a single role, specify the role by a document that includes the
-role's name and database:
+.. _rolesinfo-behavior:
 
-.. code-block:: javascript
+Behavior
+--------
 
-   rolesInfo: { role: "<rolename>", db: "<database>" }
+When specifying roles, use the syntax described here.
 
-Alternately, if the role exists in the database on which the command runs,
-you can instead specify the role just by its name:
+To specify a role from the current database, specify the role by its name:
 
 .. code-block:: javascript
 
    rolesInfo: "<rolename>"
 
-To specify multiple roles, specify an array of roles. Specify each role in
-the array as a document or string. Use a string only if the role exists on
-the database on which the command runs:
+To specify a role from another database, specify the role by a document that
+specifies the role and database:
+
+.. code-block:: javascript
+
+   rolesInfo: { role: "<rolename>", db: "<database>" }
+
+To specify multiple roles, use an array. Specify each role in the array as a
+document or string. Use a string only if the role exists on the database on
+which the command runs:
 
 .. code-block:: javascript
 
-   rolesInfo: [ "<rolename1>",
-                { role: "<rolename2>", db: "<database>" },
-                { role: "<rolename3>", db: "<database>" },
-                // <...>
-              ]
+   rolesInfo:
+     [
+       "<rolename>",
+       { role: "<rolename>", db: "<database>" },
+         ...
+     ]
 
 To specify all roles in the database on which the command runs, specify
-``1``:
+``rolesInfo: 1``. By default MongoDB displays all the :ref:`user-defined roles
+<user-defined-roles>` in the database. To include :ref:`built-in roles
+<built-in-roles>` as well, include the parameter-value pair
+``showBuiltinRoles: true``:
 
 .. code-block:: javascript
 
-   rolesInfo: 1
+   rolesInfo: 1, showBuiltinRoles: true
 
 Required Access
 ---------------
 
 .. include:: /includes/access-roles-info.rst
 
+.. _rolesinfo-output:
+
+Output
+------
+
+.. data:: rolesInfo.role
+
+   The name of the role.
+
+.. data:: rolesInfo.db
+
+   The database on which the role is defined. Every database has :ref:`built-in
+   roles <built-in-roles>`. A database might also have :ref:`user-defined
+   roles <user-defined-roles>`.
+
+.. data:: rolesInfo.roles
+
+   The roles that directly provide privileges to this role and the databases
+   on which the roles are defined.
+
+.. data:: rolesInfo.indirectRoles
+
+   .. todo:: change this to "inheritedRoles" when the software changes
+
+   All roles from which this role inherits privileges. This includes the roles
+   in the :data:`rolesInfo.roles` array as well as the roles from which the
+   roles in the :data:`rolesInfo.roles` array inherit privileges. All
+   privileges apply to the current role. The documents in this field list the
+   roles and the databases on which they are defined.
+
+.. data:: rolesInfo.privileges
+
+   All the privileges granted by this role. By default the output does not
+   include this array. To include it, specify ``showPrivileges: true`` when
+   running the :dbcommand:`rolesInfo` command.
+
+   The array includes privileges defined directly in the role as well as
+   privileges inherited from other roles.
+
+   Each set of privileges in the array is contained in its own document. Each
+   document specifies the :ref:`resources <resource-document>` the privilege
+   accesses and the :doc:`actions </reference/privilege-actions>` allowed.
+
+.. data:: rolesInfo.isBuiltin
+
+   A value of ``true`` indicates the role is a :ref:`built-in role
+   <built-in-roles>`. A value of ``false`` indicates the role is a
+   :ref:`user-defined role <user-defined-roles>`.
+
 Examples
 --------
 
@@ -64,63 +128,96 @@ role ``associate`` defined in the ``products`` database:
 
 .. code-block:: javascript
 
-   db.runCommand( { rolesInfo: { role: "associate", db: "products" } } )
+   db.runCommand(
+       {
+         rolesInfo: { role: "associate", db: "products" }
+       }
+   )
 
-If the :dbcommand:`rolesInfo` command is run on the ``products``
-database, you can specify the role by its name only, as in:
+The following command returns the role inheritance information for the role
+``siteManager`` on the database on which the command runs:
 
 .. code-block:: javascript
 
-   db.getSiblingDB("products"). runCommand( { rolesInfo: "associate" } )
+   db.runCommand(
+       {
+         rolesInfo: "siteManager"
+       }
+   )
 
-The following command returns *both* the role inheritance and the
-privileges for the role ``associate`` defined in the ``products``
-database:
+The following command returns *both* the role inheritance and the privileges
+for the role ``associate`` defined on the ``products`` database:
 
 .. code-block:: javascript
 
-   db.runCommand( { rolesInfo: { role: "associate", db: "products" },
-                    showPrivileges: true
-                } )
+   db.runCommand(
+       {
+         rolesInfo:
+           { role: "associate", db: "products" },
+           showPrivileges: true
+       }
+   )
 
 View Information for Several Roles
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To view information for several roles, use an array of roles:
+The following command returns information for two roles on two different
+databases:
 
 .. code-block:: javascript
 
-   db.runCommand( { rolesInfo: [
-                                 { role: "associate", db: "products" },
-                                 { role: "manager", db: "resources" },
-                               ]
-                } )
+   db.runCommand(
+       {
+         rolesInfo:
+           [
+             { role: "associate", db: "products" },
+             { role: "manager", db: "resources" },
+           ]
+       }
+   )
 
-To return *both* the role inheritance and the privileges for the roles,
-include the showPrivileges field:
+The following returns *both* the role inheritance and the privileges:
 
 .. code-block:: javascript
 
-   db.runCommand( { rolesInfo: [
-                                 { role: "associate", db: "products" },
-                                 { role: "manager", db: "resources" },
-                               ],
-                    showPrivileges: true
-                } )
+   db.runCommand(
+       {
+         rolesInfo:
+           [
+             { role: "associate", db: "products" },
+             { role: "manager", db: "resources" },
+           ],
+           showPrivileges: true
+       }
+   )
 
-View All Roles for a Database
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+View All User-Defined Roles for a Database
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To view all roles defined on the database the command is run, use a
-command document that resembles the following:
+The following operation returns all :ref:`user-defined roles
+<user-defined-roles>` on the database on which the command runs and includes
+privileges:
 
 .. code-block:: javascript
 
-    db.runCommand( { rolesInfo: 1 } )
+   db.runCommand(
+       {
+         rolesInfo: 1,
+         showPrivileges: true
+       }
+   )
+
+View All User-Defined and Built-In Roles for a Database
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-When viewing all roles, you can also include the ``showPrivileges``
-field in the command:
+The following operation returns all roles on the database on which the command
+runs, including both built-in and user-defined roles:
 
 .. code-block:: javascript
 
-    db.runCommand( { rolesInfo: 1, showPrivileges: 1 } )
+   db.runCommand(
+       {
+         rolesInfo: 1,
+         showBuiltinRoles: true
+       }
+   )

source/reference/system-defined-roles.txt

@@ -1,20 +1,19 @@
-====================
-System-Defined Roles
-====================
+==============
+Built-In Roles
+==============
 
-.. using System-Defined Roles instead of System Roles
-   since the user-defined roles are stored in system.roles collection
+.. Engineering wants us to use Built-in Roles instead of System-Defined Roles. -BG 2013-12-19
 
 .. default-domain:: mongodb
 
 MongoDB uses role-based authorization to give users access to data and
 commands. In addition to providing the ability to :ref:`create
 user-defined roles <user-defined-roles>`, MongoDB provides
-system-defined roles.
+built-in roles.
 
 .. TODO This page needs updates, both in content as well as style.
 
-.. _system-user-roles:
+.. _built-in-roles:
 
 Roles
 -----

source/reference/system-roles-collection.txt

@@ -114,8 +114,8 @@ A ``system.roles`` document has the following fields:
 
    .. data:: admin.system.roles.roles[n].role
 
-      The name of the role. A role can be a :ref:`system-defined role
-      <system-user-roles>` provided by MongoDB or a :ref:`user-defined
+      The name of the role. A role can be a :ref:`built-in role
+      <built-in-roles>` provided by MongoDB or a :ref:`user-defined
       role <user-defined-roles>`.
 
    .. data:: admin.system.roles.roles[n].db

source/reference/system-users-collection.txt

@@ -65,7 +65,7 @@ Each ``system.users`` document has the following fields:
 
    The :data:`~admin.system.users.roles` array contains role documents
    that specify the roles granted to the user. The array contains both
-   :ref:`system-defined roles <system-user-roles>` and :ref:`user-defined
+   :ref:`built-in roles <built-in-roles>` and :ref:`user-defined
    role <user-defined-roles>`.
 
    A role document has the following syntax:
@@ -78,8 +78,8 @@ Each ``system.users`` document has the following fields:
 
    .. data:: admin.system.users.roles[n].role
 
-      The name of a role. A role can be a :ref:`system-defined role
-      <system-user-roles>` provided by MongoDB or a :ref:`custom
+      The name of a role. A role can be a :ref:`built-in role
+      <built-in-roles>` provided by MongoDB or a :ref:`custom
       user-defined role <user-defined-roles>`.
 
    .. data:: admin.system.users.roles[n].db