Skip to content

Commit c1257d4

Browse files
tglsfdctglsfdc
committed
Improve comments in pg_hba.conf.sample and the associated SGML
documentation.
1 parent 280a77d commit c1257d4

File tree

2 files changed

+179
-132
lines changed

2 files changed

+179
-132
lines changed

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

Lines changed: 85 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,24 @@
1-
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.8 2000/10/21 01:08:34 petere Exp $ -->
1+
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.9 2000/11/21 20:44:31 tgl Exp $ -->
22

33
<chapter id="client-authentication">
44
<title>Client Authentication</title>
55

66
<para>
7-
User names from the operating system and from a
8-
<productname>Postgres</productname> database installation are
9-
logically separate. When a client application connects, it specifies
10-
which database user name it wants to connect as, similar to how one
11-
logs into a Unix computer. Within the SQL environment the active
12-
database user name determines various access privileges to database
7+
When a client application connects to the database server, it specifies which
8+
<productname>Postgres</productname> user name it wants to connect as,
9+
much the same way one logs into a Unix computer as a particular user.
10+
Within the SQL environment the active
11+
database user name determines access privileges to database
1312
objects -- see <xref linkend="user-manag"> for more information
14-
about that. It is therefore obviously essential to restrict what
15-
database user name a given client can connect as.
13+
about that. It is therefore obviously essential to restrict which
14+
database user name(s) a given client can connect as.
1615
</para>
1716

1817
<para>
1918
<firstterm>Authentication</firstterm> is the process by which the
2019
database server establishes the identity of the client, and by
2120
extension determines whether the client application (or the user
22-
which runs the client application) is permitted to connect with the
21+
who runs the client application) is permitted to connect with the
2322
user name that was requested.
2423
</para>
2524

@@ -29,14 +28,26 @@
2928
authentication methods available.
3029
</para>
3130

31+
<para>
32+
<productname>Postgres</productname> database user names are logically
33+
separate from user names of the operating system in which the server
34+
runs. If all the users of a particular server also have accounts on
35+
the server's machine, it makes sense to assign database user names
36+
that match their Unix user ids. However, a server that accepts remote
37+
connections may have many users who have no local account, and in such
38+
cases there need be no connection between database usernames and Unix
39+
usernames.
40+
</para>
41+
3242
<sect1 id="pg-hba.conf">
3343
<title>The <filename>pg_hba.conf</filename> file</title>
3444

3545
<para>
3646
Client authentication is controlled by the file
37-
<filename>pg_hba.conf</filename> in the data directory, e.g.,
38-
<filename>/usr/local/pgsql/data/pg_hba.conf</filename>. (HBA =
39-
host-based authentication) A default file is installed when the
47+
<filename>pg_hba.conf</filename> in the $PGDATA directory, e.g.,
48+
<filename>/usr/local/pgsql/data/pg_hba.conf</filename>. (HBA stands
49+
for host-based authentication.) A default <filename>pg_hba.conf</filename>
50+
file is installed when the
4051
data area is initialized by <application>initdb</application>.
4152
</para>
4253

@@ -84,7 +95,7 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
8495
<term><literal>hostssl</literal></term>
8596
<listitem>
8697
<para>
87-
This record pertains to connection attemps with SSL over
98+
This record pertains to connection attempts with SSL over
8899
TCP/IP. To make use of this option the server must be
89100
built with SSL support enabled. Furthermore, SSL must be
90101
enabled with the <option>-l</> option or equivalent configuration
@@ -99,8 +110,10 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
99110
<para>
100111
Specifies the database that this record applies to. The value
101112
<literal>all</literal> specifies that it applies to all
102-
databases, the value <literal>sameuser</> identifies the
103-
database with the same name as the connecting user.
113+
databases, while the value <literal>sameuser</> identifies the
114+
database with the same name as the connecting user. Otherwise,
115+
this is the name of a specific <productname>Postgres</productname>
116+
database.
104117
</para>
105118
</listitem>
106119
</varlistentry>
@@ -140,7 +153,7 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
140153
<para>
141154
The connection is allowed unconditionally. This method allows
142155
any user that has login access to the client host to connect as
143-
any user whatsoever.
156+
any <productname>Postgres</productname> user whatsoever.
144157
</para>
145158
</listitem>
146159
</varlistentry>
@@ -246,17 +259,18 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
246259
</varlistentry>
247260
</variablelist>
248261

