granicus.if.org Git - postgresql/blob - src/man/createuser.1

   1 .\" This is -*-nroff-*-
   2 .\" XXX standard disclaimer belongs here....
   3 .\" $Header: /cvsroot/pgsql/src/man/Attic/createuser.1,v 1.6 1998/01/26 01:42:44 scrappy Exp $
   4 .TH CREATEUSER UNIX 11/05/95 PostgreSQL PostgreSQL
   5 .SH NAME
   6 createuser - create a Postgres user
   7 .SH SYNOPSIS
   8 .BR createuser
   9 [\c
  10 .BR -a
  11 system]
  12 [\c
  13 .BR -h
  14 host]
  15 [\c
  16 .BR -p
  17 port]
  18 [username]
  19 .SH DESCRIPTION
  20 .IR Createuser
  21 creates a new Postgres user.  Only users with \*(lqusesuper\*(rq set in
  22 the \*(lqpg_user\*(rq class can create new Postgres users.  As shipped,
  23 the user \*(lqpostgres\*(rq can create users.
  24 .PP
  25 .IR Createuser
  26 is a shell script that invokes
  27 .IR psql .
  28 Hence, a
  29 .IR postmaster
  30 process must be running on the database server host before
  31 .IR createuser
  32 is executed.  In addition, the
  33 .SM PGOPTION
  34 and
  35 .SM PGREALM
  36 environment
  37 variables will be passed on to
  38 .IR psql
  39 and processed as described in
  40 .IR psql (1).
  41 .PP
  42 The optional argument
  43 .IR username
  44 specifies the name of the Postgres user to be created.  (The invoker will
  45 be prompted for a name if none is specified on the command line.)
  46 This name must be unique among all Postgres users.
  47 .PP
  48 .IR Createuser
  49 understands the following command-line options:
  50 .TP 5n
  51 .BR "-a" " system"
  52 Specifies an authentication system
  53 .IR "system"
  54 (see
  55 .IR pgintro (1))
  56 to use in connecting to the
  57 .IR postmaster
  58 process.  This option no longer has any effect.
  59 .TP
  60 .BR "-h" " host"
  61 Specifies the hostname of the machine on which the
  62 .IR postmaster
  63 is running.  Defaults to using local Unix domain sockets.
  64 .TP
  65 .BR "-p" " port"
  66 Specifies the TCP/IP port or local Unix domain socket file
  67 extension on which the
  68 .IR postmaster
  69 is listening for connections.  Defaults to 5432, or the value of the
  70 .SM PGPORT
  71 environment variable (if set).
  72 .SH "INTERACTIVE QUESTIONS"
  73 Once invoked with the above options,
  74 .IR createuser
  75 will ask a series of questions.  The new users's login name (if not
  76 given on the command line) and user-id must be specified.  (Note that
  77 the Postgres user-id must be the same as the user's Unix user-id.)  In
  78 addition, you must describe the security capabilities of the new user.
  79 Specifically, you will be asked whether the new user should be able to
  80 act as Postgres super-user, create new databases and update the system
  81 catalogs manually.
  82 .SH "SEE ALSO"
  83 destroyuser(1),
  84 psql(1),
  85 postmaster(1).
  86 .SH DIAGNOSTICS
  87 .TP 5n
  88 .BI "Error: Failed to connect to backend (host=" "xxx" ", port=" "xxx" ")"
  89 .IR Createuser
  90 could not attach to the
  91 .IR postmaster
  92 process on the specified host and port.  If you see this message,
  93 ensure that the
  94 .IR postmaster
  95 is running on the proper host and that you have specified the proper
  96 port.  If your site uses an authentication system, ensure that you
  97 have obtained the required authentication credentials.
  98 .TP
  99 .BI "user \*(lq" "username" "\*(rq is not in \*(lqpg_user\*(rq"
 100 You do not have a valid entry in the relation \*(lqpg_user\*(rq and
 101 cannot do anything with Postgres at all; contact your Postgres site
 102 administrator.
 103 .TP
 104 .IB "username" " cannot create users."
 105 You do not have permission to create new users; contact your Postgres
 106 site administrator.
 107 .TP
 108 .BI "user \*(lq" "username" "\*(rq already exists"
 109 The user to be added already has an entry in the \*(lqpg_user\*(rq
 110 class.
 111 .TP
 112 .BR "database access failed"
 113 An internal error occurred in
 114 .IR psql
 115 or the backend server.  Ensure that your Postgres site administrator has
 116 properly installed Postgres and initialized the site with
 117 .IR initdb .
 118 .SH BUGS
 119 Postgres user-ids and user names should not have anything to do with the
 120 constraints of Unix.