<!-- doc/src/sgml/client-auth.sgml -->

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

 <indexterm zone="client-authentication">
  <primary>client authentication</primary>
 </indexterm>

 <para>
  Since <productname>Pgpool-II</productname> is a middleware that works between
  <productname>PostgreSQL</> servers and a <productname>PostgreSQL</> database client, so when a client application
  connects to the <productname>Pgpool-II</productname>, <productname>Pgpool-II</productname>
  inturn connects to the <productname>PostgreSQL</> servers using the same credentials to serve the incomming
  client connection. Thus, all the access privileges and restrictions defined for the user in <productname>PostgreSQL</>
  gets automatically applied to all <productname>Pgpool-II</productname> clients, with an exceptions of
  the authentications on <productname>PostgreSQL</> side that depends on the client's IP addresses or hostnames.
  Reason being the connections to the <productname>PostgreSQL</> server are made by <productname>Pgpool-II</productname>
  on behalf of the connecting clients and <productname>PostgreSQL</> server can only see the IP address of the
  <productname>Pgpool-II</productname> server and not that of the actual client.
  Therefore, for the client host based authentications <productname>Pgpool-II</productname> has the
  <literal>pool_hba</literal> mechanism similar to the <literal>pg_hba</literal> mechanism for
  authenticating the incomming client connections.
-->
 </para>

 <sect1 id="auth-pool-hba-conf">
  <title>The <filename>pool_hba.conf</filename> File</title>

  <indexterm zone="auth-pool-hba-conf">
   <primary>pool_hba.conf</primary>
  </indexterm>

  <para>
  Just like the <filename>pg_hba.conf</filename> file for <productname>PostgreSQL</>,
  <productname>Pgpool-II</productname> supports a similar client authentication
  function using a configuration file called <filename>pool_hba.conf</filename>.
  <productname>Pgpool-II</productname> installation also includes the sample
  <filename>pool_hba.conf.sample</filename> file in the default configuration directory
  (<literal>"/usr/local/etc"</literal>).
  By default, pool_hba authentication is disabled, and setting <varname>enable_pool_hba</varname>
  to <literal>on</literal> enables it. see the <xref linkend="guc-enable-pool-hba"> configuration parameter.
  </para>

  <para>
   The format of the <filename>pool_hba.conf</filename> file follows very closely <productname>PostgreSQL</>'s <filename>pg_hba.conf</filename> format.

   The general format of the <filename>pool_hba.conf</filename> file is
   a set of records, one per line. Blank lines are ignored, as is any
   text after the <literal>#</literal> comment character.
   Records cannot be continued across lines.
   A record is made
   up of a number of fields which are separated by spaces and/or tabs.
   Fields can contain white space if the field value is double-quoted.
   Quoting one of the keywords in a database, user, or address field (e.g.,
   <literal>all</> or <literal>replication</>) makes the word lose its special
   meaning, and just match a database, user, or host with that name.
  </para>

  <para>
   Each record specifies a connection type, a client IP address range
   (if relevant for the connection type), a database name, a user name,
   and the authentication method to be used for connections matching
   these parameters. The first record with a matching connection type,
   client address, requested database, and user name is used to perform
   authentication. There is no <quote>fall-through</> or
   <quote>backup</>: if one record is chosen and the authentication
   fails, subsequent records are not considered. If no record matches,
   access is denied.
  </para>

  <para>
   A record can have one of the following formats
