description: 版本：11

20.1. 設定檔：pg_hba.conf

用戶端身份驗證由組態檔案控制，組態檔案通常名稱為 pg_hba.conf，並儲存在資料庫叢集的資料目錄中。 （HBA 代表 host-based authentication。）當 initdb 初始化資料目錄時，將安裝預設的 pg_hba.conf 檔案。但是，可以將身份驗證組態檔案放在其他路徑；請參閱 hba_file 組態參數。

pg_hba.conf 檔案的一般格式是一組記錄，每行一個。空白行將被忽略，# comment 字元後面的任何文字都將被忽略。記錄不能跨行。記錄由許多段落組成，這些段落由空格或 tab 分隔。如果段落的值用了雙引號，則段落可以包含空格。在資料庫，使用者或位址段落（例如，all 或 replication）中括起其中一個關鍵字會使該字失去其特殊含義，並且只是將資料庫，使用者或主機與該名稱相匹配。

每條記錄指定連線類型，用戶端 IP 位址範圍（如果與連線類型相關）、資料庫名稱、使用者名稱以及符合這些參數的連線身份驗證方法。具有符合的連線類型、用戶端位址、要求的資料庫和使用者名稱的第一個記錄用於執行身份驗證。沒有“fall-through”或“replication”：如果選擇了一條記錄而認證失敗，就不再考慮後續記錄。如果沒有記錄匹配，則拒絕存取。

記錄可以是下面的七種格式之一

  1. local      database  user  auth-method  [auth-options]
  2. host       database  user  address  auth-method  [auth-options]
  3. hostssl    database  user  address  auth-method  [auth-options]
  4. hostnossl  database  user  address  auth-method  [auth-options]
  5. host       database  user  IP-address  IP-mask  auth-method  [auth-options]
  6. hostssl    database  user  IP-address  IP-mask  auth-method  [auth-options]
  7. hostnossl  database  user  IP-address  IP-mask  auth-method  [auth-options]

段落的含義如下：

local

此記錄搭配使用 Unix-domain socket 的連線嘗試。如果沒有此類型的記錄，則不允許使用 Unix-domain socket 連線。

host

此記錄用於使用 TCP/IP 進行的連線嘗試。主機記錄使用 SSL 或非 SSL 連線嘗試.

重要
除非使用 listen_addresses 組態參數的適當值啟動伺服器，否則將無法進行遠端 TCP/IP 連線，因為預設行為是僅在 localhost 上監聽 TCP/IP 連線。

hostssl

此記錄會套用於使用 TCP/IP 進行的連線嘗試，但僅限於使用 SSL 加密進行連線時。

要使用此選項，必須以 SSL 建置伺服器，也必須透過設定 ssl 組態參數來啟用 SSL（有關更多訊息，請參閱第 18.9 節）。否則，將會忽略 hostssl 記錄，除非是為了記錄不能與任何連線相符合的警告。

hostnossl

此記錄類型與 hostssl 具有相反的行為；它僅套用於透過 TCP/IP 且不使用 SSL 的連線嘗試。

database

指定此記錄所要求搭配的資料庫名稱。值 all 使其搭配所有資料庫。如果請求的資料庫與請求的使用者具有相同的名稱，則可以用 sameuser 值來指定。值 samerole 指定所請求的使用者必須是與請求的資料庫同名的角色成員。 （ samegroup 是一個過時但仍然被接受的 samerole 別名。）超級使用者不被認為是同一角色的成員，除非他們直接或間接地明確地成為角色的成員，而不僅僅是作為超級使用者。值 replication 指定在請求 physical replication 連線時的記錄搭配（請注意，複寫連線不指定任何特定資料庫）。否則，這是特定 PostgreSQL 資料庫的名稱。可以透過用逗號分隔它們來設定多個資料庫名稱，也可以透過在檔案名稱前加上 @ 來指定包含資料庫名稱的額外檔案。

user

Specifies which database user name(s) this record matches. The value all specifies that it matches all users. Otherwise, this is either the name of a specific database user, or a group name preceded by +. (Recall that there is no real distinction between users and groups in PostgreSQL; a + mark really means “match any of the roles that are directly or indirectly members of this role”, while a name without a + mark matches only that specific role.) For this purpose, a superuser is only considered to be a member of a role if they are explicitly a member of the role, directly or indirectly, and not just by virtue of being a superuser. Multiple user names can be supplied by separating them with commas. A separate file containing user names can be specified by preceding the file name with @.

address

Specifies the client machine address(es) that this record matches. This field can contain either a host name, an IP address range, or one of the special key words mentioned below.

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.

Typical examples of an IPv4 address range specified this way are 172.20.143.89/32 for a single host, or 172.20.143.0/24 for a small network, or 10.6.0.0/16 for a larger one. An IPv6 address range might look like ::1/128 for a single host (in this case the IPv6 loopback address) or fe80::7a31:c1ff:0000:0000/96 for a small network. 0.0.0.0/0 represents all IPv4 addresses, and ::0/0 represents all IPv6 addresses. To specify a single host, use a mask length of 32 for IPv4 or 128 for IPv6. In a network address, do not omit trailing zeroes.

