Improve documentation of the CREATEROLE attibute.

In user-manag.sgml, document precisely what privileges are conveyed
by CREATEROLE. Make particular note of the fact that it allows
changing passwords and granting access to high-privilege roles.
Also remove the suggestion of using a user with CREATEROLE and
CREATEDB instead of a superuser, as there is no real security
advantage to this approach.

Elsewhere in the documentation, adjust text that suggests that
CREATEROLE only allows for role creation, and
refer to the documentation in user-manag.sgml as appropriate.

Patch by me, reviewed by Álvaro Herrera

Discussion: http://postgr.es/m/CA+TgmoZBsPL8nPhvYecx7iGo5qpDRqa9k_AcaW1SbOjugAY1Ag@mail.gmail.com

diff --git a/doc/src/sgml/ref/alter_role.sgml b/doc/src/sgml/ref/alter_role.sgml
index 33ac7327070b735d80e03a376d7754de261a0c55..8a8f8281375de2f13e357902c6b3b46f47bc49d8 100644 (file)
--- a/doc/src/sgml/ref/alter_role.sgml
+++ b/doc/src/sgml/ref/alter_role.sgml
@@ -320,7 +320,7 @@ ALTER ROLE fred VALID UNTIL 'infinity';
   
 
   
-   Give a role the ability to create other roles and new databases:
+   Give a role the ability to manage other roles and create new databases:
 
 
 ALTER ROLE miriam CREATEROLE CREATEDB;

diff --git a/doc/src/sgml/ref/create_role.sgml b/doc/src/sgml/ref/create_role.sgml
index 029a1933615041a102b74641e3ef1f5188b9c6db..1ccc8325588fb141a69e76719c3356e78122d556 100644 (file)
--- a/doc/src/sgml/ref/create_role.sgml
+++ b/doc/src/sgml/ref/create_role.sgml
@@ -119,11 +119,11 @@ in sync when changing the above synopsis!
       
        
         These clauses determine whether a role will be permitted to
-        create new roles (that is, execute CREATE ROLE).
-        A role with CREATEROLE privilege can also alter
-        and drop other roles.
-        If not specified,
-        NOCREATEROLE is the default.
+        create, alter, drop, comment on, change the security label for,
+        and grant or revoke membership in other roles.
+        See  for more details about what
+        capabilities are conferred by this privilege.
+        If not specified, NOCREATEROLE is the default.
        
       
      

diff --git a/doc/src/sgml/ref/createuser.sgml b/doc/src/sgml/ref/createuser.sgml
index c6a7c603f7815e4fc550e01a3ac865d1f77874b0..a41a2b24e6c53106e8ab88410ae74c90cff3ba59 100644 (file)
--- a/doc/src/sgml/ref/createuser.sgml
+++ b/doc/src/sgml/ref/createuser.sgml
@@ -41,10 +41,14 @@ PostgreSQL documentation
   
 
   
-   If you wish to create a new superuser, you must connect as a
-   superuser, not merely with CREATEROLE privilege.
+   If you wish to create a role with the SUPERUSER,
+   REPLICATION, or BYPASSRLS privilege,
+   you must connect as a superuser, not merely with
+   CREATEROLE privilege.
    Being a superuser implies the ability to bypass all access permission
-   checks within the database, so superuser access should not be granted lightly.
+   checks within the database, so superuser access should not be granted
+   lightly. CREATEROLE also conveys
+   very extensive privileges.
   
 
   
@@ -247,8 +251,12 @@ PostgreSQL documentation
       --createrole
       
        
-        The new user will be allowed to create new roles (that is,
-        this user will have CREATEROLE privilege).
+        The new user will be allowed to create, alter, drop, comment on,
+        change the security label for, and grant or revoke membership in
+        other roles; that is,
+        this user will have CREATEROLE privilege.
+        See  for more details about what
+        capabilities are conferred by this privilege.
        
       
      

diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml
index 77159879c7cfe58d722f796a7c824ba188cbe0df..7aa6bdac16360fa5efb9834e8f2079eb8f70d51c 100644 (file)
--- a/doc/src/sgml/user-manag.sgml
+++ b/doc/src/sgml/user-manag.sgml
@@ -191,7 +191,7 @@ CREATE USER name;
      
 
      
-      role creationroleprivilege to create
+       id='role-creation'>role creationroleprivilege to create
       
        
         A role must be explicitly given permission to create more roles
@@ -200,9 +200,38 @@ CREATE USER name;
         name CREATEROLE.
         A role with CREATEROLE privilege can alter and drop
         other roles, too, as well as grant or revoke membership in them.
-        However, to create, alter, drop, or change membership of a
-        superuser role, superuser status is required;
-        CREATEROLE is insufficient for that.
+        Altering a role includes most changes that can be made using
+        ALTER ROLE, including, for example, changing
+        passwords.  It also includes modifications to a role that can
+        be made using the COMMENT and
+        SECURITY LABEL commands.
+       
+       
+        However, CREATEROLE does not convey the ability to
+        create SUPERUSER roles, nor does it convey any
+        power over SUPERUSER roles that already exist.
+        Furthermore, CREATEROLE does not convey the power
+        to create REPLICATION users, nor the ability to
+        grant or revoke the REPLICATION privilege, nor the
+        ability to modify the role properties of such users.  However, it does
+        allow ALTER ROLE ... SET and
+        ALTER ROLE ... RENAME to be used on
+        REPLICATION roles, as well as the use of
+        COMMENT ON ROLE,
+        SECURITY LABEL ON ROLE,
+        and DROP ROLE.
+        Finally, CREATEROLE does not
+        confer the ability to grant or revoke the BYPASSRLS
+        privilege.
+       
+       
+        Because the CREATEROLE privilege allows a user
+        to grant or revoke membership even in roles to which it does not (yet)
+        have any access, a CREATEROLE user can obtain access
+        to the capabilities of every predefined role in the system, including
+        highly privileged roles such as
+        pg_execute_server_program and
+        pg_write_server_files.
        
       
      
@@ -280,16 +309,6 @@ CREATE USER name;
     and  commands for details.
    
 
-  
-   
-    It is good practice to create a role that has the CREATEDB
-    and CREATEROLE privileges, but is not a superuser, and then
-    use this role for all routine management of databases and roles.  This
-    approach avoids the dangers of operating as a superuser for tasks that
-    do not really require it.
-   
-  
-
   
    A role can also have role-specific defaults for many of the run-time
    configuration settings described in