.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/src/man/Attic/createuser.1,v 1.10 1998/07/24 16:36:56 momjian Exp $
.TH CREATEUSER UNIX 11/05/95 PostgreSQL PostgreSQL
.SH NAME
createuser - create a Postgres user
.SH SYNOPSIS
.BR createuser
[\c
.BR -a
system]
[\c
.BR -h
host]
[\c
.BR -p
port]
[username]
.SH DESCRIPTION
.IR Createuser
creates a new Postgres user.  Only users with \*(lqusesuper\*(rq set in
the \*(lqpg_shadow\*(rq class can create new Postgres users.  As shipped,
the user \*(lqpostgres\*(rq can create users.
.PP
.IR Createuser
is a shell script that invokes
.IR psql .
Hence, a
.IR postmaster
process must be running on the database server host before
.IR createuser
is executed.  In addition, the
.SM PGOPTION
and
.SM PGREALM
environment
variables will be passed on to
.IR psql
and processed as described in 
.IR psql(1).
.PP
The optional argument
.IR username
specifies the name of the Postgres user to be created.  (The invoker will
be prompted for a name if none is specified on the command line.)
This name must be unique among all Postgres users.
.PP
.IR Createuser
understands the following command-line options:
.TP 5n
.BR "-a" " system"
Specifies an authentication system
.IR "system"
(see 
.IR pgintro(1))
to use in connecting to the 
.IR postmaster
process.  This option no longer has any effect.
.TP
.BR "-h" " host"
Specifies the hostname of the machine on which the 
.IR postmaster
is running.  Defaults to using local Unix domain sockets.
.TP
.BR "-p" " port"
Specifies the TCP/IP port or local Unix domain socket file
extension on which the
.IR postmaster
is listening for connections.  Defaults to 5432, or the value of the
.SM PGPORT
environment variable (if set).
.SH "INTERACTIVE QUESTIONS"
Once invoked with the above options,
.IR createuser
will ask a series of questions.  The new users's login name (if not
given on the command line) and user-id must be specified.  (Note that
the Postgres user-id must be the same as the user's Unix user-id.)  In
addition, you must describe the security capabilities of the new user.
Specifically, you will be asked whether the new user should be able to
act as Postgres super-user, create new databases and update the system
catalogs manually.
.SH "SEE ALSO"
create_user(l),
destroyuser(1),
psql(1),
postmaster(1).
.SH DIAGNOSTICS
.TP 5n
.BI "Error: Failed to connect to backend (host=" "xxx" ", port=" "xxx" ")"
.IR Createuser
could not attach to the 
.IR postmaster 
process on the specified host and port.  If you see this message,
ensure that the
.IR postmaster
is running on the proper host and that you have specified the proper
port.  If your site uses an authentication system, ensure that you
have obtained the required authentication credentials.
.TP
.BI "user \*(lq" "username" "\*(rq is not in \*(lqpg_shadow\*(rq"
You do not have a valid entry in the relation \*(lqpg_shadow\*(rq and
cannot do anything with Postgres at all; contact your Postgres site
administrator.
.TP
.IB "username" " cannot create users."
You do not have permission to create new users; contact your Postgres
site administrator.
.TP
.BI "user \*(lq" "username" "\*(rq already exists"
The user to be added already has an entry in the \*(lqpg_shadow\*(rq
class.
.TP
.BR "database access failed"
An internal error occurred in 
.IR psql
or the backend server.  Ensure that your Postgres site administrator has
properly installed Postgres and initialized the site with 
.IR initdb .
.SH NOTE
The command internally runs \fIpsql\fP connected to the \fItemplate1\fP
database to perform the operation.
.SH BUGS
Postgres user-ids and user names should not have anything to do with the
constraints of Unix.