249-
The first record that matches a connection attempt is used. There
250-
is no <quote>fall-through</> or <quote>backup</>, that means, if
262+
The first record that matches a connection attempt's client IP address
263+
and requested database name is used to do the authentication step.
264+
There is no <quote>fall-through</> or <quote>backup</>: if
251265
one record is chosen and the
252266
authentication fails, the following records are not considered. If
253267
no record matches, the access will be denied.
254268
</para>
255269

256270
<para>
257-
The <filename>pg_hba.conf</filename> file is re-read before each
258-
connection attempt. It is therefore easily possible to modify
259-
access permissions while the server is running.
271+
The <filename>pg_hba.conf</filename> file is re-read during each
272+
connection attempt. It is therefore trivial to modify access
273+
permissions while the server is running: just edit the file.
260274
</para>
261275

262276
<para>
@@ -267,42 +281,44 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
267281
<example id="example-pg-hba.conf">
268282
<title>An example <filename>pg_hba.conf</filename> file</title>
269283
<programlisting>
270-
#TYPE DATABASE IP-ADDRESS MASK AUTHTYPE ARG
271-
272-
# Allow any user on the local system to connect to any database under
273-
# any user name.
274-
#
275-
host all 127.0.0.1 255.255.255.255 trust
276-
277-
# Allow any user from any host with IP address 192.168.93.x to connect
278-
# to database "template1" as the same user name that ident on that
279-
# host identifies him as (typically his Unix user name).
280-
#
281-
host template1 192.168.93.0 255.255.255.0 ident sameuser
282-
283-
# Allow a user from host 192.168.12.10 to connect to database
284-
# "template1" if the user's password in pg_shadow is supplied.
285-
#
286-
host template1 192.168.12.10 255.255.255.255 crypt
287-
288-
# In absence of the other records, this would allow anyone anywhere
289-
# except from 192.168.54.1 to connect to any database under any user
290-
# name.
291-
#
292-
host all 192.168.54.1 255.255.255.255 reject
293-
host all 0.0.0.0 0.0.0.0 trust
294-
295-
# Allow users from 192.168.77.x hosts to connect to any database, but if,
296-
# for example, ident says the user is "bryanh" and he requests to
297-
# connect as PostgreSQL user "guest1", the connection is only allowed if
298-
# there is an entry for map "omicron" in `pg_ident.conf' that says
299-
# "bryanh" is allowed to connect as "guest1".
300-
#
301-
host all 192.168.77.0 255.255.255.0 ident omicron
302-
303-
# Allow all users to connect to all databases via Unix sockets.
304-
#
305-
local all trust
284+
# TYPE DATABASE IP_ADDRESS MASK AUTHTYPE MAP
285+
286+
# Allow any user on the local system to connect to any
287+
# database under any username, but only via an IP connection:
288+
289+
host all 127.0.0.1 255.255.255.255 trust
290+
291+
# The same, over Unix-socket connections:
292+
293+
local all trust
294+
295+
# Allow any user from any host with IP address 192.168.93.x to
296+
# connect to database "template1" as the same username that ident on that
297+
# host identifies him as (typically his Unix username):
298+
299+
host template1 192.168.93.0 255.255.255.0 ident sameuser
300+
301+
# Allow a user from host 192.168.12.10 to connect to database "template1"
302+
# if the user's password in pg_shadow is correctly supplied:
303+
304+
host template1 192.168.12.10 255.255.255.255 crypt
305+
306+
# In the absence of preceding "host" lines, these two lines will reject
307+
# all connection attempts from 192.168.54.1 (since that entry will be
308+
# matched first), but allow Kerberos V5-validated connections from anywhere
309+
# else on the Internet. The zero mask means that no bits of the host IP
310+
# address are considered, so it matches any host:
311+
312+
host all 192.168.54.1 255.255.255.255 reject
313+
host all 0.0.0.0 0.0.0.0 krb5
314+
315+
# Allow users from 192.168.x.x hosts to connect to any database, if they
316+
# pass the ident check. If, for example, ident says the user is "bryanh"
317+
# and he requests to connect as PostgreSQL user "guest1", the connection
318+
# is allowed if there is an entry in pg_ident.conf for map "omicron" that
319+
# says "bryanh" is allowed to connect as "guest1":
320+
321+
host all 192.168.0.0 255.255.0.0 ident omicron
306322
</programlisting>
307323
</example>
308324
</para>
@@ -324,7 +340,7 @@ local all trust
324340
<command>CREATE USER</command> and <command>ALTER USER</command>,
325341
e.g., <userinput>CREATE USER foo WITH PASSWORD
326342
'secret';</userinput>. By default, that is, if no password has
327-
explicitly been set up, the stored password is <quote>NULL</quote>
343+
been set up, the stored password is <literal>NULL</literal>
328344
and password authentication will always fail for that user.
329345
</para>
330346

