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

3 files changed, 19 insertions, 11 deletions

diff --git a/doc/src/sgml/ref/alter_role.sgml b/doc/src/sgml/ref/alter_role.sgml
index 5aa5648ae7b..922686e5ced 100644
--- a/doc/src/sgml/ref/alter_role.sgml
+++ b/doc/src/sgml/ref/alter_role.sgml
@@ -307,7 +307,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 b6a4ea1f722..89df6dbf721 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 17579e50afb..0e1a39a3fe6 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>
@@ -221,8 +225,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>