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

提交更正

如果您在文档中看到任何不正确、与您对特定功能的体验不符或需要进一步澄清的内容,请使用 此表单 报告文档问题。