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 区域设置规则,即数字在字母之前,大写字母在小写字母之前)处理。
记录可以有多种格式
localdatabaseuserauth-method[auth-options] hostdatabaseuseraddressauth-method[auth-options] hostssldatabaseuseraddressauth-method[auth-options] hostnossldatabaseuseraddressauth-method[auth-options] hostgssencdatabaseuseraddressauth-method[auth-options] hostnogssencdatabaseuseraddressauth-method[auth-options] hostdatabaseuserIP-addressIP-maskauth-method[auth-options] hostssldatabaseuserIP-addressIP-maskauth-method[auth-options] hostnossldatabaseuserIP-addressIP-maskauth-method[auth-options] hostgssencdatabaseuserIP-addressIP-maskauth-method[auth-options] hostnogssencdatabaseuserIP-addressIP-maskauth-method[auth-options] includefileinclude_if_existsfileinclude_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-addressIP-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
如果您在文档中发现任何不正确、与您使用特定功能的经验不符或需要进一步澄清的内容,请使用此表格报告文档问题。