diff options
| -rw-r--r-- | doc/src/sgml/ref/alter_role.sgml | 2 | ||||
| -rw-r--r-- | doc/src/sgml/ref/create_role.sgml | 10 | ||||
| -rw-r--r-- | doc/src/sgml/ref/createuser.sgml | 18 | ||||
| -rw-r--r-- | doc/src/sgml/user-manag.sgml | 47 |
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 |