From 32142e2a604810d334e39f0986de0dfb646f4ffc Mon Sep 17 00:00:00 2001
From: Bruce Momjian <bruce@momjian.us>
Date: Thu, 26 Aug 2004 16:50:05 +0000
Subject: [PATCH] Update documentation to prefer CIDR format for pg_hba.conf
and use new CIDR column in examples first.
---
doc/src/sgml/client-auth.sgml | 100 +++++++++++++--------------
src/backend/libpq/pg_hba.conf.sample | 7 +-
2 files changed, 50 insertions(+), 57 deletions(-)
diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index d93e03f8e5f..2597116dbf4 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -1,5 +1,5 @@
<!--
-$PostgreSQL: pgsql/doc/src/sgml/client-auth.sgml,v 1.65 2004/03/23 01:23:48 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/client-auth.sgml,v 1.66 2004/08/26 16:50:05 momjian Exp $
-->
<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
A record may have one of the seven formats
<synopsis>
local <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>authentication-method</replaceable> <optional><replaceable>authentication-option</replaceable></optional>
+host <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>CIDR-address</replaceable> <replaceable>authentication-method</replaceable> <optional><replaceable>authentication-option</replaceable></optional>
+hostssl <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>CIDR-address</replaceable> <replaceable>authentication-method</replaceable> <optional><replaceable>authentication-option</replaceable></optional>
+hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable> <replaceable>CIDR-address</replaceable> <replaceable>authentication-method</replaceable> <optional><replaceable>authentication-option</replaceable></optional>
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>
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>
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>
-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>
-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>
-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>
</synopsis>
The meaning of the fields is as follows:
@@ -196,19 +196,23 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
</varlistentry>
<varlistentry>
- <term><replaceable>IP-address</replaceable></term>
- <term><replaceable>IP-mask</replaceable></term>
+ <term><replaceable>CIDR-address</replaceable></term>
<listitem>
<para>
- These two fields contain IP address and mask values in standard
- dotted decimal notation. (IP addresses can only be specified
- numerically, not as domain or host names.) Taken together they
- specify the client machine IP addresses that this record
- matches. The precise logic is that
-<programlisting>
-(<replaceable>actual-IP-address</replaceable> xor <replaceable>IP-address-field</replaceable>) and <replaceable>IP-mask-field</replaceable>
-</programlisting>
- must be zero for the record to match.
+ specifies the client machine IP addresses that this record
+ matches. It contains an IP address in standard dotted decimal
+ notation and a CIDR mask length. (IP addresses can only be
+ specified numerically, not as domain or host names.) For example,
+ an IPv4 CIDR mask of 8 is equivalent to an IP mask of 255.0.0.0,
+ an IPv6 CIDR mask of 64 is equivalent to an IP mask of
+ ffff:ffff:ffff:ffff::. A IPv4 CIDR mask of 32 is used for single
+ hosts.
+ </para>
+
+ <para>
+ A typical CIDR address is <literal>172.20.143.89/32</literal>.
+ There should be no white space between the IP address, the
+ <literal>/</literal>, and the CIDR mask length.
</para>
<para>
@@ -229,26 +233,17 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
</varlistentry>
<varlistentry>
+ <term><replaceable>IP-address</replaceable></term>
<term><replaceable>IP-masklen</replaceable></term>
<listitem>
<para>
- This field may be used as an alternative to the
- <replaceable>IP-mask</replaceable> notation. It is an integer
- specifying the number of high-order bits to set in the mask.
- The number must be between 0 and 32 (in the case of an IPv4
- address) or 128 (in the case of an IPv6 address) inclusive. 0
- will match any address, while 32 (or 128, respectively) will
- match only the exact host specified. The same matching logic
- is used as for a dotted notation
- <replaceable>IP-mask</replaceable>.
- </para>
-
- <para>
- There must be no white space between the
- <replaceable>IP-address</replaceable> and the
- <literal>/</literal> or the <literal>/</literal> and the
- <replaceable>IP-masklen</replaceable>, or the file will not be
- parsed correctly.
+ This may be used as an alternative to the
+ <replaceable>CIDR-address</replaceable> notation. Instead of
+ specifying the mask length, the actual mask is specified in a
+ separate column. For example, 255.0.0.0 represents a IPv4 CIDR
+ mask length of 8, and 255.255.255.255 represents a CIDR mask
+ length of 32. The same matching logic is used as for a dotted
+ notation <replaceable>IP-mask</replaceable>.
</para>
<para>
@@ -458,36 +453,36 @@ hostnossl <replaceable>database</replaceable> <replaceable>user</replaceable>
# any user name using Unix-domain sockets (the default for local
# connections).
#
-# TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD
-local all all trust
+# TYPE DATABASE USER CIDR-ADDRESS METHOD
+local all all trust
# The same using local loopback TCP/IP connections.
#
-# TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD
-host all all 127.0.0.1 255.255.255.255 trust
+# TYPE DATABASE USER CIDR-ADDRESS METHOD
+host all all 127.0.0.1/32 trust
-# The same as the last line but using a CIDR mask
+# The same as the last line but using a separate netmask column
#
-# TYPE DATABASE USER IP-ADDRESS/CIDR-mask METHOD
-host all all 127.0.0.1/32 trust
+# TYPE DATABASE USER CIDR-ADDRESS METHOD
+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 user name that ident reports for
# the connection (typically the Unix user name).
#
-# TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD
-host template1 all 192.168.93.0 255.255.255.0 ident sameuser
+# TYPE DATABASE USER CIDR-ADDRESS METHOD
+host template1 all 192.168.93.0/24 ident sameuser
-# The same as the last line but using a CIDR mask
+# The same as the last line but using a separate netmask column
#
-# TYPE DATABASE USER IP-ADDRESS/CIDR-mask METHOD
-host template1 all 192.168.93.0/24 ident sameuser
+# TYPE DATABASE USER CIDR-ADDRESS METHOD
+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 IP-MASK METHOD
-host template1 all 192.168.12.10 255.255.255.255 md5
+# TYPE DATABASE USER CIDR-ADDRESS METHOD
+host template1 all 192.168.12.10/32 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
@@ -495,9 +490,9 @@ host template1 all 192.168.12.10 255.255.255.255 md5
# 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 IP-MASK METHOD
-host all all 192.168.54.1 255.255.255.255 reject
-host all all 0.0.0.0 0.0.0.0 krb5
+# TYPE DATABASE USER CIDR-ADDRESS METHOD
+host all all 192.168.54.1/32 reject
+host all all 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
@@ -505,8 +500,8 @@ host all all 0.0.0.0 0.0.0.0 krb5
# connection is allowed if there is an entry in pg_ident.conf for map
# "omicron" that says "bryanh" is allowed to connect as "guest1".
#
-# TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD
-host all all 192.168.0.0 255.255.0.0 ident omicron
+# TYPE DATABASE USER CIDR-ADDRESS METHOD
+host all all 192.168.0.0/16 ident omicron
# If these are the only three lines for local connections, they will
# 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
# $PGDATA/admins contains a list of user names. Passwords are required in
# all cases.
#
-# TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD
+# TYPE DATABASE USER CIDR-ADDRESS METHOD
local sameuser all md5
local all @admins md5
local all +support md5
@@ -959,3 +954,4 @@ FATAL: database "testdb" does not exist
</sect1>
</chapter>
+
diff --git a/src/backend/libpq/pg_hba.conf.sample b/src/backend/libpq/pg_hba.conf.sample
index 2f061b27b4e..b0d1895590f 100644
--- a/src/backend/libpq/pg_hba.conf.sample
+++ b/src/backend/libpq/pg_hba.conf.sample
@@ -28,11 +28,8 @@
#
# CIDR-ADDRESS specifies the set of hosts the record matches.
# It is made up of an IP address and a CIDR mask that is an integer
-# between 0 and 32 (IPv6) or 128(IPv6) inclusive, that specifies
-# the number of significant bits in the mask, e.g. an IPv4 CIDR mask
-# of 8 is equivalent to an IP mask of 255.0.0.0, an IPv6 CIDR mask
-# of 64 is equivalent to an IP mask of ffff:ffff:ffff:ffff::. A
-# IPv4 CIDR mask of 32 is used for single hosts. Also, you can use a
+# (between 0 and 32 (IPv6) or 128(IPv6) inclusive) that specifies
+# the number of significant bits in the mask Also, you can use a
# separate IP address and netmask to specify the set of hosts.
#
# METHOD can be "trust", "reject", "md5", "crypt", "password",
--
GitLab