codekingpro/portable-devtools
114k
1<?xml version="1.0" encoding="UTF-8" standalone="no"?>2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>21.1. The pg_hba.conf File</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="client-authentication.html" title="Chapter 21. Client Authentication" /><link rel="next" href="auth-username-maps.html" title="21.2. User Name Maps" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">21.1. The <code class="filename">pg_hba.conf</code> File</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="client-authentication.html" title="Chapter 21. Client Authentication">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><th width="60%" align="center">Chapter 21. Client Authentication</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="auth-username-maps.html" title="21.2. User Name Maps">Next</a></td></tr></table><hr /></div><div class="sect1" id="AUTH-PG-HBA-CONF"><div class="titlepage"><div><div><h2 class="title" style="clear: both">21.1. The <code class="filename">pg_hba.conf</code> File <a href="#AUTH-PG-HBA-CONF" class="id_link">#</a></h2></div></div></div><a id="id-1.6.8.8.2" class="indexterm"></a><p>3 Client authentication is controlled by a configuration file,4 which traditionally is named5 <code class="filename">pg_hba.conf</code> and is stored in the database6 cluster's data directory.7 (<acronym class="acronym">HBA</acronym> stands for host-based authentication.) A default8 <code class="filename">pg_hba.conf</code> file is installed when the data9 directory is initialized by <a class="xref" href="app-initdb.html" title="initdb"><span class="refentrytitle"><span class="application">initdb</span></span></a>. It is10 possible to place the authentication configuration file elsewhere,11 however; see the <a class="xref" href="runtime-config-file-locations.html#GUC-HBA-FILE">hba_file</a> configuration parameter.12 </p><p>13 The general format of the <code class="filename">pg_hba.conf</code> file is14 a set of records, one per line. Blank lines are ignored, as is any15 text after the <code class="literal">#</code> comment character.16 A record can be continued onto the next line by ending the line with17 a backslash. (Backslashes are not special except at the end of a line.)18 A record is made19 up of a number of fields which are separated by spaces and/or tabs.20 Fields can contain white space if the field value is double-quoted.21 Quoting one of the keywords in a database, user, or address field (e.g.,22 <code class="literal">all</code> or <code class="literal">replication</code>) makes the word lose its special23 meaning, and just match a database, user, or host with that name.24 Backslash line continuation applies even within quoted text or comments.25 </p><p>26 Each authentication record specifies a connection type, a client IP address27 range (if relevant for the connection type), a database name, a user name,28 and the authentication method to be used for connections matching29 these parameters. The first record with a matching connection type,30 client address, requested database, and user name is used to perform31 authentication. There is no <span class="quote">“<span class="quote">fall-through</span>”</span> or32 <span class="quote">“<span class="quote">backup</span>”</span>: if one record is chosen and the authentication33 fails, subsequent records are not considered. If no record matches,34 access is denied.35 </p><p>36 Each record can be an include directive or an authentication record.37 Include directives specify files that can be included, that contain38 additional records. The records will be inserted in place of the39 include directives. Include directives only contain two fields:40 <code class="literal">include</code>, <code class="literal">include_if_exists</code> or41 <code class="literal">include_dir</code> directive and the file or directory to be42 included. The file or directory can be a relative or absolute path, and can43 be double-quoted. For the <code class="literal">include_dir</code> form, all files44 not starting with a <code class="literal">.</code> and ending with45 <code class="literal">.conf</code> will be included. Multiple files within an include46 directory are processed in file name order (according to C locale rules,47 i.e., numbers before letters, and uppercase letters before lowercase ones).48 </p><p>49 A record can have several formats:50</p><pre class="synopsis">51local <em class="replaceable"><code>database</code></em> <em class="replaceable"><code>user</code></em> <em class="replaceable"><code>auth-method</code></em> [<span class="optional"><em class="replaceable"><code>auth-options</code></em></span>]52host <em class="replaceable"><code>database</code></em> <em class="replaceable"><code>user</code></em> <em class="replaceable"><code>address</code></em> <em class="replaceable"><code>auth-method</code></em> [<span class="optional"><em class="replaceable"><code>auth-options</code></em></span>]53hostssl <em class="replaceable"><code>database</code></em> <em class="replaceable"><code>user</code></em> <em class="replaceable"><code>address</code></em> <em class="replaceable"><code>auth-method</code></em> [<span class="optional"><em class="replaceable"><code>auth-options</code></em></span>]54hostnossl <em class="replaceable"><code>database</code></em> <em class="replaceable"><code>user</code></em> <em class="replaceable"><code>address</code></em> <em class="replaceable"><code>auth-method</code></em> [<span class="optional"><em class="replaceable"><code>auth-options</code></em></span>]55hostgssenc <em class="replaceable"><code>database</code></em> <em class="replaceable"><code>user</code></em> <em class="replaceable"><code>address</code></em> <em class="replaceable"><code>auth-method</code></em> [<span class="optional"><em class="replaceable"><code>auth-options</code></em></span>]56hostnogssenc <em class="replaceable"><code>database</code></em> <em class="replaceable"><code>user</code></em> <em class="replaceable"><code>address</code></em> <em class="replaceable"><code>auth-method</code></em> [<span class="optional"><em class="replaceable"><code>auth-options</code></em></span>]57host <em class="replaceable"><code>database</code></em> <em class="replaceable"><code>user</code></em> <em class="replaceable"><code>IP-address</code></em> <em class="replaceable"><code>IP-mask</code></em> <em class="replaceable"><code>auth-method</code></em> [<span class="optional"><em class="replaceable"><code>auth-options</code></em></span>]58hostssl <em class="replaceable"><code>database</code></em> <em class="replaceable"><code>user</code></em> <em class="replaceable"><code>IP-address</code></em> <em class="replaceable"><code>IP-mask</code></em> <em class="replaceable"><code>auth-method</code></em> [<span class="optional"><em class="replaceable"><code>auth-options</code></em></span>]59hostnossl <em class="replaceable"><code>database</code></em> <em class="replaceable"><code>user</code></em> <em class="replaceable"><code>IP-address</code></em> <em class="replaceable"><code>IP-mask</code></em> <em class="replaceable"><code>auth-method</code></em> [<span class="optional"><em class="replaceable"><code>auth-options</code></em></span>]60hostgssenc <em class="replaceable"><code>database</code></em> <em class="replaceable"><code>user</code></em> <em class="replaceable"><code>IP-address</code></em> <em class="replaceable"><code>IP-mask</code></em> <em class="replaceable"><code>auth-method</code></em> [<span class="optional"><em class="replaceable"><code>auth-options</code></em></span>]61hostnogssenc <em class="replaceable"><code>database</code></em> <em class="replaceable"><code>user</code></em> <em class="replaceable"><code>IP-address</code></em> <em class="replaceable"><code>IP-mask</code></em> <em class="replaceable"><code>auth-method</code></em> [<span class="optional"><em class="replaceable"><code>auth-options</code></em></span>]62include <em class="replaceable"><code>file</code></em>63include_if_exists <em class="replaceable"><code>file</code></em>64include_dir <em class="replaceable"><code>directory</code></em>65</pre><p>66 The meaning of the fields is as follows:67 68 </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">local</code></span></dt><dd><p>69 This record matches connection attempts using Unix-domain70 sockets. Without a record of this type, Unix-domain socket71 connections are disallowed.72 </p></dd><dt><span class="term"><code class="literal">host</code></span></dt><dd><p>73 This record matches connection attempts made using TCP/IP.74 <code class="literal">host</code> records match75 <acronym class="acronym">SSL</acronym> or non-<acronym class="acronym">SSL</acronym> connection76 attempts as well as <acronym class="acronym">GSSAPI</acronym> encrypted or77 non-<acronym class="acronym">GSSAPI</acronym> encrypted connection attempts.78 </p><div class="note"><h3 class="title">Note</h3><p>79 Remote TCP/IP connections will not be possible unless80 the server is started with an appropriate value for the81 <a class="xref" href="runtime-config-connection.html#GUC-LISTEN-ADDRESSES">listen_addresses</a> configuration parameter,82 since the default behavior is to listen for TCP/IP connections83 only on the local loopback address <code class="literal">localhost</code>.84 </p></div></dd><dt><span class="term"><code class="literal">hostssl</code></span></dt><dd><p>85 This record matches connection attempts made using TCP/IP,86 but only when the connection is made with <acronym class="acronym">SSL</acronym>87 encryption.88 </p><p>89 To make use of this option the server must be built with90 <acronym class="acronym">SSL</acronym> support. Furthermore,91 <acronym class="acronym">SSL</acronym> must be enabled92 by setting the <a class="xref" href="runtime-config-connection.html#GUC-SSL">ssl</a> configuration parameter (see93 <a class="xref" href="ssl-tcp.html" title="19.9. Secure TCP/IP Connections with SSL">Section 19.9</a> for more information).94 Otherwise, the <code class="literal">hostssl</code> record is ignored except for95 logging a warning that it cannot match any connections.96 </p></dd><dt><span class="term"><code class="literal">hostnossl</code></span></dt><dd><p>97 This record type has the opposite behavior of <code class="literal">hostssl</code>;98 it only matches connection attempts made over99 TCP/IP that do not use <acronym class="acronym">SSL</acronym>.100 </p></dd><dt><span class="term"><code class="literal">hostgssenc</code></span></dt><dd><p>101 This record matches connection attempts made using TCP/IP,102 but only when the connection is made with <acronym class="acronym">GSSAPI</acronym>103 encryption.104 </p><p>105 To make use of this option the server must be built with106 <acronym class="acronym">GSSAPI</acronym> support. Otherwise,107 the <code class="literal">hostgssenc</code> record is ignored except for logging108 a warning that it cannot match any connections.109 </p></dd><dt><span class="term"><code class="literal">hostnogssenc</code></span></dt><dd><p>110 This record type has the opposite behavior of <code class="literal">hostgssenc</code>;111 it only matches connection attempts made over112 TCP/IP that do not use <acronym class="acronym">GSSAPI</acronym> encryption.113 </p></dd><dt><span class="term"><em class="replaceable"><code>database</code></em></span></dt><dd><p>114 Specifies which database name(s) this record matches. The value115 <code class="literal">all</code> specifies that it matches all databases.116 The value <code class="literal">sameuser</code> specifies that the record117 matches if the requested database has the same name as the118 requested user. The value <code class="literal">samerole</code> specifies that119 the requested user must be a member of the role with the same120 name as the requested database. (<code class="literal">samegroup</code> is an121 obsolete but still accepted spelling of <code class="literal">samerole</code>.)122 Superusers are not considered to be members of a role for the123 purposes of <code class="literal">samerole</code> unless they are explicitly124 members of the role, directly or indirectly, and not just by125 virtue of being a superuser.126 The value <code class="literal">replication</code> specifies that the record127 matches if a physical replication connection is requested, however, it128 doesn't match with logical replication connections. Note that physical129 replication connections do not specify any particular database whereas130 logical replication connections do specify it.131 Otherwise, this is the name of a specific132 <span class="productname">PostgreSQL</span> database or a regular expression.133 Multiple database names and/or regular expressions can be supplied by134 separating them with commas.135 </p><p>136 If the database name starts with a slash (<code class="literal">/</code>), the137 remainder of the name is treated as a regular expression.138 (See <a class="xref" href="functions-matching.html#POSIX-SYNTAX-DETAILS" title="9.7.3.1. Regular Expression Details">Section 9.7.3.1</a> for details of139 <span class="productname">PostgreSQL</span>'s regular expression syntax.)140 </p><p>141 A separate file containing database names and/or regular expressions142 can be specified by preceding the file name with <code class="literal">@</code>.143 </p></dd><dt><span class="term"><em class="replaceable"><code>user</code></em></span></dt><dd><p>144 Specifies which database user name(s) this record145 matches. The value <code class="literal">all</code> specifies that it146 matches all users. Otherwise, this is either the name of a specific147 database user, a regular expression (when starting with a slash148 (<code class="literal">/</code>), or a group name preceded by <code class="literal">+</code>.149 (Recall that there is no real distinction between users and groups150 in <span class="productname">PostgreSQL</span>; a <code class="literal">+</code> mark really means151 <span class="quote">“<span class="quote">match any of the roles that are directly or indirectly members152 of this role</span>”</span>, while a name without a <code class="literal">+</code> mark matches153 only that specific role.) For this purpose, a superuser is only154 considered to be a member of a role if they are explicitly a member155 of the role, directly or indirectly, and not just by virtue of156 being a superuser.157 Multiple user names and/or regular expressions can be supplied by158 separating them with commas.159 </p><p>160 If the user name starts with a slash (<code class="literal">/</code>), the161 remainder of the name is treated as a regular expression.162 (See <a class="xref" href="functions-matching.html#POSIX-SYNTAX-DETAILS" title="9.7.3.1. Regular Expression Details">Section 9.7.3.1</a> for details of163 <span class="productname">PostgreSQL</span>'s regular expression syntax.)164 </p><p>165 A separate file containing user names and/or regular expressions can166 be specified by preceding the file name with <code class="literal">@</code>.167 </p></dd><dt><span class="term"><em class="replaceable"><code>address</code></em></span></dt><dd><p>168 Specifies the client machine address(es) that this record169 matches. This field can contain either a host name, an IP170 address range, or one of the special key words mentioned below.171 </p><p>172 An IP address range is specified using standard numeric notation173 for the range's starting address, then a slash (<code class="literal">/</code>)174 and a <acronym class="acronym">CIDR</acronym> mask length. The mask175 length indicates the number of high-order bits of the client176 IP address that must match. Bits to the right of this should177 be zero in the given IP address.178 There must not be any white space between the IP address, the179 <code class="literal">/</code>, and the CIDR mask length.180 </p><p>181 Typical examples of an IPv4 address range specified this way are182 <code class="literal">172.20.143.89/32</code> for a single host, or183 <code class="literal">172.20.143.0/24</code> for a small network, or184 <code class="literal">10.6.0.0/16</code> for a larger one.185 An IPv6 address range might look like <code class="literal">::1/128</code>186 for a single host (in this case the IPv6 loopback address) or187 <code class="literal">fe80::7a31:c1ff:0000:0000/96</code> for a small188 network.189 <code class="literal">0.0.0.0/0</code> represents all190 IPv4 addresses, and <code class="literal">::0/0</code> represents191 all IPv6 addresses.192 To specify a single host, use a mask length of 32 for IPv4 or193 128 for IPv6. In a network address, do not omit trailing zeroes.194 </p><p>195 An entry given in IPv4 format will match only IPv4 connections,196 and an entry given in IPv6 format will match only IPv6 connections,197 even if the represented address is in the IPv4-in-IPv6 range.198 </p><p>199 You can also write <code class="literal">all</code> to match any IP address,200 <code class="literal">samehost</code> to match any of the server's own IP201 addresses, or <code class="literal">samenet</code> to match any address in any202 subnet that the server is directly connected to.203 </p><p>204 If a host name is specified (anything that is not an IP address205 range or a special key word is treated as a host name),206 that name is compared with the result of a reverse name207 resolution of the client's IP address (e.g., reverse DNS208 lookup, if DNS is used). Host name comparisons are case209 insensitive. If there is a match, then a forward name210 resolution (e.g., forward DNS lookup) is performed on the host211 name to check whether any of the addresses it resolves to are212 equal to the client's IP address. If both directions match,213 then the entry is considered to match. (The host name that is214 used in <code class="filename">pg_hba.conf</code> should be the one that215 address-to-name resolution of the client's IP address returns,216 otherwise the line won't be matched. Some host name databases217 allow associating an IP address with multiple host names, but218 the operating system will only return one host name when asked219 to resolve an IP address.)220 </p><p>221 A host name specification that starts with a dot222 (<code class="literal">.</code>) matches a suffix of the actual host223 name. So <code class="literal">.example.com</code> would match224 <code class="literal">foo.example.com</code> (but not just225 <code class="literal">example.com</code>).226 </p><p>227 When host names are specified228 in <code class="filename">pg_hba.conf</code>, you should make sure that229 name resolution is reasonably fast. It can be of advantage to230 set up a local name resolution cache such231 as <code class="command">nscd</code>. Also, you may wish to enable the232 configuration parameter <code class="varname">log_hostname</code> to see233 the client's host name instead of the IP address in the log.234 </p><p>235 These fields do not apply to <code class="literal">local</code> records.236 </p><div class="note"><h3 class="title">Note</h3><p>237 Users sometimes wonder why host names are handled238 in this seemingly complicated way, with two name resolutions239 including a reverse lookup of the client's IP address. This240 complicates use of the feature in case the client's reverse DNS241 entry is not set up or yields some undesirable host name.242 It is done primarily for efficiency: this way, a connection attempt243 requires at most two resolver lookups, one reverse and one forward.244 If there is a resolver problem with some address, it becomes only245 that client's problem. A hypothetical alternative246 implementation that only did forward lookups would have to247 resolve every host name mentioned in248 <code class="filename">pg_hba.conf</code> during every connection attempt.249 That could be quite slow if many names are listed.250 And if there is a resolver problem with one of the host names,251 it becomes everyone's problem.252 </p><p>253 Also, a reverse lookup is necessary to implement the suffix254 matching feature, because the actual client host name needs to255 be known in order to match it against the pattern.256 </p><p>257 Note that this behavior is consistent with other popular258 implementations of host name-based access control, such as the259 Apache HTTP Server and TCP Wrappers.260 </p></div></dd><dt><span class="term"><em class="replaceable"><code>IP-address</code></em><br /></span><span class="term"><em class="replaceable"><code>IP-mask</code></em></span></dt><dd><p>261 These two fields can be used as an alternative to the262 <em class="replaceable"><code>IP-address</code></em><code class="literal">/</code><em class="replaceable"><code>mask-length</code></em>263 notation. Instead of264 specifying the mask length, the actual mask is specified in a265 separate column. For example, <code class="literal">255.0.0.0</code> represents an IPv4266 CIDR mask length of 8, and <code class="literal">255.255.255.255</code> represents a267 CIDR mask length of 32.268 </p><p>269 These fields do not apply to <code class="literal">local</code> records.270 </p></dd><dt><span class="term"><em class="replaceable"><code>auth-method</code></em></span></dt><dd><p>271 Specifies the authentication method to use when a connection matches272 this record. The possible choices are summarized here; details273 are in <a class="xref" href="auth-methods.html" title="21.3. Authentication Methods">Section 21.3</a>. All the options274 are lower case and treated case sensitively, so even acronyms like275 <code class="literal">ldap</code> must be specified as lower case.276 277 </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">trust</code></span></dt><dd><p>278 Allow the connection unconditionally. This method279 allows anyone that can connect to the280 <span class="productname">PostgreSQL</span> database server to login as281 any <span class="productname">PostgreSQL</span> user they wish,282 without the need for a password or any other authentication. See <a class="xref" href="auth-trust.html" title="21.4. Trust Authentication">Section 21.4</a> for details.283 </p></dd><dt><span class="term"><code class="literal">reject</code></span></dt><dd><p>284 Reject the connection unconditionally. This is useful for285 <span class="quote">“<span class="quote">filtering out</span>”</span> certain hosts from a group, for example a286 <code class="literal">reject</code> line could block a specific host from connecting,287 while a later line allows the remaining hosts in a specific288 network to connect.289 </p></dd><dt><span class="term"><code class="literal">scram-sha-256</code></span></dt><dd><p>290 Perform SCRAM-SHA-256 authentication to verify the user's291 password. See <a class="xref" href="auth-password.html" title="21.5. Password Authentication">Section 21.5</a> for details.292 </p></dd><dt><span class="term"><code class="literal">md5</code></span></dt><dd><p>293 Perform SCRAM-SHA-256 or MD5 authentication to verify the294 user's password. See <a class="xref" href="auth-password.html" title="21.5. Password Authentication">Section 21.5</a>295 for details.296 </p></dd><dt><span class="term"><code class="literal">password</code></span></dt><dd><p>297 Require the client to supply an unencrypted password for298 authentication.299 Since the password is sent in clear text over the300 network, this should not be used on untrusted networks.301 See <a class="xref" href="auth-password.html" title="21.5. Password Authentication">Section 21.5</a> for details.302 </p></dd><dt><span class="term"><code class="literal">gss</code></span></dt><dd><p>303 Use GSSAPI to authenticate the user. This is only304 available for TCP/IP connections. See <a class="xref" href="gssapi-auth.html" title="21.6. GSSAPI Authentication">Section 21.6</a> for details. It can be used in conjunction305 with GSSAPI encryption.306 </p></dd><dt><span class="term"><code class="literal">sspi</code></span></dt><dd><p>307 Use SSPI to authenticate the user. This is only308 available on Windows. See <a class="xref" href="sspi-auth.html" title="21.7. SSPI Authentication">Section 21.7</a> for details.309 </p></dd><dt><span class="term"><code class="literal">ident</code></span></dt><dd><p>310 Obtain the operating system user name of the client311 by contacting the ident server on the client312 and check if it matches the requested database user name.313 Ident authentication can only be used on TCP/IP314 connections. When specified for local connections, peer315 authentication will be used instead.316 See <a class="xref" href="auth-ident.html" title="21.8. Ident Authentication">Section 21.8</a> for details.317 </p></dd><dt><span class="term"><code class="literal">peer</code></span></dt><dd><p>318 Obtain the client's operating system user name from the operating319 system and check if it matches the requested database user name.320 This is only available for local connections.321 See <a class="xref" href="auth-peer.html" title="21.9. Peer Authentication">Section 21.9</a> for details.322 </p></dd><dt><span class="term"><code class="literal">ldap</code></span></dt><dd><p>323 Authenticate using an <acronym class="acronym">LDAP</acronym> server. See <a class="xref" href="auth-ldap.html" title="21.10. LDAP Authentication">Section 21.10</a> for details.324 </p></dd><dt><span class="term"><code class="literal">radius</code></span></dt><dd><p>325 Authenticate using a RADIUS server. See <a class="xref" href="auth-radius.html" title="21.11. RADIUS Authentication">Section 21.11</a> for details.326 </p></dd><dt><span class="term"><code class="literal">cert</code></span></dt><dd><p>327 Authenticate using SSL client certificates. See328 <a class="xref" href="auth-cert.html" title="21.12. Certificate Authentication">Section 21.12</a> for details.329 </p></dd><dt><span class="term"><code class="literal">pam</code></span></dt><dd><p>330 Authenticate using the Pluggable Authentication Modules331 (PAM) service provided by the operating system. See <a class="xref" href="auth-pam.html" title="21.13. PAM Authentication">Section 21.13</a> for details.332 </p></dd><dt><span class="term"><code class="literal">bsd</code></span></dt><dd><p>333 Authenticate using the BSD Authentication service provided by the334 operating system. See <a class="xref" href="auth-bsd.html" title="21.14. BSD Authentication">Section 21.14</a> for details.335 </p></dd></dl></div><p>336 337 </p></dd><dt><span class="term"><em class="replaceable"><code>auth-options</code></em></span></dt><dd><p>338 After the <em class="replaceable"><code>auth-method</code></em> field, there can be field(s) of339 the form <em class="replaceable"><code>name</code></em><code class="literal">=</code><em class="replaceable"><code>value</code></em> that340 specify options for the authentication method. Details about which341 options are available for which authentication methods appear below.342 </p><p>343 In addition to the method-specific options listed below, there is a344 method-independent authentication option <code class="literal">clientcert</code>, which345 can be specified in any <code class="literal">hostssl</code> record.346 This option can be set to <code class="literal">verify-ca</code> or347 <code class="literal">verify-full</code>. Both options require the client348 to present a valid (trusted) SSL certificate, while349 <code class="literal">verify-full</code> additionally enforces that the350 <code class="literal">cn</code> (Common Name) in the certificate matches351 the username or an applicable mapping.352 This behavior is similar to the <code class="literal">cert</code> authentication353 method (see <a class="xref" href="auth-cert.html" title="21.12. Certificate Authentication">Section 21.12</a>) but enables pairing354 the verification of client certificates with any authentication355 method that supports <code class="literal">hostssl</code> entries.356 </p><p>357 On any record using client certificate authentication (i.e. one358 using the <code class="literal">cert</code> authentication method or one359 using the <code class="literal">clientcert</code> option), you can specify360 which part of the client certificate credentials to match using361 the <code class="literal">clientname</code> option. This option can have one362 of two values. If you specify <code class="literal">clientname=CN</code>, which363 is the default, the username is matched against the certificate's364 <code class="literal">Common Name (CN)</code>. If instead you specify365 <code class="literal">clientname=DN</code> the username is matched against the366 entire <code class="literal">Distinguished Name (DN)</code> of the certificate.367 This option is probably best used in conjunction with a username map.368 The comparison is done with the <code class="literal">DN</code> in369 <a class="ulink" href="https://datatracker.ietf.org/doc/html/rfc2253" target="_top">RFC 2253</a>370 format. To see the <code class="literal">DN</code> of a client certificate371 in this format, do372</p><pre class="programlisting">373openssl x509 -in myclient.crt -noout -subject -nameopt RFC2253 | sed "s/^subject=//"374</pre><p>375 Care needs to be taken when using this option, especially when using376 regular expression matching against the <code class="literal">DN</code>.377 </p></dd><dt><span class="term"><code class="literal">include</code></span></dt><dd><p>378 This line will be replaced by the contents of the given file.379 </p></dd><dt><span class="term"><code class="literal">include_if_exists</code></span></dt><dd><p>380 This line will be replaced by the content of the given file if the381 file exists. Otherwise, a message is logged to indicate that the file382 has been skipped.383 </p></dd><dt><span class="term"><code class="literal">include_dir</code></span></dt><dd><p>384 This line will be replaced by the contents of all the files found in385 the directory, if they don't start with a <code class="literal">.</code> and end386 with <code class="literal">.conf</code>, processed in file name order (according387 to C locale rules, i.e., numbers before letters, and uppercase letters388 before lowercase ones).389 </p></dd></dl></div><p>390 </p><p>391 Files included by <code class="literal">@</code> constructs are read as lists of names,392 which can be separated by either whitespace or commas. Comments are393 introduced by <code class="literal">#</code>, just as in394 <code class="filename">pg_hba.conf</code>, and nested <code class="literal">@</code> constructs are395 allowed. Unless the file name following <code class="literal">@</code> is an absolute396 path, it is taken to be relative to the directory containing the397 referencing file.398 </p><p>399 Since the <code class="filename">pg_hba.conf</code> records are examined400 sequentially for each connection attempt, the order of the records is401 significant. Typically, earlier records will have tight connection402 match parameters and weaker authentication methods, while later403 records will have looser match parameters and stronger authentication404 methods. For example, one might wish to use <code class="literal">trust</code>405 authentication for local TCP/IP connections but require a password for406 remote TCP/IP connections. In this case a record specifying407 <code class="literal">trust</code> authentication for connections from 127.0.0.1 would408 appear before a record specifying password authentication for a wider409 range of allowed client IP addresses.410 </p><p>411 The <code class="filename">pg_hba.conf</code> file is read on start-up and when412 the main server process receives a413 <span class="systemitem">SIGHUP</span><a id="id-1.6.8.8.10.3" class="indexterm"></a>414 signal. If you edit the file on an415 active system, you will need to signal the postmaster416 (using <code class="literal">pg_ctl reload</code>, calling the SQL function417 <code class="function">pg_reload_conf()</code>, or using <code class="literal">kill418 -HUP</code>) to make it re-read the file.419 </p><div class="note"><h3 class="title">Note</h3><p>420 The preceding statement is not true on Microsoft Windows: there, any421 changes in the <code class="filename">pg_hba.conf</code> file are immediately422 applied by subsequent new connections.423 </p></div><p>424 The system view425 <a class="link" href="view-pg-hba-file-rules.html" title="54.9. pg_hba_file_rules"><code class="structname">pg_hba_file_rules</code></a>426 can be helpful for pre-testing changes to the <code class="filename">pg_hba.conf</code>427 file, or for diagnosing problems if loading of the file did not have the428 desired effects. Rows in the view with429 non-null <code class="structfield">error</code> fields indicate problems in the430 corresponding lines of the file.431 </p><div class="tip"><h3 class="title">Tip</h3><p>432 To connect to a particular database, a user must not only pass the433 <code class="filename">pg_hba.conf</code> checks, but must have the434 <code class="literal">CONNECT</code> privilege for the database. If you wish to435 restrict which users can connect to which databases, it's usually436 easier to control this by granting/revoking <code class="literal">CONNECT</code> privilege437 than to put the rules in <code class="filename">pg_hba.conf</code> entries.438 </p></div><p>439 Some examples of <code class="filename">pg_hba.conf</code> entries are shown in440 <a class="xref" href="auth-pg-hba-conf.html#EXAMPLE-PG-HBA.CONF" title="Example 21.1. Example pg_hba.conf Entries">Example 21.1</a>. See the next section for details on the441 different authentication methods.442 </p><div class="example" id="EXAMPLE-PG-HBA.CONF"><p class="title"><strong>Example 21.1. Example <code class="filename">pg_hba.conf</code> Entries</strong></p><div class="example-contents"><pre class="programlisting">443# Allow any user on the local system to connect to any database with444# any database user name using Unix-domain sockets (the default for local445# connections).446#447# TYPE DATABASE USER ADDRESS METHOD448local all all trust449 450# The same using local loopback TCP/IP connections.451#452# TYPE DATABASE USER ADDRESS METHOD453host all all 127.0.0.1/32 trust454 455# The same as the previous line, but using a separate netmask column456#457# TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD458host all all 127.0.0.1 255.255.255.255 trust459 460# The same over IPv6.461#462# TYPE DATABASE USER ADDRESS METHOD463host all all ::1/128 trust464 465# The same using a host name (would typically cover both IPv4 and IPv6).466#467# TYPE DATABASE USER ADDRESS METHOD468host all all localhost trust469 470# The same using a regular expression for DATABASE, that allows connection471# to the database db1, db2 and any databases with a name beginning with "db"472# and finishing with a number using two to four digits (like "db1234" or473# "db12").474#475# TYPE DATABASE USER ADDRESS METHOD476local db1,"/^db\d{2,4}$",db2 all localhost trust477 478# Allow any user from any host with IP address 192.168.93.x to connect479# to database "postgres" as the same user name that ident reports for480# the connection (typically the operating system user name).481#482# TYPE DATABASE USER ADDRESS METHOD483host postgres all 192.168.93.0/24 ident484 485# Allow any user from host 192.168.12.10 to connect to database486# "postgres" if the user's password is correctly supplied.487#488# TYPE DATABASE USER ADDRESS METHOD489host postgres all 192.168.12.10/32 scram-sha-256490 491# Allow any user from hosts in the example.com domain to connect to492# any database if the user's password is correctly supplied.493#494# Require SCRAM authentication for most users, but make an exception495# for user 'mike', who uses an older client that doesn't support SCRAM496# authentication.497#498# TYPE DATABASE USER ADDRESS METHOD499host all mike .example.com md5500host all all .example.com scram-sha-256501 502# In the absence of preceding "host" lines, these three lines will503# reject all connections from 192.168.54.1 (since that entry will be504# matched first), but allow GSSAPI-encrypted connections from anywhere else505# on the Internet. The zero mask causes no bits of the host IP address to506# be considered, so it matches any host. Unencrypted GSSAPI connections507# (which "fall through" to the third line since "hostgssenc" only matches508# encrypted GSSAPI connections) are allowed, but only from 192.168.12.10.509#510# TYPE DATABASE USER ADDRESS METHOD511host all all 192.168.54.1/32 reject512hostgssenc all all 0.0.0.0/0 gss513host all all 192.168.12.10/32 gss514 515# Allow users from 192.168.x.x hosts to connect to any database, if516# they pass the ident check. If, for example, ident says the user is517# "bryanh" and he requests to connect as PostgreSQL user "guest1", the518# connection is allowed if there is an entry in pg_ident.conf for map519# "omicron" that says "bryanh" is allowed to connect as "guest1".520#521# TYPE DATABASE USER ADDRESS METHOD522host all all 192.168.0.0/16 ident map=omicron523 524# If these are the only four lines for local connections, they will525# allow local users to connect only to their own databases (databases526# with the same name as their database user name) except for users whose527# name end with "helpdesk", administrators and members of role "support",528# who can connect to all databases. The file $PGDATA/admins contains a529# list of names of administrators. Passwords are required in all cases.530#531# TYPE DATABASE USER ADDRESS METHOD532local sameuser all md5533local all /^.*helpdesk$ md5534local all @admins md5535local all +support md5536 537# The last two lines above can be combined into a single line:538local all @admins,+support md5539 540# The database column can also use lists and file names:541local db1,db2,@demodbs all md5542</pre></div></div><br class="example-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="client-authentication.html" title="Chapter 21. Client Authentication">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="client-authentication.html" title="Chapter 21. Client Authentication">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="auth-username-maps.html" title="21.2. User Name Maps">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 21. Client Authentication </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 21.2. User Name Maps</td></tr></table></div></body></html>