2 19.3. Connections and Authentication #
4 19.3.1. Connection Settings
9 19.3.1. Connection Settings #
11 listen_addresses (string) #
12 Specifies the TCP/IP address(es) on which the server is to
13 listen for connections from client applications. The value takes
14 the form of a comma-separated list of host names and/or numeric
15 IP addresses. The special entry * corresponds to all available
16 IP interfaces. The entry 0.0.0.0 allows listening for all IPv4
17 addresses and :: allows listening for all IPv6 addresses. If the
18 list is empty, the server does not listen on any IP interface at
19 all, in which case only Unix-domain sockets can be used to
20 connect to it. If the list is not empty, the server will start
21 if it can listen on at least one TCP/IP address. A warning will
22 be emitted for any TCP/IP address which cannot be opened. The
23 default value is localhost, which allows only local TCP/IP
24 “loopback” connections to be made.
26 While client authentication (Chapter 20) allows fine-grained
27 control over who can access the server, listen_addresses
28 controls which interfaces accept connection attempts, which can
29 help prevent repeated malicious connection requests on insecure
30 network interfaces. This parameter can only be set at server
34 The TCP port the server listens on; 5432 by default. Note that
35 the same port number is used for all IP addresses the server
36 listens on. This parameter can only be set at server start.
38 max_connections (integer) #
39 Determines the maximum number of concurrent connections to the
40 database server. The default is typically 100 connections, but
41 might be less if your kernel settings will not support it (as
42 determined during initdb). This parameter can only be set at
45 PostgreSQL sizes certain resources based directly on the value
46 of max_connections. Increasing its value leads to higher
47 allocation of those resources, including shared memory.
49 When running a standby server, you must set this parameter to
50 the same or higher value than on the primary server. Otherwise,
51 queries will not be allowed in the standby server.
53 reserved_connections (integer) #
54 Determines the number of connection “slots” that are reserved
55 for connections by roles with privileges of the
56 pg_use_reserved_connections role. Whenever the number of free
57 connection slots is greater than superuser_reserved_connections
58 but less than or equal to the sum of
59 superuser_reserved_connections and reserved_connections, new
60 connections will be accepted only for superusers and roles with
61 privileges of pg_use_reserved_connections. If
62 superuser_reserved_connections or fewer connection slots are
63 available, new connections will be accepted only for superusers.
65 The default value is zero connections. The value must be less
66 than max_connections minus superuser_reserved_connections. This
67 parameter can only be set at server start.
69 superuser_reserved_connections (integer) #
70 Determines the number of connection “slots” that are reserved
71 for connections by PostgreSQL superusers. At most
72 max_connections connections can ever be active simultaneously.
73 Whenever the number of active concurrent connections is at least
74 max_connections minus superuser_reserved_connections, new
75 connections will be accepted only for superusers. The connection
76 slots reserved by this parameter are intended as final reserve
77 for emergency use after the slots reserved by
78 reserved_connections have been exhausted.
80 The default value is three connections. The value must be less
81 than max_connections minus reserved_connections. This parameter
82 can only be set at server start.
84 unix_socket_directories (string) #
85 Specifies the directory of the Unix-domain socket(s) on which
86 the server is to listen for connections from client
87 applications. Multiple sockets can be created by listing
88 multiple directories separated by commas. Whitespace between
89 entries is ignored; surround a directory name with double quotes
90 if you need to include whitespace or commas in the name. An
91 empty value specifies not listening on any Unix-domain sockets,
92 in which case only TCP/IP sockets can be used to connect to the
95 A value that starts with @ specifies that a Unix-domain socket
96 in the abstract namespace should be created (currently supported
97 on Linux only). In that case, this value does not specify a
98 “directory” but a prefix from which the actual socket name is
99 computed in the same manner as for the file-system namespace.
100 While the abstract socket name prefix can be chosen freely,
101 since it is not a file-system location, the convention is to
102 nonetheless use file-system-like values such as @/tmp.
104 The default value is normally /tmp, but that can be changed at
105 build time. On Windows, the default is empty, which means no
106 Unix-domain socket is created by default. This parameter can
107 only be set at server start.
109 In addition to the socket file itself, which is named
110 .s.PGSQL.nnnn where nnnn is the server's port number, an
111 ordinary file named .s.PGSQL.nnnn.lock will be created in each
112 of the unix_socket_directories directories. Neither file should
113 ever be removed manually. For sockets in the abstract namespace,
114 no lock file is created.
116 unix_socket_group (string) #
117 Sets the owning group of the Unix-domain socket(s). (The owning
118 user of the sockets is always the user that starts the server.)
119 In combination with the parameter unix_socket_permissions this
120 can be used as an additional access control mechanism for
121 Unix-domain connections. By default this is the empty string,
122 which uses the default group of the server user. This parameter
123 can only be set at server start.
125 This parameter is not supported on Windows. Any setting will be
126 ignored. Also, sockets in the abstract namespace have no file
127 owner, so this setting is also ignored in that case.
129 unix_socket_permissions (integer) #
130 Sets the access permissions of the Unix-domain socket(s).
131 Unix-domain sockets use the usual Unix file system permission
132 set. The parameter value is expected to be a numeric mode
133 specified in the format accepted by the chmod and umask system
134 calls. (To use the customary octal format the number must start
137 The default permissions are 0777, meaning anyone can connect.
138 Reasonable alternatives are 0770 (only user and group, see also
139 unix_socket_group) and 0700 (only user). (Note that for a
140 Unix-domain socket, only write permission matters, so there is
141 no point in setting or revoking read or execute permissions.)
143 This access control mechanism is independent of the one
144 described in Chapter 20.
146 This parameter can only be set at server start.
148 This parameter is irrelevant on systems, notably Solaris as of
149 Solaris 10, that ignore socket permissions entirely. There, one
150 can achieve a similar effect by pointing unix_socket_directories
151 to a directory having search permission limited to the desired
154 Sockets in the abstract namespace have no file permissions, so
155 this setting is also ignored in that case.
158 Enables advertising the server's existence via Bonjour. The
159 default is off. This parameter can only be set at server start.
161 bonjour_name (string) #
162 Specifies the Bonjour service name. The computer name is used if
163 this parameter is set to the empty string '' (which is the
164 default). This parameter is ignored if the server was not
165 compiled with Bonjour support. This parameter can only be set at
168 19.3.2. TCP Settings #
170 tcp_keepalives_idle (integer) #
171 Specifies the amount of time with no network activity after
172 which the operating system should send a TCP keepalive message
173 to the client. If this value is specified without units, it is
174 taken as seconds. A value of 0 (the default) selects the
175 operating system's default. On Windows, setting a value of 0
176 will set this parameter to 2 hours, since Windows does not
177 provide a way to read the system default value. This parameter
178 is supported only on systems that support TCP_KEEPIDLE or an
179 equivalent socket option, and on Windows; on other systems, it
180 must be zero. In sessions connected via a Unix-domain socket,
181 this parameter is ignored and always reads as zero.
183 tcp_keepalives_interval (integer) #
184 Specifies the amount of time after which a TCP keepalive message
185 that has not been acknowledged by the client should be
186 retransmitted. If this value is specified without units, it is
187 taken as seconds. A value of 0 (the default) selects the
188 operating system's default. On Windows, setting a value of 0
189 will set this parameter to 1 second, since Windows does not
190 provide a way to read the system default value. This parameter
191 is supported only on systems that support TCP_KEEPINTVL or an
192 equivalent socket option, and on Windows; on other systems, it
193 must be zero. In sessions connected via a Unix-domain socket,
194 this parameter is ignored and always reads as zero.
196 tcp_keepalives_count (integer) #
197 Specifies the number of TCP keepalive messages that can be lost
198 before the server's connection to the client is considered dead.
199 A value of 0 (the default) selects the operating system's
200 default. This parameter is supported only on systems that
201 support TCP_KEEPCNT or an equivalent socket option (which does
202 not include Windows); on other systems, it must be zero. In
203 sessions connected via a Unix-domain socket, this parameter is
204 ignored and always reads as zero.
206 tcp_user_timeout (integer) #
207 Specifies the amount of time that transmitted data may remain
208 unacknowledged before the TCP connection is forcibly closed. If
209 this value is specified without units, it is taken as
210 milliseconds. A value of 0 (the default) selects the operating
211 system's default. This parameter is supported only on systems
212 that support TCP_USER_TIMEOUT (which does not include Windows);
213 on other systems, it must be zero. In sessions connected via a
214 Unix-domain socket, this parameter is ignored and always reads
217 client_connection_check_interval (integer) #
218 Sets the time interval between optional checks that the client
219 is still connected, while running queries. The check is
220 performed by polling the socket, and allows long running queries
221 to be aborted sooner if the kernel reports that the connection
224 This option relies on kernel events exposed by Linux, macOS,
225 illumos and the BSD family of operating systems, and is not
226 currently available on other systems.
228 If the value is specified without units, it is taken as
229 milliseconds. The default value is 0, which disables connection
230 checks. Without connection checks, the server will detect the
231 loss of the connection only at the next interaction with the
232 socket, when it waits for, receives or sends data.
234 For the kernel itself to detect lost TCP connections reliably
235 and within a known timeframe in all scenarios including network
236 failure, it may also be necessary to adjust the TCP keepalive
237 settings of the operating system, or the tcp_keepalives_idle,
238 tcp_keepalives_interval and tcp_keepalives_count settings of
241 19.3.3. Authentication #
243 authentication_timeout (integer) #
244 Maximum amount of time allowed to complete client
245 authentication. If a would-be client has not completed the
246 authentication protocol in this much time, the server closes the
247 connection. This prevents hung clients from occupying a
248 connection indefinitely. If this value is specified without
249 units, it is taken as seconds. The default is one minute (1m).
250 This parameter can only be set in the postgresql.conf file or on
251 the server command line.
253 password_encryption (enum) #
254 When a password is specified in CREATE ROLE or ALTER ROLE, this
255 parameter determines the algorithm to use to encrypt the
256 password. Possible values are scram-sha-256, which will encrypt
257 the password with SCRAM-SHA-256, and md5, which stores the
258 password as an MD5 hash. The default is scram-sha-256.
260 Note that older clients might lack support for the SCRAM
261 authentication mechanism, and hence not work with passwords
262 encrypted with SCRAM-SHA-256. See Section 20.5 for more details.
266 Support for MD5-encrypted passwords is deprecated and will be
267 removed in a future release of PostgreSQL. Refer to Section 20.5
268 for details about migrating to another password type.
270 scram_iterations (integer) #
271 The number of computational iterations to be performed when
272 encrypting a password using SCRAM-SHA-256. The default is 4096.
273 A higher number of iterations provides additional protection
274 against brute-force attacks on stored passwords, but makes
275 authentication slower. Changing the value has no effect on
276 existing passwords encrypted with SCRAM-SHA-256 as the iteration
277 count is fixed at the time of encryption. In order to make use
278 of a changed value, a new password must be set.
280 md5_password_warnings (boolean) #
281 Controls whether a WARNING about MD5 password deprecation is
282 produced when a CREATE ROLE or ALTER ROLE statement sets an
283 MD5-encrypted password. The default value is on.
285 krb_server_keyfile (string) #
286 Sets the location of the server's Kerberos key file. The default
287 is FILE:/usr/local/pgsql/etc/krb5.keytab (where the directory
288 part is whatever was specified as sysconfdir at build time; use
289 pg_config --sysconfdir to determine that). If this parameter is
290 set to an empty string, it is ignored and a system-dependent
291 default is used. This parameter can only be set in the
292 postgresql.conf file or on the server command line. See
293 Section 20.6 for more information.
295 krb_caseins_users (boolean) #
296 Sets whether GSSAPI user names should be treated
297 case-insensitively. The default is off (case sensitive). This
298 parameter can only be set in the postgresql.conf file or on the
301 gss_accept_delegation (boolean) #
302 Sets whether GSSAPI delegation should be accepted from the
303 client. The default is off meaning credentials from the client
304 will not be accepted. Changing this to on will make the server
305 accept credentials delegated to it from the client. This
306 parameter can only be set in the postgresql.conf file or on the
309 oauth_validator_libraries (string) #
310 The library/libraries to use for validating OAuth connection
311 tokens. If only one validator library is provided, it will be
312 used by default for any OAuth connections; otherwise, all oauth
313 HBA entries must explicitly set a validator chosen from this
314 list. If set to an empty string (the default), OAuth connections
315 will be refused. This parameter can only be set in the
316 postgresql.conf file.
318 Validator modules must be implemented/obtained separately;
319 PostgreSQL does not ship with any default implementations. For
320 more information on implementing OAuth validators, see
325 See Section 18.9 for more information about setting up SSL. The
326 configuration parameters for controlling transfer encryption using TLS
327 protocols are named ssl for historic reasons, even though support for
328 the SSL protocol has been deprecated. SSL is in this context used
329 interchangeably with TLS.
332 Enables SSL connections. This parameter can only be set in the
333 postgresql.conf file or on the server command line. The default
336 ssl_ca_file (string) #
337 Specifies the name of the file containing the SSL server
338 certificate authority (CA). Relative paths are relative to the
339 data directory. This parameter can only be set in the
340 postgresql.conf file or on the server command line. The default
341 is empty, meaning no CA file is loaded, and client certificate
342 verification is not performed.
344 ssl_cert_file (string) #
345 Specifies the name of the file containing the SSL server
346 certificate. Relative paths are relative to the data directory.
347 This parameter can only be set in the postgresql.conf file or on
348 the server command line. The default is server.crt.
350 ssl_crl_file (string) #
351 Specifies the name of the file containing the SSL client
352 certificate revocation list (CRL). Relative paths are relative
353 to the data directory. This parameter can only be set in the
354 postgresql.conf file or on the server command line. The default
355 is empty, meaning no CRL file is loaded (unless ssl_crl_dir is
358 ssl_crl_dir (string) #
359 Specifies the name of the directory containing the SSL client
360 certificate revocation list (CRL). Relative paths are relative
361 to the data directory. This parameter can only be set in the
362 postgresql.conf file or on the server command line. The default
363 is empty, meaning no CRLs are used (unless ssl_crl_file is set).
365 The directory needs to be prepared with the OpenSSL command
366 openssl rehash or c_rehash. See its documentation for details.
368 When using this setting, CRLs in the specified directory are
369 loaded on-demand at connection time. New CRLs can be added to
370 the directory and will be used immediately. This is unlike
371 ssl_crl_file, which causes the CRL in the file to be loaded at
372 server start time or when the configuration is reloaded. Both
373 settings can be used together.
375 ssl_key_file (string) #
376 Specifies the name of the file containing the SSL server private
377 key. Relative paths are relative to the data directory. This
378 parameter can only be set in the postgresql.conf file or on the
379 server command line. The default is server.key.
381 ssl_tls13_ciphers (string) #
382 Specifies a list of cipher suites that are allowed by
383 connections using TLS version 1.3. Multiple cipher suites can be
384 specified by using a colon separated list. If left blank, the
385 default set of cipher suites in OpenSSL will be used.
387 This parameter can only be set in the postgresql.conf file or on
388 the server command line.
390 ssl_ciphers (string) #
391 Specifies a list of SSL ciphers that are allowed by connections
392 using TLS version 1.2 and lower, see ssl_tls13_ciphers for TLS
393 version 1.3 connections. See the ciphers manual page in the
394 OpenSSL package for the syntax of this setting and a list of
395 supported values. The default value is HIGH:MEDIUM:+3DES:!aNULL.
396 The default is usually a reasonable choice unless you have
397 specific security requirements.
399 This parameter can only be set in the postgresql.conf file or on
400 the server command line.
402 Explanation of the default value:
405 Cipher suites that use ciphers from HIGH group (e.g., AES,
409 Cipher suites that use ciphers from MEDIUM group (e.g.,
413 The OpenSSL default order for HIGH is problematic because
414 it orders 3DES higher than AES128. This is wrong because
415 3DES offers less security than AES128, and it is also much
416 slower. +3DES reorders it after all other HIGH and MEDIUM
420 Disables anonymous cipher suites that do no
421 authentication. Such cipher suites are vulnerable to MITM
422 attacks and therefore should not be used.
424 Available cipher suite details will vary across OpenSSL
425 versions. Use the command openssl ciphers -v
426 'HIGH:MEDIUM:+3DES:!aNULL' to see actual details for the
427 currently installed OpenSSL version. Note that this list is
428 filtered at run time based on the server key type.
430 ssl_prefer_server_ciphers (boolean) #
431 Specifies whether to use the server's SSL cipher preferences,
432 rather than the client's. This parameter can only be set in the
433 postgresql.conf file or on the server command line. The default
436 PostgreSQL versions before 9.4 do not have this setting and
437 always use the client's preferences. This setting is mainly for
438 backward compatibility with those versions. Using the server's
439 preferences is usually better because it is more likely that the
440 server is appropriately configured.
442 ssl_groups (string) #
443 Specifies the name of the curve to use in ECDH key exchange. It
444 needs to be supported by all clients that connect. Multiple
445 curves can be specified by using a colon-separated list. It does
446 not need to be the same curve used by the server's Elliptic
447 Curve key. This parameter can only be set in the postgresql.conf
448 file or on the server command line. The default is
451 OpenSSL names for the most common curves are: prime256v1 (NIST
452 P-256), secp384r1 (NIST P-384), secp521r1 (NIST P-521). An
453 incomplete list of available groups can be shown with the
454 command openssl ecparam -list_curves. Not all of them are usable
455 with TLS though, and many supported group names and aliases are
458 In PostgreSQL versions before 18.0 this setting was named
459 ssl_ecdh_curve and only accepted a single value.
461 ssl_min_protocol_version (enum) #
462 Sets the minimum SSL/TLS protocol version to use. Valid values
463 are currently: TLSv1, TLSv1.1, TLSv1.2, TLSv1.3. Older versions
464 of the OpenSSL library do not support all values; an error will
465 be raised if an unsupported setting is chosen. Protocol versions
466 before TLS 1.0, namely SSL version 2 and 3, are always disabled.
468 The default is TLSv1.2, which satisfies industry best practices
471 This parameter can only be set in the postgresql.conf file or on
472 the server command line.
474 ssl_max_protocol_version (enum) #
475 Sets the maximum SSL/TLS protocol version to use. Valid values
476 are as for ssl_min_protocol_version, with addition of an empty
477 string, which allows any protocol version. The default is to
478 allow any version. Setting the maximum protocol version is
479 mainly useful for testing or if some component has issues
480 working with a newer protocol.
482 This parameter can only be set in the postgresql.conf file or on
483 the server command line.
485 ssl_dh_params_file (string) #
486 Specifies the name of the file containing Diffie-Hellman
487 parameters used for so-called ephemeral DH family of SSL
488 ciphers. The default is empty, in which case compiled-in default
489 DH parameters used. Using custom DH parameters reduces the
490 exposure if an attacker manages to crack the well-known
491 compiled-in DH parameters. You can create your own DH parameters
492 file with the command openssl dhparam -out dhparams.pem 2048.
494 This parameter can only be set in the postgresql.conf file or on
495 the server command line.
497 ssl_passphrase_command (string) #
498 Sets an external command to be invoked when a passphrase for
499 decrypting an SSL file such as a private key needs to be
500 obtained. By default, this parameter is empty, which means the
501 built-in prompting mechanism is used.
503 The command must print the passphrase to the standard output and
504 exit with code 0. In the parameter value, %p is replaced by a
505 prompt string. (Write %% for a literal %.) Note that the prompt
506 string will probably contain whitespace, so be sure to quote
507 adequately. A single newline is stripped from the end of the
510 The command does not actually have to prompt the user for a
511 passphrase. It can read it from a file, obtain it from a
512 keychain facility, or similar. It is up to the user to make sure
513 the chosen mechanism is adequately secure.
515 This parameter can only be set in the postgresql.conf file or on
516 the server command line.
518 ssl_passphrase_command_supports_reload (boolean) #
519 This parameter determines whether the passphrase command set by
520 ssl_passphrase_command will also be called during a
521 configuration reload if a key file needs a passphrase. If this
522 parameter is off (the default), then ssl_passphrase_command will
523 be ignored during a reload and the SSL configuration will not be
524 reloaded if a passphrase is needed. That setting is appropriate
525 for a command that requires a TTY for prompting, which might not
526 be available when the server is running. Setting this parameter
527 to on might be appropriate if the passphrase is obtained from a
530 This parameter can only be set in the postgresql.conf file or on
531 the server command line.
begriffs.com / projects / ai-pg / blob