Skip to content

Commit 6ab42ae

Browse files
peterepetere
committed
Support host names in pg_hba.conf
Peter Eisentraut, reviewed by KaiGai Kohei and Tom Lane
1 parent 3cde443 commit 6ab42ae

File tree

6 files changed

+248
-49
lines changed

6 files changed

+248
-49
lines changed

‎doc/src/sgml/client-auth.sgml

Lines changed: 93 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -80,9 +80,9 @@
8080
A record is made
8181
up of a number of fields which are separated by spaces and/or tabs.
8282
Fields can contain white space if the field value is quoted.
83-
Quoting one of the keywords in a database or user name field (e.g.,
83+
Quoting one of the keywords in a database, user, or address field (e.g.,
8484
<literal>all</> or <literal>replication</>) makes the word lose its special
85-
character, and just match a database or user with that name.
85+
character, and just match a database, user, or host with that name.
8686
</para>
8787

8888
<para>
@@ -101,9 +101,9 @@
101101
A record can have one of the seven formats
102102
<synopsis>
103103
local <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>auth-method</replaceable> <optional><replaceable>auth-options</replaceable></optional>
104-
host <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>CIDR-address</replaceable> <replaceable>auth-method</replaceable> <optional><replaceable>auth-options</replaceable></optional>
105-
hostssl <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>CIDR-address</replaceable> <replaceable>auth-method</replaceable> <optional><replaceable>auth-options</replaceable></optional>
106-
hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>CIDR-address</replaceable> <replaceable>auth-method</replaceable> <optional><replaceable>auth-options</replaceable></optional>
104+
host <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>address</replaceable> <replaceable>auth-method</replaceable> <optional><replaceable>auth-options</replaceable></optional>
105+
hostssl <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>address</replaceable> <replaceable>auth-method</replaceable> <optional><replaceable>auth-options</replaceable></optional>
106+
hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>address</replaceable> <replaceable>auth-method</replaceable> <optional><replaceable>auth-options</replaceable></optional>
107107
host <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>IP-address</replaceable> <replaceable>IP-mask</replaceable> <replaceable>auth-method</replaceable> <optional><replaceable>auth-options</replaceable></optional>
108108
hostssl <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>IP-address</replaceable> <replaceable>IP-mask</replaceable> <replaceable>auth-method</replaceable> <optional><replaceable>auth-options</replaceable></optional>
109109
hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>IP-address</replaceable> <replaceable>IP-mask</replaceable> <replaceable>auth-method</replaceable> <optional><replaceable>auth-options</replaceable></optional>
@@ -218,13 +218,17 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
218218
</varlistentry>
219219

220220
<varlistentry>
221-
<term><replaceable>CIDR-address</replaceable></term>
221+
<term><replaceable>address</replaceable></term>
222222
<listitem>
223223
<para>
224-
Specifies the client machine IP address range that this record
225-
matches. This field contains an IP address in standard dotted decimal
226-
notation and a <acronym>CIDR</> mask length. (IP addresses can only be
227-
specified numerically, not as domain or host names.) The mask
224+
Specifies the client machine addresses that this record
225+
matches. This field can contain either a host name, an IP
226+
address range, or one of the special key words mentioned below.
227+
</para>
228+
229+
<para>
230+
An IP address is specified in standard dotted decimal
231+
notation with a <acronym>CIDR</> mask length. The mask
228232
length indicates the number of high-order bits of the client
229233
IP address that must match. Bits to the right of this must
230234
be zero in the given IP address.
@@ -233,14 +237,7 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
233237
</para>
234238

235239
<para>
236-
Instead of a <replaceable>CIDR-address</replaceable>, you can write
237-
<literal>samehost</literal> to match any of the server's own IP
238-
addresses, or <literal>samenet</literal> to match any address in any
239-
subnet that the server is directly connected to.
240-
</para>
241-
242-
<para>
243-
Typical examples of a <replaceable>CIDR-address</replaceable> are
240+
Typical examples of an IP address range specified this way are
244241
<literal>172.20.143.89/32</literal> for a single host, or
245242
<literal>172.20.143.0/24</literal> for a small network, or
246243
<literal>10.6.0.0/16</literal> for a larger one.
@@ -259,6 +256,67 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
259256
support for IPv6 addresses.
260257
</para>
261258

259+
<para>
260+
You can also write
261+
<literal>samehost</literal> to match any of the server's own IP
262+
addresses, or <literal>samenet</literal> to match any address in any
263+
subnet that the server is directly connected to.
264+
</para>
265+
266+
<para>
267+
If a host name is specified (anything that is not an IP address
268+
or a special key word is processed as a potential host name),
269+
that name is compared with the result of a reverse name
270+
resolution of the client's IP address (e.g., reverse DNS
271+
lookup, if DNS is used). Host name comparisons are case
272+
insensitive. If there is a match, then a forward name
273+
resolution (e.g., forward DNS lookup) is performed on the host
274+
name to check whether any of the addresses it resolves to are
275+
equal to the client's IP address. If both directions match,
276+
then the entry is considered to match. (The host name that is
277+
used in <filename>pg_hba.conf</filename> should be the one that
278+
address-to-name resolution of the client's IP address returns,
279+
otherwise the line won't be matched. Some host name databases
280+
allow associating an IP address with multiple host names, but
281+
the operating system will only return one host name when asked
282+
to resolve an IP address.)
283+
</para>
284+
285+
<para>
286+
When host names are specified
287+
in <filename>pg_hba.conf</filename>, you should make sure that
288+
name resolution is reasonably fast. It can be of advantage to
289+
set up a local name resolution cache such
290+
as <command>nscd</command>. Also, you may wish to enable the
291+
configuration parameter <varname>log_hostname</varname> to see
292+
the client's host name instead of the IP address in the log.
293+
</para>
294+
295+
<sidebar>
296+
<para>
297+
Occasionally, users have wondered why host names are handled
298+
in this seemingly complicated way with two name resolutions
299+
and requiring reverse lookup of IP addresses, which is
300+
sometimes not set up or points to some undesirable host name.
301+
It is primarily for efficiency: A connection attempt requires
302+
two resolver lookups of the current client's address. If
303+
there is resolver problem with that address, it becomes only
304+
that client's problem. A hypothetical alternative
305+
implementation which only does forward lookups would have to
306+
resolve every host name mentioned in
307+
<filename>pg_hba.conf</filename> at every connection attempt.
308+
That would already be slow by itself. And if there is a
309+
resolver problem with one of the host names, it becomes
310+
everyone's problem.
311+
</para>
312+
313+
<para>
314+
Note that this behavior is consistent with other popular
315+
implementations of host name-based access control, such as the
316+
Apache HTTP Server and TCP Wrappers.
317+
</para>
318+
</sidebar>
319+
262320
<para>
263321
This field only applies to <literal>host</literal>,
264322
<literal>hostssl</literal>, and <literal>hostnossl</> records.
@@ -511,30 +569,40 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
511569
# any database user name using Unix-domain sockets (the default for local
512570
# connections).
513571
#
514-
# TYPE DATABASE USER CIDR-ADDRESS METHOD
572+
# TYPE DATABASE USER ADDRESS METHOD
515573
local all all trust
516574

