The pg_hba.conf file contains records that defines the authentication methods and options PostgreSQL should use during client authentication process. The authentication process is designed to be customized to your system needs.

With the pg_hba.conf file you can specify that a user connecting from a specific TCP/IP address is authorized to access a certain database. You can also give access to PostgreSQL for those who are on your local network access. You can define any combination of these methods through the adding of a record to the pg_hba.conf file. The pg_hba.conf file maintains the following syntax structure.

  • You may only place on host record per line in the file.

  • Host records are not allowed to wrap to multiple lines.

    Example 6-3. An invalid pg_hba.conf host record

    host         all         127.0.0.1
                 255.255.255.255     trust
    

  • You may comment the file. Commenting is done by placing a hash mark (#) at the beginning of each line being commented.

    Example 6-4. A valid pg_hba.conf comment

    #
    # Acme customer entries
    #
    

  • Each record will contain multiple fields. The quantity of fields is directly related to the type of host entry. The fields may be separated by tabs or spaces .

    Example 6-5. Valid pg_hba.conf entry with spaces

    host all 127.0.0.1 255.255.255.255 trust
    

    Example 6-6. A valid pg_hba.conf entry with tabs

    host    all    127.0.0.1    255.255.255.255    trust
    

There are three types of entries available in the pg_hba.conf:

  1. local -- A local entry is semantically the same as a host entry. However, you do not need to specify a host that is allowed to connect. The local pg_hba.conf entry is used for client connections that are initated from the same machine that the PostgreSQL server is operating on.

    Example 6-7. The local pg_hba.conf entry syntax.

    local database authentication-method [authentication-option]
    

  2. host -- A host entry is used to specify remote hosts that are allowed to connect to the PostgreSQL server. PostgreSQL must be running with the -i option (TCP/IP) in order for a host entry to work correctly.

    Example 6-8. The host pg_hba.conf entry syntax.

    host database IP-address IP-mask authentication method [auth - opt]
    

  3. hostssl -- A hostssl entry is user to specify hosts (remote or local) that are allowed to connect to the PostgreSQL server using SSL. The use of SSL insures that all communication between the client and the server is encrypted. In order for this to work, both the client and the server must support SSL. The PostgreSQL server must also be running with the -l (SSL) and -i (TCP/IP) options.

    Example 6-9. The hostssl pg_hba.conf entry syntax.

    hostssl database IP-address IP-mask authentication method [authentication-option]
    

Note Single line entries only
 

Remember that each entry in the pg_hba.conf must be a single line. You can not word wrap or use line breaks.

The following is a description of the keywords for the pg_hba.conf entries mentioned previously.

database

The is the database name that the client is allowed to connect to. The database keyword has three options associated with it.

all

The all keyword specifies that the client connecting can connect to any database the PostgreSQL server is hosting.

sameuser

The sameuser keyword specifies that the client can only connect to the database that matches the clients authenticated user name.

name

The name keyword specifies that the client can only connect to the database as specified by name .

IP address, IP mask

The two fields IP Address and IP mask specify either a specific IP or range of IP that are allowed to connect to the PostgreSQL server. The range is used by specifying an IP network with an associated mask.

authentication method

The authentication method specifies the type of authentication the server should use for a user trying to connect to PostgreSQL. The following is a list of options avaialble:

trust

The trust condition allows a user to connect to the PostgreSQL database without the use of a password. You are trusting the host based authentication with the use of this method.

reject

The reject condition automatically denies access to PostgreSQL for that host or user.

password

The password condition specifies that a password should exist for this user. The use of this method will require the PostgreSQL user to supply a password that matches the password found in the pg_shadow table. If you use the password method, the password will be sent in clear text.

crypt

The crypt condition is similar to the password method. However, when using crypt the password is not sent in clear text. The use of this method is not very secure but is better than using the clear text password method.
Warning Password and Crypt
 

We do not suggest the use of either of these methods without the use of an external encryption mechanism. There are sections later in this chapter that cover installing a central encryption mechansim for all of the PostgreSQL traffic.

krb4

The krb4 condition is used to specify version 4 of the Kerberos authentication system.

krb5

The krb5 condition is used to specify version 5 of the Kerberos authentication system.
Note Kerberos
 

The installation and configuration of Kerberos is beyond the scope of this book.

ident

The ident condition specifies that an ident map should be used when a host is requesting connections from a valid IP address listed in the pg_hba.conf file. For more information on the use of ident please see the ident section.

The ident condition has one option. This option specifies the name of the ident map that will be used in conjunction with the ident condition. The ident map is a text file. For more information on defining an ident map, see the section on the pg_ident.conf file.

authentication option

An optional field based on the type of authentication that is used. Please refer to the specific type of authentication you are using to determine whether or not this is required.