Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 1c77873

Browse filesBrowse files
robertmhaasrobertmhaas
committed
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
1 parent 54afdcd commit 1c77873
Copy full SHA for 1c77873

File tree

4 files changed

+52
-25
lines changed
Filter options

4 files changed

+52
-25
lines changed

‎doc/src/sgml/ref/alter_role.sgml

Copy file name to clipboardExpand all lines: doc/src/sgml/ref/alter_role.sgml
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -320,7 +320,7 @@ ALTER ROLE fred VALID UNTIL 'infinity';
320320
</para>
321321

322322
<para>
323-
Give a role the ability to create other roles and new databases:
323+
Give a role the ability to manage other roles and create new databases:
324324

325325
<programlisting>
326326
ALTER ROLE miriam CREATEROLE CREATEDB;

‎doc/src/sgml/ref/create_role.sgml

Copy file name to clipboardExpand all lines: doc/src/sgml/ref/create_role.sgml
+5-5Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -119,11 +119,11 @@ in sync when changing the above synopsis!
119119
<listitem>
120120
<para>
121121
These clauses determine whether a role will be permitted to
122-
create new roles (that is, execute <command>CREATE ROLE</command>).
123-
A role with <literal>CREATEROLE</literal> privilege can also alter
124-
and drop other roles.
125-
If not specified,
126-
<literal>NOCREATEROLE</literal> is the default.
122+
create, alter, drop, comment on, change the security label for,
123+
and grant or revoke membership in other roles.
124+
See <xref linkend='role-creation' /> for more details about what
125+
capabilities are conferred by this privilege.
126+
If not specified, <literal>NOCREATEROLE</literal> is the default.
127127
</para>
128128
</listitem>
129129
</varlistentry>

‎doc/src/sgml/ref/createuser.sgml

Copy file name to clipboardExpand all lines: doc/src/sgml/ref/createuser.sgml
+13-5Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -41,10 +41,14 @@ PostgreSQL documentation
4141
</para>
4242

4343
<para>
44-
If you wish to create a new superuser, you must connect as a
45-
superuser, not merely with <literal>CREATEROLE</literal> privilege.
44+
If you wish to create a role with the <literal>SUPERUSER</literal>,
45+
<literal>REPLICATION</literal>, or <literal>BYPASSRLS</literal> privilege,
46+
you must connect as a superuser, not merely with
47+
<literal>CREATEROLE</literal> privilege.
4648
Being a superuser implies the ability to bypass all access permission
47-
checks within the database, so superuser access should not be granted lightly.
49+
checks within the database, so superuser access should not be granted
50+
lightly. <literal>CREATEROLE</literal> also conveys
51+
<link linkend='role-creation'>very extensive privileges</link>.
4852
</para>
4953

5054
<para>
@@ -247,8 +251,12 @@ PostgreSQL documentation
247251
<term><option>--createrole</option></term>
248252
<listitem>
249253
<para>
250-
The new user will be allowed to create new roles (that is,
251-
this user will have <literal>CREATEROLE</literal> privilege).
254+
The new user will be allowed to create, alter, drop, comment on,
255+
change the security label for, and grant or revoke membership in
256+
other roles; that is,
257+
this user will have <literal>CREATEROLE</literal> privilege.
258+
See <xref linkend='role-creation' /> for more details about what
259+
capabilities are conferred by this privilege.
252260
</para>
253261
</listitem>
254262
</varlistentry>

‎doc/src/sgml/user-manag.sgml

Copy file name to clipboardExpand all lines: doc/src/sgml/user-manag.sgml
+33-14Lines changed: 33 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -191,7 +191,7 @@ CREATE USER <replaceable>name</replaceable>;
191191
</varlistentry>
192192

193193
<varlistentry>
194-
<term>role creation<indexterm><primary>role</primary><secondary>privilege to create</secondary></indexterm></term>
194+
<term id='role-creation'>role creation<indexterm><primary>role</primary><secondary>privilege to create</secondary></indexterm></term>
195195
<listitem>
196196
<para>
197197
A role must be explicitly given permission to create more roles
@@ -200,9 +200,38 @@ CREATE USER <replaceable>name</replaceable>;
200200
<replaceable>name</replaceable> CREATEROLE</literal>.
201201
A role with <literal>CREATEROLE</literal> privilege can alter and drop
202202
other roles, too, as well as grant or revoke membership in them.
203-
However, to create, alter, drop, or change membership of a
204-
superuser role, superuser status is required;
205-
<literal>CREATEROLE</literal> is insufficient for that.
203+
Altering a role includes most changes that can be made using
204+
<literal>ALTER ROLE</literal>, including, for example, changing
205+
passwords. It also includes modifications to a role that can
206+
be made using the <literal>COMMENT</literal> and
207+
<literal>SECURITY LABEL</literal> commands.
208+
</para>
209+
<para>
210+
However, <literal>CREATEROLE</literal> does not convey the ability to
211+
create <literal>SUPERUSER</literal> roles, nor does it convey any
212+
power over <literal>SUPERUSER</literal> roles that already exist.
213+
Furthermore, <literal>CREATEROLE</literal> does not convey the power
214+
to create <literal>REPLICATION</literal> users, nor the ability to
215+
grant or revoke the <literal>REPLICATION</literal> privilege, nor the
216+
ability to modify the role properties of such users. However, it does
217+
allow <literal>ALTER ROLE ... SET</literal> and
218+
<literal>ALTER ROLE ... RENAME</literal> to be used on
219+
<literal>REPLICATION</literal> roles, as well as the use of
220+
<literal>COMMENT ON ROLE</literal>,
221+
<literal>SECURITY LABEL ON ROLE</literal>,
222+
and <literal>DROP ROLE</literal>.
223+
Finally, <literal>CREATEROLE</literal> does not
224+
confer the ability to grant or revoke the <literal>BYPASSRLS</literal>
225+
privilege.
226+
</para>
227+
<para>
228+
Because the <literal>CREATEROLE</literal> privilege allows a user
229+
to grant or revoke membership even in roles to which it does not (yet)
230+
have any access, a <literal>CREATEROLE</literal> user can obtain access
231+
to the capabilities of every predefined role in the system, including
232+
highly privileged roles such as
233+
<literal>pg_execute_server_program</literal> and
234+
<literal>pg_write_server_files</literal>.
206235
</para>
207236
</listitem>
208237
</varlistentry>
@@ -280,16 +309,6 @@ CREATE USER <replaceable>name</replaceable>;
280309
and <xref linkend="sql-alterrole"/> commands for details.
281310
</para>
282311

283-
<tip>
284-
<para>
285-
It is good practice to create a role that has the <literal>CREATEDB</literal>
286-
and <literal>CREATEROLE</literal> privileges, but is not a superuser, and then
287-
use this role for all routine management of databases and roles. This
288-
approach avoids the dangers of operating as a superuser for tasks that
289-
do not really require it.
290-
</para>
291-
</tip>
292-
293312
<para>
294313
A role can also have role-specific defaults for many of the run-time
295314
configuration settings described in <xref

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.