The pool_hba.conf File
| pgpool-II 3.6.7 Documentation | |||
|---|---|---|---|
| Prev | Up | Chapter 6. Client Authentication | Next |
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