| <!-- |
| $PostgreSQL: pgsql/doc/src/sgml/ref/createuser.sgml,v 1.52 2009/02/26 16:02:37 petere Exp $ |
| PostgreSQL documentation |
| --> |
| |
| <refentry id="APP-CREATEUSER"> |
| <refmeta> |
| <refentrytitle id="APP-CREATEUSER-TITLE"><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> |
| |
| <indexterm zone="app-createuser"> |
| <primary>createuser</primary> |
| </indexterm> |
| |
| <refsynopsisdiv> |
| <cmdsynopsis> |
| <command>createuser</command> |
| <arg rep="repeat"><replaceable>option</replaceable></arg> |
| <arg><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</> 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</> privilege. |
| </para> |
| |
| <para> |
| If you wish to create a new superuser, you must connect as a |
| superuser, not merely with <literal>CREATEROLE</> privilege. |
| Being a superuser implies the ability to bypass all access permission |
| checks within the database, so superuserdom should not be granted lightly. |
| </para> |
| |
| <para> |
| <application>createuser</application> is a wrapper around the |
| <acronym>SQL</acronym> command <xref linkend="SQL-CREATEROLE" |
| endterm="SQL-CREATEROLE-title">. |
| 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</> 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>-s</></term> |
| <term><option>--superuser</></term> |
| <listitem> |
| <para> |
| The new user will be a superuser. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-S</></term> |
| <term><option>--no-superuser</></term> |
| <listitem> |
| <para> |
| The new user will not be a superuser. |
| This is the default. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-d</></term> |
| <term><option>--createdb</></term> |
| <listitem> |
| <para> |
| The new user will be allowed to create databases. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-D</></term> |
| <term><option>--no-createdb</></term> |
| <listitem> |
| <para> |
| The new user will not be allowed to create databases. |
| This is the default. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-r</></term> |
| <term><option>--createrole</></term> |
| <listitem> |
| <para> |
| The new user will be allowed to create new roles (that is, |
| this user will have <literal>CREATEROLE</> privilege). |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-R</></term> |
| <term><option>--no-createrole</></term> |
| <listitem> |
| <para> |
| The new user will not be allowed to create new roles. |
| This is the default. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-l</></term> |
| <term><option>--login</></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</></term> |
| <term><option>--no-login</></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>-i</></term> |
| <term><option>--inherit</></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</></term> |
| <term><option>--no-inherit</></term> |
| <listitem> |
| <para> |
| The new role will not automatically inherit privileges of roles |
| it is a member of. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-c <replaceable class="parameter">number</replaceable></></term> |
| <term><option>--connection-limit <replaceable class="parameter">number</replaceable></></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>-P</></term> |
| <term><option>--pwprompt</></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>-E</></term> |
| <term><option>--encrypted</></term> |
| <listitem> |
| <para> |
| Encrypts the user's password stored in the database. If not |
| specified, the default password behavior is used. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-N</></term> |
| <term><option>--unencrypted</></term> |
| <listitem> |
| <para> |
| Does not encrypt the user's password stored in the database. If |
| not specified, the default password behavior is used. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-e</></term> |
| <term><option>--echo</></term> |
| <listitem> |
| <para> |
| Echo the commands that <application>createuser</application> generates |
| and sends to the server. |
| </para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </para> |
| |
| <para> |
| You will be prompted for a name and other missing information if it |
| is not specified on the command line. |
| </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></></term> |
| <term><option>--host <replaceable class="parameter">host</replaceable></></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></></term> |
| <term><option>--port <replaceable class="parameter">port</replaceable></></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></></term> |
| <term><option>--username <replaceable class="parameter">username</replaceable></></term> |
| <listitem> |
| <para> |
| User name to connect as (not the user name to create). |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-w</></term> |
| <term><option>--no-password</></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</></term> |
| <term><option>--password</></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</> 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> |
| </variablelist> |
| |
| <para> |
| This utility, like most other <productname>PostgreSQL</> utilities, |
| also uses the environment variables supported by <application>libpq</> |
| (see <xref linkend="libpq-envars">). |
| </para> |
| |
| </refsect1> |
| |
| |
| <refsect1> |
| <title>Diagnostics</title> |
| |
| <para> |
| In case of difficulty, see <xref linkend="SQL-CREATEROLE" |
| endterm="sql-createrole-title"> 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> |
| <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</>, port 5000, avoiding the prompts and |
| 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. If the option <option>--unencrypted</option> |
| is used, the password <emphasis>will</> appear in the echoed command |
| (and possibly also in the server log and elsewhere), |
| so you don't want to use <option>-e</> in that case, if |
| anyone else can see your screen. |
| </para> |
| </refsect1> |
| |
| |
| <refsect1> |
| <title>See Also</title> |
| |
| <simplelist type="inline"> |
| <member><xref linkend="app-dropuser"></member> |
| <member><xref linkend="sql-createrole" endterm="sql-createrole-title"></member> |
| </simplelist> |
| </refsect1> |
| |
| </refentry> |