2 $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.49 2003/06/11 14:07:00 tgl Exp $
5 <chapter id="client-authentication">
6 <title>Client Authentication</title>
8 <indexterm zone="client-authentication">
9 <primary>client authentication</primary>
13 When a client application connects to the database server, it
14 specifies which <productname>PostgreSQL</productname> user name it
15 wants to connect as, much the same way one logs into a Unix computer
16 as a particular user. Within the SQL environment the active database
17 user name determines access privileges to database objects -- see
18 <xref linkend="user-manag"> for more information. Therefore, it is
19 essential to restrict which database users can connect.
23 <firstterm>Authentication</firstterm> is the process by which the
24 database server establishes the identity of the client, and by
25 extension determines whether the client application (or the user
26 who runs the client application) is permitted to connect with the
27 user name that was requested.
31 <productname>PostgreSQL</productname> offers a number of different
32 client authentication methods. The method used to authenticate a
33 particular client connection can be selected on the basis of
34 (client) host address, database, and user.
38 <productname>PostgreSQL</productname> user names are logically
39 separate from user names of the operating system in which the server
40 runs. If all the users of a particular server also have accounts on
41 the server's machine, it makes sense to assign database user names
42 that match their operating system user names. However, a server that
43 accepts remote connections may have many database users who have no local operating system
44 account, and in such cases there need be no connection between
45 database user names and OS user names.
48 <sect1 id="auth-pg-hba-conf">
49 <title>The <filename>pg_hba.conf</filename> file</title>
51 <indexterm zone="auth-pg-hba-conf">
52 <primary>pg_hba.conf</primary>
56 Client authentication is controlled by the file
57 <filename>pg_hba.conf</filename> in the data directory, e.g.,
58 <filename>/usr/local/pgsql/data/pg_hba.conf</filename>.
59 (<acronym>HBA</> stands for host-based authentication.) A default
60 <filename>pg_hba.conf</filename> file is installed when the data
61 directory is initialized by <command>initdb</command>.
65 The general format of the <filename>pg_hba.conf</filename> file is
66 a set of records, one per line. Blank lines are ignored, as is any
67 text after the <literal>#</literal> comment character. A record is made
68 up of a number of fields which are separated by spaces and/or tabs.
69 Fields can contain white space if the field value is quoted. Records
70 cannot be continued across lines.
74 Each record specifies a connection type, a client IP address range
75 (if relevant for the connection type), a database name, a user name,
76 and the authentication method to be used for connections matching
77 these parameters. The first record with a matching connection type,
78 client address, requested database, and user name is used to perform
79 authentication. There is no <quote>fall-through</> or
80 <quote>backup</>: if one record is chosen and the authentication
81 fails, subsequent records are not considered. If no record matches,
86 A record may have one of the three formats
88 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>IP-address</replaceable> <replaceable>IP-mask</replaceable> <replaceable>authentication-method</replaceable> <optional><replaceable>authentication-option</replaceable></optional>
90 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>
92 The meaning of the fields is as follows:
96 <term><literal>local</literal></term>
99 This record matches connection attempts using Unix-domain
100 sockets. Without a record of this type, Unix-domain socket
101 connections are disallowed
107 <term><literal>host</literal></term>
110 This record matches connection attempts using TCP/IP networks.
111 Note that TCP/IP connections are disabled unless the server is
112 started with the <option>-i</option> option or the
113 <varname>tcpip_socket</> configuration parameter is enabled.
119 <term><literal>hostssl</literal></term>
122 This record matches connection attempts using SSL over TCP/IP.
123 <literal>host</literal> records will match either SSL or
124 non-SSL connection attempts, but <literal>hostssl</literal>
125 records require SSL connections.
129 To be able make use of this option the server must be built
130 with SSL support enabled. Furthermore, SSL must be enabled by
131 enabling the <varname>ssl</varname> configuration parameter
132 (see <xref linkend="runtime-config"> for more information).
138 <term><replaceable>database</replaceable></term>
141 Specifies which databases this record matches. The value
142 <literal>all</literal> specifies that it matches all databases.
143 The value <literal>sameuser</> specifies that the record
144 matches if the requested database has the same name as the
145 requested user. The value <literal>samegroup</> specifies that
146 the requested user must a member of the group with the same
147 name as the requested database. Otherwise, this is the name of
148 a specific <productname>PostgreSQL</productname> database.
149 Multiple database names can be supplied by separating them with
150 commas. A file containing database names can be specified by
151 preceding the file name with <literal>@</>. The file must be in
152 the same directory as <filename>pg_hba.conf</>.
158 <term><replaceable>user</replaceable></term>
161 Specifies which <productname>PostgreSQL</> users this record
162 matches. The value <literal>all</literal> specifies that it
163 matches all users. Otherwise, this is the name of a specific
164 <productname>PostgreSQL</productname> user. Multiple user names
165 can be supplied by separating them with commas. Group names can
166 be specified by preceding the group name with <literal>+</>. A
167 file containing user names can be specified by preceding the
168 file name with <literal>@</>. The file must be in the same
169 directory as <filename>pg_hba.conf</>.
175 <term><replaceable>IP-address</replaceable></term>
176 <term><replaceable>IP-mask</replaceable></term>
179 These two fields contain IP address/mask values in standard
180 dotted decimal notation. (IP addresses can only be specified
181 numerically, not as domain or host names.) Taken together they
182 specify the client machine IP addresses that this record
183 matches. The precise logic is that
185 (<replaceable>actual-IP-address</replaceable> xor <replaceable>IP-address-field</replaceable>) and <replaceable>IP-mask-field</replaceable>
187 must be zero for the record to match. (Of course IP addresses
188 can be spoofed but this consideration is beyond the scope of
189 <productname>PostgreSQL</productname>.) If you machine supports
190 IPv6, the default <filename>pg_hba.conf</> file will have an
191 IPv6 entry for <literal>localhost</>. You can add your own IPv6
192 entries to the file. IPv6 entries are used only for IPv6
197 These fields only apply to <literal>host</literal> and
198 <literal>hostssl</literal> records.
204 <term><replaceable>authentication-method</replaceable></term>
207 Specifies the authentication method to use when connecting via
208 this record. The possible choices are summarized here; details
209 are in <xref linkend="auth-methods">.
213 <term><literal>trust</></term>
216 The connection is allowed unconditionally. This method
217 allows anyone that can connect to the
218 <productname>PostgreSQL</productname> database server to login as
219 any <productname>PostgreSQL</productname> user they like,
220 without the need for a password. See <xref
221 linkend="auth-trust"> for details.
227 <term><literal>reject</></term>
230 The connection is rejected unconditionally. This is useful for
231 <quote>filtering out</> certain hosts from a group.
237 <term><literal>md5</></term>
240 Requires the client to supply an MD5 encrypted password for
241 authentication. This is the only method that allows encrypted
242 passwords to be stored in <structname>pg_shadow</structname>.
243 See <xref linkend="auth-password"> for details.
249 <term><literal>crypt</></term>
252 Like the <literal>md5</literal> method but uses older <function>crypt()</>
253 encryption, which is needed for pre-7.2 clients.
254 <literal>md5</literal> is preferred for 7.2 and later clients.
255 See <xref linkend="auth-password"> for details.
261 <term><literal>password</></term>
264 Same as <literal>md5</>, but the password is sent in clear text over the
265 network. This should not be used on untrusted networks.
266 See <xref linkend="auth-password"> for details.
272 <term><literal>krb4</></term>
275 Kerberos V4 is used to authenticate the user. This is only
276 available for TCP/IP connections. See <xref
277 linkend="kerberos-auth"> for details.
283 <term><literal>krb5</></term>
286 Kerberos V5 is used to authenticate the user. This is only
287 available for TCP/IP connections. See <xref
288 linkend="kerberos-auth"> for details.
294 <term><literal>ident</></term>
297 Obtain the operating system user name of the client (for
298 TCP/IP connections by contacting the ident server on the
299 client, for local connections by getting it from the
300 operating system) and check if the user is allowed to
301 connect as the requested database user by consulting the map
302 specified after the <literal>ident</literal> key word.
306 If you use the map <literal>sameuser</literal>, the user
307 names are required to be identical. If not, the map name is
308 looked up in the file <filename>pg_ident.conf</filename>
309 in the same directory as <filename>pg_hba.conf</filename>.
310 The connection is accepted if that file contains an
311 entry for this map name with the operating-system user name
312 and the requested <productname>PostgreSQL</productname> user
317 For local connections, this only works on machines that
318 support Unix-domain socket credentials (currently
319 <systemitem class=osname>Linux</>, <systemitem
320 class=osname>FreeBSD</>, <systemitem class=osname>NetBSD</>,
321 <systemitem class=osname>OpenBSD</>, and
322 <systemitem class=osname>BSD/OS</>).
326 See <xref linkend="auth-ident"> below for details.
332 <term><literal>pam</></term>
335 Authenticate using the Pluggable Authentication Modules
336 (PAM) service provided by the operating system. See <xref
337 linkend="auth-pam"> for details.
348 <term><replaceable>authentication-option</replaceable></term>
351 The meaning of this optional field depends on the chosen
352 authentication method and is described in the next section.
360 Since the <filename>pg_hba.conf</filename> records are examined
361 sequentially for each connection attempt, the order of the records is
362 significant. Typically, earlier records will have tight connection
363 match parameters and weaker authentication methods, while later
364 records will have looser match parameters and stronger authentication
365 methods. For example, one might wish to use <literal>trust</>
366 authentication for local TCP/IP connections but require a password for
367 remote TCP/IP connections. In this case a record specifying
368 <literal>trust</> authentication for connections from 127.0.0.1 would
369 appear before a record specifying password authentication for a wider
370 range of allowed client IP addresses.
375 Do not prevent the superuser from accessing the <literal>template1</literal>
376 database. Various utility commands need access to <literal>template1</literal>.
381 The <filename>pg_hba.conf</filename> file is read on start-up and when
382 the main server process (<command>postmaster</>) receives a
383 <systemitem>SIGHUP</systemitem><indexterm><primary>SIGHUP</primary></indexterm>
384 signal. If you edit the file on an
385 active system, you will need to signal the <command>postmaster</>
386 (using <literal>pg_ctl reload</> or <literal>kill -HUP</>) to make it
391 An example of a <filename>pg_hba.conf</filename> file is shown in
392 <xref linkend="example-pg-hba.conf">. See the next section for details on the
393 different authentication methods.
396 <example id="example-pg-hba.conf">
397 <title>An example <filename>pg_hba.conf</filename> file</title>
399 # Allow any user on the local system to connect to any database under
400 # any user name using Unix-domain sockets (the default for local
403 # TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD
406 # The same using local loopback TCP/IP connections.
408 # TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD
409 host all all 127.0.0.1 255.255.255.255 trust
411 # Allow any user from any host with IP address 192.168.93.x to connect
412 # to database "template1" as the same user name that ident reports for
413 # the connection (typically the Unix user name).
415 # TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD
416 host template1 all 192.168.93.0 255.255.255.0 ident sameuser
418 # Allow a user from host 192.168.12.10 to connect to database
419 # "template1" if the user's password is correctly supplied.
421 # TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD
422 host template1 all 192.168.12.10 255.255.255.255 md5
424 # In the absence of preceding "host" lines, these two lines will
425 # reject all connection from 192.168.54.1 (since that entry will be
426 # matched first), but allow Kerberos V connections from anywhere else
427 # on the Internet. The zero mask means that no bits of the host IP
428 # address are considered so it matches any host.
430 # TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD
431 host all all 192.168.54.1 255.255.255.255 reject
432 host all all 0.0.0.0 0.0.0.0 krb5
434 # Allow users from 192.168.x.x hosts to connect to any database, if
435 # they pass the ident check. If, for example, ident says the user is
436 # "bryanh" and he requests to connect as PostgreSQL user "guest1", the
437 # connection is allowed if there is an entry in pg_ident.conf for map
438 # "omicron" that says "bryanh" is allowed to connect as "guest1".
440 # TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD
441 host all all 192.168.0.0 255.255.0.0 ident omicron
443 # If these are the only three lines for local connections, they will
444 # allow local users to connect only to their own databases (databases
445 # with the same name as their user name) except for administrators and
446 # members of group "support" who may connect to all databases. The file
447 # $PGDATA/admins contains a list of user names. Passwords are required in
450 # TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD
451 local sameuser all md5
452 local all @admins md5
453 local all +support md5
455 # The last two lines above can be combined into a single line:
456 local all @admins,+support md5
458 # The database column can also use lists and file names, but not groups:
459 local db1,db2,@demodbs all md5
464 <sect1 id="auth-methods">
465 <title>Authentication methods</title>
467 The following describes the authentication methods in more detail.
470 <sect2 id="auth-trust">
471 <title>Trust authentication</title>
474 When <literal>trust</> authentication is specified,
475 <productname>PostgreSQL</productname> assumes that anyone who can
476 connect to the server is authorized to access the database as
477 whatever database user he specifies (including the database superuser).
478 This method should only be used when there is adequate operating system-level
479 protection on connections to the server.
483 <literal>trust</> authentication is appropriate and very
484 convenient for local connections on a single-user workstation. It
485 is usually <emphasis>not</> appropriate by itself on a multiuser
486 machine. However, you may be able to use <literal>trust</> even
487 on a multiuser machine, if you restrict access to the server's
488 Unix-domain socket file using file-system permissions. To do this, set the
489 <varname>unix_socket_permissions</varname> (and possibly
490 <varname>unix_socket_group</varname>) configuration parameters as
491 described in <xref linkend="runtime-config-general">. Or you
492 could set the <varname>unix_socket_directory</varname>
493 configuration parameter to place the socket file in a suitably
494 restricted directory.
498 Setting file-system permissions only helps for Unix-socket connections.
499 Local TCP/IP connections are not restricted by it; therefore, if you want
500 to use file-system permissions for local security, remove the <literal>host ...
501 127.0.0.1 ...</> line from <filename>pg_hba.conf</>, or change it to a
502 non-<literal>trust</> authentication method.
506 <literal>trust</> authentication is only suitable for TCP/IP connections
507 if you trust every user on every machine that is allowed to connect
508 to the server by the <filename>pg_hba.conf</> lines that specify
509 <literal>trust</>. It is seldom reasonable to use <literal>trust</>
510 for any TCP/IP connections other than those from <systemitem>localhost</> (127.0.0.1).
515 <sect2 id="auth-password">
516 <title>Password authentication</title>
525 <primary>password</primary>
529 The password-based authentication methods are <literal>md5</>,
530 <literal>crypt</>, and <literal>password</>. These methods operate
531 similarly except for the way that the password is sent across the
532 connection. If you are at all concerned about password
533 <quote>sniffing</> attacks then <literal>md5</> is preferred, with
534 <literal>crypt</> a second choice if you must support pre-7.2
535 clients. Plain <literal>password</> should especially be avoided for
536 connections over the open Internet (unless you use SSL, SSH, or
537 other communications security wrappers around the connection).
541 <productname>PostgreSQL</productname> database passwords are
542 separate from operating system user passwords. The password for
543 each database user is stored in the <literal>pg_shadow</> system
544 catalog table. Passwords can be managed with the SQL
545 commands <command>CREATE USER</command> and <command>ALTER
546 USER</command>, e.g., <userinput>CREATE USER foo WITH PASSWORD
547 'secret';</userinput>. By default, that is, if no password has
548 been set up, the stored password is null and
549 password authentication will always fail for that user.
553 To restrict the set of users that are allowed to connect to
554 certain databases, list the users in the <replaceable>user</>
555 column of <filename>pg_hba.conf</filename>, as explained in the
561 <sect2 id="kerberos-auth">
562 <title>Kerberos authentication</title>
564 <indexterm zone="kerberos-auth">
565 <primary>Kerberos</primary>
569 <productname>Kerberos</productname> is an industry-standard secure
570 authentication system suitable for distributed computing over a
571 public network. A description of the
572 <productname>Kerberos</productname> system is far beyond the scope
573 of this document; in all generality it can be quite complex (yet
574 powerful). The <ulink
575 url="http://www.nrl.navy.mil/CCS/people/kenh/kerberos-faq.html">Kerberos
576 <acronym>FAQ</></ulink> or <ulink
577 url="ftp://athena-dist.mit.edu">MIT Project Athena</ulink> can be
578 a good starting point for exploration. Several sources for
579 <productname>Kerberos</> distributions exist.
583 In order to use <productname>Kerberos</>, support for it must be
584 enabled at build time. See <xref linkend="installation"> for more
585 information. Both Kerberos 4 and 5 are supported, but only one
586 version can be supported in any one build.
590 <productname>PostgreSQL</> operates like a normal Kerberos service.
591 The name of the service principal is
592 <literal><replaceable>servicename</>/<replaceable>hostname</>@<replaceable>realm</></literal>, where
593 <replaceable>servicename</> is <literal>postgres</literal> (unless a
594 different service name was selected at configure time with
595 <literal>./configure --with-krb-srvnam=whatever</>).
596 <replaceable>hostname</> is the fully qualified host name of the
597 server machine. The service principal's realm is the preferred realm
598 of the server machine.
602 Client principals must have their <productname>PostgreSQL</> user
603 name as their first component, for example
604 <literal>pgusername/otherstuff@realm</>. At present the realm of
605 the client is not checked by <productname>PostgreSQL</>; so if you
606 have cross-realm authentication enabled, then any principal in any
607 realm that can communicate with yours will be accepted.
611 Make sure that your server key file is readable (and preferably only
612 readable) by the <productname>PostgreSQL</productname> server
613 account. (See also <xref linkend="postgres-user">). The location of the
614 key file is specified with the <varname>krb_server_keyfile</> run-time
615 configuration parameter. (See also <xref
616 linkend="runtime-config">.) The default is <filename>/etc/srvtab</>
617 if you are using Kerberos 4 and
618 <filename>FILE:/usr/local/pgsql/etc/krb5.keytab</> (or whichever
619 directory was specified as <varname>sysconfdir</> at build time)
624 To generate the keytab file, use for example (with version 5)
626 <prompt>kadmin% </><userinput>ank -randkey postgres/server.my.domain.org</>
627 <prompt>kadmin% </><userinput>ktadd -k krb5.keytab postgres/server.my.domain.org</>
629 Read the <productname>Kerberos</> documentation for details.
633 When connecting to the database make sure you have a ticket for a
634 principal matching the requested database user name. An example: For
635 database user name <literal>fred</>, both principal
636 <literal>fred@EXAMPLE.COM</> and
637 <literal>fred/users.example.com@EXAMPLE.COM</> can be used to
638 authenticate to the database server.
642 <ulink url="http://www.kernel.org/pub/linux/libs/pam/"><productname>Linux-PAM</></ulink>
645 If you use <application>mod_auth_kerb</application> from
646 <ulink url="http://modauthkerb.sf.net">http://modauthkerb.sf.net</ulink>
647 and <application>mod_perl</application> on your
648 <productname>Apache</productname> web server, you can use
649 <literal>AuthType KerberosV5SaveCredentials</literal> with a
650 <application>mod_perl</application> script. This gives secure
651 database access over the web, no extra passwords required.
656 <sect2 id="auth-ident">
657 <title>Ident-based authentication</title>
660 <primary>ident</primary>
664 The ident authentication method works by inspecting the client's
665 operating system user name and determining the allowed database
666 user names by using a map file that lists the permitted
667 corresponding user name pairs. The determination of the client's
668 user name is the security-critical point, and it works differently
669 depending on the connection type.
673 <title>Ident Authentication over TCP/IP</title>
676 The <quote>Identification Protocol</quote> is described in
677 <citetitle>RFC 1413</citetitle>. Virtually every Unix-like
678 operating system ships with an ident server that listens on TCP
679 port 113 by default. The basic functionality of an ident server
680 is to answer questions like <quote>What user initiated the
681 connection that goes out of your port <replaceable>X</replaceable>
682 and connects to my port <replaceable>Y</replaceable>?</quote>.
683 Since <productname>PostgreSQL</> knows both <replaceable>X</> and
684 <replaceable>Y</> when a physical connection is established, it
685 can interrogate the ident server on the host of the connecting
686 client and could theoretically determine the operating system user
687 for any given connection this way.
691 The drawback of this procedure is that it depends on the integrity
692 of the client: if the client machine is untrusted or compromised
693 an attacker could run just about any program on port 113 and
694 return any user name he chooses. This authentication method is
695 therefore only appropriate for closed networks where each client
696 machine is under tight control and where the database and system
697 administrators operate in close contact. In other words, you must
698 trust the machine running the ident server.
701 <attribution>RFC 1413</attribution>
703 The Identification Protocol is not intended as an authorization
704 or access control protocol.
711 <title>Ident Authentication over Local Sockets</title>
714 On systems supporting <symbol>SO_PEERCRED</symbol> requests for
715 Unix-domain sockets (currently <systemitem
716 class="osname">Linux</>, <systemitem class="osname">FreeBSD</>,
717 <systemitem class="osname">NetBSD</>, <systemitem class=osname>OpenBSD</>,
718 and <systemitem class="osname">BSD/OS</>), ident authentication can also
719 be applied to local connections. In this case, no security risk is added by
720 using ident authentication; indeed it is a preferable choice for
721 local connections on such systems.
725 On systems without <symbol>SO_PEERCRED</> requests, ident
726 authentication is only available for TCP/IP connections. As a
727 work around, it is possible to specify the <systemitem
728 class="systemname">localhost</> address <systemitem
729 class="systemname">127.0.0.1</> and make connections to this
735 <title>Ident Maps</title>
738 When using ident-based authentication, after having determined the
739 name of the operating system user that initiated the connection,
740 <productname>PostgreSQL</productname> checks whether that user is
741 allowed to connect as the database user he is requesting to connect
742 as. This is controlled by the ident map argument that follows the
743 <literal>ident</> key word in the <filename>pg_hba.conf</filename>
744 file. There is a predefined ident map <literal>sameuser</literal>,
745 which allows any operating system user to connect as the database
746 user of the same name (if the latter exists). Other maps must be
752 other than <literal>sameuser</literal> are defined in the file
753 <filename>pg_ident.conf</filename><indexterm><primary>pg_ident.conf</primary></indexterm>
754 in the data directory, which contains lines of the general form:
756 <replaceable>map-name</> <replaceable>ident-username</> <replaceable>database-username</>
758 Comments and whitespace are handled in the usual way. The
759 <replaceable>map-name</> is an arbitrary name that will be used to
760 refer to this mapping in <filename>pg_hba.conf</filename>. The other
761 two fields specify which operating system user is allowed to connect
762 as which database user. The same <replaceable>map-name</> can be
763 used repeatedly to specify more user-mappings within a single map.
764 There is no restriction regarding how many database users a given
765 operating system user may correspond to and vice versa.
769 The <filename>pg_ident.conf</filename> file is read on start-up and
770 when the main server process (<command>postmaster</>) receives a
771 <systemitem>SIGHUP</systemitem><indexterm><primary>SIGHUP</primary></indexterm>
772 signal. If you edit the file on an
773 active system, you will need to signal the <command>postmaster</>
774 (using <literal>pg_ctl reload</> or <literal>kill -HUP</>) to make it
779 A <filename>pg_ident.conf</filename> file that could be used in
780 conjunction with the <filename>pg_hba.conf</> file in <xref
781 linkend="example-pg-hba.conf"> is shown in <xref
782 linkend="example-pg-ident.conf">. In this example setup, anyone
783 logged in to a machine on the 192.168 network that does not have the
784 Unix user name <literal>bryanh</>, <literal>ann</>, or
785 <literal>robert</> would not be granted access. Unix user
786 <literal>robert</> would only be allowed access when he tries to
787 connect as <productname>PostgreSQL</> user <literal>bob</>, not
788 as <literal>robert</> or anyone else. <literal>ann</> would
789 only be allowed to connect as <literal>ann</>. User
790 <literal>bryanh</> would be allowed to connect as either
791 <literal>bryanh</> himself or as <literal>guest1</>.
794 <example id="example-pg-ident.conf">
795 <title>An example <filename>pg_ident.conf</> file</title>
797 # MAPNAME IDENT-USERNAME PG-USERNAME
799 omicron bryanh bryanh
801 # bob has user name robert on these machines
803 # bryanh can also connect as guest1
804 omicron bryanh guest1
810 <sect2 id="auth-pam">
811 <title>PAM Authentication</title>
814 This authentication method operates similarly to
815 <literal>password</literal> except that it uses PAM (Pluggable
816 Authentication Modules) as the authentication mechanism. The
817 default PAM service name is <literal>postgresql</literal>. You can
818 optionally supply you own service name after the <literal>pam</>
819 key word in the file <filename>pg_hba.conf</filename>. For more information about PAM, please read
821 url="http://www.kernel.org/pub/linux/libs/pam/"><productname>Linux-PAM</>
822 Page</ulink> and the <ulink
823 url="http://www.sun.com/software/solaris/pam/"><systemitem
824 class="osname">Solaris</> PAM Page</ulink>.
829 <sect1 id="client-authentication-problems">
830 <title>Authentication problems</title>
833 Genuine authentication failures and related problems generally
834 manifest themselves through error messages like the following.
839 No pg_hba.conf entry for host 123.123.123.123, user andym, database testdb
841 This is what you are most likely to get if you succeed in contacting
842 the server, but it does not want to talk to you. As the message
843 suggests, the server refused the connection request because it found
844 no authorizing entry in its <filename>pg_hba.conf</filename>
850 Password authentication failed for user 'andym'
852 Messages like this indicate that you contacted the server, and it is
853 willing to talk to you, but not until you pass the authorization
854 method specified in the <filename>pg_hba.conf</filename> file. Check
855 the password you are providing, or check your Kerberos or ident
856 software if the complaint mentions one of those authentication
862 FATAL 1: user "andym" does not exist
864 The indicated user name was not found.
869 FATAL 1: Database "testdb" does not exist in the system catalog.
871 The database you are trying to connect to does not exist. Note that
872 if you do not specify a database name, it defaults to the database
873 user name, which may or may not be the right thing.
877 Note that the server log may contain more information about an
878 authentication failure than is reported to the client. If you are
879 confused about the reason for a failure, check the log.