Authentication improvements:

A new pg_hba.conf column, USER
Allow specifiction of lists of users separated by commas
Allow group names specified by +
Allow include files containing lists of users specified by @
Allow lists of databases, and database files
Allow samegroup in database column to match group name matching dbname
Removal of secondary password files
Remove pg_passwd utility
Lots of code cleanup in user.c and hba.c
New data/global/pg_pwd format
New data/global/pg_group file

4 files changed, 274 insertions, 448 deletions

diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index 76542f98720..4afd179a4b1 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.33 2002/03/22 19:20:06 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.34 2002/04/04 04:25:44 momjian Exp $
 -->
 
 <chapter id="client-authentication">
@@ -10,14 +10,13 @@ $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.33 2002/03/22 19:20:06
  </indexterm>
 
  <para>
-  When a client application connects to the database server, it specifies which
-  <productname>PostgreSQL</productname> user name it wants to connect as,
-  much the same way one logs into a Unix computer as a particular user.
-  Within the SQL environment the active
-  database user name determines access privileges to database
-  objects -- see <xref linkend="user-manag"> for more information
-  about that. It is therefore obviously essential to restrict which
-  database user name(s) a given client can connect as.
+  When a client application connects to the database server, it
+  specifies which <productname>PostgreSQL</productname> user name it
+  wants to connect as, much the same way one logs into a Unix computer
+  as a particular user. Within the SQL environment the active database
+  user name determines access privileges to database objects -- see
+  <xref linkend="user-manag"> for more information. Therefore, it is
+  essential to restrict which database users can connect.
  </para>
 
  <para>
@@ -30,20 +29,19 @@ $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.33 2002/03/22 19:20:06
 
  <para>
   <productname>PostgreSQL</productname> offers a number of different
-  client authentication methods.  The method to be used can be selected
-  on the basis of (client) host and database; some authentication methods
-  allow you to restrict by user name as well.
+  client authentication methods. The method to be used can be selected
+  on the basis of (client) host, database, and user.
  </para>
 
  <para>
-  <productname>PostgreSQL</productname> database user names are logically
+  <productname>PostgreSQL</productname> user names are logically
   separate from user names of the operating system in which the server
-  runs.  If all the users of a particular server also have accounts on
+  runs. If all the users of a particular server also have accounts on
   the server's machine, it makes sense to assign database user names
-  that match their operating system user names.  However, a server that accepts remote
-  connections may have many users who have no local account, and in such
-  cases there need be no connection between database user names and OS
-  user names.
+  that match their operating system user names. However, a server that
+  accepts remote connections may have many users who have no local
+  account, and in such cases there need be no connection between
+  database user names and OS user names.
  </para>
 
  <sect1 id="pg-hba-conf">
@@ -56,39 +54,39 @@ $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.33 2002/03/22 19:20:06
   <para>
    Client authentication is controlled by the file
    <filename>pg_hba.conf</filename> in the data directory, e.g.,
-   <filename>/usr/local/pgsql/data/pg_hba.conf</filename>. (<acronym>HBA</> stands
-   for host-based authentication.) A default <filename>pg_hba.conf</filename>
-   file is installed when the
-   data area is initialized by <command>initdb</command>.
+   <filename>/usr/local/pgsql/data/pg_hba.conf</filename>.
+   (<acronym>HBA</> stands for host-based authentication.) A default
+   <filename>pg_hba.conf</filename> file is installed when the data area
+   is initialized by <command>initdb</command>.
   </para>
 
   <para>
-   The general format of the <filename>pg_hba.conf</filename> file is
-   of a set of records, one per line. Blank lines and lines beginning
-   with a hash character (<quote>#</quote>) are ignored. A record is
-   made up of a number of fields which are separated by spaces and/or
-   tabs.  Records cannot be continued across lines.
+   The general format of the <filename>pg_hba.conf</filename> file is of
+   a set of records, one per line. Blank lines are ignored, as is any
+   text after the <quote>#</quote> comment character. A record is made
+   up of a number of fields which are separated by spaces and/or tabs.
+   Fields can contain white space if the field value is quoted. Records
+   cannot be continued across lines.
   </para>
 
   <para>
    Each record specifies a connection type, a client IP address range
-   (if relevant for the connection type), a database name or names,
+   (if relevant for the connection type), a database name, a user name,
    and the authentication method to be used for connections matching
-   these parameters.
-   The first record that matches the type, client address, and requested
-   database name of a connection attempt is used to do the
-   authentication step.  There is no <quote>fall-through</> or
+   these parameters. The first record with a matching connection type,
+   client address, requested database, and user name is used to perform
+   authentication. There is no <quote>fall-through</> or
    <quote>backup</>: if one record is chosen and the authentication
-   fails, the following records are not considered. If no record
-   matches, the access will be denied.
+   fails, subsequent records are not considered. If no record matches,
+   access is denied.
   </para>
 
   <para>
    A record may have one of the three formats
    <synopsis>
-local   <replaceable>database</replaceable> <replaceable>authentication-method</replaceable> [ <replaceable>authentication-option</replaceable> ]
-host    <replaceable>database</replaceable> <replaceable>IP-address</replaceable> <replaceable>IP-mask</replaceable> <replaceable>authentication-method</replaceable> [ <replaceable>authentication-option</replaceable> ]
-hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable> <replaceable>IP-mask</replaceable> <replaceable>authentication-method</replaceable> [ <replaceable>authentication-option</replaceable> ]
+local   <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>authentication-method</replaceable> [ <replaceable>authentication-option</replaceable> ]
+host    <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>IP-address</replaceable> <replaceable>IP-mask</replaceable> <replaceable>authentication-method</replaceable>
+hostssl <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>IP-address</replaceable> <replaceable>IP-mask</replaceable> <replaceable>authentication-method</replaceable>
     </synopsis>
    The meaning of the fields is as follows:
 
@@ -97,7 +95,7 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
      <term><literal>local</literal></term>
      <listitem>
       <para>
-       This record pertains to connection attempts over Unix domain
+       This record applies to connection attempts using Unix domain
        sockets.
       </para>
      </listitem>
@@ -107,10 +105,11 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
      <term><literal>host</literal></term>
      <listitem>
       <para>
-       This record pertains to connection attempts over TCP/IP
-       networks. Note that TCP/IP connections are completely disabled
-       unless the server is started with the <option>-i</option> switch or
-       the equivalent configuration parameter is set.
+       This record applied to connection attempts using TCP/IP networks.
+       Note that TCP/IP connections are disabled unless the server is
+       started with the <option>-i</option> option or the
+       <literal>tcpip_socket</> <filename>postgresql.conf</>
+       configuration parameter is enabled.
       </para>
      </listitem>
     </varlistentry>
@@ -119,13 +118,13 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
      <term><literal>hostssl</literal></term>
      <listitem>
       <para>
-       This record pertains to connection attempts with SSL over
+       This record applies to connection attempts using SSL over
        TCP/IP. To make use of this option the server must be
        built with SSL support enabled. Furthermore, SSL must be
        enabled with the <option>-l</> option or equivalent configuration
        setting when the server is started.  (Note: <literal>host</literal>
        records will match either SSL or non-SSL connection attempts, but
-       <literal>hostssl</literal> records match only SSL connections.)
+       <literal>hostssl</literal> records requires SSL connections.)
       </para>
      </listitem>
     </varlistentry>
