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
文件的通用格式是一组记录,每行一条记录。空行将被忽略,#
注释字符之后的任何文本也将被忽略。可以通过在行尾添加反斜杠将记录延续到下一行。(反斜杠除了在一行的末尾外,没有特殊含义。)记录由多个字段组成,这些字段用空格和/或制表符分隔。如果字段值用双引号引起来,则字段可以包含空格。在数据库、用户或地址字段中引用关键字之一(例如,all
或 replication
)会使该单词失去其特殊含义,而只是匹配具有该名称的数据库、用户或主机。反斜杠行延续甚至在带引号的文本或注释中也适用。
每个身份验证记录都指定一个连接类型、一个客户端 IP 地址范围(如果与连接类型相关)、一个数据库名称、一个用户名以及用于匹配这些参数的连接的身份验证方法。将使用具有匹配的连接类型、客户端地址、请求的数据库和用户名的第一个记录执行身份验证。没有 “回退” 或 “备份”:如果选择了一条记录并且身份验证失败,则不会考虑后续记录。如果没有记录匹配,则拒绝访问。
每个记录都可以是 include 指令或身份验证记录。Include 指令指定可以包含其他记录的文件。这些记录将插入到 include 指令的位置。Include 指令仅包含两个字段:include
、include_if_exists
或 include_dir
指令以及要包含的文件或目录。文件或目录可以是相对路径或绝对路径,并且可以用双引号引起来。对于 include_dir
形式,将包含所有不以 .
开头且以 .conf
结尾的文件。include 目录中的多个文件按文件名顺序(根据 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.
的连接尝试
此记录匹配使用 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
以这种方式指定的 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-ca
或 verify-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
如果您在文档中发现任何不正确、与您使用特定功能的经验不符或需要进一步澄清的内容,请使用此表格报告文档问题。