517575
# The same using local loopback TCP/IP connections.
518576
#
519-
# TYPE DATABASE USER CIDR-ADDRESS METHOD
577+
# TYPE DATABASE USER ADDRESS METHOD
520578
host all all 127.0.0.1/32 trust
521579

522580
# The same as the previous line, but using a separate netmask column
523581
#
524582
# TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD
525583
host all all 127.0.0.1 255.255.255.255 trust
526584

585+
# The same over IPv6.
586+
#
587+
# TYPE DATABASE USER ADDRESS METHOD
588+
host all all ::1/128 trust
589+
590+
# The same using a host name (would typically cover both IPv4 and IPv6).
591+
#
592+
# TYPE DATABASE USER ADDRESS METHOD
593+
host all all localhost trust
594+
527595
# Allow any user from any host with IP address 192.168.93.x to connect
528596
# to database "postgres" as the same user name that ident reports for
529597
# the connection (typically the operating system user name).
530598
#
531-
# TYPE DATABASE USER CIDR-ADDRESS METHOD
599+
# TYPE DATABASE USER ADDRESS METHOD
532600
host postgres all 192.168.93.0/24 ident
533601

534602
# Allow any user from host 192.168.12.10 to connect to database
535603
# "postgres" if the user's password is correctly supplied.
536604
#
537-
# TYPE DATABASE USER CIDR-ADDRESS METHOD
605+
# TYPE DATABASE USER ADDRESS METHOD
538606
host postgres all 192.168.12.10/32 md5
539607

540608
# In the absence of preceding "host" lines, these two lines will
@@ -543,7 +611,7 @@ host postgres all 192.168.12.10/32 md5
543611
# on the Internet. The zero mask causes no bits of the host IP
544612
# address to be considered, so it matches any host.
545613
#
546-
# TYPE DATABASE USER CIDR-ADDRESS METHOD
614+
# TYPE DATABASE USER ADDRESS METHOD
547615
host all all 192.168.54.1/32 reject
548616
host all all 0.0.0.0/0 krb5
549617

@@ -553,7 +621,7 @@ host all all 0.0.0.0/0 krb5
553621
# connection is allowed if there is an entry in pg_ident.conf for map
554622
# "omicron" that says "bryanh" is allowed to connect as "guest1".
555623
#
556-
# TYPE DATABASE USER CIDR-ADDRESS METHOD
624+
# TYPE DATABASE USER ADDRESS METHOD
557625
host all all 192.168.0.0/16 ident map=omicron
558626

559627
# If these are the only three lines for local connections, they will
@@ -563,7 +631,7 @@ host all all 192.168.0.0/16 ident map=omicro
563631
# $PGDATA/admins contains a list of names of administrators. Passwords
564632
# are required in all cases.
565633
#
566-
# TYPE DATABASE USER CIDR-ADDRESS METHOD
634+
# TYPE DATABASE USER ADDRESS METHOD
567635
local sameuser all md5
568636
local all @admins md5
569637
local all +support md5

0 commit comments

Comments
 (0)