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 分隔。 如果欄位值用雙引號引起來,則欄位可以包含空白。 在資料庫、使用者或位址欄位中引用其中一個關鍵字 (例如,all
或 replication
) 會使該詞失去其特殊含義,而僅比對具有該名稱的資料庫、使用者或主機。 反斜線行繼續適用於引號文字或註解中。
每個驗證記錄指定一個連線類型、一個用戶端 IP 位址範圍 (如果與連線類型相關)、一個資料庫名稱、一個使用者名稱,以及用於比對這些參數的連線的驗證方法。 具有比對的連線類型、用戶端位址、請求的資料庫和使用者名稱的第一個記錄用於執行驗證。 沒有「fall-through」或「backup」:如果選擇了一個記錄並且驗證失敗,則不會考慮後續的記錄。 如果沒有記錄比對,則拒絕存取。
每個記錄都可以是一個包含指示詞或一個驗證記錄。 包含指示詞指定可以包含的檔案,其中包含其他記錄。 這些記錄將被插入到包含指示詞的位置。 包含指示詞僅包含兩個欄位:include
、include_if_exists
或 include_dir
指示詞以及要包含的檔案或目錄。 檔案或目錄可以是相對或絕對路徑,並且可以用雙引號引起來。 對於 include_dir
形式,所有不以 .
開頭並以 .conf
結尾的檔案都將被包含。 包含目錄中的多個檔案將按照檔案名稱順序處理 (根據 C 地區規則,即數字在字母之前,大寫字母在小寫字母之前)。
一個記錄可以有多種格式
localdatabase
user
auth-method
[auth-options
] hostdatabase
user
address
auth-method
[auth-options
] hostssldatabase
user
address
auth-method
[auth-options
] hostnossldatabase
user
address
auth-method
[auth-options
] hostgssencdatabase
user
address
auth-method
[auth-options
] hostnogssencdatabase
user
address
auth-method
[auth-options
] hostdatabase
user
IP-address
IP-mask
auth-method
[auth-options
] hostssldatabase
user
IP-address
IP-mask
auth-method
[auth-options
] hostnossldatabase
user
IP-address
IP-mask
auth-method
[auth-options
] hostgssencdatabase
user
IP-address
IP-mask
auth-method
[auth-options
] hostnogssencdatabase
user
IP-address
IP-mask
auth-method
[auth-options
] includefile
include_if_existsfile
include_dirdirectory
欄位的含義如下
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
指定請求的使用者必須是與請求的資料庫具有相同名稱的角色成員。(samegroup
是 samerole
的過時但仍然可接受的拼寫。) 超級使用者不被視為 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-ca
或 verify-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
如果您在文件裡面看到任何不正確、與您特定功能的使用經驗不符或需要進一步澄清的地方,請使用此表單來報告文件問題。