支援版本:目前版本 (17) / 16 / 15 / 14 / 13
開發版本:devel
不支援版本:12 / 11 / 10 / 9.6 / 9.5 / 9.4 / 9.3 / 9.2 / 9.1 / 9.0 / 8.4 / 8.3 / 8.2

20.1. pg_hba.conf 檔案 #

用戶端驗證由一個組態檔控制,該檔案傳統上被命名為 pg_hba.conf 並儲存在資料庫叢集的資料目錄中。(HBA代表基於主機的驗證。) 當使用 initdb 初始化資料目錄時,會安裝預設的 pg_hba.conf 檔案。 然而,可以將驗證組態檔放在其他地方;請參閱 hba_file 組態參數。

pg_hba.conf 檔案會在啟動時以及主伺服器程序接收到 SIGHUP 訊號時讀取。 如果您在活動系統上編輯該檔案,則需要向 postmaster 發送訊號 (使用 pg_ctl reload、呼叫 SQL 函數 pg_reload_conf() 或使用 kill -HUP) 以使其重新讀取該檔案。

注意

前面的陳述在 Microsoft Windows 上不成立:在該系統上,pg_hba.conf 檔案中的任何變更都會立即由後續的新連線套用。

系統檢視 pg_hba_file_rules 對於預先測試對 pg_hba.conf 檔案的變更,或在檔案載入未產生所需效果時診斷問題很有幫助。 檢視中具有非空 error 欄位的列表示檔案中對應的行存在問題。

pg_hba.conf 檔案的一般格式是一組記錄,每行一條。 空白行會被忽略,# 註解字元之後的任何文字也會被忽略。 一個記錄可以透過在行尾加上反斜線來繼續到下一行。(反斜線除了在行尾之外,沒有特殊意義。) 一個記錄由多個欄位組成,這些欄位由空格和/或 Tab 分隔。 如果欄位值用雙引號引起來,則欄位可以包含空白。 在資料庫、使用者或位址欄位中引用其中一個關鍵字 (例如,allreplication) 會使該詞失去其特殊含義,而僅比對具有該名稱的資料庫、使用者或主機。 反斜線行繼續適用於引號文字或註解中。

每個驗證記錄指定一個連線類型、一個用戶端 IP 位址範圍 (如果與連線類型相關)、一個資料庫名稱、一個使用者名稱,以及用於比對這些參數的連線的驗證方法。 具有比對的連線類型、用戶端位址、請求的資料庫和使用者名稱的第一個記錄用於執行驗證。 沒有fall-throughbackup:如果選擇了一個記錄並且驗證失敗,則不會考慮後續的記錄。 如果沒有記錄比對,則拒絕存取。

每個記錄都可以是一個包含指示詞或一個驗證記錄。 包含指示詞指定可以包含的檔案,其中包含其他記錄。 這些記錄將被插入到包含指示詞的位置。 包含指示詞僅包含兩個欄位:includeinclude_if_existsinclude_dir 指示詞以及要包含的檔案或目錄。 檔案或目錄可以是相對或絕對路徑,並且可以用雙引號引起來。 對於 include_dir 形式,所有不以 . 開頭並以 .conf 結尾的檔案都將被包含。 包含目錄中的多個檔案將按照檔案名稱順序處理 (根據 C 地區規則,即數字在字母之前,大寫字母在小寫字母之前)。

一個記錄可以有多種格式

local               database  user  auth-method [auth-options]
host                database  user  address     auth-method  [auth-options]
hostssl             database  user  address     auth-method  [auth-options]
hostnossl           database  user  address     auth-method  [auth-options]
hostgssenc          database  user  address     auth-method  [auth-options]
hostnogssenc        database  user  address     auth-method  [auth-options]
host                database  user  IP-address  IP-mask      auth-method  [auth-options]
hostssl             database  user  IP-address  IP-mask      auth-method  [auth-options]
hostnossl           database  user  IP-address  IP-mask      auth-method  [auth-options]
hostgssenc          database  user  IP-address  IP-mask      auth-method  [auth-options]
hostnogssenc        database  user  IP-address  IP-mask      auth-method  [auth-options]
include             file
include_if_exists   file
include_dir         directory

欄位的含義如下

local

此記錄比對使用 Unix 網域套接字的連線嘗試。 如果沒有此類型的記錄,則不允許 Unix 網域套接字連線。

host

