diff options
Diffstat (limited to 'doc/src/sgml/html/runtime-config-connection.html')
| -rw-r--r-- | doc/src/sgml/html/runtime-config-connection.html | 582 |
1 files changed, 582 insertions, 0 deletions
diff --git a/doc/src/sgml/html/runtime-config-connection.html b/doc/src/sgml/html/runtime-config-connection.html new file mode 100644 index 0000000..46aa012 --- /dev/null +++ b/doc/src/sgml/html/runtime-config-connection.html @@ -0,0 +1,582 @@ +<?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>20.3. Connections and Authentication</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="runtime-config-file-locations.html" title="20.2. File Locations" /><link rel="next" href="runtime-config-resource.html" title="20.4. Resource Consumption" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">20.3. Connections and Authentication</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="runtime-config-file-locations.html" title="20.2. File Locations">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><th width="60%" align="center">Chapter 20. Server Configuration</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="runtime-config-resource.html" title="20.4. Resource Consumption">Next</a></td></tr></table><hr /></div><div class="sect1" id="RUNTIME-CONFIG-CONNECTION"><div class="titlepage"><div><div><h2 class="title" style="clear: both">20.3. Connections and Authentication <a href="#RUNTIME-CONFIG-CONNECTION" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SETTINGS">20.3.1. Connection Settings</a></span></dt><dt><span class="sect2"><a href="runtime-config-connection.html#RUNTIME-CONFIG-TCP-SETTINGS">20.3.2. TCP Settings</a></span></dt><dt><span class="sect2"><a href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-AUTHENTICATION">20.3.3. Authentication</a></span></dt><dt><span class="sect2"><a href="runtime-config-connection.html#RUNTIME-CONFIG-CONNECTION-SSL">20.3.4. SSL</a></span></dt></dl></div><div class="sect2" id="RUNTIME-CONFIG-CONNECTION-SETTINGS"><div class="titlepage"><div><div><h3 class="title">20.3.1. Connection Settings <a href="#RUNTIME-CONFIG-CONNECTION-SETTINGS" class="id_link">#</a></h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt id="GUC-LISTEN-ADDRESSES"><span class="term"><code class="varname">listen_addresses</code> (<code class="type">string</code>) + <a id="id-1.6.7.6.2.2.1.1.3" class="indexterm"></a> + </span> <a href="#GUC-LISTEN-ADDRESSES" class="id_link">#</a></dt><dd><p> + Specifies the TCP/IP address(es) on which the server is + to listen for connections from client applications. + The value takes the form of a comma-separated list of host names + and/or numeric IP addresses. The special entry <code class="literal">*</code> + corresponds to all available IP interfaces. The entry + <code class="literal">0.0.0.0</code> allows listening for all IPv4 addresses and + <code class="literal">::</code> allows listening for all IPv6 addresses. + If the list is empty, the server does not listen on any IP interface + at all, in which case only Unix-domain sockets can be used to connect + to it. If the list is not empty, the server will start if it + can listen on at least one TCP/IP address. A warning will be + emitted for any TCP/IP address which cannot be opened. + The default value is <span class="systemitem">localhost</span>, + which allows only local TCP/IP <span class="quote">“<span class="quote">loopback</span>”</span> connections to be + made. + </p><p> + While client authentication (<a class="xref" href="client-authentication.html" title="Chapter 21. Client Authentication">Chapter 21</a>) allows fine-grained control + over who can access the server, <code class="varname">listen_addresses</code> + controls which interfaces accept connection attempts, which + can help prevent repeated malicious connection requests on + insecure network interfaces. This parameter can only be set + at server start. + </p></dd><dt id="GUC-PORT"><span class="term"><code class="varname">port</code> (<code class="type">integer</code>) + <a id="id-1.6.7.6.2.2.2.1.3" class="indexterm"></a> + </span> <a href="#GUC-PORT" class="id_link">#</a></dt><dd><p> + The TCP port the server listens on; 5432 by default. Note that the + same port number is used for all IP addresses the server listens on. + This parameter can only be set at server start. + </p></dd><dt id="GUC-MAX-CONNECTIONS"><span class="term"><code class="varname">max_connections</code> (<code class="type">integer</code>) + <a id="id-1.6.7.6.2.2.3.1.3" class="indexterm"></a> + </span> <a href="#GUC-MAX-CONNECTIONS" class="id_link">#</a></dt><dd><p> + Determines the maximum number of concurrent connections to the + database server. The default is typically 100 connections, but + might be less if your kernel settings will not support it (as + determined during <span class="application">initdb</span>). This parameter can + only be set at server start. + </p><p> + When running a standby server, you must set this parameter to the + same or higher value than on the primary server. Otherwise, queries + will not be allowed in the standby server. + </p></dd><dt id="GUC-RESERVED-CONNECTIONS"><span class="term"><code class="varname">reserved_connections</code> (<code class="type">integer</code>) + <a id="id-1.6.7.6.2.2.4.1.3" class="indexterm"></a> + </span> <a href="#GUC-RESERVED-CONNECTIONS" class="id_link">#</a></dt><dd><p> + Determines the number of connection <span class="quote">“<span class="quote">slots</span>”</span> that are + reserved for connections by roles with privileges of the + <a class="link" href="predefined-roles.html#PREDEFINED-ROLES-TABLE" title="Table 22.1. Predefined Roles"><code class="literal">pg_use_reserved_connections</code></a> + role. Whenever the number of free connection slots is greater than + <a class="xref" href="runtime-config-connection.html#GUC-SUPERUSER-RESERVED-CONNECTIONS">superuser_reserved_connections</a> but less than or + equal to the sum of <code class="varname">superuser_reserved_connections</code> + and <code class="varname">reserved_connections</code>, new connections will be + accepted only for superusers and roles with privileges of + <code class="literal">pg_use_reserved_connections</code>. If + <code class="varname">superuser_reserved_connections</code> or fewer connection + slots are available, new connections will be accepted only for + superusers. + </p><p> + The default value is zero connections. The value must be less than + <code class="varname">max_connections</code> minus + <code class="varname">superuser_reserved_connections</code>. This parameter can + only be set at server start. + </p></dd><dt id="GUC-SUPERUSER-RESERVED-CONNECTIONS"><span class="term"><code class="varname">superuser_reserved_connections</code> + (<code class="type">integer</code>) + <a id="id-1.6.7.6.2.2.5.1.3" class="indexterm"></a> + </span> <a href="#GUC-SUPERUSER-RESERVED-CONNECTIONS" class="id_link">#</a></dt><dd><p> + Determines the number of connection <span class="quote">“<span class="quote">slots</span>”</span> that + are reserved for connections by <span class="productname">PostgreSQL</span> + superusers. At most <a class="xref" href="runtime-config-connection.html#GUC-MAX-CONNECTIONS">max_connections</a> + connections can ever be active simultaneously. Whenever the + number of active concurrent connections is at least + <code class="varname">max_connections</code> minus + <code class="varname">superuser_reserved_connections</code>, new + connections will be accepted only for superusers. The connection slots + reserved by this parameter are intended as final reserve for emergency + use after the slots reserved by + <a class="xref" href="runtime-config-connection.html#GUC-RESERVED-CONNECTIONS">reserved_connections</a> have been exhausted. + </p><p> + The default value is three connections. The value must be less + than <code class="varname">max_connections</code> minus + <code class="varname">reserved_connections</code>. + This parameter can only be set at server start. + </p></dd><dt id="GUC-UNIX-SOCKET-DIRECTORIES"><span class="term"><code class="varname">unix_socket_directories</code> (<code class="type">string</code>) + <a id="id-1.6.7.6.2.2.6.1.3" class="indexterm"></a> + </span> <a href="#GUC-UNIX-SOCKET-DIRECTORIES" class="id_link">#</a></dt><dd><p> + Specifies the directory of the Unix-domain socket(s) on which the + server is to listen for connections from client applications. + Multiple sockets can be created by listing multiple directories + separated by commas. Whitespace between entries is + ignored; surround a directory name with double quotes if you need + to include whitespace or commas in the name. + An empty value + specifies not listening on any Unix-domain sockets, in which case + only TCP/IP sockets can be used to connect to the server. + </p><p> + A value that starts with <code class="literal">@</code> specifies that a + Unix-domain socket in the abstract namespace should be created + (currently supported on Linux only). In that case, this value + does not specify a <span class="quote">“<span class="quote">directory</span>”</span> but a prefix from which + the actual socket name is computed in the same manner as for the + file-system namespace. While the abstract socket name prefix can be + chosen freely, since it is not a file-system location, the convention + is to nonetheless use file-system-like values such as + <code class="literal">@/tmp</code>. + </p><p> + The default value is normally + <code class="filename">/tmp</code>, but that can be changed at build time. + On Windows, the default is empty, which means no Unix-domain socket is + created by default. + This parameter can only be set at server start. + </p><p> + In addition to the socket file itself, which is named + <code class="literal">.s.PGSQL.<em class="replaceable"><code>nnnn</code></em></code> where + <em class="replaceable"><code>nnnn</code></em> is the server's port number, an ordinary file + named <code class="literal">.s.PGSQL.<em class="replaceable"><code>nnnn</code></em>.lock</code> will be + created in each of the <code class="varname">unix_socket_directories</code> directories. + Neither file should ever be removed manually. + For sockets in the abstract namespace, no lock file is created. + </p></dd><dt id="GUC-UNIX-SOCKET-GROUP"><span class="term"><code class="varname">unix_socket_group</code> (<code class="type">string</code>) + <a id="id-1.6.7.6.2.2.7.1.3" class="indexterm"></a> + </span> <a href="#GUC-UNIX-SOCKET-GROUP" class="id_link">#</a></dt><dd><p> + Sets the owning group of the Unix-domain socket(s). (The owning + user of the sockets is always the user that starts the + server.) In combination with the parameter + <code class="varname">unix_socket_permissions</code> this can be used as + an additional access control mechanism for Unix-domain connections. + By default this is the empty string, which uses the default + group of the server user. This parameter can only be set at + server start. + </p><p> + This parameter is not supported on Windows. Any setting will be + ignored. Also, sockets in the abstract namespace have no file owner, + so this setting is also ignored in that case. + </p></dd><dt id="GUC-UNIX-SOCKET-PERMISSIONS"><span class="term"><code class="varname">unix_socket_permissions</code> (<code class="type">integer</code>) + <a id="id-1.6.7.6.2.2.8.1.3" class="indexterm"></a> + </span> <a href="#GUC-UNIX-SOCKET-PERMISSIONS" class="id_link">#</a></dt><dd><p> + Sets the access permissions of the Unix-domain socket(s). Unix-domain + sockets use the usual Unix file system permission set. + The parameter value is expected to be a numeric mode + specified in the format accepted by the + <code class="function">chmod</code> and <code class="function">umask</code> + system calls. (To use the customary octal format the number + must start with a <code class="literal">0</code> (zero).) + </p><p> + The default permissions are <code class="literal">0777</code>, meaning + anyone can connect. Reasonable alternatives are + <code class="literal">0770</code> (only user and group, see also + <code class="varname">unix_socket_group</code>) and <code class="literal">0700</code> + (only user). (Note that for a Unix-domain socket, only write + permission matters, so there is no point in setting or revoking + read or execute permissions.) + </p><p> + This access control mechanism is independent of the one + described in <a class="xref" href="client-authentication.html" title="Chapter 21. Client Authentication">Chapter 21</a>. + </p><p> + This parameter can only be set at server start. + </p><p> + This parameter is irrelevant on systems, notably Solaris as of Solaris + 10, that ignore socket permissions entirely. There, one can achieve a + similar effect by pointing <code class="varname">unix_socket_directories</code> to a + directory having search permission limited to the desired audience. + </p><p> + Sockets in the abstract namespace have no file permissions, so this + setting is also ignored in that case. + </p></dd><dt id="GUC-BONJOUR"><span class="term"><code class="varname">bonjour</code> (<code class="type">boolean</code>) + <a id="id-1.6.7.6.2.2.9.1.3" class="indexterm"></a> + </span> <a href="#GUC-BONJOUR" class="id_link">#</a></dt><dd><p> + Enables advertising the server's existence via + <span class="productname">Bonjour</span>. The default is off. + This parameter can only be set at server start. + </p></dd><dt id="GUC-BONJOUR-NAME"><span class="term"><code class="varname">bonjour_name</code> (<code class="type">string</code>) + <a id="id-1.6.7.6.2.2.10.1.3" class="indexterm"></a> + </span> <a href="#GUC-BONJOUR-NAME" class="id_link">#</a></dt><dd><p> + Specifies the <span class="productname">Bonjour</span> service + name. The computer name is used if this parameter is set to the + empty string <code class="literal">''</code> (which is the default). This parameter is + ignored if the server was not compiled with + <span class="productname">Bonjour</span> support. + This parameter can only be set at server start. + </p></dd></dl></div></div><div class="sect2" id="RUNTIME-CONFIG-TCP-SETTINGS"><div class="titlepage"><div><div><h3 class="title">20.3.2. TCP Settings <a href="#RUNTIME-CONFIG-TCP-SETTINGS" class="id_link">#</a></h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt id="GUC-TCP-KEEPALIVES-IDLE"><span class="term"><code class="varname">tcp_keepalives_idle</code> (<code class="type">integer</code>) + <a id="id-1.6.7.6.3.2.1.1.3" class="indexterm"></a> + </span> <a href="#GUC-TCP-KEEPALIVES-IDLE" class="id_link">#</a></dt><dd><p> + Specifies the amount of time with no network activity after which + the operating system should send a TCP keepalive message to the client. + If this value is specified without units, it is taken as seconds. + A value of 0 (the default) selects the operating system's default. + On Windows, setting a value of 0 will set this parameter to 2 hours, + since Windows does not provide a way to read the system default value. + This parameter is supported only on systems that support + <code class="symbol">TCP_KEEPIDLE</code> or an equivalent socket option, and on + Windows; on other systems, it must be zero. + In sessions connected via a Unix-domain socket, this parameter is + ignored and always reads as zero. + </p></dd><dt id="GUC-TCP-KEEPALIVES-INTERVAL"><span class="term"><code class="varname">tcp_keepalives_interval</code> (<code class="type">integer</code>) + <a id="id-1.6.7.6.3.2.2.1.3" class="indexterm"></a> + </span> <a href="#GUC-TCP-KEEPALIVES-INTERVAL" class="id_link">#</a></dt><dd><p> + Specifies the amount of time after which a TCP keepalive message + that has not been acknowledged by the client should be retransmitted. + If this value is specified without units, it is taken as seconds. + A value of 0 (the default) selects the operating system's default. + On Windows, setting a value of 0 will set this parameter to 1 second, + since Windows does not provide a way to read the system default value. + This parameter is supported only on systems that support + <code class="symbol">TCP_KEEPINTVL</code> or an equivalent socket option, and on + Windows; on other systems, it must be zero. + In sessions connected via a Unix-domain socket, this parameter is + ignored and always reads as zero. + </p></dd><dt id="GUC-TCP-KEEPALIVES-COUNT"><span class="term"><code class="varname">tcp_keepalives_count</code> (<code class="type">integer</code>) + <a id="id-1.6.7.6.3.2.3.1.3" class="indexterm"></a> + </span> <a href="#GUC-TCP-KEEPALIVES-COUNT" class="id_link">#</a></dt><dd><p> + Specifies the number of TCP keepalive messages that can be lost before + the server's connection to the client is considered dead. + A value of 0 (the default) selects the operating system's default. + This parameter is supported only on systems that support + <code class="symbol">TCP_KEEPCNT</code> or an equivalent socket option (which does not include Windows); + on other systems, it must be zero. + In sessions connected via a Unix-domain socket, this parameter is + ignored and always reads as zero. + </p></dd><dt id="GUC-TCP-USER-TIMEOUT"><span class="term"><code class="varname">tcp_user_timeout</code> (<code class="type">integer</code>) + <a id="id-1.6.7.6.3.2.4.1.3" class="indexterm"></a> + </span> <a href="#GUC-TCP-USER-TIMEOUT" class="id_link">#</a></dt><dd><p> + Specifies the amount of time that transmitted data may + remain unacknowledged before the TCP connection is forcibly closed. + If this value is specified without units, it is taken as milliseconds. + A value of 0 (the default) selects the operating system's default. + This parameter is supported only on systems that support + <code class="symbol">TCP_USER_TIMEOUT</code> (which does not include Windows); on other systems, it must be zero. + In sessions connected via a Unix-domain socket, this parameter is + ignored and always reads as zero. + </p></dd><dt id="GUC-CLIENT-CONNECTION-CHECK-INTERVAL"><span class="term"><code class="varname">client_connection_check_interval</code> (<code class="type">integer</code>) + <a id="id-1.6.7.6.3.2.5.1.3" class="indexterm"></a> + </span> <a href="#GUC-CLIENT-CONNECTION-CHECK-INTERVAL" class="id_link">#</a></dt><dd><p> + Sets the time interval between optional checks that the client is still + connected, while running queries. The check is performed by polling + the socket, and allows long running queries to be aborted sooner if + the kernel reports that the connection is closed. + </p><p> + This option relies on kernel events exposed by Linux, macOS, illumos + and the BSD family of operating systems, and is not currently available + on other systems. + </p><p> + If the value is specified without units, it is taken as milliseconds. + The default value is <code class="literal">0</code>, which disables connection + checks. Without connection checks, the server will detect the loss of + the connection only at the next interaction with the socket, when it + waits for, receives or sends data. + </p><p> + For the kernel itself to detect lost TCP connections reliably and within + a known timeframe in all scenarios including network failure, it may + also be necessary to adjust the TCP keepalive settings of the operating + system, or the <a class="xref" href="runtime-config-connection.html#GUC-TCP-KEEPALIVES-IDLE">tcp_keepalives_idle</a>, + <a class="xref" href="runtime-config-connection.html#GUC-TCP-KEEPALIVES-INTERVAL">tcp_keepalives_interval</a> and + <a class="xref" href="runtime-config-connection.html#GUC-TCP-KEEPALIVES-COUNT">tcp_keepalives_count</a> settings of + <span class="productname">PostgreSQL</span>. + </p></dd></dl></div></div><div class="sect2" id="RUNTIME-CONFIG-CONNECTION-AUTHENTICATION"><div class="titlepage"><div><div><h3 class="title">20.3.3. Authentication <a href="#RUNTIME-CONFIG-CONNECTION-AUTHENTICATION" class="id_link">#</a></h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt id="GUC-AUTHENTICATION-TIMEOUT"><span class="term"><code class="varname">authentication_timeout</code> (<code class="type">integer</code>) + <a id="id-1.6.7.6.4.2.1.1.3" class="indexterm"></a> + <a id="id-1.6.7.6.4.2.1.1.4" class="indexterm"></a> + <a id="id-1.6.7.6.4.2.1.1.5" class="indexterm"></a> + </span> <a href="#GUC-AUTHENTICATION-TIMEOUT" class="id_link">#</a></dt><dd><p> + Maximum amount of time allowed to complete client authentication. If a + would-be client has not completed the authentication protocol in + this much time, the server closes the connection. This prevents + hung clients from occupying a connection indefinitely. + If this value is specified without units, it is taken as seconds. + The default is one minute (<code class="literal">1m</code>). + This parameter can only be set in the <code class="filename">postgresql.conf</code> + file or on the server command line. + </p></dd><dt id="GUC-PASSWORD-ENCRYPTION"><span class="term"><code class="varname">password_encryption</code> (<code class="type">enum</code>) + <a id="id-1.6.7.6.4.2.2.1.3" class="indexterm"></a> + </span> <a href="#GUC-PASSWORD-ENCRYPTION" class="id_link">#</a></dt><dd><p> + When a password is specified in <a class="xref" href="sql-createrole.html" title="CREATE ROLE"><span class="refentrytitle">CREATE ROLE</span></a> or + <a class="xref" href="sql-alterrole.html" title="ALTER ROLE"><span class="refentrytitle">ALTER ROLE</span></a>, this parameter determines the + algorithm to use to encrypt the password. Possible values are + <code class="literal">scram-sha-256</code>, which will encrypt the password with + SCRAM-SHA-256, and <code class="literal">md5</code>, which stores the password + as an MD5 hash. The default is <code class="literal">scram-sha-256</code>. + </p><p> + Note that older clients might lack support for the SCRAM authentication + mechanism, and hence not work with passwords encrypted with + SCRAM-SHA-256. See <a class="xref" href="auth-password.html" title="21.5. Password Authentication">Section 21.5</a> for more details. + </p></dd><dt id="GUC-SCRAM-ITERATIONS"><span class="term"><code class="varname">scram_iterations</code> (<code class="type">integer</code>) + <a id="id-1.6.7.6.4.2.3.1.3" class="indexterm"></a> + </span> <a href="#GUC-SCRAM-ITERATIONS" class="id_link">#</a></dt><dd><p> + The number of computational iterations to be performed when encrypting + a password using SCRAM-SHA-256. The default is <code class="literal">4096</code>. + A higher number of iterations provides additional protection against + brute-force attacks on stored passwords, but makes authentication + slower. Changing the value has no effect on existing passwords + encrypted with SCRAM-SHA-256 as the iteration count is fixed at the + time of encryption. In order to make use of a changed value, a new + password must be set. + </p></dd><dt id="GUC-KRB-SERVER-KEYFILE"><span class="term"><code class="varname">krb_server_keyfile</code> (<code class="type">string</code>) + <a id="id-1.6.7.6.4.2.4.1.3" class="indexterm"></a> + </span> <a href="#GUC-KRB-SERVER-KEYFILE" class="id_link">#</a></dt><dd><p> + Sets the location of the server's Kerberos key file. The default is + <code class="filename">FILE:/usr/local/pgsql/etc/krb5.keytab</code> + (where the directory part is whatever was specified + as <code class="varname">sysconfdir</code> at build time; use + <code class="literal">pg_config --sysconfdir</code> to determine that). + If this parameter is set to an empty string, it is ignored and a + system-dependent default is used. + This parameter can only be set in the + <code class="filename">postgresql.conf</code> file or on the server command line. + See <a class="xref" href="gssapi-auth.html" title="21.6. GSSAPI Authentication">Section 21.6</a> for more information. + </p></dd><dt id="GUC-KRB-CASEINS-USERS"><span class="term"><code class="varname">krb_caseins_users</code> (<code class="type">boolean</code>) + <a id="id-1.6.7.6.4.2.5.1.3" class="indexterm"></a> + </span> <a href="#GUC-KRB-CASEINS-USERS" class="id_link">#</a></dt><dd><p> + Sets whether GSSAPI user names should be treated + case-insensitively. + The default is <code class="literal">off</code> (case sensitive). This parameter can only be + set in the <code class="filename">postgresql.conf</code> file or on the server command line. + </p></dd><dt id="GUC-GSS-ACCEPT-DELEGATION"><span class="term"><code class="varname">gss_accept_delegation</code> (<code class="type">boolean</code>) + <a id="id-1.6.7.6.4.2.6.1.3" class="indexterm"></a> + </span> <a href="#GUC-GSS-ACCEPT-DELEGATION" class="id_link">#</a></dt><dd><p> + Sets whether GSSAPI delegation should be accepted from the client. + The default is <code class="literal">off</code> meaning credentials from the client will + <span class="emphasis"><em>not</em></span> be accepted. Changing this to <code class="literal">on</code> will make the server + accept credentials delegated to it from the client. This parameter can only be + set in the <code class="filename">postgresql.conf</code> file or on the server command line. + </p></dd><dt id="GUC-DB-USER-NAMESPACE"><span class="term"><code class="varname">db_user_namespace</code> (<code class="type">boolean</code>) + <a id="id-1.6.7.6.4.2.7.1.3" class="indexterm"></a> + </span> <a href="#GUC-DB-USER-NAMESPACE" class="id_link">#</a></dt><dd><p> + This parameter enables per-database user names. It is off by default. + This parameter can only be set in the <code class="filename">postgresql.conf</code> + file or on the server command line. + </p><p> + If this is on, you should create users as <em class="replaceable"><code>username@dbname</code></em>. + When <em class="replaceable"><code>username</code></em> is passed by a connecting client, + <code class="literal">@</code> and the database name are appended to the user + name and that database-specific user name is looked up by the + server. Note that when you create users with names containing + <code class="literal">@</code> within the SQL environment, you will need to + quote the user name. + </p><p> + With this parameter enabled, you can still create ordinary global + users. Simply append <code class="literal">@</code> when specifying the user + name in the client, e.g., <code class="literal">joe@</code>. The <code class="literal">@</code> + will be stripped off before the user name is looked up by the + server. + </p><p> + <code class="varname">db_user_namespace</code> causes the client's and + server's user name representation to differ. + Authentication checks are always done with the server's user name + so authentication methods must be configured for the + server's user name, not the client's. Because + <code class="literal">md5</code> uses the user name as salt on both the + client and server, <code class="literal">md5</code> cannot be used with + <code class="varname">db_user_namespace</code>. + </p><div class="note"><h3 class="title">Note</h3><p> + This feature is intended as a temporary measure until a + complete solution is found. At that time, this option will + be removed. + </p></div></dd></dl></div></div><div class="sect2" id="RUNTIME-CONFIG-CONNECTION-SSL"><div class="titlepage"><div><div><h3 class="title">20.3.4. SSL <a href="#RUNTIME-CONFIG-CONNECTION-SSL" class="id_link">#</a></h3></div></div></div><p> + See <a class="xref" href="ssl-tcp.html" title="19.9. Secure TCP/IP Connections with SSL">Section 19.9</a> for more information about setting up + <acronym class="acronym">SSL</acronym>. The configuration parameters for controlling + transfer encryption using <acronym class="acronym">TLS</acronym> protocols are named + <code class="literal">ssl</code> for historic reasons, even though support for + the <acronym class="acronym">SSL</acronym> protocol has been deprecated. + <acronym class="acronym">SSL</acronym> is in this context used interchangeably with + <acronym class="acronym">TLS</acronym>. + </p><div class="variablelist"><dl class="variablelist"><dt id="GUC-SSL"><span class="term"><code class="varname">ssl</code> (<code class="type">boolean</code>) + <a id="id-1.6.7.6.5.3.1.1.3" class="indexterm"></a> + </span> <a href="#GUC-SSL" class="id_link">#</a></dt><dd><p> + Enables <acronym class="acronym">SSL</acronym> connections. + This parameter can only be set in the <code class="filename">postgresql.conf</code> + file or on the server command line. + The default is <code class="literal">off</code>. + </p></dd><dt id="GUC-SSL-CA-FILE"><span class="term"><code class="varname">ssl_ca_file</code> (<code class="type">string</code>) + <a id="id-1.6.7.6.5.3.2.1.3" class="indexterm"></a> + </span> <a href="#GUC-SSL-CA-FILE" class="id_link">#</a></dt><dd><p> + Specifies the name of the file containing the SSL server certificate + authority (CA). + Relative paths are relative to the data directory. + This parameter can only be set in the <code class="filename">postgresql.conf</code> + file or on the server command line. + The default is empty, meaning no CA file is loaded, + and client certificate verification is not performed. + </p></dd><dt id="GUC-SSL-CERT-FILE"><span class="term"><code class="varname">ssl_cert_file</code> (<code class="type">string</code>) + <a id="id-1.6.7.6.5.3.3.1.3" class="indexterm"></a> + </span> <a href="#GUC-SSL-CERT-FILE" class="id_link">#</a></dt><dd><p> + Specifies the name of the file containing the SSL server certificate. + Relative paths are relative to the data directory. + This parameter can only be set in the <code class="filename">postgresql.conf</code> + file or on the server command line. + The default is <code class="filename">server.crt</code>. + </p></dd><dt id="GUC-SSL-CRL-FILE"><span class="term"><code class="varname">ssl_crl_file</code> (<code class="type">string</code>) + <a id="id-1.6.7.6.5.3.4.1.3" class="indexterm"></a> + </span> <a href="#GUC-SSL-CRL-FILE" class="id_link">#</a></dt><dd><p> + Specifies the name of the file containing the SSL client certificate + revocation list (CRL). + Relative paths are relative to the data directory. + This parameter can only be set in the <code class="filename">postgresql.conf</code> + file or on the server command line. + The default is empty, meaning no CRL file is loaded (unless + <a class="xref" href="runtime-config-connection.html#GUC-SSL-CRL-DIR">ssl_crl_dir</a> is set). + </p></dd><dt id="GUC-SSL-CRL-DIR"><span class="term"><code class="varname">ssl_crl_dir</code> (<code class="type">string</code>) + <a id="id-1.6.7.6.5.3.5.1.3" class="indexterm"></a> + </span> <a href="#GUC-SSL-CRL-DIR" class="id_link">#</a></dt><dd><p> + Specifies the name of the directory containing the SSL client + certificate revocation list (CRL). Relative paths are relative to the + data directory. This parameter can only be set in + the <code class="filename">postgresql.conf</code> file or on the server command + line. The default is empty, meaning no CRLs are used (unless + <a class="xref" href="runtime-config-connection.html#GUC-SSL-CRL-FILE">ssl_crl_file</a> is set). + </p><p> + The directory needs to be prepared with the + <span class="productname">OpenSSL</span> command + <code class="literal">openssl rehash</code> or <code class="literal">c_rehash</code>. See + its documentation for details. + </p><p> + When using this setting, CRLs in the specified directory are loaded + on-demand at connection time. New CRLs can be added to the directory + and will be used immediately. This is unlike <a class="xref" href="runtime-config-connection.html#GUC-SSL-CRL-FILE">ssl_crl_file</a>, which causes the CRL in the file to be + loaded at server start time or when the configuration is reloaded. + Both settings can be used together. + </p></dd><dt id="GUC-SSL-KEY-FILE"><span class="term"><code class="varname">ssl_key_file</code> (<code class="type">string</code>) + <a id="id-1.6.7.6.5.3.6.1.3" class="indexterm"></a> + </span> <a href="#GUC-SSL-KEY-FILE" class="id_link">#</a></dt><dd><p> + Specifies the name of the file containing the SSL server private key. + Relative paths are relative to the data directory. + This parameter can only be set in the <code class="filename">postgresql.conf</code> + file or on the server command line. + The default is <code class="filename">server.key</code>. + </p></dd><dt id="GUC-SSL-CIPHERS"><span class="term"><code class="varname">ssl_ciphers</code> (<code class="type">string</code>) + <a id="id-1.6.7.6.5.3.7.1.3" class="indexterm"></a> + </span> <a href="#GUC-SSL-CIPHERS" class="id_link">#</a></dt><dd><p> + Specifies a list of <acronym class="acronym">SSL</acronym> cipher suites that are + allowed to be used by SSL connections. See the + <span class="citerefentry"><span class="refentrytitle">ciphers</span></span> + manual page in the <span class="productname">OpenSSL</span> package for the + syntax of this setting and a list of supported values. Only + connections using TLS version 1.2 and lower are affected. There is + currently no setting that controls the cipher choices used by TLS + version 1.3 connections. The default value is + <code class="literal">HIGH:MEDIUM:+3DES:!aNULL</code>. The default is usually a + reasonable choice unless you have specific security requirements. + </p><p> + This parameter can only be set in the + <code class="filename">postgresql.conf</code> file or on the server command + line. + </p><p> + Explanation of the default value: + </p><div class="variablelist"><dl class="variablelist"><dt id="GUC-SSL-CIPHERS-HIGH"><span class="term"><code class="literal">HIGH</code></span> <a href="#GUC-SSL-CIPHERS-HIGH" class="id_link">#</a></dt><dd><p> + Cipher suites that use ciphers from <code class="literal">HIGH</code> group (e.g., + AES, Camellia, 3DES) + </p></dd><dt id="GUC-SSL-CIPHERS-MEDIUM"><span class="term"><code class="literal">MEDIUM</code></span> <a href="#GUC-SSL-CIPHERS-MEDIUM" class="id_link">#</a></dt><dd><p> + Cipher suites that use ciphers from <code class="literal">MEDIUM</code> group + (e.g., RC4, SEED) + </p></dd><dt id="GUC-SSL-CIPHERS-PLUS-3DES"><span class="term"><code class="literal">+3DES</code></span> <a href="#GUC-SSL-CIPHERS-PLUS-3DES" class="id_link">#</a></dt><dd><p> + The <span class="productname">OpenSSL</span> default order for + <code class="literal">HIGH</code> is problematic because it orders 3DES + higher than AES128. This is wrong because 3DES offers less + security than AES128, and it is also much slower. + <code class="literal">+3DES</code> reorders it after all other + <code class="literal">HIGH</code> and <code class="literal">MEDIUM</code> ciphers. + </p></dd><dt id="GUC-SSL-CIPHERS-NOT-ANULL"><span class="term"><code class="literal">!aNULL</code></span> <a href="#GUC-SSL-CIPHERS-NOT-ANULL" class="id_link">#</a></dt><dd><p> + Disables anonymous cipher suites that do no authentication. Such + cipher suites are vulnerable to <acronym class="acronym">MITM</acronym> attacks and + therefore should not be used. + </p></dd></dl></div><p> + </p><p> + Available cipher suite details will vary across + <span class="productname">OpenSSL</span> versions. Use the command + <code class="literal">openssl ciphers -v 'HIGH:MEDIUM:+3DES:!aNULL'</code> to + see actual details for the currently installed + <span class="productname">OpenSSL</span> version. Note that this list is + filtered at run time based on the server key type. + </p></dd><dt id="GUC-SSL-PREFER-SERVER-CIPHERS"><span class="term"><code class="varname">ssl_prefer_server_ciphers</code> (<code class="type">boolean</code>) + <a id="id-1.6.7.6.5.3.8.1.3" class="indexterm"></a> + </span> <a href="#GUC-SSL-PREFER-SERVER-CIPHERS" class="id_link">#</a></dt><dd><p> + Specifies whether to use the server's SSL cipher preferences, rather + than the client's. + This parameter can only be set in the <code class="filename">postgresql.conf</code> + file or on the server command line. + The default is <code class="literal">on</code>. + </p><p> + Older PostgreSQL versions do not have this setting and always use the + client's preferences. This setting is mainly for backward + compatibility with those versions. Using the server's preferences is + usually better because it is more likely that the server is appropriately + configured. + </p></dd><dt id="GUC-SSL-ECDH-CURVE"><span class="term"><code class="varname">ssl_ecdh_curve</code> (<code class="type">string</code>) + <a id="id-1.6.7.6.5.3.9.1.3" class="indexterm"></a> + </span> <a href="#GUC-SSL-ECDH-CURVE" class="id_link">#</a></dt><dd><p> + Specifies the name of the curve to use in <acronym class="acronym">ECDH</acronym> key + exchange. It needs to be supported by all clients that connect. + It does not need to be the same curve used by the server's Elliptic + Curve key. + This parameter can only be set in the <code class="filename">postgresql.conf</code> + file or on the server command line. + The default is <code class="literal">prime256v1</code>. + </p><p> + <span class="productname">OpenSSL</span> names for the most common curves + are: + <code class="literal">prime256v1</code> (NIST P-256), + <code class="literal">secp384r1</code> (NIST P-384), + <code class="literal">secp521r1</code> (NIST P-521). + The full list of available curves can be shown with the command + <code class="command">openssl ecparam -list_curves</code>. Not all of them + are usable in <acronym class="acronym">TLS</acronym> though. + </p></dd><dt id="GUC-SSL-MIN-PROTOCOL-VERSION"><span class="term"><code class="varname">ssl_min_protocol_version</code> (<code class="type">enum</code>) + <a id="id-1.6.7.6.5.3.10.1.3" class="indexterm"></a> + </span> <a href="#GUC-SSL-MIN-PROTOCOL-VERSION" class="id_link">#</a></dt><dd><p> + Sets the minimum SSL/TLS protocol version to use. Valid values are + currently: <code class="literal">TLSv1</code>, <code class="literal">TLSv1.1</code>, + <code class="literal">TLSv1.2</code>, <code class="literal">TLSv1.3</code>. Older + versions of the <span class="productname">OpenSSL</span> library do not + support all values; an error will be raised if an unsupported setting + is chosen. Protocol versions before TLS 1.0, namely SSL version 2 and + 3, are always disabled. + </p><p> + The default is <code class="literal">TLSv1.2</code>, which satisfies industry + best practices as of this writing. + </p><p> + This parameter can only be set in the <code class="filename">postgresql.conf</code> + file or on the server command line. + </p></dd><dt id="GUC-SSL-MAX-PROTOCOL-VERSION"><span class="term"><code class="varname">ssl_max_protocol_version</code> (<code class="type">enum</code>) + <a id="id-1.6.7.6.5.3.11.1.3" class="indexterm"></a> + </span> <a href="#GUC-SSL-MAX-PROTOCOL-VERSION" class="id_link">#</a></dt><dd><p> + Sets the maximum SSL/TLS protocol version to use. Valid values are as + for <a class="xref" href="runtime-config-connection.html#GUC-SSL-MIN-PROTOCOL-VERSION">ssl_min_protocol_version</a>, with addition of + an empty string, which allows any protocol version. The default is to + allow any version. Setting the maximum protocol version is mainly + useful for testing or if some component has issues working with a + newer protocol. + </p><p> + This parameter can only be set in the <code class="filename">postgresql.conf</code> + file or on the server command line. + </p></dd><dt id="GUC-SSL-DH-PARAMS-FILE"><span class="term"><code class="varname">ssl_dh_params_file</code> (<code class="type">string</code>) + <a id="id-1.6.7.6.5.3.12.1.3" class="indexterm"></a> + </span> <a href="#GUC-SSL-DH-PARAMS-FILE" class="id_link">#</a></dt><dd><p> + Specifies the name of the file containing Diffie-Hellman parameters + used for so-called ephemeral DH family of SSL ciphers. The default is + empty, in which case compiled-in default DH parameters used. Using + custom DH parameters reduces the exposure if an attacker manages to + crack the well-known compiled-in DH parameters. You can create your own + DH parameters file with the command + <code class="command">openssl dhparam -out dhparams.pem 2048</code>. + </p><p> + This parameter can only be set in the <code class="filename">postgresql.conf</code> + file or on the server command line. + </p></dd><dt id="GUC-SSL-PASSPHRASE-COMMAND"><span class="term"><code class="varname">ssl_passphrase_command</code> (<code class="type">string</code>) + <a id="id-1.6.7.6.5.3.13.1.3" class="indexterm"></a> + </span> <a href="#GUC-SSL-PASSPHRASE-COMMAND" class="id_link">#</a></dt><dd><p> + Sets an external command to be invoked when a passphrase for + decrypting an SSL file such as a private key needs to be obtained. By + default, this parameter is empty, which means the built-in prompting + mechanism is used. + </p><p> + The command must print the passphrase to the standard output and exit + with code 0. In the parameter value, <code class="literal">%p</code> is + replaced by a prompt string. (Write <code class="literal">%%</code> for a + literal <code class="literal">%</code>.) Note that the prompt string will + probably contain whitespace, so be sure to quote adequately. A single + newline is stripped from the end of the output if present. + </p><p> + The command does not actually have to prompt the user for a + passphrase. It can read it from a file, obtain it from a keychain + facility, or similar. It is up to the user to make sure the chosen + mechanism is adequately secure. + </p><p> + This parameter can only be set in the <code class="filename">postgresql.conf</code> + file or on the server command line. + </p></dd><dt id="GUC-SSL-PASSPHRASE-COMMAND-SUPPORTS-RELOAD"><span class="term"><code class="varname">ssl_passphrase_command_supports_reload</code> (<code class="type">boolean</code>) + <a id="id-1.6.7.6.5.3.14.1.3" class="indexterm"></a> + </span> <a href="#GUC-SSL-PASSPHRASE-COMMAND-SUPPORTS-RELOAD" class="id_link">#</a></dt><dd><p> + This parameter determines whether the passphrase command set by + <code class="varname">ssl_passphrase_command</code> will also be called during a + configuration reload if a key file needs a passphrase. If this + parameter is off (the default), then + <code class="varname">ssl_passphrase_command</code> will be ignored during a + reload and the SSL configuration will not be reloaded if a passphrase + is needed. That setting is appropriate for a command that requires a + TTY for prompting, which might not be available when the server is + running. Setting this parameter to on might be appropriate if the + passphrase is obtained from a file, for example. + </p><p> + This parameter can only be set in the <code class="filename">postgresql.conf</code> + file or on the server command line. + </p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="runtime-config-file-locations.html" title="20.2. File Locations">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="runtime-config.html" title="Chapter 20. Server Configuration">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="runtime-config-resource.html" title="20.4. Resource Consumption">Next</a></td></tr><tr><td width="40%" align="left" valign="top">20.2. File Locations </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"> 20.4. Resource Consumption</td></tr></table></div></body></html>
\ No newline at end of file |