@@ -134,12 +133,35 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
      <term><replaceable>database</replaceable></term>
      <listitem>
       <para>
-       Specifies the database that this record applies to. The value
+       Specifies the database for this record. The value
        <literal>all</literal> specifies that it applies to all
        databases, while the value <literal>sameuser</> identifies the
-       database with the same name as the connecting user.  Otherwise,
-       this is the name of a specific <productname>PostgreSQL</productname>
-       database.
+       database with the same name as the connecting user. The value
+       <literal>samegroup</> identifies a group with the same name as
+       the database name. Only members of this group can connect to the
+       database. Otherwise, this is the name of a specific
+       <productname>PostgreSQL</productname> database. Multiple database
+       names can be supplied by separating them with commas. A file
+       containing database names can be specified by preceding the file
+       name with <literal>@</>. The file must be in the same directory
+       as <filename>pg_hba.conf</>.
+      </para>
+     </listitem>
+    </varlistentry>
+
+    <varlistentry>
+     <term><replaceable>user</replaceable></term>
+     <listitem>
+      <para>
+       Specifies the user for this record. The value
+       <literal>all</literal> specifies that it applies to all users.
+       Otherwise, this is the name of a specific
+       <productname>PostgreSQL</productname> user. Multiple user names
+       can be supplied by separating them with commas. Group names can
+       be specified by preceding the group name with <literal>+</>. A
+       file containing user names can be specified by preceding the file
+       name with <literal>@</>. The file must be in the same directory
+       as <filename>pg_hba.conf</>.
       </para>
      </listitem>
     </varlistentry>
@@ -149,10 +171,9 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
      <term><replaceable>IP mask</replaceable></term>
      <listitem>
       <para>