此記錄比對使用 TCP/IP 進行的連線嘗試。 host 記錄比對SSL或非SSL連線嘗試以及GSSAPI加密或非GSSAPI加密連線嘗試。

注意

除非伺服器啟動時 listen_addresses 組態參數具有適當的值,否則遠端 TCP/IP 連線將無法進行,因為預設行為是僅在本地迴路位址 localhost 上監聽 TCP/IP 連線。

hostssl

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

要使用此選項,必須使用SSL支援來建置伺服器。 此外,SSL必須設定 ssl 組態參數啟用 (詳見 第 18.9 節 以取得更多資訊)。否則,hostssl 紀錄將被忽略,除了記錄一則警告訊息,指出它無法比對任何連線。

hostnossl

此紀錄類型與 hostssl 的行為相反;它僅比對透過 TCP/IP 進行且不使用SSL.

hostgssenc

此記錄比對使用 TCP/IP 進行的連線嘗試,但僅限於使用GSSAPI加密時。

要使用此選項,必須使用GSSAPI支援的連線嘗試。否則,hostgssenc 紀錄將被忽略,除了記錄一則警告訊息,指出它無法比對任何連線。

hostnogssenc

此紀錄類型與 hostgssenc 的行為相反;它僅比對透過 TCP/IP 進行且不使用GSSAPI加密時。

database

指定此紀錄比對的資料庫名稱。值 all 指定比對所有資料庫。值 sameuser 指定如果請求的資料庫與請求的使用者具有相同的名稱,則該紀錄比對。值 samerole 指定請求的使用者必須是與請求的資料庫具有相同名稱的角色成員。(samegroupsamerole 的過時但仍然可接受的拼寫。) 超級使用者不被視為 samerole 角色的成員,除非他們明確地直接或間接地成為該角色的成員,而不僅僅是因為他們是超級使用者。值 replication 指定如果請求實體複寫連線,則該紀錄比對,但是,它不比對邏輯複寫連線。請注意,實體複寫連線未指定任何特定的資料庫,而邏輯複寫連線則指定了它。否則,這是特定 PostgreSQL 資料庫的名稱或正規表示式。可以透過用逗號分隔來提供多個資料庫名稱和/或正規表示式。

如果資料庫名稱以斜線 (/) 開頭,則名稱的其餘部分將被視為正規表示式。(有關 PostgreSQL 正規表示式語法的詳細資訊,請參閱 第 9.7.3.1 節。)

可以透過在檔案名稱前面加上 @ 來指定包含資料庫名稱和/或正規表示式的單獨檔案。

user

指定此紀錄比對的資料庫使用者名稱。值 all 指定比對所有使用者。否則,這是一個特定的資料庫使用者的名稱、一個正規表示式 (當以斜線 (/) 開頭時),或一個以 + 開頭的群組名稱。(請記住,在 PostgreSQL 中,使用者和群組之間沒有真正的區別;+ 符號實際上意味著 比對直接或間接屬於此角色的任何角色,而沒有 + 符號的名稱僅比對該特定角色。) 就此而言,超級使用者僅在他們明確地直接或間接地成為該角色的成員時,才被視為該角色的成員,而不僅僅是因為他們是超級使用者。可以透過用逗號分隔來提供多個使用者名稱和/或正規表示式。

如果使用者名稱以斜線 (/) 開頭,則名稱的其餘部分將被視為正規表示式。(有關 PostgreSQL 正規表示式語法的詳細資訊,請參閱 第 9.7.3.1 節。)

可以透過在檔案名稱前面加上 @ 來指定包含使用者名稱和/或正規表示式的單獨檔案。

address

指定此紀錄比對的用戶端電腦位址。此欄位可以包含主機名稱、IP 位址範圍或下面提到的特殊關鍵字之一。

IP 位址範圍使用範圍起始位址的標準數字表示法指定,然後使用斜線 (/) 和CIDR遮罩長度。遮罩長度表示用戶端 IP 位址中必須比對的高位元數。給定的 IP 位址中,此位元右側的位元應為零。IP 位址、/ 和 CIDR 遮罩長度之間不得有任何空格。

以此方式指定的 IPv4 位址範圍的典型範例包括 172.20.143.89/32 (對於單個主機)、172.20.143.0/24 (對於小型網路) 或 10.6.0.0/16 (對於較大的網路)。IPv6 位址範圍可能看起來像 ::1/128 (對於單個主機,在本例中為 IPv6 迴路位址) 或 fe80::7a31:c1ff:0000:0000/96 (對於小型網路)。0.0.0.0/0 表示所有 IPv4 位址,而 ::0/0 表示所有 IPv6 位址。若要指定單個主機,請對 IPv4 使用 32 的遮罩長度,或對 IPv6 使用 128 的遮罩長度。在網路位址中,請勿省略尾隨零。

