Improve comments in pg_hba.conf.sample and the associated SGML

documentation.

1 files changed, 94 insertions, 63 deletions

diff --git a/src/backend/libpq/pg_hba.conf.sample b/src/backend/libpq/pg_hba.conf.sample
index 44010c7b9c5..66b0252c0f1 100644
--- a/src/backend/libpq/pg_hba.conf.sample
+++ b/src/backend/libpq/pg_hba.conf.sample
@@ -1,28 +1,23 @@
 #
-#
 #                   PostgreSQL HOST ACCESS CONTROL FILE
 #
 # 
 # This file controls what hosts are allowed to connect to what databases
-# and specifies some options on how users on a particular host are
-# identified. It is read each time a host tries to make a connection to a
-# database.
+# 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
+# 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
@@ -33,21 +28,29 @@
 # ------------------
 # 
 # This record identifies a set of network hosts that are permitted to
-# connect to databases. No network hosts are permitted to connect except
-# as specified by a "host" record. See the record type "local" to specify
-# permitted connections for local users via UNIX domain sockets.
+# connect to databases via IP connections. No hosts are permitted to connect
+# over IP except as specified by a "host" record.
 #
 # Format:
 # 
-#   host DBNAME IP_ADDRESS ADDRESS_MASK AUTHTYPE [AUTH_ARGUMENT]
+#   host  DBNAME  IP_ADDRESS  ADDRESS_MASK  AUTHTYPE  [AUTH_ARGUMENT]
 # 
-# DBNAME is the name of a PostgreSQL database, "all" to indicate all
+# 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 user name.
+# 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 Database DBNAME. There is a separate section about AUTHTYPE below.
+# 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.
+#
+# 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"
@@ -55,26 +58,31 @@
 #
 # The format of this record is identical to that of "host".
 #
-# This record identifies the authentication to use when connecting to a
-# particular database via TCP/IP sockets over SSL. Note that normal
-# "host" records are also matched - "hostssl" records can be used to
-# require a SSL connection. This keyword is only available if the server
-# is compiled with SSL support enabled.
+# 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.
+#
+# This keyword is only available if the server was compiled with SSL
+# support enabled.
 
 
 # Record type "local"
 # ------------------
 # 
-# This record identifies the authentication to use when connecting to a
-# particular database via a local UNIX socket.
+# This record identifies the authentication to use when connecting to
+# the server via a local UNIX socket.  UNIX-socket connections will be
+# allowed only if this record type appears.
 #
 # Format:
 # 
-#   local DBNAME AUTHTYPE [AUTH_ARGUMENT]
+#   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 supports only
-# AUTHTYPEs "trust", "password", "crypt", and "reject".
+# the IP_ADDRESS and ADDRESS_MASK are omitted.
+#
+# As with "host" records, the first "local" record matching the requested
+# database name controls whether the connection is allowed.
 
 
 # Authentication Types (AUTHTYPE)
@@ -82,7 +90,8 @@
 #
 # 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 his connection parameters.
+# 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.
@@ -90,68 +99,90 @@
 #   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). See pg_passwd(1). If it
-#   		is omitted then the password is compared with the user's
-#   		entry in the pg_shadow table.
+#   		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.
 #
 #   ident:  	Authentication is done by the ident server on the remote
-#   		host, via the ident (RFC 1413) protocol. AUTH_ARGUMENT,
-#   		if specified, is a map name to be found in the
-#   		pg_ident.conf file. That table maps from ident usernames
-#   		to PostgreSQL usernames. The special map name "sameuser"
-#   		indicates an implied map (not found in pg_ident.conf)
-#   		that maps every ident username to the identical
-#   		PostgreSQL username.
+#   		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.
 #
 #   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".
 
 
 # Examples
 # --------
 #
-# TYPE       DATABASE    IP_ADDRESS    MASK                AUTHTYPE  MAP
+# TYPE       DATABASE    IP_ADDRESS    MASK               AUTHTYPE  MAP
 # 
-#host         all         127.0.0.1    255.255.255.255     trust     
-# 
-# The above allows any user on the local system to connect to any
-# database under any username.
+# Allow any user on the local system to connect to any
+# database under any username, but only via an IP connection:
 #
-#host         template1   192.168.93.0 255.255.255.0       ident     sameuser
-# 
-# The above allows 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       all         127.0.0.1     255.255.255.255    trust     
+#
+# The same, over Unix-socket connections:
+#
+# local      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):
 #
-#host         template1   192.168.12.10 255.255.255.255    crypt
+# host       template1   192.168.93.0  255.255.255.0      ident     sameuser
 # 
-# The above allows a user from host 192.168.12.10 to connect to
-# database template1 if the user's password in pg_shadow is
-# supplied. User passwords are optionally assigned when a 
-# user is created.
+# 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:
 #
-#host         all        192.168.54.1  255.255.255.255     reject
-#host         all        0.0.0.0       0.0.0.0             trust
+# host       template1   192.168.12.10 255.255.255.255    crypt
 #
-# The above would allow anyone anywhere except from 192.168.54.1 to
-# connect to any database under any username.
+# 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:
 #
-#host         all        192.168.77.0  255.255.255.0       ident     omicron
+# host       all        192.168.54.1   255.255.255.255    reject
+# host       all        0.0.0.0        0.0.0.0            krb5
 #
-# The above would allow users from 192.168.77.x hosts to connect to any
-# database, but if Ident says the user is "bryanh" and he requests to
-# connect as PostgreSQL user "guest1", the connection is only allowed if
-# there is an entry for map "omicron" in pg_ident.conf that says "bryanh"
-# is allowed to connect as "guest1".
+# 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
+#
+
+
+# Put your actual configuration here
+# ----------------------------------
 
+# This default configuration allows any local user to connect as any
+# PostgreSQL username, over either UNIX domain sockets or IP:
 
-# By default, allow anything over UNIX domain sockets and localhost.
 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
+# something other than "trust" authentication.