1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
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>
|