以 IPv4 格式給定的項目將僅比對 IPv4 連線,而以 IPv6 格式給定的項目將僅比對 IPv6 連線,即使表示的位址位於 IPv4-in-IPv6 範圍內也是如此。

您也可以寫入 all 來比對任何 IP 位址、samehost 來比對伺服器自己的任何 IP 位址,或 samenet 來比對伺服器直接連接的任何子網路中的任何位址。

如果指定了主機名稱 (任何不是 IP 位址範圍或特殊關鍵字的內容都會被視為主機名稱),則會將該名稱與用戶端 IP 位址的反向名稱解析結果進行比較 (例如,如果使用 DNS,則為反向 DNS 查詢)。主機名稱比較不區分大小寫。如果存在比對,則會對主機名稱執行正向名稱解析 (例如,正向 DNS 查詢),以檢查其解析到的任何位址是否等於用戶端的 IP 位址。如果兩個方向都比對,則該項目將被視為比對。(在 pg_hba.conf 中使用的主機名稱應為用戶端 IP 位址的位址到名稱解析所傳回的主機名稱,否則將不會比對該行。某些主機名稱資料庫允許將 IP 位址與多個主機名稱相關聯,但作業系統只會在要求解析 IP 位址時傳回一個主機名稱。)

以點 (.) 開頭的主機名稱規格比對實際主機名稱的字尾。因此,.example.com 將比對 foo.example.com (但不僅僅比對 example.com)。

當在 pg_hba.conf 中指定主機名稱時,您應確保名稱解析速度夠快。設定本機名稱解析快取(例如 nscd)可能會有所幫助。此外,您可能希望啟用組態參數 log_hostname,以便在日誌中看到用戶端的主機名稱,而不是 IP 位址。

這些欄位不適用於 local 紀錄。

注意

使用者有時會想知道為什麼主機名稱會以這種看似複雜的方式處理,包括兩次名稱解析,其中包含用戶端 IP 位址的反向查詢。如果用戶端的反向 DNS 紀錄未設定或產生一些不理想的主機名稱,這會使此功能的使用變得複雜。這樣做主要是為了效率:透過這種方式,連線嘗試最多只需要兩次解析器查詢,一次反向查詢和一次正向查詢。如果某個位址存在解析器問題,那麼這只會是該用戶端的問題。假設另一種只進行正向查詢的實作方式,則必須在每次連線嘗試期間解析 pg_hba.conf 中提到的每個主機名稱。如果列出了許多名稱,這可能會非常慢。而且如果其中一個主機名稱存在解析器問題,那麼這將成為每個人的問題。

此外,反向查詢是實作後綴匹配功能所必需的,因為需要知道實際的用戶端主機名稱才能將其與模式進行匹配。

請注意,這種行為與其他流行的基於主機名稱的存取控制實作(例如 Apache HTTP Server 和 TCP Wrappers)一致。

IP 位址
IP 遮罩

這兩個欄位可以用作 IP 位址/遮罩長度 標記法的替代方案。無需指定遮罩長度,而是在單獨的欄位中指定實際的遮罩。例如,255.0.0.0 代表 IPv4 CIDR 遮罩長度 8,而 255.255.255.255 代表 CIDR 遮罩長度 32。

這些欄位不適用於 local 紀錄。

auth-method (驗證方法)

指定連線符合此紀錄時要使用的驗證方法。此處總結了可能的選擇;詳細資訊請參閱 第 20.3 節。所有選項均為小寫,且區分大小寫,因此即使是像 ldap 這樣的縮寫也必須指定為小寫。

trust (信任)

無條件允許連線。此方法允許任何可以連線到 PostgreSQL 資料庫伺服器的人以他們想要的任何 PostgreSQL 使用者身分登入,而無需密碼或任何其他驗證。詳細資訊請參閱 第 20.4 節

reject (拒絕)

無條件拒絕連線。這對於從群組中過濾掉某些主機很有用,例如,reject 行可以阻止特定主機連線,而後面的行則允許特定網路中的其餘主機連線。

scram-sha-256

執行 SCRAM-SHA-256 驗證以驗證使用者的密碼。詳細資訊請參閱 第 20.5 節

md5

