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
-   of each entry are separated by colons.  The first field is the user
-   name, the second field is the encrypted password.  Other fields are
+   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