diff --git a/doc/src/sgml/ref/pg_passwd.sgml b/doc/src/sgml/ref/pg_passwd.sgml
index 589ba1864126fe1b65d02edcc725add66589619e..8e244c237fd609e7649fdbfdd283d44a4179bf93 100644
--- a/doc/src/sgml/ref/pg_passwd.sgml
+++ b/doc/src/sgml/ref/pg_passwd.sgml
@@ -1,5 +1,5 @@
<!--
-$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>
diff --git a/src/backend/libpq/password.c b/src/backend/libpq/password.c
index 77b09be18a4eaf8b9a6153626d9dd715573d4908..2d4559a296c42f0631846d539d8332041ff61d83 100644
--- a/src/backend/libpq/password.c
+++ b/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'
diff --git a/src/backend/libpq/pg_hba.conf.sample b/src/backend/libpq/pg_hba.conf.sample
index 66b0252c0f18c1d2b7cf482edf967748c4661c83..ddd3994a7236ab2942581c2d425463bd2e30c158 100644
--- a/src/backend/libpq/pg_hba.conf.sample
+++ b/src/backend/libpq/pg_hba.conf.sample
@@ -1,188 +1,217 @@
-#
-# PostgreSQL HOST ACCESS CONTROL FILE
-#
-#
-# This file controls what hosts are allowed to connect to what databases
-# and specifies how users on a particular host are identified. It is read
-# by the PostgreSQL postmaster each time a host tries to make a connection
-# to a database.
-#
-# Each line (terminated by a newline character) is a record. A record
-# cannot be continued across two lines.
-#
-# There are 3 kinds of records:
-# 1) comment: Starts with #.
-# 2) empty: Contains nothing excepting spaces and tabs.
-# 3) record: anything else.
-# Only record lines are significant.
-#
-# A record consists of tokens separated by spaces or tabs. Spaces and
-# tabs at the beginning and end of a record are ignored, as are extra
-# spaces and tabs between two tokens.
-#
-# The first token in a record is the record type. The interpretation of
-# the rest of the record depends on the record type.
-
-
-# Record type "host"
-# ------------------
#
-# This record identifies a set of network hosts that are permitted to
-# connect to databases via IP connections. No hosts are permitted to connect
-# over IP except as specified by a "host" record.
-#
+# PostgreSQL HOST-BASED ACCESS (HBA) CONTROL FILE
+#
+#
+# This file controls:
+#
+# o which hosts are allowed to connect
+# o how users are authenticated on each host
+# o databases accessible by each host
+#
+# It is read by the PostgreSQL postmaster each time a host tries to make a
+# connection to a database.
+#
+# Each line is a new record. Records cannot be continued across multiple
+# lines. Lines beginning with # (comments) and blank lines are ignored. A
+# record consists of tokens separated by multiple spaces or tabs.
+#
+# The first token of a record indicates its type. The remainder of the
+# record is interpreted based on its type.
+#
+# Record Types
+# ============
+#
+# There are three types of records:
+#
+# o host
+# o hostssl
+# o local
+#
+# host
+# ----
+#
+# This record identifies the networked hosts that are permitted to connect
+# via IP connections.
+#
# Format:
#
-# host DBNAME IP_ADDRESS ADDRESS_MASK AUTHTYPE [AUTH_ARGUMENT]
-#
-# DBNAME is the name of a PostgreSQL database, or "all" to indicate all
-# databases, or "sameuser" to restrict a user's access to a database with
-# the same name as the user.
-#
-# IP_ADDRESS and ADDRESS_MASK are a standard dotted decimal IP address
-# and mask to identify a set of hosts. These hosts are allowed to connect
-# to the database(s) identified by DBNAME. Note that the IP address must
-# be specified numerically, not as a domain name.
-#
-# AUTHTYPE and AUTH_ARGUMENT are described below.
-#
+# host DBNAME IP_ADDRESS ADDRESS_MASK AUTH_TYPE [AUTH_ARGUMENT]
+#
+# DBNAME can be:
+#
+# o the name of a PostgreSQL database
+# o "all" to indicate all databases
+# o "sameuser" to allow access only to databases with the same
+# name as the connecting user
+#
+# IP_ADDRESS and ADDRESS_MASK are standard dotted decimal IP address and
+# mask values. IP addresses can only be specified numerically, not as
+# 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 scans to find the first entry that matches
-# the connecting host IP address and the requested database name. This
-# entry's AUTHTYPE will then be used to verify or reject the connection.
-# If no entry matches the host+database, the connection is rejected.
-
-
-# Record type "hostssl"
-# ---------------------
-#
-# The format of this record is identical to that of "host".
-#
+# 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
+# -------
+#
+# The format of this record is identical to "host".
+#
# 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; write "hostssl" if you want to
-# accept *only* SSL-secured connections from this host or hosts.
-#
+# 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.
+#
# This keyword is only available if the server was compiled with SSL
# support enabled.
-
-
-# Record type "local"
-# ------------------
+#
+#
+# local
+# -----
#
# This record identifies the authentication to use when connecting to
-# the server via a local UNIX socket. UNIX-socket connections will be
+# the server via a local UNIX domain socket. UNIX-socket connections are
# allowed only if this record type appears.
-#
+#
# Format:
#
-# local DBNAME AUTHTYPE [AUTH_ARGUMENT]
-#
-# The format is the same as that of the "host" record type except that
-# the IP_ADDRESS and ADDRESS_MASK are omitted.
-#
+# local DBNAME AUTH_TYPE [AUTH_ARGUMENT]
+#
+# 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 controls whether the connection is allowed.
-
-
-# Authentication Types (AUTHTYPE)
-# -------------------------------
-#
-# AUTHTYPE is a keyword indicating the method used to authenticate the
-# user, i.e. to determine that the user is authorized to connect under
-# the PostgreSQL username supplied in the connection request. A
-# different AUTHTYPE can be specified for each record in the file.
-#
-# trust: No authentication is done. Trust that the user has the
-# authority to use whatever username he specifies.
-#
+# database name is used.
+#
+#
+#
+# Authentication Types (AUTH_TYPE)
+# ================================
+#
+# AUTH_TYPE indicates the method used to authenticate users. The username
+# is specified in the connection request. A different AUTH_TYPE can be
+# specified for each record in the file.
+#
+# trust: No authentication is done. Any valid username is accepted,
+# including the PostgreSQL superuser. This option should
+# be use only for machines where all users are truested.
+#
# password: Authentication is done by matching a password supplied
-# in clear by the host. If AUTH_ARGUMENT is specified then
-# the password is compared with the user's entry in that
-# file (in the $PGDATA directory). These per-host password
-# files can be maintained with the pg_passwd(1) utility.
-# If no AUTH_ARGUMENT appears then the password is compared
-# with the user's entry in the pg_shadow table.
-#
-# crypt: Same as 'password', but authentication is done by
-# encrypting the password sent over the network.
-#
+# in clear by the host. If no AUTH_ARGUMENT is used, the
+# password is compared with the user's entry in the
+# pg_shadow table.
+#
+# 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
+# up in pg_shadow. If a password exists in the file, it is
+# it 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
+# 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.
+#
+# crypt: Same as "password", but authentication is done by
+# encrypting the password sent over the network. This is
+# always preferable to "password" except for old clients
+# that don't support "crypt". Also, crypt can use
+# usernames stored in secondary password files but not
+# secondary passwords.
+#
# ident: Authentication is done by the ident server on the remote
-# host, via the ident (RFC 1413) protocol. An AUTH_ARGUMENT
-# is required: it is a map name to be found in the
-# $PGDATA/pg_ident.conf file. The connection is accepted
-# if pg_ident.conf contains an entry for this map name with
-# the ident-supplied username and the requested PostgreSQL
-# username. The special map name "sameuser" indicates an
-# implied map (not sought in pg_ident.conf) that maps every
-# ident username to the identical PostgreSQL username.
-#
+# host. AUTH_ARGUMENT is required and maps names found in
+# the $PGDATA/pg_ident.conf file. The connection is
+# accepted if the file contains an entry for this map
+# name with the ident-supplied username and the requested
+# PostgreSQL username. The special map name "sameuser"
+# indicates an implied map (not in pg_ident.conf)
+# that maps each ident username to the identical
+# PostgreSQL username.
+#
# krb4: Kerberos V4 authentication is used.
-#
+#
# krb5: Kerberos V5 authentication is used.
-#
-# reject: Reject the connection.
-#
-# Local (UNIX socket) connections support only AUTHTYPEs "trust",
-# "password", "crypt", and "reject".
-
-
+#
+# reject: Reject the connection. This is used to reject certain hosts
+# that are part of a network specified later in the file.
+# To be effective, "reject" must appear before the later
+# entries.
+#
+# Local UNIX-domain socket connections support only the AUTH_TYPEs of
+# "trust", "password", "crypt", and "reject".
+#
+#
+#
# Examples
-# --------
-#
-# TYPE DATABASE IP_ADDRESS MASK AUTHTYPE MAP
+# ========
#
-# Allow any user on the local system to connect to any
-# database under any username, but only via an IP connection:
-#
-# host all 127.0.0.1 255.255.255.255 trust
-#
-# The same, over Unix-socket connections:
-#
+#
+# Allow any user on the local system to connect to any database under any
+# username using Unix-domain sockets (the default for local connections):
+# TYPE DATABASE IP_ADDRESS MASK AUTH_TYPE AUTH_ARGUMENT
# local all trust
-#
+#
+# The same using IP connections on the same machine:
+# TYPE DATABASE IP_ADDRESS MASK AUTH_TYPE AUTH_ARGUMENT
+# host all 127.0.0.1 255.255.255.255 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):
-#
-# host template1 192.168.93.0 255.255.255.0 ident sameuser
+# connect to database "template1" as the same username that ident reports
+# for the connection (typically his Unix username):
+#
+# TYPE DATABASE IP_ADDRESS MASK AUTH_TYPE AUTH_ARGUMENT
+# host template1 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:
-#
+#
+# TYPE DATABASE IP_ADDRESS MASK AUTH_TYPE AUTH_ARGUMENT
# host template1 192.168.12.10 255.255.255.255 crypt
-#
+#
# 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
-# matched first), but allow Kerberos V5-validated connections from anywhere
-# else on the Internet. The zero mask means that no bits of the host IP
-# address are considered, so it matches any host:
-#
+# all connection from 192.168.54.1 (since that entry will be matched
+# first), but allow Kerberos V5-validated connections from anywhere else
+# on the Internet. The zero mask means that no bits of the host IP address
+# are considered, so it matches any host:
+#
+#
+# TYPE DATABASE IP_ADDRESS MASK AUTH_TYPE AUTH_ARGUMENT
# host all 192.168.54.1 255.255.255.255 reject
# host 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"
-# and he requests to connect as PostgreSQL user "guest1", the connection
-# 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
-#
-
-
+#
+# Allow users from 192.168.x.x hosts to connect to any database if they
+# pass the ident check. For example, if ident says the user is "james" and
+# he requests to connect as PostgreSQL user "guest", the connection is
+# allowed if there is an entry in $PGDATA/pg_ident.conf with map name
+# "phoenix" that says "james" is allowed to connect as "guest":
+#
+# TYPE DATABASE IP_ADDRESS MASK AUTH_TYPE AUTH_ARGUMENT
+# host all 192.168.0.0 255.255.0.0 ident phoenix
+#
+# 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 as any
+# ==================================
+#
+# This default configuration allows any local user to connect with any
# PostgreSQL username, over either UNIX domain sockets or IP:
-
-local all trust
-host all 127.0.0.1 255.255.255.255 trust
-
+#
# If you want to allow non-local connections, you will need to add more
-# "host" records (and don't forget to start the postmaster with "-i"!).
-
-# CAUTION: if you are on a multiple-user machine, the above default
-# configuration is probably too liberal for you --- change it to use
+# "host" records. Also, remember IP connections are only enabled if you
+# start the postmaster with the -i option.
+#
+# CAUTION: if you are on a multiple-user machine, the default
+# configuration is probably too liberal for you. Change it to use
# something other than "trust" authentication.
+#
+# TYPE DATABASE IP_ADDRESS MASK AUTH_TYPE AUTH_ARGUMENT
+
+local all trust
+host all 127.0.0.1 255.255.255.255 trust
+
diff --git a/src/backend/libpq/pg_ident.conf.sample b/src/backend/libpq/pg_ident.conf.sample
index 4abaff974140ae267ea74563d9eeb50c3f57e927..d321461c0c8e2fda5004b1715a31b6edbd0164d5 100644
--- a/src/backend/libpq/pg_ident.conf.sample
+++ b/src/backend/libpq/pg_ident.conf.sample
@@ -1,29 +1,31 @@
-# 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