Shrink the pg_hba.conf and pg_ident.conf default files and move most of the

inline documentation to the main docs.

2 files changed, 78 insertions, 289 deletions

diff --git a/src/backend/libpq/pg_hba.conf.sample b/src/backend/libpq/pg_hba.conf.sample
index 05e6959b4de..5338c79104b 100644
--- a/src/backend/libpq/pg_hba.conf.sample
+++ b/src/backend/libpq/pg_hba.conf.sample
@@ -1,259 +1,48 @@
-# 
-#		  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 on postmaster startup and when the postmaster receives a SIGHUP.
-# If you edit the file on a running system, you have to SIGHUP the postmaster
-# for the changes to take effect, or use "pg_ctl reload".
-# 
-# Each line is a new record. Records cannot span multiple lines. 
-# Comments begin with # and continue to the end of the line. 
-# Blank lines are ignored. A record consists of tokens separated by 
-# spaces or tabs.
-# 
-# Each record specifies a connection type and authentication method. Most
-# records also can restrict based on database name or IP address. 
-#
-# When reading this file, 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 the connection type. The
-# remainder of the record is interpreted based on that type.
-# 
-# Record Types
-# ============
-# 
-# There are three record types:
-# 	o host
-# 	o hostssl
-# 	o local
-# 
-# host
-# ----
-# 
-# This record identifies hosts that are permitted to connect via TCP/IP.
-# 
-# Format:
-# 
-#   host       DATABASE    USER      IP_ADDRESS    MASK               AUTH_TYPE
-# 
-# DATABASE can be:
-#	o a database name
-#	o "sameuser", which means a user can only access a database with the
-#	  same name as their user name
-#	o "samegroup", which means a user can only access databases when they
-#	  are members of a group with the same name as the database name
-#	o "all", which matches all databases
-#	o a list of database names, separated by commas
-#	o a file name containing database names, starting with '@'
-#
-# USER can be:
-#	o a user name
-#	o "all", which matches all users
-#	o a list of user names, separated by commas
-#	o a group name, starting with '+'
-#	o a file name containing user names, starting with '@'
-#
-# Files read using '@' can contain comma-separated database/user names,
-# or one name per line.  The files can also contain comments using '#'.
-#
-# IP_ADDRESS and MASK are standard dotted decimal IP address and
-# mask values. IP addresses can only be specified numerically, not as
-# domain or host names.
-# 
-# Do not prevent the superuser from accessing the template1 database.
-# Various utility commands need access to template1.
-# 
-# AUTH_TYPE is described below.
-#
-# 
-# hostssl
-# -------
-# 
-# The format of this record is identical to "host".
-# 
-# It specifies hosts that require connection via secure SSL. "host"
-# allows SSL connections too, but "hostssl" requires SSL-secured
-# connections.
-# 
-# This keyword is only available if the server was compiled with SSL
-# support.
-# 
-# 
-# local
-# -----
-# 
-# This record identifies the authentication for local UNIX domain socket
-# connections. Without this record, UNIX-socket connections are disallowed
-# 
-# Format:
-#   local      DATABASE    USER      AUTH_TYPE
-# 
-# This format is identical to the "host" record type except there are no
-# IP_ADDRESS and MASK fields.
-#
-# 
-# 
-# Authentication Types (AUTH_TYPE)
-# ================================
-# 
-# AUTH_TYPE indicates the method used to authenticate users. Each record
-# has an AUTH_TYPE.
-#
-#   trust: 
-#		No authentication is done. Any valid user name is accepted,
-# 		including the PostgreSQL superuser. This option should
-# 		be used only for hosts where all users are trusted.
-# 
-#   md5:
-#	  	Requires the client to supply an MD5 encrypted password for
-#		authentication.  This is the only method that allows encrypted
-#		passwords to be stored in pg_shadow.
-# 
-#   crypt:
-#	  	Same as "md5", but uses crypt for pre-7.2 clients.
-#
-#   password:
-#		Same as "md5", but the password is sent in cleartext over
-#		the network.  This should not be used on untrusted
-#		networks.
-# 
-#   ident:
-#		For TCP/IP connections, authentication is done by contacting the
-#		ident server on the client host. This is only as secure as the
-#		client machine. You must specify the map name after the 'ident'
-#		keyword. It determines how to map remote user names to
-#		PostgreSQL user names. If you use "sameuser", the user names are
-#		assumed to be identical. If not, the map name is looked up
-#		in the $PGDATA/pg_ident.conf file. The connection is accepted if
-#		that file contains an entry for this map name with the
-#		ident-supplied username and the requested PostgreSQL username.
-#
-#		On machines that support unix-domain socket credentials
-#		(currently Linux, FreeBSD, NetBSD, and BSD/OS), ident allows
-#		reliable authentication of 'local' connections without ident 
-#		running on the local machine.
-#
-#   krb4:
-#		Kerberos V4 authentication is used.  Allowed only for
-#		TCP/IP connections, not for local UNIX-domain sockets.
-# 
-#   krb5:
-#		Kerberos V5 authentication is used.  Allowed only for
-#		TCP/IP connections, not for local UNIX-domain sockets.
-# 
-#   pam:
-#		Authentication is done by PAM using the default service name
-#		"postgresql". You can specify your own service name by adding
-#		the service name after the 'pam' keyword. To use this option,
-#		PostgreSQL must be configured --with-pam.
-#
-#   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.
-#
-# 
-# 
-# Examples
-# ========
-# 
-# 
-# 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    USER       IP_ADDRESS    MASK               AUTH_TYPE
-# local      all         all                                         trust
-# 
-# The same using local loopback TCP/IP connections:
-#
-# TYPE      DATABASE     USER    IP_ADDRESS    MASK               AUTH_TYPE
-# host      all          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 reports
-# for the connection (typically his Unix username):
-# 
-# TYPE       DATABASE    USER    IP_ADDRESS    MASK               AUTH_TYPE
-# host       template1   all     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 is correctly supplied:
-# 
-# TYPE       DATABASE    USER     IP_ADDRESS    MASK               AUTH_TYPE
-# host       template1   all      192.168.12.10 255.255.255.255    md5
-# 
-# In the absence of preceding "host" lines, these two lines will reject
-# all connection from 192.168.54.1 (since that entry will be matched
-# first), but allow Kerberos V5 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    USER     IP_ADDRESS    MASK               AUTH_TYPE
-# host       all         all      192.168.54.1  255.255.255.255    reject
-# host       all         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. 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":
-# See $PGDATA/pg_ident.conf for more information on Ident maps.
-# 
-# TYPE       DATABASE    USER     IP_ADDRESS    MASK               AUTH_TYPE
-# host       all         all      192.168.0.0    255.255.0.0       ident phoenix
-#
-# If these are the only three lines for local connections, they will
-# allow local users to connect only to their own databases (databases
-# with the same name as their user name) except for administrators and
-# members of group 'support' who may connect to all databases . The file
-# $PGDATA/admins contains a list of user names. Passwords are required in
-# all cases.
-#
-# TYPE       DATABASE    USER      IP_ADDRESS    MASK               AUTH_TYPE
-# local      sameuser    all                                        md5
-# local      all         @admins                                    md5
-# local      all         +support                                   md5
-#
-# The last two lines above can be combined into a single line:
-#
-# local      all         @admins,+support                           md5
-#
-# The database column can also use lists and file names, but not groups:
-#
-# local      db1,db2,@demodbs  all                                  md5
-#
-#
-# 
+# PostgreSQL Client Authentication Configuration File
+# ===================================================
+#
+# Refer to the PostgreSQL Administrator's Guide, chapter "Client
+# Authentication" for a complete description.  A short synopsis
+# follows.
+#
+# This file controls: which hosts are allowed to connect, how clients
+# are authenticated, which PostgreSQL user names they can use, which
+# databases they can access.  Records take one of three forms:
+#
+# local    DATABASE  USER  METHOD  [OPTION]
+# host     DATABASE  USER  IP-ADDRESS  IP-MASK  METHOD  [OPTION]
+# hostssl  DATABASE  USER  IP-ADDRESS  IP-MASK  METHOD  [OPTION]
+#
+# (The uppercase quantities should be replaced by actual values.)
+# DATABASE can be "all", "sameuser", "samegroup", a database name (or
+# a comma-separated list thereof), or a file name prefixed with "@".
+# USER can be "all", an actual user name or a group name prefixed with
+# "+" or a list containing either.  IP-ADDRESS and IP-MASK specify the
+# set of hosts the record matches.  METHOD can be "trust", "reject",
+# "md5", "crypt", "password", "krb4", "krb5", "ident", or "pam".  Note
+# that "password" uses clear-text passwords; "md5" is preferred for
+# encrypted passwords.  OPTION is the ident map or the name of the PAM
+# service.
+#
+# This file is read on server startup and when the postmaster receives
+# a SIGHUP signal.  If you edit the file on a running system, you have
+# to SIGHUP the postmaster for the changes to take effect, or use
+# "pg_ctl reload".
+
+# Put your actual configuration here
+# ----------------------------------
 #
