<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/createuser.sgml,v 1.36 2003/08/31 17:32:22 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.  
   Only superusers (users with <literal>usesuper</literal> set in
   the <literal>pg_shadow</literal> table) can create 
   new <productname>PostgreSQL</productname> users,
   so <application>createuser</application> must be
   invoked by someone who can connect as a <productname>PostgreSQL</productname>
   superuser.
  </para>

  <para>
   Being a superuser also implies the ability to bypass 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-CREATEUSER"
   endterm="SQL-CREATEUSER-title">.  The database server must be 
   running on the targeted host. There is nothing special
   about creating users via this or other methods. Also, any
   default settings and environment variables used by the
   <application>libpq</application> front-end library will apply.
  </para>

  <para>
   Passwords can only be added later or changed using the
   <acronym>SQL</acronym> command <xref linkend="SQL-ALTERUSER" 
   endterm="SQL-ALTERUSER-title">.
  </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 unique among all <productname>PostgreSQL</productname> users.
       </para>
      </listitem>
     </varlistentry>  

     <varlistentry>
      <term><option>-a</></term>
      <term><option>--adduser</></term>
      <listitem>
       <para>
	The new user is allowed to create other users.
	(Note: Actually, this makes the new user a <emphasis>superuser</>.
	The option is poorly named.)
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-A</></term>
      <term><option>--no-adduser</></term>
      <listitem>
       <para>
	The new user is not allowed to create other users (i.e.,
	the new user is a regular user, not a superuser).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-d</></term>
      <term><option>--createdb</></term>
      <listitem>
       <para>
	The new user is allowed to create databases.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-D</></term>
      <term><option>--no-createdb</></term>
      <listitem>
       <para>
	The new user is not allowed to create databases.
       </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>-E</></term>
      <term><option>--encrypted</></term>
      <listitem>
       <para>
	Encrypts the user's password stored in the database. If not
	specified, the default is used.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-i <replaceable class="parameter">number</replaceable></></term>
      <term><option>--sysid <replaceable class="parameter">number</replaceable></></term>
      <listitem>
       <para>
       Allows you to pick a non-default user ID for the new user. This is not
       necessary, but some people like it.
       </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 is used.
       </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>-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>

    <variablelist>
     <varlistentry>
      <term><computeroutput>CREATE USER</computeroutput></term>
      <listitem>
       <para>
        The user was successfully created.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><computeroutput>createuser: creation of user "<replaceable class="parameter">username</replaceable>" failed</computeroutput></term>
      <listitem>
       <para>
        Something went wrong. The user was not created.
       </para>
      </listitem>
     </varlistentry>

    </variablelist>

   <para>
    If there is an error condition, the backend error message will be displayed.
    See <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">
    for possibilities.
   </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>Is the new user allowed to create databases? (y/n) </computeroutput><userinput>n</userinput>
<computeroutput>Shall the new user be allowed to create more new users? (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 -p 5000 -h eden -D -A -e joe</userinput>
<computeroutput>CREATE USER "joe" NOCREATEDB NOCREATEUSER</computeroutput>
<computeroutput>CREATE USER</computeroutput>
</screen>
   </para>
 </refsect1>


 <refsect1>
  <title>See Also</title>

  <simplelist type="inline">
   <member><xref linkend="app-dropuser"></member>
   <member><xref linkend="sql-createuser" endterm="sql-createuser-title"></member>
  </simplelist>
 </refsect1>

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->
