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 43ae1629ea40a8317c7a39080d34addaccb30046..583c189b694c840f99c9e90e6f59366c501c8fd9 100644 (file)
--- a/doc/src/sgml/ref/alter_role.sgml
+++ b/doc/src/sgml/ref/alter_role.sgml
@@ -305,7 +305,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 c03b11a5752b0d4f3dfb56fd0c4cf4be1964657a..48298934225704a7da5bada974ae839e1b1ef4ee 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 f43b4a4adaa3074b71f32107e584cbf8aef37e0d..64d386431ef639a1a8121a16a5f0b0e76b5afa41 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.
   
 
   
@@ -221,8 +225,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 c64c470f76ef67056550dbf975dd520d1763cdb8..6358efe820c2dd181d0c6a45b97ed35b2b5ba0cd 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.
        
       
      
@@ -277,16 +306,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