支持的版本:当前 (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 文件的通用格式是一组记录,每行一条记录。空行将被忽略,# 注释字符之后的任何文本也将被忽略。可以通过在行尾添加反斜杠将记录延续到下一行。(反斜杠除了在一行的末尾外,没有特殊含义。)记录由多个字段组成,这些字段用空格和/或制表符分隔。如果字段值用双引号引起来,则字段可以包含空格。在数据库、用户或地址字段中引用关键字之一(例如,allreplication)会使该单词失去其特殊含义,而只是匹配具有该名称的数据库、用户或主机。反斜杠行延续甚至在带引号的文本或注释中也适用。

每个身份验证记录都指定一个连接类型、一个客户端 IP 地址范围(如果与连接类型相关)、一个数据库名称、一个用户名以及用于匹配这些参数的连接的身份验证方法。将使用具有匹配的连接类型、客户端地址、请求的数据库和用户名的第一个记录执行身份验证。没有 回退备份:如果选择了一条记录并且身份验证失败,则不会考虑后续记录。如果没有记录匹配,则拒绝访问。

每个记录都可以是 include 指令或身份验证记录。Include 指令指定可以包含其他记录的文件。这些记录将插入到 include 指令的位置。Include 指令仅包含两个字段:includeinclude_if_existsinclude_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 配置参数来启用(有关更多信息,请参见 第 18.9 节)。否则,除了记录警告它无法匹配任何连接之外,hostssl 记录将被忽略。

hostnossl

此记录类型的行为与 hostssl 相反;它仅匹配通过 TCP/IP 发起的未使用SSL.

的连接尝试

此记录匹配使用 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

以这种方式指定的 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 服务器和 TCP Wrappers)一致。

IP-address
IP-mask

这两个字段可以用来替代 IP-address/mask-length 表示法。不是指定掩码长度,而是在单独的列中指定实际的掩码。例如,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(公用名)与用户名或适用的映射相匹配。此行为类似于 cert 身份验证方法(请参见第 20.12 节),但允许将客户端证书的验证与任何支持 hostssl 条目的身份验证方法配对。

在任何使用客户端证书身份验证的记录上(即使用 cert 身份验证方法或使用 clientcert 选项的记录),您可以使用 clientname 选项指定要匹配的客户端证书凭据的哪个部分。此选项可以有两个值。如果您指定 clientname=CN(这是默认值),则将用户名与证书的 公用名 (CN) 进行匹配。如果改为指定 clientname=DN,则将用户名与证书的整个 可分辨名称 (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

提交更正

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