-       These two fields specify to which client machines a
-       <literal>host</literal> or <literal>hostssl</literal>
-       record applies, based on their IP
-       address. (Of course IP addresses can be spoofed but this
+       These two fields specify the client machine IP addresses
+       (<literal>host</literal> or <literal>hostssl</literal>) for this
+       record. (Of course IP addresses can be spoofed but this
        consideration is beyond the scope of
        <productname>PostgreSQL</productname>.) The precise logic is that
        <blockquote>
@@ -169,10 +190,9 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
      <term><replaceable>authentication method</replaceable></term>
      <listitem>
       <para>
-       Specifies the method that users must use to authenticate themselves
-       when connecting under the control of this authentication record.
-       The possible choices are summarized here,
-       details are in <xref linkend="auth-methods">.
+       Specifies the authentication method to use when connecting via
+       this record. The possible choices are summarized here; details
+       are in <xref linkend="auth-methods">.
 
        <variablelist>
         <varlistentry>
@@ -190,66 +210,41 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
         <term><literal>reject</></term>
         <listitem>
          <para>
-          The connection is rejected unconditionally. This is mostly
-          useful to <quote>filter out</> certain hosts from a group.
+          The connection is rejected unconditionally. This is useful for
+          <quote>filtering out</> certain hosts from a group.
          </para>
         </listitem>
        </varlistentry>
 
        <varlistentry>
-        <term><literal>password</></term>
+        <term><literal>md5</></term>
         <listitem>
          <para>
-          The client is required to supply a password which is required to
-	  match the database password that was set up for the user.
-         </para>
-
-         <para>
-          An optional file name may be specified after the
-          <literal>password</literal> keyword. This file is expected to
-          contain a list of users who may connect using this record,
-          and optionally alternative passwords for them.
-         </para>
-
-         <para>
-          The password is sent over the wire in clear text. For better
-          protection, use the <literal>md5</literal> or 
-          <literal>crypt</literal> methods.
+          Requires the client to supply an MD5 encrypted password for
+          authentication. This is the only method that allows encrypted
+          passwords to be stored in pg_shadow.
          </para>
         </listitem>
        </varlistentry>
 
        <varlistentry>
-        <term><literal>md5</></term>
+        <term><literal>crypt</></term>
         <listitem>
          <para>
-          Like the <literal>password</literal> method, but the password
-          is sent over the wire encrypted using a simple
-          challenge-response protocol. This protects against incidental
-          wire-sniffing.  This is now the recommended choice for
-	  password-based authentication.
-         </para>
-
-         <para>
-	  The name of a file may follow the
-          <literal>md5</literal> keyword.  It contains a list of users
-          who may connect using this record.
+          Like <literal>md5</literal> method but uses older crypt
+          encryption, which is needed for pre-7.2 clients.
+          <literal>md5</literal> is preferred for 7.2 and later clients.
          </para>
         </listitem>
        </varlistentry>
 
        <varlistentry>
-        <term><literal>crypt</></term>
+        <term><literal>password</></term>
         <listitem>
          <para>
-          Like the <literal>md5</literal> method but uses older crypt
-          encryption, which is needed for pre-7.2
-	  clients. <literal>md5</literal> is
-          preferred for 7.2 and later clients. The <literal>crypt</>
-          method is not compatible with encrypting passwords in
-          <filename>pg_shadow</>, and may fail if client and server
-          machines have different implementations of the crypt() library
-          routine.
+          Same as "md5", but the password is sent in cleartext over the
+          network. This should not be used on untrusted networks.
+         </para>
          </para>
         </listitem>
        </varlistentry>
@@ -278,34 +273,36 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
         <term><literal>ident</></term>
         <listitem>
 	 <para>
-	  The identity of the user as determined on login to the
-	  operating system is used by <productname>PostgreSQL</productname>
-	  to determine whether the user
-          is allowed to connect as the requested database user.
-	  For TCP/IP connections the user's identity is determined by
-	  contacting the <firstterm>ident</firstterm> server on the client
-	  host.  (Note that this is only as reliable as the remote ident
-	  server; ident authentication should never be used for remote hosts
-	  whose administrators are not trustworthy.)
-	  On operating systems
-	  supporting <symbol>SO_PEERCRED</> requests for Unix domain sockets,
-	  ident authentication is possible for local connections;
-	  the system is then asked for the connecting user's identity.
-	 </para>
+          For TCP/IP connections, authentication is done by contacting
+          the <firstterm>ident</firstterm> server on the client host.
+          This is only as secure as the client machine. You must specify
+          the map name after the 'ident' keyword. It determines how to
+          map remote user names to PostgreSQL user names. If you use
+          "sameuser", the user names are assumed to be identical. If
+          not, the map name is looked up in the $PGDATA/pg_ident.conf
+          file. The connection is accepted if that file contains an
+          entry for this map name with the ident-supplied user name and
+          the requested PostgreSQL user name.
+         </para>
+         <para>
+          On machines that support unix-domain socket credentials
+          (currently Linux, FreeBSD, NetBSD, and BSD/OS), ident allows
+          reliable authentication of 'local' connections without ident
+          running on the local machine.
+         </para>
          <para>
-	  On systems without <symbol>SO_PEERCRED</> requests, ident authentication
-	  is only available for TCP/IP connections.  As a workaround,
-	  it is possible to
-	  specify the <systemitem class="systemname">localhost</> address
-          <systemitem class="systemname">127.0.0.1</> and make connections
-	  to this address.
+	  On systems without <symbol>SO_PEERCRED</> requests, ident
+	  authentication is only available for TCP/IP connections. As a
+	  work around, it is possible to specify the <systemitem
+	  class="systemname">localhost</> address <systemitem
+	  class="systemname">127.0.0.1</> and make connections to this
+	  address.
 	 </para>
          <para>
-          The <replaceable>authentication option</replaceable> following
-          the <literal>ident</> keyword specifies the name of an
-          <firstterm>ident map</firstterm> that specifies which operating
-          system users equate with which database users. See below for
-          details.
+          Following the <literal>ident</> keyword, an <firstterm>ident
+          map</firstterm> name should be supplied which specifies which
+          operating system users equate with which database users. See
+          below for details.
          </para>
         </listitem>
        </varlistentry>
@@ -315,17 +312,16 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
         <listitem>
          <para>
           This authentication type operates similarly to
-          <firstterm>password</firstterm>, with the main difference that
-          it will use PAM (Pluggable Authentication Modules) as the
-          authentication mechanism. The <replaceable>authentication
-          option</replaceable> following the <literal>pam</> keyword
-          specifies the service name that will be passed to PAM. The
-          default service name is <literal>postgresql</literal>.
-          For more information about PAM, please read the <ulink
-          url="http://www.kernel.org/pub/linux/libs/pam/"><productname>Linux-PAM</productname>
-          Page</ulink> and/or the <ulink 
-          url="http://www.sun.com/software/solaris/pam/"><systemitem class="osname">Solaris</> PAM
-          Page</ulink>.
+          <firstterm>password</firstterm> except that it uses PAM
+          (Pluggable Authentication Modules) as the authentication
+          mechanism. The default PAM service name is
+          <literal>postgresql</literal>. You can optionally supply you
+          own service name after the <literal>pam</> keyword in the
+          file. For more information about PAM, please read the <ulink
+          url="http://www.kernel.org/pub/linux/libs/pam/"><productname>L
+          inux-PAM</productname> Page</ulink> and the <ulink
+          url="http://www.sun.com/software/solaris/pam/"><systemitem
+          class="osname">Solaris</> PAM Page</ulink>.
          </para>
         </listitem>
        </varlistentry>
@@ -336,42 +332,33 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
      </listitem>
     </varlistentry>
 
-    <varlistentry>
-     <term><replaceable>authentication option</replaceable></term>
-     <listitem>
-      <para>
-       This field is interpreted differently depending on the
-       authentication method, as described above.
-      </para>
-     </listitem>
-    </varlistentry>
    </variablelist>
   </para>
 
   <para>
    Since the <filename>pg_hba.conf</filename> records are examined
    sequentially for each connection attempt, the order of the records is
-   very significant.  Typically, earlier records will have tight
-   connection match parameters and weaker authentication methods,
-   while later records will have looser match parameters and stronger
-   authentication methods.  For example, one might wish to use
-   <literal>trust</> authentication for local TCP connections but
-   require a password for remote TCP connections.  In this case a
-   record specifying <literal>trust</> authentication for connections
-   from 127.0.0.1 would appear before a record specifying password
-   authentication for a wider range of allowed client IP addresses.
+   significant. Typically, earlier records will have tight connection
+   match parameters and weaker authentication methods, while later
+   records will have looser match parameters and stronger authentication
+   methods. For example, one might wish to use <literal>trust</>
+   authentication for local TCP connections but require a password for
+   remote TCP connections. In this case a record specifying
+   <literal>trust</> authentication for connections from 127.0.0.1 would
+   appear before a record specifying password authentication for a wider
+   range of allowed client IP addresses.
   </para>
 
   <para>
     <indexterm>
      <primary>SIGHUP</primary>
     </indexterm>
-   The <filename>pg_hba.conf</filename> file is read on start-up
-   and when the <application>postmaster</> receives a
+   The <filename>pg_hba.conf</filename> file is read on start-up and when
+   the <application>postmaster</> receives a
    <systemitem>SIGHUP</systemitem> signal. If you edit the file on an
    active system, you will need to signal the <application>postmaster</>
-   (using <literal>pg_ctl reload</> or <literal>kill -HUP</>)
-   to make it re-read the file.
+   (using <literal>pg_ctl reload</> or <literal>kill -HUP</>) to make it
+   re-read the file.
   </para>
 
   <para>
@@ -382,27 +369,27 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
    <example id="example-pg-hba.conf">
     <title>An example <filename>pg_hba.conf</filename> file</title>
 <programlisting>
-# TYPE       DATABASE    IP_ADDRESS    MASK               AUTHTYPE  MAP
+# TYPE       DATABASE    USER       IP_ADDRESS    MASK               AUTHTYPE
 
 # Allow any user on the local system to connect to any
-# database under any username, but only via an IP connection:
+# database under any user name, but only via an IP connection:
 
-host         all         127.0.0.1     255.255.255.255    trust     
+host         all         all        127.0.0.1     255.255.255.255    trust     
 
 # The same, over Unix-socket connections:
 
-local        all                                          trust
+local        all         all                                         trust
 
 # Allow any user from any host with IP address 192.168.93.x to
-# connect to database "template1" as the same username that ident on that
-# host identifies him as (typically his Unix username):
+# connect to database "template1" as the same user name that ident on that
+# host identifies him as (typically his Unix user name):
 
-host         template1   192.168.93.0  255.255.255.0      ident     sameuser
+host         template1   all        192.168.93.0  255.255.255.0      ident sameuser
 
 # Allow a user from host 192.168.12.10 to connect to database "template1"
-# if the user's password in pg_shadow is correctly supplied:
+# if the user's password is correctly supplied:
 
-host         template1   192.168.12.10 255.255.255.255    md5
+host         template1   all        192.168.12.10 255.255.255.255    md5
 
 # In the absence of preceding "host" lines, these two lines will reject
 # all connection attempts from 192.168.54.1 (since that entry will be
@@ -410,8 +397,8 @@ host         template1   192.168.12.10 255.255.255.255    md5
 # else on the Internet. The zero mask means that no bits of the host IP
 # address are considered, so it matches any host:
 
-host         all        192.168.54.1   255.255.255.255    reject
-host         all        0.0.0.0        0.0.0.0            krb5
+host         all        all         192.168.54.1   255.255.255.255    reject
+host         all        all         0.0.0.0        0.0.0.0            krb5
 
 # Allow users from 192.168.x.x hosts to connect to any database, if they
 # pass the ident check.  If, for example, ident says the user is "bryanh"
@@ -419,7 +406,7 @@ host         all        0.0.0.0        0.0.0.0            krb5
 # is allowed if there is an entry in pg_ident.conf for map "omicron" that
 # says "bryanh" is allowed to connect as "guest1":
 
-host         all        192.168.0.0    255.255.0.0        ident     omicron
+host         all        all         192.168.0.0    255.255.0.0        ident omicron
 
 # If these are the only two lines for local connections, they will allow
 # local users to connect only to their own databases (database named the
@@ -429,8 +416,8 @@ host         all        192.168.0.0    255.255.0.0        ident     omicron
 # cases.  (If you prefer to use ident authorization, an ident map can
 # serve a parallel purpose to the password list file used here.)
 
-local        sameuser                                     md5
-local        all                                          md5  admins
+local        sameuser   all                                            md5
+local        all        @admins                                        md5
 </programlisting>
    </example>
   </para>
@@ -490,86 +477,49 @@ local        all                                          md5  admins
    <title>Password authentication</title>
 
    <indexterm>
-    <primary>password</primary>
+    <primary>MD5</>
    </indexterm>
    <indexterm>
-    <primary>MD5</>
+    <primary>crypt</>
+   </indexterm>
+   <indexterm>
+    <primary>password</primary>
    </indexterm>
 
    <para>
     Password-based authentication methods include <literal>md5</>,
-    <literal>crypt</>, and <literal>password</>.  These methods operate
+    <literal>crypt</>, and <literal>password</>. These methods operate
     similarly except for the way that the password is sent across the
-    connection.  If you are at all concerned about password <quote>sniffing</>
-    attacks then <literal>md5</> is preferred, with <literal>crypt</> a
-    second choice if you must support obsolete clients.  Plain
-    <literal>password</> should especially be avoided for connections over
-    the open Internet (unless you use SSL, SSH, or other communications
-    security wrappers around the connection).
+    connection. If you are at all concerned about password
+    <quote>sniffing</> attacks then <literal>md5</> is preferred, with
+    <literal>crypt</> a second choice if you must support pre-7.2
+    clients. Plain <literal>password</> should especially be avoided for
+    connections over the open Internet (unless you use SSL, SSH, or
+    other communications security wrappers around the connection).
    </para>
 
    <para>
-    <productname>PostgreSQL</productname> database passwords are separate from
-    operating system user passwords. Ordinarily, the password for each
-    database user is stored in the pg_shadow system catalog table.
-    Passwords can be managed with the query language commands
-    <command>CREATE USER</command> and <command>ALTER USER</command>,
-    e.g., <userinput>CREATE USER foo WITH PASSWORD
-    'secret';</userinput>. By default, that is, if no password has
-    been set up, the stored password is <literal>NULL</literal>
-    and password authentication will always fail for that user.
+    <productname>PostgreSQL</productname> database passwords are
+    separate from operating system user passwords. Ordinarily, the
+    password for each database user is stored in the pg_shadow system
+    catalog table. Passwords can be managed with the query language
+    commands <command>CREATE USER</command> and <command>ALTER
+    USER</command>, e.g., <userinput>CREATE USER foo WITH PASSWORD
+    'secret';</userinput>. By default, that is, if no password has been
+    set up, the stored password is <literal>NULL</literal> and password
+    authentication will always fail for that user.
    </para>
 
    <para>
     To restrict the set of users that are allowed to connect to certain
-    databases, list the set of users in a separate file (one user name
-    per line) in the same directory that <filename>pg_hba.conf</> is in,
-    and mention the (base) name of the file after the
-    <literal>password</>, <literal>md5</>, or <literal>crypt</> keyword,
-    respectively, in <filename>pg_hba.conf</>. If you do not use this
-    feature, then any user that is known to the database system can
-    connect to any database (so long as he supplies the correct password,
-    of course).
-   </para>
-
-   <para>
-    These files can also be used to apply a different set of passwords
-    to a particular database or set thereof. In that case, the files
-    have a format similar to the standard Unix password file
-    <filename>/etc/passwd</filename>, that is,
-<synopsis>
-<replaceable>username</replaceable>:<replaceable>password</replaceable>
-</synopsis>
-    Any extra colon-separated fields following the password are
-    ignored. The password is expected to be encrypted using the
-    system's <function>crypt()</function> function. The utility
-    program <application>pg_passwd</application> that is installed
-    with <productname>PostgreSQL</productname> can be used to manage
-    these password files.
-   </para>
-
-   <para>
-    Lines with and without passwords can be mixed in secondary
-    password files. Lines without password indicate use of the main
-    password in <literal>pg_shadow</> that is managed by
-    <command>CREATE USER</> and <command>ALTER USER</>. Lines with
-    passwords will cause that password to be used. A password entry of
-    <quote>+</quote> also means using the pg_shadow password.
-   </para>
-
-   <para>
-    Alternative passwords cannot be used when using the <literal>md5</>
-    or <literal>crypt</> methods. The file will be read as
-    usual, but the password field will simply be ignored and the
-    <literal>pg_shadow</> password will always be used.
-   </para>
-
-   <para>
-    Note that using alternative passwords like this means that one can
-    no longer use <command>ALTER USER</command> to change one's
-    password. It will appear to work but the password one is
-    changing is not the password that the system will end up
-    using.
+    databases, list the users separated by commas, or in a separate
+    file. The file should contain user names separated by commas or one
+    user name per line, and be in the same directory as
+    <filename>pg_hba.conf</>. Mention the (base) name of the file
+    preceded with <literal>@</>in the <literal>USER</> column. The
+    <literal>DATABASE</> column can similarly accept a list of values or
+    a file name. You can also specify group names by preceding the group
+    name with <literal>+</>.
    </para>
 
   </sect2>
@@ -588,10 +538,10 @@ local        all                                          md5  admins
     <productname>Kerberos</productname> system is far beyond the scope
     of this document; in all generality it can be quite complex (yet
     powerful). The <ulink
-    url="http://www.nrl.navy.mil/CCS/people/kenh/kerberos-faq.html">Kerberos
-    <acronym>FAQ</></ulink> or <ulink
-    url="ftp://athena-dist.mit.edu">MIT Project Athena</ulink> can be
-    a good starting point for exploration. Several sources for
+    url="http://www.nrl.navy.mil/CCS/people/kenh/kerberos-faq.html">Kerb
+    eros <acronym>FAQ</></ulink> or <ulink
+    url="ftp://athena-dist.mit.edu">MIT Project Athena</ulink> can be a
+    good starting point for exploration. Several sources for
     <productname>Kerberos</> distributions exist.
    </para>
 
@@ -606,34 +556,33 @@ local        all                                          md5  admins
    <para>
     <productname>PostgreSQL</> operates like a normal Kerberos service.
     The name of the service principal is
-    <replaceable>servicename/hostname@realm</>, where 
-    <replaceable>servicename</> is <literal>postgres</literal>
-    (unless a different service name was selected at configure time
-    with <literal>./configure --with-krb-srvnam=whatever</>).
-    <replaceable>hostname</> is the fully qualified domain name of the server
-    machine.  The service principal's realm is the preferred realm of the
-    server machine.
+    <replaceable>servicename/hostname@realm</>, where
+    <replaceable>servicename</> is <literal>postgres</literal> (unless a
+    different service name was selected at configure time with
+    <literal>./configure --with-krb-srvnam=whatever</>).
+    <replaceable>hostname</> is the fully qualified domain name of the
+    server machine. The service principal's realm is the preferred realm
+    of the server machine.
    </para>
 
    <para>
-    Client principals must have their <productname>PostgreSQL</> user name as
-    their first component, for example
-    <replaceable>pgusername/otherstuff@realm</>.
-    At present the realm of the client is not checked by
-    <productname>PostgreSQL</>; so
-    if you have cross-realm authentication enabled, then any principal
-    in any realm that can communicate with yours will be accepted.
+    Client principals must have their <productname>PostgreSQL</> user
+    name as their first component, for example
+    <replaceable>pgusername/otherstuff@realm</>. At present the realm of
+    the client is not checked by <productname>PostgreSQL</>; so if you
+    have cross-realm authentication enabled, then any principal in any
+    realm that can communicate with yours will be accepted.
    </para>
 
    <para>
-    Make sure that your server key file is readable (and
-    preferably only readable) by the
-    <productname>PostgreSQL</productname> server account (see 
-    <xref linkend="postgres-user">). The location of the key file
-    is specified with the <varname>krb_server_keyfile</> run time
-    configuration parameter. (See also <xref linkend="runtime-config">.)
-    The default is <filename>/etc/srvtab</> if you are using Kerberos 4
-    and <filename>FILE:/usr/local/pgsql/etc/krb5.keytab</> (or whichever
+    Make sure that your server key file is readable (and preferably only
+    readable) by the <productname>PostgreSQL</productname> server
+    account (see <xref linkend="postgres-user">). The location of the
+    key file is specified with the <varname>krb_server_keyfile</> run
+    time configuration parameter. (See also <xref
+    linkend="runtime-config">.) The default is <filename>/etc/srvtab</>
+    if you are using Kerberos 4 and
+    <filename>FILE:/usr/local/pgsql/etc/krb5.keytab</> (or whichever
     directory was specified as <varname>sysconfdir</> at build time)
     with Kerberos 5.
    </para>
@@ -649,18 +598,20 @@ local        all                                          md5  admins
 
    <para>
     When connecting to the database make sure you have a ticket for a
-    principal matching the requested database user name. 
-    An example: For database user name <literal>fred</>, both principal
+    principal matching the requested database user name. An example: For
+    database user name <literal>fred</>, both principal
     <literal>fred@EXAMPLE.COM</> and
-    <literal>fred/users.example.com@EXAMPLE.COM</> can be
-    used to authenticate to the database server. 
+    <literal>fred/users.example.com@EXAMPLE.COM</> can be used to
+    authenticate to the database server.
    </para>
 
    <para>
-    If you use <application>mod_auth_krb</application> and <application>mod_perl</application> on your <productname>Apache</productname> web server,
-    you can use <literal>AuthType KerberosV5SaveCredentials</literal> with a <application>mod_perl</application>
-    script. This gives secure database access over the web, no extra
-    passwords required.
+    If you use <application>mod_auth_krb</application> and
+    <application>mod_perl</application> on your
+    <productname>Apache</productname> web server, you can use
+    <literal>AuthType KerberosV5SaveCredentials</literal> with a
+    <application>mod_perl</application> script. This gives secure
+    database access over the web, no extra passwords required.
    </para>
 
   </sect2>
@@ -707,55 +658,54 @@ local        all                                          md5  admins
    </para>
 
    <para>
-    On systems supporting <symbol>SO_PEERCRED</symbol> requests for Unix-domain sockets,
-    ident authentication can also be applied to local connections.  In this
-    case, no security risk is added by using ident authentication; indeed
-    it is a preferable choice for local connections on such a system.
+    On systems supporting <symbol>SO_PEERCRED</symbol> requests for
+    Unix-domain sockets, ident authentication can also be applied to
+    local connections. In this case, no security risk is added by using
+    ident authentication; indeed it is a preferable choice for local
+    connections on such systems.
    </para>
 
    <para>
     When using ident-based authentication, after having determined the
     name of the operating system user that initiated the connection,
-    <productname>PostgreSQL</productname> checks whether that user is allowed
-    to connect as the database user he is requesting to connect as.
-    This is controlled by the ident map
-    argument that follows the <literal>ident</> keyword in the
-    <filename>pg_hba.conf</filename> file. There is a predefined ident map
-    <literal>sameuser</literal>, which allows any operating system
-    user to connect as the database user of the same name (if the
-    latter exists). Other maps must be created manually.
+    <productname>PostgreSQL</productname> checks whether that user is
+    allowed to connect as the database user he is requesting to connect
+    as. This is controlled by the ident map argument that follows the
+    <literal>ident</> keyword in the <filename>pg_hba.conf</filename>
+    file. There is a predefined ident map <literal>sameuser</literal>,
+    which allows any operating system user to connect as the database
+    user of the same name (if the latter exists). Other maps must be
+    created manually.
    </para>
 
    <para>
-    <indexterm><primary>pg_ident.conf</primary></indexterm>
-    Ident maps other than <literal>sameuser</literal> are defined
-    in the file <filename>pg_ident.conf</filename>
-    in the data directory, which contains lines of the general form:
+    <indexterm><primary>pg_ident.conf</primary></indexterm> Ident maps
+    other than <literal>sameuser</literal> are defined in the file
+    <filename>pg_ident.conf</filename> in the data directory, which
+    contains lines of the general form:
 <synopsis>
 <replaceable>map-name</> <replaceable>ident-username</> <replaceable>database-username</>
 </synopsis>
-    Comments and whitespace are handled in the usual way.
-    The <replaceable>map-name</> is an arbitrary name that will be
-    used to refer to this mapping in <filename>pg_hba.conf</filename>.
-    The other two fields specify which operating system user is
-    allowed to connect as which database user. The same
-    <replaceable>map-name</> can be used repeatedly to specify more
-    user-mappings within a single map. There is no restriction regarding
-    how many 
-    database users a given operating system user may correspond to and vice
-    versa.
+    Comments and whitespace are handled in the usual way. The
+    <replaceable>map-name</> is an arbitrary name that will be used to
+    refer to this mapping in <filename>pg_hba.conf</filename>. The other
+    two fields specify which operating system user is allowed to connect
+    as which database user. The same <replaceable>map-name</> can be
+    used repeatedly to specify more user-mappings within a single map.
+    There is no restriction regarding how many database users a given
+    operating system user may correspond to and vice versa.
    </para>
 
   <para>
     <indexterm>
      <primary>SIGHUP</primary>
     </indexterm>
-   The <filename>pg_ident.conf</filename> file is read on start-up
-   and when the <application>postmaster</> receives a
+   The <filename>pg_ident.conf</filename> file is read on start-up and
+   when the <application>postmaster</> receives a
    <systemitem>SIGHUP</systemitem> signal. If you edit the file on an
    active system, you will need to signal the <application>postmaster</>
-   (using <literal>pg_ctl reload</> or <literal>kill -HUP</>)
-   to make it re-read the file.
+   (using <literal>pg_ctl reload</> or <literal>kill -HUP</>) to make it
+   re-read the file.
   </para>
 
    <para>
@@ -763,13 +713,14 @@ local        all                                          md5  admins
     conjunction with the <filename>pg_hba.conf</> file in <xref
     linkend="example-pg-hba.conf"> is shown in <xref
     linkend="example-pg-ident.conf">. In this example setup, anyone
-    logged in to a machine on the 192.168 network that does not have
-    the Unix user name <systemitem>bryanh</>, <systemitem>ann</>, or <systemitem>robert</> would not be granted access.
-    Unix user <systemitem>robert</> would only be allowed access when he tries to
-    connect as <productname>PostgreSQL</> user <systemitem>bob</>,
-      not as <systemitem>robert</>
-    or anyone else. <systemitem>ann</> would only be allowed to connect as
-    <systemitem>ann</>. User <systemitem>bryanh</> would be allowed to connect as either
+    logged in to a machine on the 192.168 network that does not have the
+    Unix user name <systemitem>bryanh</>, <systemitem>ann</>, or
+    <systemitem>robert</> would not be granted access. Unix user
+    <systemitem>robert</> would only be allowed access when he tries to
+    connect as <productname>PostgreSQL</> user <systemitem>bob</>, not
+    as <systemitem>robert</> or anyone else. <systemitem>ann</> would
+    only be allowed to connect as <systemitem>ann</>. User
+    <systemitem>bryanh</> would be allowed to connect as either
     <systemitem>bryanh</> himself or as <systemitem>guest1</>.
    </para>
 
@@ -780,7 +731,7 @@ local        all                                          md5  admins
 
 omicron        bryanh       bryanh
 omicron        ann          ann
-# bob has username robert on these machines
+# bob has user name robert on these machines
 omicron        robert       bob
 # bryanh can also connect as guest1
 omicron        bryanh       guest1
@@ -799,30 +750,30 @@ omicron        bryanh       guest1
 
    <para>
 <ProgramListing>
-No pg_hba.conf entry for host 123.123.123.123, user joeblow, database testdb
+No pg_hba.conf entry for host 123.123.123.123, user andym, database testdb
 </ProgramListing>
-    This is what you are most likely to get if you succeed in
-    contacting the server, but it does not want to talk to you. As the
-    message suggests, the server refused the connection request
-    because it found no authorizing entry in its <filename>pg_hba.conf</filename>
+    This is what you are most likely to get if you succeed in contacting
+    the server, but it does not want to talk to you. As the message
+    suggests, the server refused the connection request because it found
+    no authorizing entry in its <filename>pg_hba.conf</filename>
     configuration file.
    </para>
 
    <para>
 <ProgramListing>
-Password authentication failed for user 'joeblow'
+Password authentication failed for user 'andym'
 </ProgramListing>
-    Messages like this indicate that you contacted the server, and
-    it is willing to talk to you, but not until you pass the
-    authorization method specified in the
-    <filename>pg_hba.conf</filename> file. Check the password you are
-    providing, or check your Kerberos or ident software if the
-    complaint mentions one of those authentication types.
+    Messages like this indicate that you contacted the server, and it is
+    willing to talk to you, but not until you pass the authorization
+    method specified in the <filename>pg_hba.conf</filename> file. Check
+    the password you are providing, or check your Kerberos or ident
+    software if the complaint mentions one of those authentication
+    types.
    </para>
 
    <para>
 <ProgramListing>
-FATAL 1:  user "joeblow" does not exist
+FATAL 1:  user "andym" does not exist
 </ProgramListing>
     The indicated user name was not found.
    </para>
@@ -837,9 +788,9 @@ FATAL 1:  Database "testdb" does not exist in the system catalog.
    </para>
 
    <para>
-    Note that the server log may contain more information
-    about an authentication failure than is reported to the client.
-    If you are confused about the reason for a failure, check the log.
+    Note that the server log may contain more information about an
+    authentication failure than is reported to the client. If you are
+    confused about the reason for a failure, check the log.
    </para>
   </sect1>
 
diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml
index 460f150bc89..61d979a5643 100644
--- a/doc/src/sgml/ref/allfiles.sgml
+++ b/doc/src/sgml/ref/allfiles.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/allfiles.sgml,v 1.36 2002/03/19 02:18:12 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/allfiles.sgml,v 1.37 2002/04/04 04:25:45 momjian Exp $
 PostgreSQL documentation
 Complete list of usable sgml source files in this directory.
 -->
@@ -125,7 +125,6 @@ Complete list of usable sgml source files in this directory.
 <!entity pgCtl              system "pg_ctl-ref.sgml">
 <!entity pgDump             system "pg_dump.sgml">
 <!entity pgDumpall          system "pg_dumpall.sgml">
-<!entity pgPasswd           system "pg_passwd.sgml">
 <!entity pgRestore          system "pg_restore.sgml">
 <!entity pgTclSh            system "pgtclsh.sgml">
 <!entity pgTkSh             system "pgtksh.sgml">
diff --git a/doc/src/sgml/ref/pg_passwd.sgml b/doc/src/sgml/ref/pg_passwd.sgml
deleted file mode 100644
index 13125b08e27..00000000000
--- a/doc/src/sgml/ref/pg_passwd.sgml
+++ /dev/null
@@ -1,123 +0,0 @@
-<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/pg_passwd.sgml,v 1.10 2001/12/08 03:24:38 thomas Exp $
-PostgreSQL documentation
--->
-
-<refentry id="APP-PG-PASSWD">
- <docinfo>
-  <date>2000-11-18</date>
- </docinfo>
-
- <refmeta>
-  <refentrytitle id="APP-PG-PASSWD-TITLE"><application>pg_passwd</application></refentrytitle>
-  <manvolnum>1</manvolnum>
-  <refmiscinfo>Application</refmiscinfo>
- </refmeta>
-
- <refnamediv>
-  <refname>pg_passwd</refname>
-  <refpurpose>change a secondary <productname>PostgreSQL</> password file</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
-  <cmdsynopsis>
-   <command>pg_passwd</command>
-   <arg choice="plain"><replaceable>filename</replaceable></arg>
-  </cmdsynopsis>
- </refsynopsisdiv>
-
- <refsect1 id="app-pg-passwd-description">
-  <title>Description</title>
-  <para>
-   <application>pg_passwd</application> is a tool for manipulating flat
-   text password files. These files can control client authentication of
-   the <productname>PostgreSQL</productname> server. More information
-   about setting up this authentication mechanism can be found in the
-   <citetitle>Administrator's Guide</citetitle>.
-  </para>
-
-  <para>
-   The format of a text password file is one entry per line; the fields
-   of each entry are separated by colons. The first field is the user
-   name, the second field is the encrypted password. Other fields are
-   ignored (to allow password files to be shared between applications
-   that use similar formats). <application>pg_passwd</application>
-   enables users to interactively add entries to such a file, to alter
-   passwords of existing entries, and to encrypt such passwords.
-  </para>
-
-  <para>
-   Supply the name of the password file as argument to the
-   <application>pg_passwd</application> command. To be used by
-   PostgreSQL, the file needs to be located in the server's data
-   directory, and the base name of the file needs to be specified in the
-   <filename>pg_hba.conf</filename> access control file.
-
-<screen>
-<prompt>$</prompt> <userinput>pg_passwd /usr/local/pgsql/data/passwords</userinput>
-<computeroutput>File "/usr/local/pgsql/data/passwords" does not exist.  Create? (y/n):</computeroutput> <userinput>y</userinput>
-<prompt>Username:</prompt> <userinput>guest</userinput>
-<prompt>Password:</prompt>
-<prompt>Re-enter password:</prompt>
-</screen>
-
-   where the <literal>Password:</literal> and <literal>Re-enter
-   password:</literal> prompts require the same password input which
-   is not displayed on the terminal.  Note that the password is limited
-   to eight useful characters by restrictions of the standard crypt(3)
-   library routine.
-  </para>
-
-  <para>
-   The original password file is renamed to
-   <filename>passwords.bk</filename>.
-  </para>
-
-  <para>
-   To make use of this password file, put a line like the following in
-   <filename>pg_hba.conf</filename>:
-
-<programlisting>
-host  mydb     133.65.96.250   255.255.255.255 password passwords
-</programlisting>
-
-   which would allow access to database mydb from host 133.65.96.250 using
-   the passwords listed in the <filename>passwords</filename> file (and
-   only to the users listed in that file).
-  </para>
-
-  <note>
-   <para>
-    It is also useful to have entries in a password file with empty
-    password fields. (This is different from an empty password.) Such
-    entries allow you to restrict users who can access the system. These
-    entries cannot be managed by <application>pg_passwd</application>,
-    but you can edit password files manually.
-   </para>
-  </note>
- </refsect1>
-
- <refsect1 id="app-pg-passwd-seealso">
-  <title>See also</title>
-  <para>
-   <citetitle>PostgreSQL Administrator's Guide</citetitle>
-  </para>
- </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:
--->
diff --git a/doc/src/sgml/reference.sgml b/doc/src/sgml/reference.sgml
index b6b63254462..41d419dd2ea 100644
--- a/doc/src/sgml/reference.sgml
+++ b/doc/src/sgml/reference.sgml
@@ -1,5 +1,5 @@
 <!-- reference.sgml
-$Header: /cvsroot/pgsql/doc/src/sgml/reference.sgml,v 1.24 2002/03/19 02:18:11 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/reference.sgml,v 1.25 2002/04/04 04:25:44 momjian Exp $
 
 PostgreSQL Reference Manual
 -->
@@ -191,7 +191,6 @@ Disable this chapter until we have more functions documented.
    &initlocation;
    &ipcclean;
    &pgCtl;
-   &pgPasswd;
    &postgres;
    &postmaster;