diff options
Diffstat (limited to 'doc/src/sgml/html/auth-pg-hba-conf.html')
| -rw-r--r-- | doc/src/sgml/html/auth-pg-hba-conf.html | 542 |
1 files changed, 542 insertions, 0 deletions
diff --git a/doc/src/sgml/html/auth-pg-hba-conf.html b/doc/src/sgml/html/auth-pg-hba-conf.html new file mode 100644 index 0000000..a2b8216 --- /dev/null +++ b/doc/src/sgml/html/auth-pg-hba-conf.html @@ -0,0 +1,542 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!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.2 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> + Client authentication is controlled by a configuration file, + which traditionally is named + <code class="filename">pg_hba.conf</code> and is stored in the database + cluster's data directory. + (<acronym class="acronym">HBA</acronym> stands for host-based authentication.) A default + <code class="filename">pg_hba.conf</code> file is installed when the data + directory is initialized by <a class="xref" href="app-initdb.html" title="initdb"><span class="refentrytitle"><span class="application">initdb</span></span></a>. It is + possible to place the authentication configuration file elsewhere, + however; see the <a class="xref" href="runtime-config-file-locations.html#GUC-HBA-FILE">hba_file</a> configuration parameter. + </p><p> + The general format of the <code class="filename">pg_hba.conf</code> file is + a set of records, one per line. Blank lines are ignored, as is any + text after the <code class="literal">#</code> comment character. + A record can be continued onto the next line by ending the line with + a backslash. (Backslashes are not special except at the end of a line.) + A record is made + up of a number of fields which are separated by spaces and/or tabs. + Fields can contain white space if the field value is double-quoted. + Quoting one of the keywords in a database, user, or address field (e.g., + <code class="literal">all</code> or <code class="literal">replication</code>) makes the word lose its special + meaning, and just match a database, user, or host with that name. + Backslash line continuation applies even within quoted text or comments. + </p><p> + Each authentication record specifies a connection type, a client IP address + range (if relevant for the connection type), a database name, a user name, + and the authentication method to be used for connections matching + these parameters. The first record with a matching connection type, + client address, requested database, and user name is used to perform + authentication. There is no <span class="quote">“<span class="quote">fall-through</span>”</span> or + <span class="quote">“<span class="quote">backup</span>”</span>: if one record is chosen and the authentication + fails, subsequent records are not considered. If no record matches, + access is denied. + </p><p> + Each record can be an include directive or an authentication record. + Include directives specify files that can be included, that contain + additional records. The records will be inserted in place of the + include directives. Include directives only contain two fields: + <code class="literal">include</code>, <code class="literal">include_if_exists</code> or + <code class="literal">include_dir</code> directive and the file or directory to be + included. The file or directory can be a relative or absolute path, and can + be double-quoted. For the <code class="literal">include_dir</code> form, all files + not starting with a <code class="literal">.</code> and ending with + <code class="literal">.conf</code> will be included. Multiple files within an include + directory are processed in file name order (according to C locale rules, + i.e., numbers before letters, and uppercase letters before lowercase ones). + </p><p> + A record can have several formats: +</p><pre class="synopsis"> +local <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>] +host <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>] +hostssl <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>] +hostnossl <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>] +hostgssenc <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>] +hostnogssenc <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>] +host <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>] +hostssl <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>] +hostnossl <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>] +hostgssenc <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>] +hostnogssenc <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>] +include <em class="replaceable"><code>file</code></em> +include_if_exists <em class="replaceable"><code>file</code></em> +include_dir <em class="replaceable"><code>directory</code></em> +</pre><p> + The meaning of the fields is as follows: + + </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">local</code></span></dt><dd><p> + This record matches connection attempts using Unix-domain + sockets. Without a record of this type, Unix-domain socket + connections are disallowed. + </p></dd><dt><span class="term"><code class="literal">host</code></span></dt><dd><p> + This record matches connection attempts made using TCP/IP. + <code class="literal">host</code> records match + <acronym class="acronym">SSL</acronym> or non-<acronym class="acronym">SSL</acronym> connection + attempts as well as <acronym class="acronym">GSSAPI</acronym> encrypted or + non-<acronym class="acronym">GSSAPI</acronym> encrypted connection attempts. + </p><div class="note"><h3 class="title">Note</h3><p> + Remote TCP/IP connections will not be possible unless + the server is started with an appropriate value for the + <a class="xref" href="runtime-config-connection.html#GUC-LISTEN-ADDRESSES">listen_addresses</a> configuration parameter, + since the default behavior is to listen for TCP/IP connections + only on the local loopback address <code class="literal">localhost</code>. + </p></div></dd><dt><span class="term"><code class="literal">hostssl</code></span></dt><dd><p> + This record matches connection attempts made using TCP/IP, + but only when the connection is made with <acronym class="acronym">SSL</acronym> + encryption. + </p><p> + To make use of this option the server must be built with + <acronym class="acronym">SSL</acronym> support. Furthermore, + <acronym class="acronym">SSL</acronym> must be enabled + by setting the <a class="xref" href="runtime-config-connection.html#GUC-SSL">ssl</a> configuration parameter (see + <a class="xref" href="ssl-tcp.html" title="19.9. Secure TCP/IP Connections with SSL">Section 19.9</a> for more information). + Otherwise, the <code class="literal">hostssl</code> record is ignored except for + logging a warning that it cannot match any connections. + </p></dd><dt><span class="term"><code class="literal">hostnossl</code></span></dt><dd><p> + This record type has the opposite behavior of <code class="literal">hostssl</code>; + it only matches connection attempts made over + TCP/IP that do not use <acronym class="acronym">SSL</acronym>. + </p></dd><dt><span class="term"><code class="literal">hostgssenc</code></span></dt><dd><p> + This record matches connection attempts made using TCP/IP, + but only when the connection is made with <acronym class="acronym">GSSAPI</acronym> + encryption. + </p><p> + To make use of this option the server must be built with + <acronym class="acronym">GSSAPI</acronym> support. Otherwise, + the <code class="literal">hostgssenc</code> record is ignored except for logging + a warning that it cannot match any connections. + </p></dd><dt><span class="term"><code class="literal">hostnogssenc</code></span></dt><dd><p> + This record type has the opposite behavior of <code class="literal">hostgssenc</code>; + it only matches connection attempts made over + TCP/IP that do not use <acronym class="acronym">GSSAPI</acronym> encryption. + </p></dd><dt><span class="term"><em class="replaceable"><code>database</code></em></span></dt><dd><p> + Specifies which database name(s) this record matches. The value + <code class="literal">all</code> specifies that it matches all databases. + The value <code class="literal">sameuser</code> specifies that the record + matches if the requested database has the same name as the + requested user. The value <code class="literal">samerole</code> specifies that + the requested user must be a member of the role with the same + name as the requested database. (<code class="literal">samegroup</code> is an + obsolete but still accepted spelling of <code class="literal">samerole</code>.) + Superusers are not considered to be members of a role for the + purposes of <code class="literal">samerole</code> unless they are explicitly + members of the role, directly or indirectly, and not just by + virtue of being a superuser. + The value <code class="literal">replication</code> specifies that the record + matches if a physical replication connection is requested, however, it + doesn't match with logical replication connections. Note that physical + replication connections do not specify any particular database whereas + logical replication connections do specify it. + Otherwise, this is the name of a specific + <span class="productname">PostgreSQL</span> database or a regular expression. + Multiple database names and/or regular expressions can be supplied by + separating them with commas. + </p><p> + If the database name starts with a slash (<code class="literal">/</code>), the + remainder of the name is treated as a regular expression. + (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 of + <span class="productname">PostgreSQL</span>'s regular expression syntax.) + </p><p> + A separate file containing database names and/or regular expressions + can be specified by preceding the file name with <code class="literal">@</code>. + </p></dd><dt><span class="term"><em class="replaceable"><code>user</code></em></span></dt><dd><p> + Specifies which database user name(s) this record + matches. The value <code class="literal">all</code> specifies that it + matches all users. Otherwise, this is either the name of a specific + database user, a regular expression (when starting with a slash + (<code class="literal">/</code>), or a group name preceded by <code class="literal">+</code>. + (Recall that there is no real distinction between users and groups + in <span class="productname">PostgreSQL</span>; a <code class="literal">+</code> mark really means + <span class="quote">“<span class="quote">match any of the roles that are directly or indirectly members + of this role</span>”</span>, while a name without a <code class="literal">+</code> mark matches + only that specific role.) For this purpose, a superuser is only + considered to be a member of a role if they are explicitly a member + of the role, directly or indirectly, and not just by virtue of + being a superuser. + Multiple user names and/or regular expressions can be supplied by + separating them with commas. + </p><p> + If the user name starts with a slash (<code class="literal">/</code>), the + remainder of the name is treated as a regular expression. + (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 of + <span class="productname">PostgreSQL</span>'s regular expression syntax.) + </p><p> + A separate file containing user names and/or regular expressions can + be specified by preceding the file name with <code class="literal">@</code>. + </p></dd><dt><span class="term"><em class="replaceable"><code>address</code></em></span></dt><dd><p> + Specifies the client machine address(es) that this record + matches. This field can contain either a host name, an IP + address range, or one of the special key words mentioned below. + </p><p> + An IP address range is specified using standard numeric notation + for the range's starting address, then a slash (<code class="literal">/</code>) + and a <acronym class="acronym">CIDR</acronym> mask length. The mask + length indicates the number of high-order bits of the client + IP address that must match. Bits to the right of this should + be zero in the given IP address. + There must not be any white space between the IP address, the + <code class="literal">/</code>, and the CIDR mask length. + </p><p> + Typical examples of an IPv4 address range specified this way are + <code class="literal">172.20.143.89/32</code> for a single host, or + <code class="literal">172.20.143.0/24</code> for a small network, or + <code class="literal">10.6.0.0/16</code> for a larger one. + An IPv6 address range might look like <code class="literal">::1/128</code> + for a single host (in this case the IPv6 loopback address) or + <code class="literal">fe80::7a31:c1ff:0000:0000/96</code> for a small + network. + <code class="literal">0.0.0.0/0</code> represents all + IPv4 addresses, and <code class="literal">::0/0</code> represents + all IPv6 addresses. + To specify a single host, use a mask length of 32 for IPv4 or + 128 for IPv6. In a network address, do not omit trailing zeroes. + </p><p> + An entry given in IPv4 format will match only IPv4 connections, + and an entry given in IPv6 format will match only IPv6 connections, + even if the represented address is in the IPv4-in-IPv6 range. + </p><p> + You can also write <code class="literal">all</code> to match any IP address, + <code class="literal">samehost</code> to match any of the server's own IP + addresses, or <code class="literal">samenet</code> to match any address in any + subnet that the server is directly connected to. + </p><p> + If a host name is specified (anything that is not an IP address + range or a special key word is treated as a host name), + that name is compared with the result of a reverse name + resolution of the client's IP address (e.g., reverse DNS + lookup, if DNS is used). Host name comparisons are case + insensitive. If there is a match, then a forward name + resolution (e.g., forward DNS lookup) is performed on the host + name to check whether any of the addresses it resolves to are + equal to the client's IP address. If both directions match, + then the entry is considered to match. (The host name that is + used in <code class="filename">pg_hba.conf</code> should be the one that + address-to-name resolution of the client's IP address returns, + otherwise the line won't be matched. Some host name databases + allow associating an IP address with multiple host names, but + the operating system will only return one host name when asked + to resolve an IP address.) + </p><p> + A host name specification that starts with a dot + (<code class="literal">.</code>) matches a suffix of the actual host + name. So <code class="literal">.example.com</code> would match + <code class="literal">foo.example.com</code> (but not just + <code class="literal">example.com</code>). + </p><p> + When host names are specified + in <code class="filename">pg_hba.conf</code>, you should make sure that + name resolution is reasonably fast. It can be of advantage to + set up a local name resolution cache such + as <code class="command">nscd</code>. Also, you may wish to enable the + configuration parameter <code class="varname">log_hostname</code> to see + the client's host name instead of the IP address in the log. + </p><p> + These fields do not apply to <code class="literal">local</code> records. + </p><div class="note"><h3 class="title">Note</h3><p> + Users sometimes wonder why host names are handled + in this seemingly complicated way, with two name resolutions + including a reverse lookup of the client's IP address. This + complicates use of the feature in case the client's reverse DNS + entry is not set up or yields some undesirable host name. + It is done primarily for efficiency: this way, a connection attempt + requires at most two resolver lookups, one reverse and one forward. + If there is a resolver problem with some address, it becomes only + that client's problem. A hypothetical alternative + implementation that only did forward lookups would have to + resolve every host name mentioned in + <code class="filename">pg_hba.conf</code> during every connection attempt. + That could be quite slow if many names are listed. + And if there is a resolver problem with one of the host names, + it becomes everyone's problem. + </p><p> + Also, a reverse lookup is necessary to implement the suffix + matching feature, because the actual client host name needs to + be known in order to match it against the pattern. + </p><p> + Note that this behavior is consistent with other popular + implementations of host name-based access control, such as the + Apache HTTP Server and TCP Wrappers. + </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> + These two fields can be used as an alternative to the + <em class="replaceable"><code>IP-address</code></em><code class="literal">/</code><em class="replaceable"><code>mask-length</code></em> + notation. Instead of + specifying the mask length, the actual mask is specified in a + separate column. For example, <code class="literal">255.0.0.0</code> represents an IPv4 + CIDR mask length of 8, and <code class="literal">255.255.255.255</code> represents a + CIDR mask length of 32. + </p><p> + These fields do not apply to <code class="literal">local</code> records. + </p></dd><dt><span class="term"><em class="replaceable"><code>auth-method</code></em></span></dt><dd><p> + Specifies the authentication method to use when a connection matches + this record. The possible choices are summarized here; details + are in <a class="xref" href="auth-methods.html" title="21.3. Authentication Methods">Section 21.3</a>. All the options + are lower case and treated case sensitively, so even acronyms like + <code class="literal">ldap</code> must be specified as lower case. + + </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">trust</code></span></dt><dd><p> + Allow the connection unconditionally. This method + allows anyone that can connect to the + <span class="productname">PostgreSQL</span> database server to login as + any <span class="productname">PostgreSQL</span> user they wish, + 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. + </p></dd><dt><span class="term"><code class="literal">reject</code></span></dt><dd><p> + Reject the connection unconditionally. This is useful for + <span class="quote">“<span class="quote">filtering out</span>”</span> certain hosts from a group, for example a + <code class="literal">reject</code> line could block a specific host from connecting, + while a later line allows the remaining hosts in a specific + network to connect. + </p></dd><dt><span class="term"><code class="literal">scram-sha-256</code></span></dt><dd><p> + Perform SCRAM-SHA-256 authentication to verify the user's + password. See <a class="xref" href="auth-password.html" title="21.5. Password Authentication">Section 21.5</a> for details. + </p></dd><dt><span class="term"><code class="literal">md5</code></span></dt><dd><p> + Perform SCRAM-SHA-256 or MD5 authentication to verify the + user's password. See <a class="xref" href="auth-password.html" title="21.5. Password Authentication">Section 21.5</a> + for details. + </p></dd><dt><span class="term"><code class="literal">password</code></span></dt><dd><p> + Require the client to supply an unencrypted password for + authentication. + Since the password is sent in clear text over the + network, this should not be used on untrusted networks. + See <a class="xref" href="auth-password.html" title="21.5. Password Authentication">Section 21.5</a> for details. + </p></dd><dt><span class="term"><code class="literal">gss</code></span></dt><dd><p> + Use GSSAPI to authenticate the user. This is only + 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 conjunction + with GSSAPI encryption. + </p></dd><dt><span class="term"><code class="literal">sspi</code></span></dt><dd><p> + Use SSPI to authenticate the user. This is only + available on Windows. See <a class="xref" href="sspi-auth.html" title="21.7. SSPI Authentication">Section 21.7</a> for details. + </p></dd><dt><span class="term"><code class="literal">ident</code></span></dt><dd><p> + Obtain the operating system user name of the client + by contacting the ident server on the client + and check if it matches the requested database user name. + Ident authentication can only be used on TCP/IP + connections. When specified for local connections, peer + authentication will be used instead. + See <a class="xref" href="auth-ident.html" title="21.8. Ident Authentication">Section 21.8</a> for details. + </p></dd><dt><span class="term"><code class="literal">peer</code></span></dt><dd><p> + Obtain the client's operating system user name from the operating + system and check if it matches the requested database user name. + This is only available for local connections. + See <a class="xref" href="auth-peer.html" title="21.9. Peer Authentication">Section 21.9</a> for details. + </p></dd><dt><span class="term"><code class="literal">ldap</code></span></dt><dd><p> + 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. + </p></dd><dt><span class="term"><code class="literal">radius</code></span></dt><dd><p> + Authenticate using a RADIUS server. See <a class="xref" href="auth-radius.html" title="21.11. RADIUS Authentication">Section 21.11</a> for details. + </p></dd><dt><span class="term"><code class="literal">cert</code></span></dt><dd><p> + Authenticate using SSL client certificates. See + <a class="xref" href="auth-cert.html" title="21.12. Certificate Authentication">Section 21.12</a> for details. + </p></dd><dt><span class="term"><code class="literal">pam</code></span></dt><dd><p> + Authenticate using the Pluggable Authentication Modules + (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. + </p></dd><dt><span class="term"><code class="literal">bsd</code></span></dt><dd><p> + Authenticate using the BSD Authentication service provided by the + operating system. See <a class="xref" href="auth-bsd.html" title="21.14. BSD Authentication">Section 21.14</a> for details. + </p></dd></dl></div><p> + + </p></dd><dt><span class="term"><em class="replaceable"><code>auth-options</code></em></span></dt><dd><p> + After the <em class="replaceable"><code>auth-method</code></em> field, there can be field(s) of + the form <em class="replaceable"><code>name</code></em><code class="literal">=</code><em class="replaceable"><code>value</code></em> that + specify options for the authentication method. Details about which + options are available for which authentication methods appear below. + </p><p> + In addition to the method-specific options listed below, there is a + method-independent authentication option <code class="literal">clientcert</code>, which + can be specified in any <code class="literal">hostssl</code> record. + This option can be set to <code class="literal">verify-ca</code> or + <code class="literal">verify-full</code>. Both options require the client + to present a valid (trusted) SSL certificate, while + <code class="literal">verify-full</code> additionally enforces that the + <code class="literal">cn</code> (Common Name) in the certificate matches + the username or an applicable mapping. + This behavior is similar to the <code class="literal">cert</code> authentication + method (see <a class="xref" href="auth-cert.html" title="21.12. Certificate Authentication">Section 21.12</a>) but enables pairing + the verification of client certificates with any authentication + method that supports <code class="literal">hostssl</code> entries. + </p><p> + On any record using client certificate authentication (i.e. one + using the <code class="literal">cert</code> authentication method or one + using the <code class="literal">clientcert</code> option), you can specify + which part of the client certificate credentials to match using + the <code class="literal">clientname</code> option. This option can have one + of two values. If you specify <code class="literal">clientname=CN</code>, which + is the default, the username is matched against the certificate's + <code class="literal">Common Name (CN)</code>. If instead you specify + <code class="literal">clientname=DN</code> the username is matched against the + entire <code class="literal">Distinguished Name (DN)</code> of the certificate. + This option is probably best used in conjunction with a username map. + The comparison is done with the <code class="literal">DN</code> in + <a class="ulink" href="https://tools.ietf.org/html/rfc2253" target="_top">RFC 2253</a> + format. To see the <code class="literal">DN</code> of a client certificate + in this format, do +</p><pre class="programlisting"> +openssl x509 -in myclient.crt -noout -subject -nameopt RFC2253 | sed "s/^subject=//" +</pre><p> + Care needs to be taken when using this option, especially when using + regular expression matching against the <code class="literal">DN</code>. + </p></dd><dt><span class="term"><code class="literal">include</code></span></dt><dd><p> + This line will be replaced by the contents of the given file. + </p></dd><dt><span class="term"><code class="literal">include_if_exists</code></span></dt><dd><p> + This line will be replaced by the content of the given file if the + file exists. Otherwise, a message is logged to indicate that the file + has been skipped. + </p></dd><dt><span class="term"><code class="literal">include_dir</code></span></dt><dd><p> + This line will be replaced by the contents of all the files found in + the directory, if they don't start with a <code class="literal">.</code> and end + with <code class="literal">.conf</code>, processed in file name order (according + to C locale rules, i.e., numbers before letters, and uppercase letters + before lowercase ones). + </p></dd></dl></div><p> + </p><p> + Files included by <code class="literal">@</code> constructs are read as lists of names, + which can be separated by either whitespace or commas. Comments are + introduced by <code class="literal">#</code>, just as in + <code class="filename">pg_hba.conf</code>, and nested <code class="literal">@</code> constructs are + allowed. Unless the file name following <code class="literal">@</code> is an absolute + path, it is taken to be relative to the directory containing the + referencing file. + </p><p> + Since the <code class="filename">pg_hba.conf</code> records are examined + sequentially for each connection attempt, the order of the records is + significant. Typically, earlier records will have tight connection + match parameters and weaker authentication methods, while later + records will have looser match parameters and stronger authentication + methods. For example, one might wish to use <code class="literal">trust</code> + authentication for local TCP/IP connections but require a password for + remote TCP/IP connections. In this case a record specifying + <code class="literal">trust</code> authentication for connections from 127.0.0.1 would + appear before a record specifying password authentication for a wider + range of allowed client IP addresses. + </p><p> + The <code class="filename">pg_hba.conf</code> file is read on start-up and when + the main server process receives a + <span class="systemitem">SIGHUP</span><a id="id-1.6.8.8.10.3" class="indexterm"></a> + signal. If you edit the file on an + active system, you will need to signal the postmaster + (using <code class="literal">pg_ctl reload</code>, calling the SQL function + <code class="function">pg_reload_conf()</code>, or using <code class="literal">kill + -HUP</code>) to make it re-read the file. + </p><div class="note"><h3 class="title">Note</h3><p> + The preceding statement is not true on Microsoft Windows: there, any + changes in the <code class="filename">pg_hba.conf</code> file are immediately + applied by subsequent new connections. + </p></div><p> + The system view + <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> + can be helpful for pre-testing changes to the <code class="filename">pg_hba.conf</code> + file, or for diagnosing problems if loading of the file did not have the + desired effects. Rows in the view with + non-null <code class="structfield">error</code> fields indicate problems in the + corresponding lines of the file. + </p><div class="tip"><h3 class="title">Tip</h3><p> + To connect to a particular database, a user must not only pass the + <code class="filename">pg_hba.conf</code> checks, but must have the + <code class="literal">CONNECT</code> privilege for the database. If you wish to + restrict which users can connect to which databases, it's usually + easier to control this by granting/revoking <code class="literal">CONNECT</code> privilege + than to put the rules in <code class="filename">pg_hba.conf</code> entries. + </p></div><p> + Some examples of <code class="filename">pg_hba.conf</code> entries are shown in + <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 the + different authentication methods. + </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"> +# 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 the database db1, db2 and 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 +local db1,"/^db\d{2,4}$",db2 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 +</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.2 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 21.2. User Name Maps</td></tr></table></div></body></html>
\ No newline at end of file |