<synopsis>
local      <replaceable>database</replaceable>  <replaceable>user</replaceable>  <replaceable>auth-method</replaceable>  <optional><replaceable>auth-options</replaceable></optional>
host       <replaceable>database</replaceable>  <replaceable>user</replaceable>  <replaceable>CIDR-address</replaceable>  <replaceable>auth-method</replaceable>  <optional><replaceable>auth-options</replaceable></optional>
</synopsis>
   The meaning of the fields is as follows:

   <variablelist>
    <varlistentry>
     <term><literal>local</literal></term>
     <listitem>
      <para>
       This record matches connection attempts using Unix-domain
       sockets.  Without a record of this type, Unix-domain socket
       connections are disallowed.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>host</literal></term>
     <listitem>
      <para>
       This record matches connection attempts made using TCP/IP.
       <literal>host</literal> records match either
       <acronym>SSL</acronym> or non-<acronym>SSL</acronym> connection
       attempts.
      </para>
     <note>
      <para>
       Remote TCP/IP connections will not be possible unless
       the server is started with an appropriate value for the
       <xref linkend="guc-listen-addresses"> configuration parameter,
       since the default behavior is to listen for TCP/IP connections
       only on the local loopback address <literal>localhost</>.
      </para>
     </note>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><replaceable>database</replaceable></term>
     <listitem>
      <para>
       Specifies which database name(s) this record matches.  The value
       <literal>all</literal> specifies that it matches all databases.
      <note>
       <para>
       <literal>"samegroup"</literal> for database field is not supported:
       </para>
       <para>
        Since <productname>Pgpool-II</productname> does not know anything about
        users in the <productname>PostgreSQL</> backend server, the database name is simply
        compared against the entries in the databaseE field of <filename>pool_hba.conf</filename>.
       </para>
      </note>
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><replaceable>user</replaceable></term>
     <listitem>
      <para>
       Specifies which database user name(s) this record
       matches. The value <literal>all</literal> specifies that it
       matches all users.  Otherwise, this is the name of a specific
       database user
       <note>
       <para>
       group names following <literal>"+"</literal> for user field is not supported:
       </para>
       <para>
       This is for the same reason as for the <literal>"samegroup"</literal> of database field.
       A user name is simply checked against the entries in the user field of
       <filename>pool_hba.conf</filename>.
       </para>
      </note>
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><replaceable>address</replaceable></term>
     <listitem>
      <para>
       Specifies the client machine address(es) that this record matches.
       An IP address range is specified using standard numeric notation
       for the range's starting address, then a slash (<literal>/</literal>)
       and a <acronym>CIDR</> mask length.  The mask
       length indicates the number of high-order bits of the client
       IP address that must match.  Bits to the right of this should
       be zero in the given IP address.
       There must not be any white space between the IP address, the
       <literal>/</literal>, and the CIDR mask length.

       <note>
       <para>
       Pv6 IP address/mask is currently not supported
       </para>
       </note>
      </para>

      <para>
       This field only applies to <literal>host</literal> records.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><replaceable>auth-method</replaceable></term>
     <listitem>
      <para>
       Specifies the authentication method to use when a connection matches
       this record. The possible choices are summarized here; details
       are in <xref linkend="auth-methods">.

       <variablelist>
        <varlistentry>
         <term><literal>trust</></term>
         <listitem>
         <para>
          Allow the connection unconditionally. This method
          allows anyone that can connect to the
          <productname>Pgpool-II</productname>.
         </para>
        </listitem>
       </varlistentry>

       <varlistentry>
        <term><literal>reject</></term>
        <listitem>
         <para>
          Reject the connection unconditionally. This is useful for
          <quote>filtering out</> certain hosts, for example a
          <literal>reject</> line could block a specific host from connecting.
         </para>
        </listitem>
       </varlistentry>

       <varlistentry>
        <term><literal>md5</></term>
        <listitem>
         <para>
          Require the client to supply a double-MD5-hashed password for
          authentication.

        <note>
        <para>
         To use <literal>md5</literal> authentication, you need to register
         the user name and password in <filename>"pool_passwd"</filename>.
         See <xref linkend="auth-md5"> for more details.
         </para>
        </note>
         </para>
        </listitem>
       </varlistentry>

       <varlistentry>
        <term><literal>pam</></term>
        <listitem>
         <para>
          Authenticate using the Pluggable Authentication Modules
          (PAM) service provided by the operating system.
          See <xref linkend="auth-pam"> for details.
         </para>
         <para>
         PAM authentication is supported using user information on the host
         where <productname>Pgpool-II</productname> is running.
         To enable PAM support the <productname>Pgpool-II</productname>
         must be configured with <command>"--with-pam"</command>
         </para>
         <para>
         To enable PAM authentication, you must create a service-configuration file
         for <productname>Pgpool-II</productname> in the system's PAM configuration
         directory (that is usually located at <literal>"/etc/pam.d"</literal>).
         A sample service-configuration file is also installed as <literal>"share/pgpool.pam"</literal>
         under the install directory.
         </para>
        </listitem>
       </varlistentry>
      </variablelist>

      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><replaceable>auth-options</replaceable></term>
     <listitem>
      <para>
       After the <replaceable>auth-method</> field, there can be field(s) of
       the form <replaceable>name</><literal>=</><replaceable>value</> that
       specify options for the authentication method.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>

  <para>
   Since the <filename>pool_hba.conf</filename> records are examined
   sequentially for each connection attempt, the order of the records is
   significant. Typically, earlier records will have tight connection
   match parameters and weaker authentication methods, while later
   records will have looser match parameters and stronger authentication
   methods. For example, one might wish to use <literal>trust</>
   authentication for local TCP/IP connections but require a password for
   remote TCP/IP connections. In this case a record specifying
   <literal>trust</> authentication for connections from 127.0.0.1 would
   appear before a record specifying password authentication for a wider
   range of allowed client IP addresses.
  </para>

  <tip>
    <para>
        All pool_hba authentication options described in this section are
        about the authentication taking place between a client and the
        <productname>Pgpool-II</productname>.
        A client still has to go through the <productname>PostgreSQL</>'s authentication
        process and must have the <literal>CONNECT</> privilege for the
        database on the backend <productname>PostgreSQL</> server.
    </para>
    <para>
        As far as pool_hba is concerned, it does not matter if a user name
        and/or database name given by a client
        (i.e. <command>psql -U testuser testdb</command>)
        really exists in the backend. pool_hba only cares if a match in the
        <filename>pool_hba.conf</filename> can be found or not.
    </para>
  </tip>

  <para>
   Some examples of <filename>pool_hba.conf</filename> entries.
   See the next section for details on the different authentication methods.
  </para>

   <example id="example-pg-hba.conf">
    <title>Example <filename>pool_hba.conf</filename> Entries</title>