+# CAUTION: The default configuration allows any local user to connect
+# using any PostgreSQL user name, including the superuser, over either
+# Unix-domain sockets or TCP/IP.  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.
 #
-# 
-# Put your actual configuration here
-# ==================================
-# 
-# The default configuration allows any local user to connect using any
-# PostgreSQL username, including the superuser, over either UNIX domain
-# sockets or TCP/IP.
-# 
-# If you want to allow non-local connections, you need to add more "host"
-# records. Also, remember TCP/IP connections are only enabled if you
-# start the postmaster with the -i flag, or enable "tcpip_socket" in
-# $PGDATA/postgresql.conf.
-# 
-# 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      USER      IP_ADDRESS    MASK               AUTH_TYPE
+# If you want to allow non-local connections, you need to add more
+# "host" records.  Also, remember TCP/IP connections are only enabled
+# if you enable "tcpip_socket" in postgresql.conf.
+
+# TYPE  DATABASE    USER        IP-ADDRESS        IP-MASK           METHOD
 
-local        all           all                                        trust
-host         all           all       127.0.0.1     255.255.255.255    trust
+local   all         all                                             trust
+host    all         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 3f00226f14d..4a7334c7763 100644
--- a/src/backend/libpq/pg_ident.conf.sample
+++ b/src/backend/libpq/pg_ident.conf.sample
@@ -1,35 +1,35 @@
-# 
-# 		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
-# 
-# It is read on postmaster startup and when the postmaster receives a SIGHUP.
-# If you edit the file on a running system, you have to SIGHUP the postmaster
-# for the changes to take effect.
+# PostgreSQL Ident Authentication Maps
+# ====================================
 #