@@ -336,12 +352,12 @@ local all trust
336352
file after the <literal>password</> or <literal>crypt</> keyword,
337353
respectively, in <filename>pg_hba.conf</>. If you do not use this
338354
feature, then any user that is known to the database system can
339-
connect to any database (as long as he passes password
355+
connect to any database (so long as he passes password
340356
authentication, of course).
341357
</para>
342358

343359
<para>
344-
These files can also be used a apply a different set of passwords
360+
These files can also be used to apply a different set of passwords
345361
to a particular database or set thereof. In that case, the files
346362
have a format similar to the standard Unix password file
347363
<filename>/etc/passwd</filename>, that is,
@@ -401,7 +417,7 @@ local all trust
401417

402418
<para>
403419
In order to use <productname>Kerberos</>, support for it must be
404-
enable at build time. Both Kerberos 4 and 5 are supported
420+
enabled at build time. Both Kerberos 4 and 5 are supported
405421
(<literal>./configure --with-krb4</> or <literal>./configure
406422
--with-krb5</> respectively).
407423
</para>
@@ -411,7 +427,7 @@ local all trust
411427
service. The name of the service principal is normally
412428
<literal>postgres</literal>, unless it was changed during the
413429
build. Make sure that your server key file is readable (and
414-
preferrably only readable) by the Postgres server account (see
430+
preferably only readable) by the Postgres server account (see
415431
<xref linkend="postgres-user">). The location of the key file
416432
is specified with the <varname>krb_server_keyfile</> run time
417433
configuration parameter. (See also <xref linkend="runtime-config">.)
@@ -553,13 +569,13 @@ local all trust
553569
A <filename>pg_ident.conf</filename> file that could be used in
554570
conjunction with the <filename>pg_hba.conf</> file in <xref
555571
linkend="example-pg-hba.conf"> is shown in <xref
556-
linkend="example-pg-ident.conf">. In that example setup, anyone
557-
logged in to a machine on the 192.168.77 network that does not have
558-
the a user name bryanh, ann, or robert would not be granted access.
572+
linkend="example-pg-ident.conf">. In this example setup, anyone
573+
logged in to a machine on the 192.168 network that does not have
574+
the Unix user name bryanh, ann, or robert would not be granted access.
559575
Unix user robert would only be allowed access when he tries to
560-
connect as <quote>bob</quote>, not as <quote>robert</quote> or
561-
anyone else. <quote>ann</quote> would only be allowed to connect
562-
<quote>as herself</>. User bryanh would be allowed to connect as either
576+
connect as Postgres user <quote>bob</quote>, not as <quote>robert</quote>
577+
or anyone else. <quote>ann</quote> would only be allowed to connect as
578+
<quote>ann</>. User bryanh would be allowed to connect as either
563579
<quote>bryanh</> himself or as <quote>guest1</>.
564580
</para>
565581

0 commit comments

Comments
 (0)