From c1257d4c5c9f9632eda42a8660af587bf9712a3a Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Tue, 21 Nov 2000 20:44:32 +0000
Subject: [PATCH] Improve comments in pg_hba.conf.sample and the associated
SGML documentation.
---
doc/src/sgml/client-auth.sgml | 154 ++++++++++++++------------
src/backend/libpq/pg_hba.conf.sample | 157 ++++++++++++++++-----------
2 files changed, 179 insertions(+), 132 deletions(-)
diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index 616867fbd38..af603a62e83 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -1,25 +1,24 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.8 2000/10/21 01:08:34 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.9 2000/11/21 20:44:31 tgl Exp $ -->
<chapter id="client-authentication">
<title>Client Authentication</title>
<para>
- User names from the operating system and from a
- <productname>Postgres</productname> database installation are
- logically separate. When a client application connects, it specifies
- which database user name it wants to connect as, similar to how one
- logs into a Unix computer. Within the SQL environment the active
- database user name determines various access privileges to database
+ When a client application connects to the database server, it specifies which
+ <productname>Postgres</productname> user name it wants to connect as,
+ much the same way one logs into a Unix computer as a particular user.
+ Within the SQL environment the active
+ database user name determines access privileges to database
objects -- see <xref linkend="user-manag"> for more information
- about that. It is therefore obviously essential to restrict what
- database user name a given client can connect as.
+ about that. It is therefore obviously essential to restrict which
+ database user name(s) a given client can connect as.
</para>
<para>
<firstterm>Authentication</firstterm> is the process by which the
database server establishes the identity of the client, and by
extension determines whether the client application (or the user
- which runs the client application) is permitted to connect with the
+ who runs the client application) is permitted to connect with the
user name that was requested.
</para>
@@ -29,14 +28,26 @@
authentication methods available.
</para>
+ <para>
+ <productname>Postgres</productname> database user names are logically
+ separate from user names of the operating system in which the server
+ runs. If all the users of a particular server also have accounts on
+ the server's machine, it makes sense to assign database user names
+ that match their Unix user ids. However, a server that accepts remote
+ connections may have many users who have no local account, and in such
+ cases there need be no connection between database usernames and Unix
+ usernames.
+ </para>
+
<sect1 id="pg-hba.conf">
<title>The <filename>pg_hba.conf</filename> file</title>
<para>
Client authentication is controlled by the file
- <filename>pg_hba.conf</filename> in the data directory, e.g.,
- <filename>/usr/local/pgsql/data/pg_hba.conf</filename>. (HBA =
- host-based authentication) A default file is installed when the
+ <filename>pg_hba.conf</filename> in the $PGDATA directory, e.g.,
+ <filename>/usr/local/pgsql/data/pg_hba.conf</filename>. (HBA stands
+ for host-based authentication.) A default <filename>pg_hba.conf</filename>
+ file is installed when the
data area is initialized by <application>initdb</application>.
</para>
@@ -84,7 +95,7 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
<term><literal>hostssl</literal></term>
<listitem>
<para>
- This record pertains to connection attemps with SSL over
+ This record pertains to connection attempts with SSL over
TCP/IP. To make use of this option the server must be
built with SSL support enabled. Furthermore, SSL must be
enabled with the <option>-l</> option or equivalent configuration
@@ -99,8 +110,10 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
<para>
Specifies the database that this record applies to. The value
<literal>all</literal> specifies that it applies to all
- databases, the value <literal>sameuser</> identifies the
- database with the same name as the connecting user.
+ databases, while the value <literal>sameuser</> identifies the
+ database with the same name as the connecting user. Otherwise,
+ this is the name of a specific <productname>Postgres</productname>
+ database.
</para>
</listitem>
</varlistentry>
@@ -140,7 +153,7 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
<para>
The connection is allowed unconditionally. This method allows
any user that has login access to the client host to connect as
- any user whatsoever.
+ any <productname>Postgres</productname> user whatsoever.
</para>
</listitem>
</varlistentry>
@@ -246,17 +259,18 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
</varlistentry>
</variablelist>
- The first record that matches a connection attempt is used. There
- is no <quote>fall-through</> or <quote>backup</>, that means, if
+ The first record that matches a connection attempt's client IP address
+ and requested database name is used to do the authentication step.
+ There is no <quote>fall-through</> or <quote>backup</>: if
one record is chosen and the
authentication fails, the following records are not considered. If
no record matches, the access will be denied.
</para>
<para>
- The <filename>pg_hba.conf</filename> file is re-read before each
- connection attempt. It is therefore easily possible to modify
- access permissions while the server is running.
+ The <filename>pg_hba.conf</filename> file is re-read during each
+ connection attempt. It is therefore trivial to modify access
+ permissions while the server is running: just edit the file.
</para>
<para>
@@ -267,42 +281,44 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
<example id="example-pg-hba.conf">
<title>An example <filename>pg_hba.conf</filename> file</title>
<programlisting>
-#TYPE DATABASE IP-ADDRESS MASK AUTHTYPE ARG
-
-# Allow any user on the local system to connect to any database under
-# any user name.
-#
-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 user name that ident on that
-# host identifies him as (typically his Unix user name).
-#
-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 supplied.
-#
-host template1 192.168.12.10 255.255.255.255 crypt
-
-# In absence of the other records, this would allow anyone anywhere
-# except from 192.168.54.1 to connect to any database under any user
-# name.
-#
-host all 192.168.54.1 255.255.255.255 reject
-host all 0.0.0.0 0.0.0.0 trust
-
-# Allow users from 192.168.77.x hosts to connect to any database, but if,
-# for example, 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".
-#
-host all 192.168.77.0 255.255.255.0 ident omicron
-
-# Allow all users to connect to all databases via Unix sockets.
-#
-local all trust
+# 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:
+
+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.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:
+
+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:
+
+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
</programlisting>
</example>
</para>
@@ -324,7 +340,7 @@ local all trust
<command>CREATE USER</command> and <command>ALTER USER</command>,
e.g., <userinput>CREATE USER foo WITH PASSWORD
'secret';</userinput>. By default, that is, if no password has
- explicitly been set up, the stored password is <quote>NULL</quote>
+ been set up, the stored password is <literal>NULL</literal>
and password authentication will always fail for that user.
</para>
@@ -336,12 +352,12 @@ local all trust
file after the <literal>password</> or <literal>crypt</> keyword,
respectively, in <filename>pg_hba.conf</>. If you do not use this
feature, then any user that is known to the database system can
- connect to any database (as long as he passes password
+ connect to any database (so long as he passes password
authentication, of course).
</para>
<para>
- These files can also be used a apply a different set of passwords
+ These files can also be used to apply a different set of passwords
to a particular database or set thereof. In that case, the files
have a format similar to the standard Unix password file
<filename>/etc/passwd</filename>, that is,
@@ -401,7 +417,7 @@ local all trust
<para>
In order to use <productname>Kerberos</>, support for it must be
- enable at build time. Both Kerberos 4 and 5 are supported
+ enabled at build time. Both Kerberos 4 and 5 are supported
(<literal>./configure --with-krb4</> or <literal>./configure
--with-krb5</> respectively).
</para>
@@ -411,7 +427,7 @@ local all trust
service. The name of the service principal is normally
<literal>postgres</literal>, unless it was changed during the
build. Make sure that your server key file is readable (and
- preferrably only readable) by the Postgres server account (see
+ preferably only readable) by the Postgres server account (see
<xref linkend="postgres-user">). The location of the key file
is specified with the <varname>krb_server_keyfile</> run time
configuration parameter. (See also <xref linkend="runtime-config">.)
@@ -553,13 +569,13 @@ local all trust
A <filename>pg_ident.conf</filename> file that could be used in
conjunction with the <filename>pg_hba.conf</> file in <xref
linkend="example-pg-hba.conf"> is shown in <xref
- linkend="example-pg-ident.conf">. In that example setup, anyone
- logged in to a machine on the 192.168.77 network that does not have
- the a user name bryanh, ann, or robert would not be granted access.
+ linkend="example-pg-ident.conf">. In this example setup, anyone
+ logged in to a machine on the 192.168 network that does not have
+ the Unix user name bryanh, ann, or robert would not be granted access.
Unix user robert would only be allowed access when he tries to
- connect as <quote>bob</quote>, not as <quote>robert</quote> or
- anyone else. <quote>ann</quote> would only be allowed to connect
- <quote>as herself</>. User bryanh would be allowed to connect as either
+ connect as Postgres user <quote>bob</quote>, not as <quote>robert</quote>
+ or anyone else. <quote>ann</quote> would only be allowed to connect as
+ <quote>ann</>. User bryanh would be allowed to connect as either
<quote>bryanh</> himself or as <quote>guest1</>.
</para>
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.
--
GitLab