Improve wording of authentication files.

doc/src/sgml/ref/pg_passwd.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/pg_passwd.sgml,v 1.6 2001/02/20 01:16:49 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/pg_passwd.sgml,v 1.7 2001/06/18 16:11:30 momjian Exp $
 Postgres documentation
 -->
 
@@ -16,7 +16,7 @@ Postgres documentation
 
  <refnamediv>
   <refname>pg_passwd</refname>
-  <refpurpose>Manipulate a text password file</refpurpose>
+  <refpurpose>Manipulate a secondary password file</refpurpose>
  </refnamediv>
 
  <refsynopsisdiv>
@@ -29,30 +29,28 @@ Postgres documentation
  <refsect1 id="app-pg-passwd-description">
   <title>Description</title>
   <para>
-   <application>pg_passwd</application> is a tool to manipulate a flat
-   text password file for the purpose of using that file to control
-   client authentication of the
-   <productname>PostgreSQL</productname> server.  More information
+   <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 form of a text password file is one entry per line; the fields
+   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).  The functionality of the
-   <application>pg_passwd</application> utility is to enable a user to
-   interactively add entries to such a file, to alter passwords of
-   existing entries, and to take care of encrypting the passwords.
+   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 of use for client authentication 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
+   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>
@@ -90,11 +88,11 @@ host  mydb     133.65.96.250   255.255.255.255 password passwords
 
   <note>
    <para>
-    It is also useful to have entries in a password file with an empty
-    password field.  (This is different from an empty password.)
-    These entries cannot be managed by
-    <application>pg_passwd</application>, but it is always possible to
-    edit password files manually.
+    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>

src/backend/libpq/password.c

@@ -2,7 +2,7 @@
  * Portions Copyright (c) 1996-2001, PostgreSQL Global Development Group
  * Portions Copyright (c) 1994, Regents of the University of California
  *
- * $Id: password.c,v 1.36 2001/03/22 03:59:30 momjian Exp $
+ * $Id: password.c,v 1.37 2001/06/18 16:11:30 momjian Exp $
  *
  */
 
@@ -76,9 +76,11 @@ verify_password(const Port *port, const char *user, const char *password)
 			FreeFile(pw_file);
 
 			/*
-			 * If the password is empty of "+" then we use the regular
+			 * If the password is empty or "+" then we use the regular
 			 * pg_shadow passwords. If we use crypt then we have to use
-			 * pg_shadow passwords no matter what.
+			 * pg_shadow passwords no matter what.  This is because
+			 * the current code needs non-encrypted passwords to
+			 * encrypt with a random salt.
 			 */
 			if (port->auth_method == uaCrypt
 				|| test_pw == NULL || test_pw[0] == '\0'

src/backend/libpq/pg_ident.conf.sample

-# This is the pg_ident.conf file, which is used with Postgres ident-based
-# authentication (a subtype of host-based authentication).
-
-# This is a table of ident usernames (typically Unix usernames) and 
-# their corresponding Postgres usernames.  For example, user "bryanh" on
-# some particular remote system may equate to Postgres user "guest1".
-
-# This file contains multiple maps.  Each has a name.  The pg_hba.conf
-# file determines what connections relate to this file and for those that
-# do, which map to use.
-
-# Each record consists of 3 tokens:
-#
-# 1) map name
-# 2) ident username
-# 3) Postgres username
-
-# Note that it is possible for one user to map to multiple Postgres usernames.
-# A user always has to specify when he connects what Postgres username he is
-# using.  This file is only used to validate that selection.
-
-# If you just need a one-to-one correspondence between usernames reported
-# by ident and Postgres usernames, you don't need this file.  Instead use
-# the special map name "sameuser" in pg_hba.conf.
-
-#MAP       IDENT    POSTGRES USERNAME
-
-#testmap   robert   bob
-#testmap   lucy     lucy
+# 
+# 		PostgreSQL IDENT-BASED AUTHENTICATION MAPS
+# 
+# This file controls PostgreSQL ident-based authentication. It maps ident
+# usernames (typically Unix usernames) to their corresponding PostgreSQL
+# usernames. Entries are grouped by map name. Each record consists of
+# three fields:
+# 
+# 	o map name
+# 	o ident username
+# 	o PostgreSQL username
+# 
+# For example, the following entry equates user "james" on a remote system
+# to PostgreSQL user "guest" in the map named "phoenix":
+# 
+# MAP       IDENT    PGUSERNAME
+# phoenix   james    guest
+# 
+# "phoenix" can now be used by an "ident" record in $DATA/pg_hba.conf.
+# 
+# Multiple maps may be specified in this file and used by pg_hba.conf.
+# 
+# Note that it is possible for a remote user to map to multiple PostgreSQL
+# usernames. The PostgreSQL username specified at connection time controls
+# which one is used.
+# 
+# If all ident usernames and PostgreSQL usernames are the same, you don't
+# need this file. Instead, use the special map name "sameuser" in
+# pg_hba.conf.
+# 
+# MAP     IDENT    PGUSERNAME