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
<literal>CREATEROLE</literal> 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

4 files changed, 52 insertions, 25 deletions

diff --git a/doc/src/sgml/ref/alter_role.sgml b/doc/src/sgml/ref/alter_role.sgml
index 33ac7327070..8a8f8281375 100644
--- 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';
   </para>
 
   <para>
-   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:
 
 <programlisting>
 ALTER ROLE miriam CREATEROLE CREATEDB;
diff --git a/doc/src/sgml/ref/create_role.sgml b/doc/src/sgml/ref/create_role.sgml
index 029a1933615..1ccc8325588 100644
--- 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!
       <listitem>
        <para>
         These clauses determine whether a role will be permitted to
-        create new roles (that is, execute <command>CREATE ROLE</command>).
-        A role with <literal>CREATEROLE</literal> privilege can also alter
-        and drop other roles.
-        If not specified,
-        <literal>NOCREATEROLE</literal> is the default.
+        create, alter, drop, comment on, change the security label for,
+        and grant or revoke membership in other roles.
+        See <xref linkend='role-creation' /> for more details about what
+        capabilities are conferred by this privilege.
+        If not specified, <literal>NOCREATEROLE</literal> is the default.
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/ref/createuser.sgml b/doc/src/sgml/ref/createuser.sgml
index c6a7c603f78..a41a2b24e6c 100644
--- a/doc/src/sgml/ref/createuser.sgml
+++ b/doc/src/sgml/ref/createuser.sgml
@@ -41,10 +41,14 @@ PostgreSQL documentation
   </para>
 
   <para>
-   If you wish to create a new superuser, you must connect as a
-   superuser, not merely with <literal>CREATEROLE</literal> privilege.
+   If you wish to create a role with the <literal>SUPERUSER</literal>,
+   <literal>REPLICATION</literal>, or <literal>BYPASSRLS</literal> privilege,
+   you must connect as a superuser, not merely with
+   <literal>CREATEROLE</literal> 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. <literal>CREATEROLE</literal> also conveys
+   <link linkend='role-creation'>very extensive privileges</link>.
   </para>
 
   <para>
@@ -247,8 +251,12 @@ PostgreSQL documentation
       <term><option>--createrole</option></term>
       <listitem>
        <para>
-        The new user will be allowed to create new roles (that is,
-        this user will have <literal>CREATEROLE</literal> 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 <literal>CREATEROLE</literal> privilege.
+        See <xref linkend='role-creation' /> for more details about what
+        capabilities are conferred by this privilege.
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml
index 77159879c7c..7aa6bdac163 100644
--- a/doc/src/sgml/user-manag.sgml
+++ b/doc/src/sgml/user-manag.sgml
@@ -191,7 +191,7 @@ CREATE USER <replaceable>name</replaceable>;
      </varlistentry>
 
      <varlistentry>
-      <term>role creation<indexterm><primary>role</primary><secondary>privilege to create</secondary></indexterm></term>
+      <term id='role-creation'>role creation<indexterm><primary>role</primary><secondary>privilege to create</secondary></indexterm></term>
       <listitem>
        <para>
         A role must be explicitly given permission to create more roles
@@ -200,9 +200,38 @@ CREATE USER <replaceable>name</replaceable>;
         <replaceable>name</replaceable> CREATEROLE</literal>.
         A role with <literal>CREATEROLE</literal> 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;
-        <literal>CREATEROLE</literal> is insufficient for that.
+        Altering a role includes most changes that can be made using
+        <literal>ALTER ROLE</literal>, including, for example, changing
+        passwords.  It also includes modifications to a role that can
+        be made using the <literal>COMMENT</literal> and
+        <literal>SECURITY LABEL</literal> commands.
+       </para>
+       <para>
+        However, <literal>CREATEROLE</literal> does not convey the ability to
+        create <literal>SUPERUSER</literal> roles, nor does it convey any
+        power over <literal>SUPERUSER</literal> roles that already exist.
+        Furthermore, <literal>CREATEROLE</literal> does not convey the power
+        to create <literal>REPLICATION</literal> users, nor the ability to
+        grant or revoke the <literal>REPLICATION</literal> privilege, nor the
+        ability to modify the role properties of such users.  However, it does
+        allow <literal>ALTER ROLE ... SET</literal> and
+        <literal>ALTER ROLE ... RENAME</literal> to be used on
+        <literal>REPLICATION</literal> roles, as well as the use of
+        <literal>COMMENT ON ROLE</literal>,
+        <literal>SECURITY LABEL ON ROLE</literal>,
+        and <literal>DROP ROLE</literal>.
+        Finally, <literal>CREATEROLE</literal> does not
+        confer the ability to grant or revoke the <literal>BYPASSRLS</literal>
+        privilege.
+       </para>
+       <para>
+        Because the <literal>CREATEROLE</literal> privilege allows a user
+        to grant or revoke membership even in roles to which it does not (yet)
+        have any access, a <literal>CREATEROLE</literal> user can obtain access
+        to the capabilities of every predefined role in the system, including
+        highly privileged roles such as
+        <literal>pg_execute_server_program</literal> and
+        <literal>pg_write_server_files</literal>.
        </para>
       </listitem>
      </varlistentry>
@@ -280,16 +309,6 @@ CREATE USER <replaceable>name</replaceable>;
     and <xref linkend="sql-alterrole"/> commands for details.
    </para>
 
-  <tip>
-   <para>
-    It is good practice to create a role that has the <literal>CREATEDB</literal>
-    and <literal>CREATEROLE</literal> 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.
-   </para>
-  </tip>
-
   <para>
    A role can also have role-specific defaults for many of the run-time
    configuration settings described in <xref