postgresql/doc/src/sgml/ref/createuser.sgml

<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/createuser.sgml,v 1.45 2006/09/16 00:30:18 momjian 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>

     <varlistentry>
      <term><option>-q</></term>
      <term><option>--quiet</></term>
      <listitem>
       <para>
        Do not display a response.
       </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>--password</></term>
      <listitem>
       <para>
        Force password prompt (to connect to the server, not for the
        password of the new user).
       </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>
 </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>
<computeroutput>CREATE USER</computeroutput>
</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>
<computeroutput>CREATE ROLE</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 'xyzzy' SUPERUSER CREATEDB CREATEROLE INHERIT LOGIN;</computeroutput>
<computeroutput>CREATE ROLE</computeroutput>
</screen>
    In the above example, the new password isn't actually echoed when typed,
    but we show what was typed for clarity.  However the password
    <emphasis>will</> appear in the echoed command, as illustrated &mdash;
    so you don't want to use <literal>-e</> when assigning a password, 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>
   <member>Environment Variables (<xref linkend="libpq-envars">)</member>
  </simplelist>
 </refsect1>

</refentry>