執行 SCRAM-SHA-256 或 MD5 驗證以驗證使用者的密碼。詳細資訊請參閱 第 20.5 節

password (密碼)

要求用戶端提供未加密的密碼以進行驗證。由於密碼以純文字形式在網路上傳送,因此不應在不受信任的網路上使用此方法。詳細資訊請參閱 第 20.5 節

gss

使用 GSSAPI 驗證使用者。這僅適用於 TCP/IP 連線。詳細資訊請參閱 第 20.6 節。它可以與 GSSAPI 加密結合使用。

sspi

使用 SSPI 驗證使用者。這僅適用於 Windows。詳細資訊請參閱 第 20.7 節

ident

透過聯絡用戶端上的 ident 伺服器來取得用戶端的作業系統使用者名稱,並檢查它是否與請求的資料庫使用者名稱匹配。Ident 驗證只能用於 TCP/IP 連線。當為本機連線指定時,將改用 peer 驗證。詳細資訊請參閱 第 20.8 節

peer

從作業系統取得用戶端的作業系統使用者名稱,並檢查它是否與請求的資料庫使用者名稱匹配。這僅適用於本機連線。詳細資訊請參閱 第 20.9 節

ldap

使用LDAP伺服器進行驗證。詳細資訊請參閱 第 20.10 節

radius

使用 RADIUS 伺服器進行驗證。詳細資訊請參閱 第 20.11 節

cert

使用 SSL 用戶端憑證進行驗證。詳細資訊請參閱 第 20.12 節

pam

使用作業系統提供的可插拔驗證模組 (PAM) 服務進行驗證。詳細資訊請參閱 第 20.13 節

bsd

使用作業系統提供的 BSD 驗證服務進行驗證。詳細資訊請參閱 第 20.14 節

auth-options (驗證選項)

auth-method 欄位之後,可以有 name=value 形式的欄位,這些欄位指定驗證方法的選項。有關哪些選項可用於哪些驗證方法的詳細資訊如下所示。

除了下面列出的特定於方法的選項之外,還有一個與方法無關的驗證選項 clientcert,可以在任何 hostssl 紀錄中指定。此選項可以設定為 verify-caverify-full。這兩個選項都要求用戶端提供有效的(受信任的)SSL 憑證,而 verify-full 還額外強制要求憑證中的 cn (Common Name) 與使用者名稱或適用的對應關係相符。此行為與 cert 驗證方法類似(請參閱 第 20.12 節),但能夠將用戶端憑證的驗證與任何支援 hostssl 項目的驗證方法配對。

在使用用戶端憑證驗證的任何紀錄中 (例如,使用 cert 驗證方法或使用 clientcert 選項的紀錄),您可以使用 clientname 選項指定要比對用戶端憑證憑據的哪個部分。 這個選項可以有兩個值。 如果您指定 clientname=CN(這是預設值),則使用者名稱會與憑證的 Common Name (CN) 比對。 如果您改為指定 clientname=DN,則使用者名稱會與憑證的整個 Distinguished Name (DN) 比對。 這個選項可能最好與使用者名稱對應一起使用。 此比較使用 RFC 2253 格式的 DN 進行。 若要以這種格式查看用戶端憑證的 DN,請執行

openssl x509 -in myclient.crt -noout -subject -nameopt RFC2253 | sed "s/^subject=//"

使用此選項時需要小心,尤其是在對 DN 使用正則表達式比對時。

include

這一行將被給定檔案的內容替換。

include_if_exists

如果檔案存在,這一行將被給定檔案的內容替換。 否則,將記錄一條消息,指示該檔案已被跳過。

include_dir

這一行將被目錄中找到的所有檔案的內容替換,如果它們不是以 . 開頭且以 .conf 結尾,則按照檔名順序處理(根據 C 語言環境規則,即數字在字母之前,大寫字母在小寫字母之前)。

@ 結構包含的檔案將被讀取為名稱列表,這些名稱可以用空格或逗號分隔。 註解由 # 引入,就像在 pg_hba.conf 中一樣,並且允許巢狀 @ 結構。 除非 @ 後面的檔案名稱是絕對路徑,否則它被視為相對於包含參考檔案的目錄。

