Skip to content

Commit 32142e2

Browse files
committed
Update documentation to prefer CIDR format for pg_hba.conf and use new
CIDR column in examples first.
1 parent 8ec3221 commit 32142e2

File tree

2 files changed

+50
-57
lines changed

2 files changed

+50
-57
lines changed

doc/src/sgml/client-auth.sgml

Lines changed: 48 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/client-auth.sgml,v 1.65 2004/03/23 01:23:48 tgl Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/client-auth.sgml,v 1.66 2004/08/26 16:50:05 momjian Exp $
33
-->
44

55
<chapter id="client-authentication">
@@ -86,12 +86,12 @@ $PostgreSQL: pgsql/doc/src/sgml/client-auth.sgml,v 1.65 2004/03/23 01:23:48 tgl
8686
A record may have one of the seven formats
8787
<synopsis>
8888
local <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>authentication-method</replaceable> <optional><replaceable>authentication-option</replaceable></optional>
89+
host <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>CIDR-address</replaceable> <replaceable>authentication-method</replaceable> <optional><replaceable>authentication-option</replaceable></optional>
90+
hostssl <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>CIDR-address</replaceable> <replaceable>authentication-method</replaceable> <optional><replaceable>authentication-option</replaceable></optional>
91+
hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>CIDR-address</replaceable> <replaceable>authentication-method</replaceable> <optional><replaceable>authentication-option</replaceable></optional>
8992
host <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>IP-address</replaceable> <replaceable>IP-mask</replaceable> <replaceable>authentication-method</replaceable> <optional><replaceable>authentication-option</replaceable></optional>
9093
hostssl <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>IP-address</replaceable> <replaceable>IP-mask</replaceable> <replaceable>authentication-method</replaceable> <optional><replaceable>authentication-option</replaceable></optional>
9194
hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>IP-address</replaceable> <replaceable>IP-mask</replaceable> <replaceable>authentication-method</replaceable> <optional><replaceable>authentication-option</replaceable></optional>
92-
host <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>IP-address</replaceable>/<replaceable>IP-masklen</replaceable> <replaceable>authentication-method</replaceable> <optional><replaceable>authentication-option</replaceable></optional>
93-
hostssl <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>IP-address</replaceable>/<replaceable>IP-masklen</replaceable> <replaceable>authentication-method</replaceable> <optional><replaceable>authentication-option</replaceable></optional>
94-
hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>IP-address</replaceable>/<replaceable>IP-masklen</replaceable> <replaceable>authentication-method</replaceable> <optional><replaceable>authentication-option</replaceable></optional>
9595
</synopsis>
9696
The meaning of the fields is as follows:
9797

@@ -196,19 +196,23 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
196196
</varlistentry>
197197

198198
<varlistentry>
199-
<term><replaceable>IP-address</replaceable></term>
200-
<term><replaceable>IP-mask</replaceable></term>
199+
<term><replaceable>CIDR-address</replaceable></term>
201200
<listitem>
202201
<para>
203-
These two fields contain IP address and mask values in standard
204-
dotted decimal notation. (IP addresses can only be specified
205-
numerically, not as domain or host names.) Taken together they
206-
specify the client machine IP addresses that this record
207-
matches. The precise logic is that
208-
<programlisting>
209-
(<replaceable>actual-IP-address</replaceable> xor <replaceable>IP-address-field</replaceable>) and <replaceable>IP-mask-field</replaceable>
210-
</programlisting>
211-
must be zero for the record to match.
202+
specifies the client machine IP addresses that this record
203+
matches. It contains an IP address in standard dotted decimal
204+
notation and a CIDR mask length. (IP addresses can only be
205+
specified numerically, not as domain or host names.) For example,
206+
an IPv4 CIDR mask of 8 is equivalent to an IP mask of 255.0.0.0,
207+
an IPv6 CIDR mask of 64 is equivalent to an IP mask of
208+
ffff:ffff:ffff:ffff::. A IPv4 CIDR mask of 32 is used for single
209+
hosts.
210+
</para>
211+
212+
<para>
213+
A typical CIDR address is <literal>172.20.143.89/32</literal>.
214+
There should be no white space between the IP address, the
215+
<literal>/</literal>, and the CIDR mask length.
212216
</para>
213217

214218
<para>
@@ -229,26 +233,17 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
229233
</varlistentry>
230234

231235
<varlistentry>
236+
<term><replaceable>IP-address</replaceable></term>
232237
<term><replaceable>IP-masklen</replaceable></term>
233238
<listitem>
234239
<para>
235-
This field may be used as an alternative to the
236-
<replaceable>IP-mask</replaceable> notation. It is an integer
237-
specifying the number of high-order bits to set in the mask.
238-
The number must be between 0 and 32 (in the case of an IPv4
239-
address) or 128 (in the case of an IPv6 address) inclusive. 0
240-
will match any address, while 32 (or 128, respectively) will
241-
match only the exact host specified. The same matching logic
242-
is used as for a dotted notation
243-
<replaceable>IP-mask</replaceable>.
244-
</para>
245-
246-
<para>
247-
There must be no white space between the
248-
<replaceable>IP-address</replaceable> and the
249-
<literal>/</literal> or the <literal>/</literal> and the
250-
<replaceable>IP-masklen</replaceable>, or the file will not be
251-
parsed correctly.
240+
This may be used as an alternative to the
241+
<replaceable>CIDR-address</replaceable> notation. Instead of
242+
specifying the mask length, the actual mask is specified in a
243+
separate column. For example, 255.0.0.0 represents a IPv4 CIDR
244+
mask length of 8, and 255.255.255.255 represents a CIDR mask
245+
length of 32. The same matching logic is used as for a dotted
246+
notation <replaceable>IP-mask</replaceable>.
252247
</para>
253248