<programlisting>
# Allow any user on the local system to connect to any database with
# any database user name using Unix-domain sockets (the default for local
# connections).
#
# TYPE  DATABASE        USER            ADDRESS                 METHOD
local   all             all                                     trust

# The same using local loopback TCP/IP connections.
#
# TYPE  DATABASE        USER            ADDRESS                 METHOD
host    all             all             127.0.0.1/32            trust

# Allow any user from host 192.168.12.10 to connect to database
# "postgres" if the user's password is correctly supplied.
#
# TYPE  DATABASE        USER            ADDRESS                 METHOD
host    postgres        all             192.168.12.10/32        md5
</programlisting>
   </example>
 </sect1>

 <sect1 id="auth-methods">
  <title>Authentication Methods</title>
  <para>
   The following subsections describe the authentication methods in more detail.
  </para>

  <sect2 id="auth-trust">
   <title>Trust Authentication</title>

   <para>
    When <literal>trust</> authentication is specified,
    <productname>Pgpool-II</productname> assumes that anyone who can
    connect to the server is authorized to access connect with
    whatever database user name they specify.
   </para>
  </sect2>

  <sect2 id="auth-md5">
   <title>MD5 Password Authentication</title>

   <indexterm>
    <primary>MD5</>
   </indexterm>

   <para>
    This authentication method is the password-based authentication
    methods in which MD-5-hashed password is sent by client.
    Since <productname>Pgpool-II</productname> does not has the visibility
    of <productname>PostgreSQL</>'s database user password and client application only sends
    the MD5-hash of the password, so <literal>md5</literal> authentication
    in <productname>Pgpool-II</productname> is supported using the
    <xref linkend="guc-pool-passwd"> authentication file.
   </para>

    <sect3 id="md5-authentication-file-format">
    <title>Authentication file format</title>

    <para>
        This <literal>pool_passwd</literal> file should contain lines in the following format:
    <programlisting>
        "username:encrypted_passwd"
    </programlisting>
    </para>
    </sect3>

    <sect3 id="setting-md5-authentication">
    <title>Setting md5 Authentication</title>
    <indexterm zone="setting-md5-authentication">
        <primary>MD5</primary>
    </indexterm>

    <para>
        here are the steps to enable <literal>md5</literal> authentication:
    </para>
    <para>
        1- Login as the database's operating system user and type
        <command>"pg_md5 --md5auth --username= "</command>
        user name and <literal>md5</literal> encrypted password are registered
        into pool_passwd.
        If pool_passwd does not exist yet, pg_md5 command will automatically create it for you.
        <note>
        <para>
        user name and password must be identical to those registered in <productname>PostgreSQL</> server
        </para>
        </note>
    </para>

    <para>
        2- Add an appropriate md5 entry to <filename>pool_hba.conf</filename>.
        See <xref linkend="auth-pool-hba-conf"> for more details.
    </para>
    <para>
        3- After changing md5 password(in both pool_passwd and <productname>PostgreSQL</> of course),
        reload the pgpool configurations.
    </para>
    </sect3>

  </sect2>

  <sect2 id="auth-pam">
   <title>PAM Authentication</title>

   <indexterm zone="auth-pam">
    <primary>PAM</primary>
   </indexterm>

   <para>
    This authentication method uses PAM (Pluggable
    Authentication Modules) as the authentication mechanism. The
    default PAM service name is <literal>pgpool</literal>.
    PAM authentication is supported using user information on
    the host where <productname>Pgpool-II</productname> is executed.
    For more
    information about PAM, please read the
    <ulink url="http://www.kernel.org/pub/linux/libs/pam/">
    <productname>Linux-PAM</> Page</ulink>.
   </para>

   <para>
    To enable PAM authentication, you need to create a service-configuration
    file for <productname>Pgpool-II</productname> in the system's
    PAM configuration directory (which is usually at <literal>"/etc/pam.d"</literal>).
    A sample service-configuration file is installed as
    <filename>"share/pgpool.pam"</filename> under the install directory.
   </para>

   <note>
    <para>
     To enable PAM support the <productname>Pgpool-II</productname>
     must be configured with <command>"--with-pam"</command>
    </para>
   </note>
  </sect2>
 </sect1>

 </chapter>
