diff options
Diffstat (limited to 'doc/src/sgml/ref/createuser.sgml')
| -rw-r--r-- | doc/src/sgml/ref/createuser.sgml | 506 |
1 files changed, 506 insertions, 0 deletions
diff --git a/doc/src/sgml/ref/createuser.sgml b/doc/src/sgml/ref/createuser.sgml new file mode 100644 index 0000000..0e1a39a --- /dev/null +++ b/doc/src/sgml/ref/createuser.sgml @@ -0,0 +1,506 @@ +<!-- +doc/src/sgml/ref/createuser.sgml +PostgreSQL documentation +--> + +<refentry id="app-createuser"> + <indexterm zone="app-createuser"> + <primary>createuser</primary> + </indexterm> + + <refmeta> + <refentrytitle><application>createuser</application></refentrytitle> + <manvolnum>1</manvolnum> + <refmiscinfo>Application</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>createuser</refname> + <refpurpose>define a new <productname>PostgreSQL</productname> user account</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>createuser</command> + <arg rep="repeat"><replaceable>connection-option</replaceable></arg> + <arg rep="repeat"><replaceable>option</replaceable></arg> + <arg choice="opt"><replaceable>username</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + + <refsect1> + <title>Description</title> + <para> + <application>createuser</application> creates a + new <productname>PostgreSQL</productname> user (or more precisely, a role). + Only superusers and users with <literal>CREATEROLE</literal> privilege can create + new users, so <application>createuser</application> must be + invoked by someone who can connect as a superuser or a user with + <literal>CREATEROLE</literal> privilege. + </para> + + <para> + 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. <literal>CREATEROLE</literal> also conveys + <link linkend='role-creation'>very extensive privileges</link>. + </para> + + <para> + <application>createuser</application> is a wrapper around the + <acronym>SQL</acronym> command <link linkend="sql-createrole"><command>CREATE ROLE</command></link>. + There is no effective difference between creating users via + this utility and via other methods for accessing the server. + </para> + + </refsect1> + + + <refsect1> + <title>Options</title> + + <para> + <application>createuser</application> accepts the following command-line arguments: + + <variablelist> + <varlistentry> + <term><replaceable class="parameter">username</replaceable></term> + <listitem> + <para> + Specifies the name of the <productname>PostgreSQL</productname> user + to be created. + This name must be different from all existing roles in this + <productname>PostgreSQL</productname> installation. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-c <replaceable class="parameter">number</replaceable></option></term> + <term><option>--connection-limit=<replaceable class="parameter">number</replaceable></option></term> + <listitem> + <para> + Set a maximum number of connections for the new user. + The default is to set no limit. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-d</option></term> + <term><option>--createdb</option></term> + <listitem> + <para> + The new user will be allowed to create databases. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-D</option></term> + <term><option>--no-createdb</option></term> + <listitem> + <para> + The new user will not be allowed to create databases. This is the + default. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-e</option></term> + <term><option>--echo</option></term> + <listitem> + <para> + Echo the commands that <application>createuser</application> generates + and sends to the server. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-E</option></term> + <term><option>--encrypted</option></term> + <listitem> + <para> + This option is obsolete but still accepted for backward + compatibility. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-g <replaceable class="parameter">role</replaceable></option></term> + <term><option>--role=<replaceable class="parameter">role</replaceable></option></term> + <listitem> + <para> + Indicates role to which this role will be added immediately as a new + member. Multiple roles to which this role will be added as a member + can be specified by writing multiple + <option>-g</option> switches. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-i</option></term> + <term><option>--inherit</option></term> + <listitem> + <para> + The new role will automatically inherit privileges of roles + it is a member of. + This is the default. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-I</option></term> + <term><option>--no-inherit</option></term> + <listitem> + <para> + The new role will not automatically inherit privileges of roles + it is a member of. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--interactive</option></term> + <listitem> + <para> + Prompt for the user name if none is specified on the command line, and + also prompt for whichever of the options + <option>-d</option>/<option>-D</option>, + <option>-r</option>/<option>-R</option>, + <option>-s</option>/<option>-S</option> is not specified on the command + line. (This was the default behavior up to PostgreSQL 9.1.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-l</option></term> + <term><option>--login</option></term> + <listitem> + <para> + The new user will be allowed to log in (that is, the user name + can be used as the initial session user identifier). + This is the default. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-L</option></term> + <term><option>--no-login</option></term> + <listitem> + <para> + The new user will not be allowed to log in. + (A role without login privilege is still useful as a means of + managing database permissions.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-P</option></term> + <term><option>--pwprompt</option></term> + <listitem> + <para> + If given, <application>createuser</application> will issue a prompt for + the password of the new user. This is not necessary if you do not plan + on using password authentication. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-r</option></term> + <term><option>--createrole</option></term> + <listitem> + <para> + 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> + + <varlistentry> + <term><option>-R</option></term> + <term><option>--no-createrole</option></term> + <listitem> + <para> + The new user will not be allowed to create new roles. This is the + default. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-s</option></term> + <term><option>--superuser</option></term> + <listitem> + <para> + The new user will be a superuser. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-S</option></term> + <term><option>--no-superuser</option></term> + <listitem> + <para> + The new user will not be a superuser. This is the default. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-V</option></term> + <term><option>--version</option></term> + <listitem> + <para> + Print the <application>createuser</application> version and exit. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--replication</option></term> + <listitem> + <para> + The new user will have the <literal>REPLICATION</literal> privilege, + which is described more fully in the documentation for <xref + linkend="sql-createrole"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--no-replication</option></term> + <listitem> + <para> + The new user will not have the <literal>REPLICATION</literal> + privilege, which is described more fully in the documentation for <xref + linkend="sql-createrole"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-?</option></term> + <term><option>--help</option></term> + <listitem> + <para> + Show help about <application>createuser</application> command line + arguments, and exit. + </para> + </listitem> + </varlistentry> + + </variablelist> + </para> + + <para> + <application>createuser</application> also accepts the following + command-line arguments for connection parameters: + + <variablelist> + <varlistentry> + <term><option>-h <replaceable class="parameter">host</replaceable></option></term> + <term><option>--host=<replaceable class="parameter">host</replaceable></option></term> + <listitem> + <para> + Specifies the host name of the machine on which the + server + is running. If the value begins with a slash, it is used + as the directory for the Unix domain socket. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-p <replaceable class="parameter">port</replaceable></option></term> + <term><option>--port=<replaceable class="parameter">port</replaceable></option></term> + <listitem> + <para> + Specifies the TCP port or local Unix domain socket file + extension on which the server + is listening for connections. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-U <replaceable class="parameter">username</replaceable></option></term> + <term><option>--username=<replaceable class="parameter">username</replaceable></option></term> + <listitem> + <para> + User name to connect as (not the user name to create). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-w</option></term> + <term><option>--no-password</option></term> + <listitem> + <para> + Never issue a password prompt. If the server requires + password authentication and a password is not available by + other means such as a <filename>.pgpass</filename> file, the + connection attempt will fail. This option can be useful in + batch jobs and scripts where no user is present to enter a + password. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-W</option></term> + <term><option>--password</option></term> + <listitem> + <para> + Force <application>createuser</application> to prompt for a + password (for connecting to the server, not for the + password of the new user). + </para> + + <para> + This option is never essential, since + <application>createuser</application> will automatically prompt + for a password if the server demands password authentication. + However, <application>createuser</application> will waste a + connection attempt finding out that the server wants a password. + In some cases it is worth typing <option>-W</option> to avoid the extra + connection attempt. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + + <refsect1> + <title>Environment</title> + + <variablelist> + <varlistentry> + <term><envar>PGHOST</envar></term> + <term><envar>PGPORT</envar></term> + <term><envar>PGUSER</envar></term> + + <listitem> + <para> + Default connection parameters + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>PG_COLOR</envar></term> + <listitem> + <para> + Specifies whether to use color in diagnostic messages. Possible values + are <literal>always</literal>, <literal>auto</literal> and + <literal>never</literal>. + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + This utility, like most other <productname>PostgreSQL</productname> utilities, + also uses the environment variables supported by <application>libpq</application> + (see <xref linkend="libpq-envars"/>). + </para> + + </refsect1> + + + <refsect1> + <title>Diagnostics</title> + + <para> + In case of difficulty, see <xref linkend="sql-createrole"/> + and <xref linkend="app-psql"/> for + discussions of potential problems and error messages. + The database server must be running at the + targeted host. Also, any default connection settings and environment + variables used by the <application>libpq</application> front-end + library will apply. + </para> + + </refsect1> + + + <refsect1> + <title>Examples</title> + + <para> + To create a user <literal>joe</literal> on the default database + server: +<screen> +<prompt>$ </prompt><userinput>createuser joe</userinput> +</screen> + </para> + + <para> + To create a user <literal>joe</literal> on the default database + server with prompting for some additional attributes: +<screen> +<prompt>$ </prompt><userinput>createuser --interactive joe</userinput> +<computeroutput>Shall the new role be a superuser? (y/n) </computeroutput><userinput>n</userinput> +<computeroutput>Shall the new role be allowed to create databases? (y/n) </computeroutput><userinput>n</userinput> +<computeroutput>Shall the new role be allowed to create more new roles? (y/n) </computeroutput><userinput>n</userinput> +</screen> + </para> + + <para> + To create the same user <literal>joe</literal> using the + server on host <literal>eden</literal>, port 5000, with attributes explicitly specified, + taking a look at the underlying command: +<screen> +<prompt>$ </prompt><userinput>createuser -h eden -p 5000 -S -D -R -e joe</userinput> +<computeroutput>CREATE ROLE joe NOSUPERUSER NOCREATEDB NOCREATEROLE INHERIT LOGIN;</computeroutput> +</screen> + </para> + + <para> + To create the user <literal>joe</literal> as a superuser, + and assign a password immediately: +<screen> +<prompt>$ </prompt><userinput>createuser -P -s -e joe</userinput> +<computeroutput>Enter password for new role: </computeroutput><userinput>xyzzy</userinput> +<computeroutput>Enter it again: </computeroutput><userinput>xyzzy</userinput> +<computeroutput>CREATE ROLE joe PASSWORD 'md5b5f5ba1a423792b526f799ae4eb3d59e' SUPERUSER CREATEDB CREATEROLE INHERIT LOGIN;</computeroutput> +</screen> + In the above example, the new password isn't actually echoed when typed, + but we show what was typed for clarity. As you see, the password is + encrypted before it is sent to the client. + </para> + </refsect1> + + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="app-dropuser"/></member> + <member><xref linkend="sql-createrole"/></member> + </simplelist> + </refsect1> + +</refentry> |