1- <!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.22 2001/10/04 22:27:18 petere Exp $ -->
1+ <!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.23 2001/11/02 18:39:57 tgl Exp $ -->
22
33<chapter id="client-authentication">
44 <title>Client Authentication</title>
6767 tabs. Records cannot be continued across lines.
6868 </para>
6969
70+ <para>
71+ Each record specifies a connection type, a client IP address range
72+ (if relevant for the connection type), a database name or names,
73+ and the authentication method to be used for connections matching
74+ these parameters.
75+ The first record that matches the type, client address and requested
76+ database name of a connection attempt is used to do the
77+ authentication step. There is no <quote>fall-through</> or
78+ <quote>backup</>: if one record is chosen and the authentication
79+ fails, the following records are not considered. If no record
80+ matches, the access will be denied.
81+ </para>
82+
7083 <para>
7184 A record may have one of the three formats
7285 <synopsis>
@@ -107,7 +120,9 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
107120 TCP/IP. To make use of this option the server must be
108121 built with SSL support enabled. Furthermore, SSL must be
109122 enabled with the <option>-l</> option or equivalent configuration
110- setting when the server is started.
123+ setting when the server is started. (Note: <literal>host</literal>
124+ records will match either SSL or non-SSL connection attempts, but
125+ <literal>hostssl</literal> records match only SSL connections.)
111126 </para>
112127 </listitem>
113128 </varlistentry>
@@ -131,8 +146,9 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
131146 <term><replaceable>IP mask</replaceable></term>
132147 <listitem>
133148 <para>
134- These two fields control to which hosts a
135- <literal>host</literal> record applies, based on their IP
149+ These two fields specify to which client machines a
150+ <literal>host</literal> or <literal>hostssl</literal>
151+ record applies, based on their IP
136152 address. (Of course IP addresses can be spoofed but this
137153 consideration is beyond the scope of
138154 <productname>Postgres</productname>.) The precise logic is that
@@ -151,7 +167,8 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
151167 <listitem>
152168 <para>
153169 Specifies the method that users must use to authenticate themselves
154- when connecting to that database. The possible choices follow,
170+ when connecting under the control of this authentication record.
171+ The possible choices are summarized here,
155172 details are in <xref linkend="auth-methods">.
156173
157174 <variablelist>
@@ -322,17 +339,27 @@ hostssl <replaceable>database</replaceable> <replaceable>IP-address</replaceable
322339 </listitem>
323340 </varlistentry>
324341 </variablelist>
342+ </para>
325343
326- The first record that matches the client IP address and requested
327- database name of a connection attempt is used to do the
328- authentication step. There is no <quote>fall-through</> or
329- <quote>backup</>: if one record is chosen and the authentication
330- fails, the following records are not considered. If no record
331- matches, the access will be denied.
344+ <para>
345+ Since the <filename>pg_hba.conf</filename> records are examined
346+ sequentially for each connection attempt, order of the records is
347+ very significant. Typically, earlier records will have tight
348+ connection match parameters and weaker authentication methods,
349+ while later records will have looser match parameters and stronger
350+ authentication methods. For example, one might wish to use
351+ <literal>trust</> authentication for local TCP connections but
352+ require a password for remote TCP connections. In this case a
353+ record specifying <literal>trust</> authentication for connections
354+ from 127.0.0.1 would appear before a record specifying password
355+ authentication for a wider range of allowed client IP addresses.
332356 </para>
333357
334358 <para>
335- The <filename>pg_hba.conf</filename> file is loaded only on startup
359+ <indexterm>
360+ <primary>SIGHUP</primary>
361+ </indexterm>
362+ The <filename>pg_hba.conf</filename> file is read on startup
336363 and when the <application>postmaster</> receives a
337364 <systemitem>SIGHUP</systemitem> signal. If you edit the file on an
338365 active system, you will need to signal the <application>postmaster</>
@@ -632,15 +659,16 @@ host all 192.168.0.0 255.255.0.0 ident omicron
632659 to connect as the database user he is requesting to connect as.
633660 This is controlled by the ident map
634661 argument that follows the <literal>ident</> keyword in the
635- <filename>pg_hba.conf</filename> file.The simplest ident map is
662+ <filename>pg_hba.conf</filename> file.There is a predefined ident map
636663 <literal>sameuser</literal>, which allows any operating system
637664 user to connect as the database user of the same name (if the
638665 latter exists). Other maps must be created manually.
639666 </para>
640667
641668 <para>
642669 <indexterm><primary>pg_ident.conf</primary></indexterm>
643- Ident maps are held in the file <filename>pg_ident.conf</filename>
670+ Ident maps other than <literal>sameuser</literal> are defined
671+ in the file <filename>pg_ident.conf</filename>
644672 in the data directory, which contains lines of the general form:
645673<synopsis>
646674<replaceable>map-name</> <replaceable>ident-username</> <replaceable>database-username</>
@@ -657,6 +685,18 @@ host all 192.168.0.0 255.255.0.0 ident omicron
657685 versa.
658686 </para>
659687
688+ <para>
689+ <indexterm>
690+ <primary>SIGHUP</primary>
691+ </indexterm>
692+ The <filename>pg_ident.conf</filename> file is read on startup
693+ and when the <application>postmaster</> receives a
694+ <systemitem>SIGHUP</systemitem> signal. If you edit the file on an
695+ active system, you will need to signal the <application>postmaster</>
696+ (using <application>pg_ctl reload</> or <application>kill -HUP</>)
697+ to make it re-read the file.
698+ </para>
699+
660700 <para>
661701 A <filename>pg_ident.conf</filename> file that could be used in
662702 conjunction with the <filename>pg_hba.conf</> file in <xref