Add example of using 'sameuser' followed by 'all' pg_hba records to

enforce a limit on who can connect to databases other than their own.
From a recent discussion in pg-admin.

doc/src/sgml/client-auth.sgml

-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.26 2001/11/12 19:19:39 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.27 2001/11/18 23:24:16 tgl Exp $ -->
 
 <chapter id="client-authentication">
  <title>Client Authentication</title>
@@ -27,9 +27,10 @@
  </para>
 
  <para>
-  <productname>Postgres</productname> offers client authentication by
-  (client) host and by database, with a number of different
-  authentication methods available.
+  <productname>Postgres</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.
  </para>
 
  <para>
@@ -197,16 +198,15 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
         <term><literal>password</></term>
         <listitem>
          <para>
-          The client is required to supply a password with the connection
-          attempt which is required to match the password that was set up
-          for the user.
+          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 that this record pertains to, and
-          optionally alternative passwords.
+          contain a list of users who may connect using this record,
+          and optionally alternative passwords for them.
          </para>
 
          <para>
@@ -224,9 +224,14 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
           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. The name of a file may follow the
+          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
-          for this record.
+          who may connect using this record.
          </para>
         </listitem>
        </varlistentry>
@@ -236,9 +241,10 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
         <listitem>
          <para>
           Like the <literal>md5</literal> method but uses older crypt
-          authentication for pre-7.2 clients. <literal>md5</literal> is
+          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 also not compatible with encrypting passwords in
+          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.
@@ -333,7 +339,7 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
      <listitem>
       <para>
        This field is interpreted differently depending on the
-       authentication method, as described there.
+       authentication method, as described above.
       </para>
      </listitem>
     </varlistentry>
@@ -412,6 +418,17 @@ host         all        0.0.0.0        0.0.0.0            krb5
 # says "bryanh" is allowed to connect as "guest1":
 
 host         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
+# same as the user name), except for administrators who may connect to
+# all databases.  The file $PGDATA/admins lists the user names who are
+# permitted to connect to all databases.  Passwords are required in all
+# 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
 </programlisting>
    </example>
   </para>
@@ -434,7 +451,7 @@ host         all        192.168.0.0    255.255.0.0        ident     omicron
    </indexterm>
 
    <para>
-    <productname>Postgres</> database passwords are separate from any
+    <productname>Postgres</> 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
@@ -453,8 +470,8 @@ host         all        192.168.0.0    255.255.0.0        ident     omicron
     <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 passes password
-    authentication, of course).
+    connect to any database (so long as he supplies the correct password,
+    of course).
    </para>
 
    <para>
@@ -492,8 +509,8 @@ host         all        192.168.0.0    255.255.0.0        ident     omicron
    <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 still appear to work but the password one is
-    actually changing is not the password that the system will end up
+    password. It will appear to work but the password one is
+    changing is not the password that the system will end up
     using.
    </para>
 

src/backend/libpq/pg_hba.conf.sample

@@ -16,6 +16,13 @@
 # Blank lines are ignored. A record consists of tokens separated by 
 # multiple spaces or tabs.
 # 
+# Each record specifies the authentication method to be used for connections
+# of a certain type that match a certain set of IP addresses (if relevant
+# for the connection type) and a certain database or databases.  The
+# postmaster finds the first record that matches the connection type,
+# client address, and database name, and uses that record to perform client
+# authentication.  If no record matches, the connection is rejected.
+#
 # The first token of a record indicates its type. The remainder of the
 # record is interpreted based on its type.
 # 
@@ -30,7 +37,7 @@
 # host
 # ----
 # 
-# This record identifies the networked hosts that are permitted to connect
+# This record identifies networked hosts that are permitted to connect
 # via IP connections.
 # 
 # Format:
@@ -48,12 +55,7 @@
 # domain or host names.
 # 
 # AUTH_TYPE and AUTH_ARGUMENT are described below.
-# 
-# There can be multiple "host" records, possibly with overlapping sets of
-# host addresses. The postmaster finds the first entry that matches the
-# connecting host IP address and the requested database name. If no entry
-# matches the database/hostname combination, the connection is rejected.
-# 
+#
 # 
 # hostssl
 # -------