254249
<para>
@@ -458,55 +453,55 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
458453
# any user name using Unix-domain sockets (the default for local
459454
# connections).
460455
#
461-
# TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD
462-
local all all trust
456+
# TYPE DATABASE USER CIDR-ADDRESS METHOD
457+
local all all trust
463458

464459
# The same using local loopback TCP/IP connections.
465460
#
466-
# TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD
467-
host all all 127.0.0.1 255.255.255.255 trust
461+
# TYPE DATABASE USER CIDR-ADDRESS METHOD
462+
host all all 127.0.0.1/32 trust
468463

469-
# The same as the last line but using a CIDR mask
464+
# The same as the last line but using a separate netmask column
470465
#
471-
# TYPE DATABASE USER IP-ADDRESS/CIDR-mask METHOD
472-
host all all 127.0.0.1/32 trust
466+
# TYPE DATABASE USER CIDR-ADDRESS METHOD
467+
host all all 127.0.0.1 255.255.255.255 trust
473468

474469
# Allow any user from any host with IP address 192.168.93.x to connect
475470
# to database "template1" as the same user name that ident reports for
476471
# the connection (typically the Unix user name).
477472
#
478-
# TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD
479-
host template1 all 192.168.93.0 255.255.255.0 ident sameuser
473+
# TYPE DATABASE USER CIDR-ADDRESS METHOD
474+
host template1 all 192.168.93.0/24 ident sameuser
480475

481-
# The same as the last line but using a CIDR mask
476+
# The same as the last line but using a separate netmask column
482477
#
483-
# TYPE DATABASE USER IP-ADDRESS/CIDR-mask METHOD
484-
host template1 all 192.168.93.0/24 ident sameuser
478+
# TYPE DATABASE USER CIDR-ADDRESS METHOD
479+
host template1 all 192.168.93.0 255.255.255.0 ident sameuser
485480

486481
# Allow a user from host 192.168.12.10 to connect to database
487482
# "template1" if the user's password is correctly supplied.
488483
#
489-
# TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD
490-
host template1 all 192.168.12.10 255.255.255.255 md5
484+
# TYPE DATABASE USER CIDR-ADDRESS METHOD
485+
host template1 all 192.168.12.10/32 md5
491486

492487
# In the absence of preceding "host" lines, these two lines will
493488
# reject all connection from 192.168.54.1 (since that entry will be
494489
# matched first), but allow Kerberos V connections from anywhere else
495490
# on the Internet. The zero mask means that no bits of the host IP
496491
# address are considered so it matches any host.
497492
#
498-
# TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD
499-
host all all 192.168.54.1 255.255.255.255 reject
500-
host all all 0.0.0.0 0.0.0.0 krb5
493+
# TYPE DATABASE USER CIDR-ADDRESS METHOD
494+
host all all 192.168.54.1/32 reject
495+
host all all 0.0.0.0/0 krb5
501496

502497
# Allow users from 192.168.x.x hosts to connect to any database, if
503498
# they pass the ident check. If, for example, ident says the user is
504499
# "bryanh" and he requests to connect as PostgreSQL user "guest1", the
505500
# connection is allowed if there is an entry in pg_ident.conf for map
506501
# "omicron" that says "bryanh" is allowed to connect as "guest1".
507502
#
508-
# TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD
509-
host all all 192.168.0.0 255.255.0.0 ident omicron
503+
# TYPE DATABASE USER CIDR-ADDRESS METHOD
504+
host all all 192.168.0.0/16 ident omicron
510505

511506
# If these are the only three lines for local connections, they will
512507
# allow local users to connect only to their own databases (databases
@@ -515,7 +510,7 @@ host all all 192.168.0.0 255.255.0.0 ident omicro
515510
# $PGDATA/admins contains a list of user names. Passwords are required in
516511
# all cases.
517512
#
518-
# TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD
513+
# TYPE DATABASE USER CIDR-ADDRESS METHOD
519514
local sameuser all md5
520515
local all @admins md5
521516
local all +support md5
@@ -959,3 +954,4 @@ FATAL: database "testdb" does not exist
959954
</sect1>
960955

961956
</chapter>
957+

src/backend/libpq/pg_hba.conf.sample

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -28,11 +28,8 @@
2828
#
2929
# CIDR-ADDRESS specifies the set of hosts the record matches.
3030
# It is made up of an IP address and a CIDR mask that is an integer
31-
# between 0 and 32 (IPv6) or 128(IPv6) inclusive, that specifies
32-
# the number of significant bits in the mask, e.g. an IPv4 CIDR mask
33-
# of 8 is equivalent to an IP mask of 255.0.0.0, an IPv6 CIDR mask
34-
# of 64 is equivalent to an IP mask of ffff:ffff:ffff:ffff::. A
35-
# IPv4 CIDR mask of 32 is used for single hosts. Also, you can use a
31+
# (between 0 and 32 (IPv6) or 128(IPv6) inclusive) that specifies
32+
# the number of significant bits in the mask Also, you can use a
3633
# separate IP address and netmask to specify the set of hosts.
3734
#
3835
# METHOD can be "trust", "reject", "md5", "crypt", "password",

0 commit comments

Comments
 (0)