由於會針對每個連線嘗試依序檢查 pg_hba.conf 紀錄,因此紀錄的順序非常重要。 通常,較早的紀錄將具有嚴格的連線比對參數和較弱的驗證方法,而較晚的紀錄將具有較寬鬆的比對參數和較強的驗證方法。 例如,可能希望對本機 TCP/IP 連線使用 trust 驗證,但要求遠端 TCP/IP 連線使用密碼。 在這種情況下,指定來自 127.0.0.1 連線的 trust 驗證的紀錄將出現在指定更廣泛的允許用戶端 IP 位址範圍的密碼驗證紀錄之前。

提示

若要連線到特定資料庫,使用者不僅必須通過 pg_hba.conf 檢查,而且必須具有該資料庫的 CONNECT 權限。 如果您想限制哪些使用者可以連線到哪些資料庫,通常更容易通過授予/撤銷 CONNECT 權限來控制它,而不是將規則放在 pg_hba.conf 條目中。

pg_hba.conf 條目的一些範例顯示在 範例 20.1 中。 有關不同驗證方法的詳細資訊,請參閱下一節。

範例 20.1. pg_hba.conf 條目範例

# 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

# The same as the previous line, but using a separate netmask column
#
# TYPE  DATABASE        USER            IP-ADDRESS      IP-MASK             METHOD
host    all             all             127.0.0.1       255.255.255.255     trust

# The same over IPv6.
#
# TYPE  DATABASE        USER            ADDRESS                 METHOD
host    all             all             ::1/128                 trust

# The same using a host name (would typically cover both IPv4 and IPv6).
#
# TYPE  DATABASE        USER            ADDRESS                 METHOD
host    all             all             localhost               trust

# The same using a regular expression for DATABASE, that allows connection
# to any databases with a name beginning with "db" and finishing with a
# number using two to four digits (like "db1234" or "db12").
#
# TYPE  DATABASE        USER            ADDRESS                 METHOD
host    "/^db\d{2,4}$"  all             localhost               trust

# Allow any user from any host with IP address 192.168.93.x to connect
# to database "postgres" as the same user name that ident reports for
# the connection (typically the operating system user name).
#
# TYPE  DATABASE        USER            ADDRESS                 METHOD
host    postgres        all             192.168.93.0/24         ident

# 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        scram-sha-256

# Allow any user from hosts in the example.com domain to connect to
# any database if the user's password is correctly supplied.
#
# Require SCRAM authentication for most users, but make an exception
# for user 'mike', who uses an older client that doesn't support SCRAM
# authentication.
#
# TYPE  DATABASE        USER            ADDRESS                 METHOD
host    all             mike            .example.com            md5
host    all             all             .example.com            scram-sha-256

# In the absence of preceding "host" lines, these three lines will
# reject all connections from 192.168.54.1 (since that entry will be
# matched first), but allow GSSAPI-encrypted connections from anywhere else
# on the Internet.  The zero mask causes no bits of the host IP address to
# be considered, so it matches any host.  Unencrypted GSSAPI connections
# (which "fall through" to the third line since "hostgssenc" only matches
# encrypted GSSAPI connections) are allowed, but only from 192.168.12.10.
#
# TYPE  DATABASE        USER            ADDRESS                 METHOD
host    all             all             192.168.54.1/32         reject
hostgssenc all          all             0.0.0.0/0               gss
host    all             all             192.168.12.10/32        gss

# Allow users from 192.168.x.x hosts to connect to any database, if
# they pass the ident check.  If, for example, ident says the user is
# "bryanh" and he requests to connect as PostgreSQL user "guest1", the
# connection is allowed if there is an entry in pg_ident.conf for map
# "omicron" that says "bryanh" is allowed to connect as "guest1".
#
# TYPE  DATABASE        USER            ADDRESS                 METHOD
host    all             all             192.168.0.0/16          ident map=omicron

# If these are the only four lines for local connections, they will
# allow local users to connect only to their own databases (databases
# with the same name as their database user name) except for users whose
# name end with "helpdesk", administrators and members of role "support",
# who can connect to all databases.  The file $PGDATA/admins contains a
# list of names of administrators.  Passwords are required in all cases.
#
# TYPE  DATABASE        USER            ADDRESS                 METHOD
local   sameuser        all                                     md5
local   all             /^.*helpdesk$                           md5
local   all             @admins                                 md5
local   all             +support                                md5

# The last two lines above can be combined into a single line:
local   all             @admins,+support                        md5

# The database column can also use lists and file names:
local   db1,db2,@demodbs  all                                   md5

提交更正

如果您在文件裡面看到任何不正確、與您特定功能的使用經驗不符或需要進一步澄清的地方,請使用此表單來報告文件問題。