The pool_hba.conf File

pgpool-II 3.6.5 Documentation
Prev | Up | Chapter 6. Client Authentication | Next

# 6.1. The `pool_hba.conf` File

Just like the `pg_hba.conf` file for PostgreSQL, Pgpool-II supports a similar client authentication function using a configuration file called `pool_hba.conf`. Pgpool-II installation also includes the sample `pool_hba.conf.sample` file in the default configuration directory (`"/usr/local/etc"`). By default, pool_hba authentication is disabled, and setting `enable_pool_hba` to `on` enables it. see the enable_pool_hba configuration parameter.

The format of the `pool_hba.conf` file follows very closely PostgreSQL's `pg_hba.conf` format. The general format of the `pool_hba.conf` file is a set of records, one per line. Blank lines are ignored, as is any text after the `#` 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., `all` or `replication`) makes the word lose its special meaning, and just match a database, user, or host with that name.

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 "fall-through" or "backup": if one record is chosen and the authentication fails, subsequent records are not considered. If no record matches, access is denied.

A record can have one of the following formats

    local      database  user  auth-method  [auth-options]
    host       database  user  CIDR-address  auth-method  [auth-options]

The meaning of the fields is as follows:

`local`

  This record matches connection attempts using Unix-domain sockets. Without a record of this type, Unix-domain socket connections are disallowed.

`host`

  This record matches connection attempts made using TCP/IP. `host` records match either SSL or non-SSL connection attempts.

  > Note: Remote TCP/IP connections will not be possible unless the server is started with an appropriate value for the listen_addresses configuration parameter, since the default behavior is to listen for TCP/IP connections only on the local loopback address `localhost`.

`database`

  Specifies which database name(s) this record matches. The value `all` specifies that it matches all databases.

  > Note: `"samegroup"` for database field is not supported:

  > Since Pgpool-II does not know anything about users in the PostgreSQL backend server, the database name is simply compared against the entries in the databaseE field of `pool_hba.conf`.

`user`

  Specifies which database user name(s) this record matches. The value `all` specifies that it matches all users. Otherwise, this is the name of a specific database user

  > Note: group names following `"+"` for user field is not supported:

  > This is for the same reason as for the `"samegroup"` of database field. A user name is simply checked against the entries in the user field of `pool_hba.conf`.

`address`

  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 (`/`) and a 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 `/`, and the CIDR mask length.

  > Note: Pv6 IP address/mask is currently not supported

  This field only applies to `host` records.

`auth-method`

  Specifies the authentication method to use when a connection matches this record. The possible choices are summarized here; details are in Section 6.2.

  `trust`

    Allow the connection unconditionally. This method allows anyone that can connect to the Pgpool-II.

  `reject`

    Reject the connection unconditionally. This is useful for "filtering out" certain hosts, for example a `reject` line could block a specific host from connecting.

  `md5`

    Require the client to supply a double-MD5-hashed password for authentication.

    > Note: To use `md5` authentication, you need to register the user name and password in `"pool_passwd"`. See Section 6.2.2 for more details.

  `pam`

    Authenticate using the Pluggable Authentication Modules (PAM) service provided by the operating system. See Section 6.2.3 for details.

    PAM authentication is supported using user information on the host where Pgpool-II is running. To enable PAM support the Pgpool-II must be configured with `"--with-pam"`

    To enable PAM authentication, you must create a service-configuration file for Pgpool-II in the system's PAM configuration directory (that is usually located at `"/etc/pam.d"`). A sample service-configuration file is also installed as `"share/pgpool.pam"` under the install directory.

`auth-options`

  After the `auth-method` field, there can be field(s) of the form `name``=``value` that specify options for the authentication method.

Since the `pool_hba.conf` 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 `trust` authentication for local TCP/IP connections but require a password for remote TCP/IP connections. In this case a record specifying `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.

> Tip: All pool_hba authentication options described in this section are about the authentication taking place between a client and the Pgpool-II. A client still has to go through the PostgreSQL's authentication process and must have the `CONNECT` privilege for the database on the backend PostgreSQL server.

> 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. `psql -U testuser testdb`) really exists in the backend. pool_hba only cares if a match in the `pool_hba.conf` can be found or not.

Some examples of `pool_hba.conf` entries. See the next section for details on the different authentication methods.

Example 6-1. Example `pool_hba.conf` Entries

    # 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

Prev | Home | Next
Client Authentication | Up | Authentication Methods