An entry given in IPv4 format will match only IPv4 connections, and an entry given in IPv6 format will match only IPv6 connections, even if the represented address is in the IPv4-in-IPv6 range. Note that entries in IPv6 format will be rejected if the system’s C library does not have support for IPv6 addresses.

You can also write all to match any IP address, samehost to match any of the server’s own IP addresses, or samenet to match any address in any subnet that the server is directly connected to.

If a host name is specified (anything that is not an IP address range or a special key word is treated as a host name), that name is compared with the result of a reverse name resolution of the client’s IP address (e.g., reverse DNS lookup, if DNS is used). Host name comparisons are case insensitive. If there is a match, then a forward name resolution (e.g., forward DNS lookup) is performed on the host name to check whether any of the addresses it resolves to are equal to the client’s IP address. If both directions match, then the entry is considered to match. (The host name that is used in pg_hba.conf should be the one that address-to-name resolution of the client’s IP address returns, otherwise the line won’t be matched. Some host name databases allow associating an IP address with multiple host names, but the operating system will only return one host name when asked to resolve an IP address.)

A host name specification that starts with a dot (.) matches a suffix of the actual host name. So .example.com would match foo.example.com (but not just example.com).

When host names are specified in pg_hba.conf, you should make sure that name resolution is reasonably fast. It can be of advantage to set up a local name resolution cache such as nscd. Also, you may wish to enable the configuration parameter log_hostname to see the client’s host name instead of the IP address in the log.

This field only applies to host, hostssl, and hostnossl records.

Note

Users sometimes wonder why host names are handled in this seemingly complicated way, with two name resolutions including a reverse lookup of the client’s IP address. This complicates use of the feature in case the client’s reverse DNS entry is not set up or yields some undesirable host name. It is done primarily for efficiency: this way, a connection attempt requires at most two resolver lookups, one reverse and one forward. If there is a resolver problem with some address, it becomes only that client’s problem. A hypothetical alternative implementation that only did forward lookups would have to resolve every host name mentioned in pg_hba.conf during every connection attempt. That could be quite slow if many names are listed. And if there is a resolver problem with one of the host names, it becomes everyone’s problem.

Also, a reverse lookup is necessary to implement the suffix matching feature, because the actual client host name needs to be known in order to match it against the pattern.

Note that this behavior is consistent with other popular implementations of host name-based access control, such as the Apache HTTP Server and TCP Wrappers.

IP-address
IP-mask

These two fields can be used as an alternative to the IP-address/mask-length notation. Instead of specifying the mask length, the actual mask is specified in a separate column. For example, 255.0.0.0 represents an IPv4 CIDR mask length of 8, and 255.255.255.255represents a CIDR mask length of 32.

These fields only apply to host, hostssl, and hostnossl 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 20.3.

trust

Allow the connection unconditionally. This method allows anyone that can connect to the PostgreSQL database server to login as any PostgreSQL user they wish, without the need for a password or any other authentication. See Section 20.3.1 for details.

reject

Reject the connection unconditionally. This is useful for “filtering out” certain hosts from a group, for example a reject line could block a specific host from connecting, while a later line allows the remaining hosts in a specific network to connect.

scram-sha-256

Perform SCRAM-SHA-256 authentication to verify the user’s password. See Section 20.3.2 for details.

md5

Perform SCRAM-SHA-256 or MD5 authentication to verify the user’s password. See Section 20.3.2 for details.

password

Require the client to supply an unencrypted password for authentication. Since the password is sent in clear text over the network, this should not be used on untrusted networks. See Section 20.3.2 for details.

gss

Use GSSAPI to authenticate the user. This is only available for TCP/IP connections. See Section 20.3.3 for details.

sspi

Use SSPI to authenticate the user. This is only available on Windows. See Section 20.3.4 for details.

ident

Obtain the operating system user name of the client by contacting the ident server on the client and check if it matches the requested database user name. Ident authentication can only be used on TCP/IP connections. When specified for local connections, peer authentication will be used instead. See Section 20.3.5 for details.

peer

Obtain the client’s operating system user name from the operating system and check if it matches the requested database user name. This is only available for local connections. See Section 20.3.6 for details.

ldap

Authenticate using an LDAP server. See Section 20.3.7 for details.

radius

Authenticate using a RADIUS server. See Section 20.3.8 for details.

cert

Authenticate using SSL client certificates. See Section 20.3.9 for details.

pam

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

bsd

Authenticate using the BSD Authentication service provided by the operating system. See Section 20.3.11 for details.

auth-options

After the auth-method field, there can be field(s) of the form name=value that specify options for the authentication method. Details about which options are available for which authentication methods appear below.

In addition to the method-specific options listed below, there is one method-independent authentication option clientcert, which can be specified in any hostssl record. When set to 1, this option requires the client to present a valid (trusted) SSL certificate, in addition to the other requirements of the authentication method.

Files included by @ constructs are read as lists of names, which can be separated by either whitespace or commas. Comments are introduced by #, just as in pg_hba.conf, and nested @ constructs are allowed. Unless the file name following @ is an absolute path, it is taken to be relative to the directory containing the referencing file.