@@ -62,8 +64,8 @@
 # 
 # This record identifies a set of network hosts that are permitted to
 # connect to databases over secure SSL IP connections. Note that a "host"
-# record will also allow SSL connections.  "hostssl" forces these
-# hosts to use *only* SSL-secured connections.
+# record will also allow SSL connections.  "hostssl" matches *only*
+# SSL-secured connections.
 # 
 # This keyword is only available if the server was compiled with SSL
 # support enabled.
@@ -81,10 +83,7 @@
 # 
 # This format is identical to the "host" record type except the IP_ADDRESS
 # and ADDRESS_MASK fields are omitted.
-# 
-# As with "host" records, the first "local" record matching the requested
-# database name is used.
-# 
+#
 # 
 # 
 # Authentication Types (AUTH_TYPE)
@@ -105,24 +104,26 @@
 # 
 # 		If AUTH_ARGUMENT is specified, the username is looked up
 # 		in that file in the $PGDATA directory. If the username
-# 		exists but there is no password, the password is looked
+# 		is found but there is no password, the password is looked
 # 		up in pg_shadow. If a password exists in the file, it is
-# 		it used instead. These secondary files allow fine-grained
+# 		used instead. These secondary files allow fine-grained
 # 		control over who can access which databases and whether
-# 		a non-default passwords are required. The same file can be
+# 		a non-default password is required. The same file can be
 # 		used in multiple records for easier administration.
 # 		Password files can be maintained with the pg_passwd(1)
 # 		utility. Remember, these passwords override pg_shadow
 # 		passwords.
 # 
-#   md5:  	Same as "password", but authentication is done by
-#		encrypting the password sent over the network. This is
-#		always preferable to "password" except for pre-7.2 clients
-#		that don't support it. Also, md5 can use usernames stored
-#		in secondary password files but not passwords stored there.
+#   md5:  	Same as "password", but the password is encrypted while
+#		being sent over the network. This method is preferable to
+#		"password" except for pre-7.2 clients that don't support it.
+#		NOTE: md5 can use usernames stored in secondary password
+#		files but ignores passwords stored there.  The pg_shadow
+#		password will always be used.
 # 
 #   crypt:  	Same as "md5", but uses crypt for pre-7.2 clients.  You can
-#		not store encrypted passwords if you use this option.
+#		not store encrypted passwords in pg_shadow if you use this
+#		method.
 #
 #   ident:	For TCP/IP connections, authentication is done by contacting
 #		the ident server on the client host.  Remember, this is
@@ -168,7 +169,7 @@
 # TYPE       DATABASE    IP_ADDRESS    MASK               AUTH_TYPE  AUTH_ARGUMENT
 # local      all                                          trust
 # 
-# The same using IP connections on the same machine:
+# The same using local loopback IP connections:
 # TYPE       DATABASE    IP_ADDRESS    MASK               AUTH_TYPE  AUTH_ARGUMENT
 # host       all         127.0.0.1     255.255.255.255    trust     
 # 
@@ -204,14 +205,28 @@
 # 
 # TYPE       DATABASE    IP_ADDRESS    MASK               AUTH_TYPE  AUTH_ARGUMENT
 # host       all        192.168.0.0    255.255.0.0        ident      phoenix
+#
+# 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
+# same as the user name), except for administrators who may connect to
+# all databases.  The file $PGDATA/admins lists the user names who are
+# permitted to connect to all databases.  Passwords are required in all
+# cases.  (If you prefer to use ident authorization, an ident map can
+# serve a parallel purpose to the password list file used here.)
+#
+# TYPE       DATABASE    IP_ADDRESS    MASK               AUTH_TYPE  AUTH_ARGUMENT
+# local      sameuser                                     md5
+# local      all                                          md5  admins
 # 
 # See $PGDATA/pg_ident.conf for more information on Ident maps.
+#
+#
 # 
 # Put your actual configuration here
 # ==================================
 # 
 # This default configuration allows any local user to connect with any
-# PostgreSQL username, over either UNIX domain sockets or IP:
+# PostgreSQL username, over either UNIX domain sockets or IP.
 # 
 # If you want to allow non-local connections, you will need to add more
 # "host" records. Also, remember IP connections are only enabled if you