2025年9月25日: PostgreSQL 18 釋出!
支援的版本: 當前 (18) / 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 檔案。不過,也可以將認證配置檔案放在其他地方;請參閱 runtime-config-file-locations.html#GUC-HBA-FILE 中的 hba_file 配置引數。

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

注意

上述宣告在 Microsoft Windows 上不成立:在 Windows 上,pg_hba.conf 檔案中的任何更改都會立即被後續的新連線應用。

系統檢視 pg_hba_file_rules 可以幫助預測試對 pg_hba.conf 檔案的更改,或在檔案載入未達到預期效果時診斷問題。檢視中具有非空 error 欄位的行表示檔案中相應行存在問題。

pg_hba.conf 檔案的通用格式是一組記錄,每行一條。空行將被忽略,# 註釋字元後的任何文字也將被忽略。記錄可以透過在行末新增反斜槓來延續到下一行。(反斜槓除了在行末之外沒有特殊含義。)記錄由多個由空格和/或製表符分隔的欄位組成。如果欄位值被雙引號括起來,欄位可以包含空格。引用資料庫、使用者或地址欄位中的關鍵字之一(例如,all 或 replication)會使其失去特殊含義,而僅匹配具有該名稱的資料庫、使用者或主機。反斜槓換行在帶引號文字或註釋中也適用。

每個認證記錄指定一種連線型別、一個客戶端 IP 地址範圍(如果與連線型別相關)、一個數據庫名稱、一個使用者名稱以及用於匹配這些引數的連線的認證方法。具有匹配的連線型別、客戶端地址、請求的資料庫和使用者名稱的第一個記錄用於執行認證。沒有“fall-through”或“backup”:如果選擇了一個記錄但認證失敗,則不會考慮後續記錄。如果沒有記錄匹配,則拒絕訪問。

每條記錄都可以是 include 指令或認證記錄。Include 指令指定可以包含的檔案,這些檔案包含其他記錄。記錄將插入到 include 指令的位置。Include 指令只包含兩個欄位:include、include_if_exists 或 include_dir 指令和要包含的檔案或目錄。檔案或目錄可以是相對路徑或絕對路徑,並且可以被雙引號括起來。對於 include_dir 形式,所有不以 . 開頭且以 .conf 結尾的檔案都將被包含。Include 目錄中的多個檔案按檔名順序處理(根據 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 配置引數(有關更多資訊,請參閱 Section 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 正則表示式語法詳情,請參閱 Section 9.7.3.1。)

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

user

指定此記錄匹配的資料庫使用者名稱稱。值 all 指定匹配所有使用者。否則,這是特定資料庫使用者的名稱、正則表示式(當以斜槓 (/) 開頭時)或以 + 開頭的組名。(請記住,PostgreSQL 中使用者和組之間沒有真正的區別;+ 標記實際上意味著“匹配此角色的任何直接或間接成員的角色”,而沒有 + 標記的名稱僅匹配該特定角色。)出於此目的,除非超級使用者是角色的顯式成員(直接或間接),否則他們不被視為角色的成員,而不僅僅是因為他們是超級使用者。可以透過用逗號分隔來提供多個使用者名稱和/或正則表示式。

如果使用者名稱以斜槓 (/) 開頭,則名稱的其餘部分被視為正則表示式。(有關 PostgreSQL 正則表示式語法詳情,請參閱 Section 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 地址。要指定單個主機,請使用 32(對於 IPv4)或 128(對於 IPv6)的掩碼長度。在網路地址中,請勿省略尾隨零。

以 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 伺服器和 TCP Wrappers)一致。

IP 地址
IP 掩碼

這兩個欄位可以替代 IP 地址/掩碼長度表示法。不是指定掩碼長度,而是在單獨的列中指定實際掩碼。例如,255.0.0.0 表示 IPv4 CIDR 掩碼長度為 8,255.255.255.255 表示 CIDR 掩碼長度為 32。

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

auth-method

指定在連線匹配此記錄時使用的認證方法。此處彙總了可能的選擇;詳情請參閱 Section 20.3。所有選項都小寫且區分大小寫,因此即使是像 ldap 這樣的縮寫也必須小寫。

trust

無條件允許連線。此方法允許任何能夠連線到 PostgreSQL 資料庫伺服器的人以任何他們想要的 PostgreSQL 使用者身份登入,而無需密碼或其他認證。詳情請參閱 Section 20.4。

reject

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

scram-sha-256

執行 SCRAM-SHA-256 認證以驗證使用者的密碼。詳情請參閱 Section 20.5。

md5

執行 SCRAM-SHA-256 或 MD5 認證以驗證使用者的密碼。詳情請參閱 Section 20.5。

警告

MD5 加密密碼的支援已棄用,將在 PostgreSQL 的未來版本中移除。有關遷移到其他密碼型別的詳細資訊,請參閱第 20.5 節

password

要求客戶端提供未加密的密碼進行認證。由於密碼以明文形式在網路上傳輸,因此不應在不受信任的網路上使用此方法。詳情請參閱 Section 20.5。

gss

使用 GSSAPI 認證使用者。這僅適用於 TCP/IP 連線。詳情請參閱 Section 20.6。它可以與 GSSAPI 加密結合使用。

sspi

使用 SSPI 認證使用者。這僅在 Windows 上可用。詳情請參閱 Section 20.7。

ident

透過聯絡客戶端上的 ident 伺服器獲取客戶端的作業系統使用者名稱,並檢查其是否與請求的資料庫使用者名稱匹配。Ident 認證只能用於 TCP/IP 連線。當為本地連線指定時,將使用 peer 認證。詳情請參閱 Section 20.8。

peer

從作業系統獲取客戶端的作業系統使用者名稱,並檢查其是否與請求的資料庫使用者名稱匹配。這僅適用於本地連線。詳情請參閱 Section 20.9。

ldap

使用LDAP伺服器進行認證。詳情請參閱 Section 20.10。

radius

使用 RADIUS 伺服器進行認證。詳情請參閱 Section 20.11。

cert

使用 SSL 客戶端證書進行認證。詳情請參閱 Section 20.12。

pam

使用作業系統提供的可插拔認證模組 (PAM) 服務進行認證。詳情請參閱 Section 20.13。

bsd

使用作業系統提供的 BSD 認證服務進行認證。詳情請參閱 Section 20.14。

oauth

使用第三方 OAuth 2.0 身份提供商進行授權和可選認證。詳情請參閱 Section 20.15。

auth-options

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

除了下面列出的特定於方法的選項外,還有一個與方法無關的認證選項 clientcert,可以在任何 hostssl 記錄中指定。此選項可以設定為 verify-ca 或 verify-full。這兩個選項都要求客戶端提供一個有效的(受信任的)SSL 證書,而 verify-full 另外強制要求證書中的 cn(Common Name)與使用者名稱或適用的對映匹配。此行為類似於 cert 認證方法(請參閱 Section 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 條目的一些示例顯示在 Example 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

提交更正

如果您在文件中看到任何不正確、與您對特定功能的體驗不符或需要進一步澄清的內容,請使用 此表單 報告文件問題。