Since the pg_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.

The pg_hba.conf file is read on start-up and when the main server process receives a SIGHUP signal. If you edit the file on an active system, you will need to signal the postmaster (using pg_ctl reload or kill -HUP) to make it re-read the file.

Note

The preceding statement is not true on Microsoft Windows: there, any changes in the pg_hba.conf file are immediately applied by subsequent new connections.

The system view pg_hba_file_rules can be helpful for pre-testing changes to the pg_hba.conf file, or for diagnosing problems if loading of the file did not have the desired effects. Rows in the view with non-null error fields indicate problems in the corresponding lines of the file.

Tip

To connect to a particular database, a user must not only pass the pg_hba.conf checks, but must have the CONNECT privilege for the database. If you wish to restrict which users can connect to which databases, it’s usually easier to control this by granting/revoking CONNECTprivilege than to put the rules in pg_hba.conf entries.

Some examples of pg_hba.conf entries are shown in Example 20.1. See the next section for details on the different authentication methods.

Example 20.1. Example pg_hba.conf Entries

  1. # Allow any user on the local system to connect to any database with
  2. # any database user name using Unix-domain sockets (the default for local
  3. # connections).
  4. #
  5. # TYPE  DATABASE        USER            ADDRESS                 METHOD
  6. local   all             all                                     trust
  8. # The same using local loopback TCP/IP connections.
  9. #
  10. # TYPE  DATABASE        USER            ADDRESS                 METHOD
  11. host    all             all             127.0.0.1/32            trust
  13. # The same as the previous line, but using a separate netmask column
  14. #
  15. # TYPE  DATABASE        USER            IP-ADDRESS      IP-MASK             METHOD
  16. host    all             all             127.0.0.1       255.255.255.255     trust
  18. # The same over IPv6.
  19. #
  20. # TYPE  DATABASE        USER            ADDRESS                 METHOD
  21. host    all             all             ::1/128                 trust
  23. # The same using a host name (would typically cover both IPv4 and IPv6).
  24. #
  25. # TYPE  DATABASE        USER            ADDRESS                 METHOD
  26. host    all             all             localhost               trust
  28. # Allow any user from any host with IP address 192.168.93.x to connect
  29. # to database "postgres" as the same user name that ident reports for
  30. # the connection (typically the operating system user name).
  31. #
  32. # TYPE  DATABASE        USER            ADDRESS                 METHOD
  33. host    postgres        all             192.168.93.0/24         ident
  35. # Allow any user from host 192.168.12.10 to connect to database
  36. # "postgres" if the user's password is correctly supplied.
  37. #
  38. # TYPE  DATABASE        USER            ADDRESS                 METHOD
  39. host    postgres        all             192.168.12.10/32        scram-sha-256
  41. # Allow any user from hosts in the example.com domain to connect to
  42. # any database if the user's password is correctly supplied.
  43. #
  44. # Require SCRAM authentication for most users, but make an exception
  45. # for user 'mike', who uses an older client that doesn't support SCRAM
  46. # authentication.
  47. #
  48. # TYPE  DATABASE        USER            ADDRESS                 METHOD
  49. host    all             mike            .example.com            md5
  50. host    all             all             .example.com            scram-sha-256
  52. # In the absence of preceding "host" lines, these two lines will
  53. # reject all connections from 192.168.54.1 (since that entry will be
  54. # matched first), but allow GSSAPI connections from anywhere else
  55. # on the Internet.  The zero mask causes no bits of the host IP
  56. # address to be considered, so it matches any host.
  57. #
  58. # TYPE  DATABASE        USER            ADDRESS                 METHOD
  59. host    all             all             192.168.54.1/32         reject
  60. host    all             all             0.0.0.0/0               gss
  62. # Allow users from 192.168.x.x hosts to connect to any database, if
  63. # they pass the ident check.  If, for example, ident says the user is
  64. # "bryanh" and he requests to connect as PostgreSQL user "guest1", the
  65. # connection is allowed if there is an entry in pg_ident.conf for map
  66. # "omicron" that says "bryanh" is allowed to connect as "guest1".
  67. #
  68. # TYPE  DATABASE        USER            ADDRESS                 METHOD
  69. host    all             all             192.168.0.0/16          ident map=omicron
  71. # If these are the only three lines for local connections, they will
  72. # allow local users to connect only to their own databases (databases
  73. # with the same name as their database user name) except for administrators
  74. # and members of role "support", who can connect to all databases.  The file
  75. # $PGDATA/admins contains a list of names of administrators.  Passwords
  76. # are required in all cases.
  77. #
  78. # TYPE  DATABASE        USER            ADDRESS                 METHOD
  79. local   sameuser        all                                     md5
  80. local   all             @admins                                 md5
  81. local   all             +support                                md5
  83. # The last two lines above can be combined into a single line:
  84. local   all             @admins,+support                        md5
  86. # The database column can also use lists and file names:
  87. local   db1,db2,@demodbs  all                                   md5