-# 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
+# Refer to the PostgreSQL Administrator's Guide, chapter "Client
+# Authentication" for a complete description.  A short synopsis
+# follows.
+#
+# This file controls PostgreSQL ident-based authentication. It maps
+# ident user names (typically Unix user names) to their corresponding
+# PostgreSQL user names.  Records are of the form:
+#
+# MAPNAME  IDENT-USERNAME  PG-USERNAME
+#
+# (The uppercase quantities should be replaced by actual values.)
+# MAPNAME is the (otherwise freely chosen) map name that was used in
+# pg_hba.conf.  IDENT-USERNAME is the detected user name of the
+# client.  PG-USERNAME is the request PostgreSQL user name.  The
+# existence of a record specifies that IDENT-USERNAME may connect as
+# PG-USERNAME.  Multiple maps may be specified in this file and used
+# by pg_hba.conf.
+#
+# This file is read on server startup and when the postmaster receives
+# a SIGHUP signal.  If you edit the file on a running system, you have
+# to SIGHUP the postmaster for the changes to take effect, or use
+# "pg_ctl reload".
+
+# Put your actual configuration here
+# ----------------------------------
+#
+# No map names are defined in the default configuration.  If all ident
+# user names and PostgreSQL user names are the same, you don't need
+# this file.  Instead, use the special map name "sameuser" in
 # pg_hba.conf.
-# 
-# MAP     IDENT    PGUSERNAME
+
+# MAPNAME     IDENT-USERNAME    PG-USERNAME