Doc: document possible need to raise kernel's somaxconn limit.

tglsfdc · tglsfdc · commit 1a9c3ffd6428 · 2022-08-23T09:56:13.000-04:00
On fast machines, it's possible for applications such as pgbench to issue connection requests so quickly that the postmaster's listen queue overflows in the kernel, resulting in unexpected failures (with not-very-helpful error messages). Most modern OSes allow the queue size to be increased, so document how to do that. Per report from Kevin McKibbin. Discussion: https://postgr.es/m/CADc_NKg2d+oZY9mg4DdQdoUcGzN2kOYXBu-3--RW_hEe0tUV=g@mail.gmail.com
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
@@ -1343,6 +1343,22 @@ default:\
     linkend="guc-max-files-per-process"> configuration parameter to
     limit the consumption of open files.
    </para>
+
+   <para>
+    Another kernel limit that may be of concern when supporting large
+    numbers of client connections is the maximum socket connection queue
+    length.  If more than that many connection requests arrive within a very
+    short period, some may get rejected before the postmaster can service
+    the requests, with those clients receiving unhelpful connection failure
+    errors such as <quote>Resource temporarily unavailable</quote> or
+    <quote>Connection refused</quote>.  The default queue length limit is 128
+    on many platforms.  To raise it, adjust the appropriate kernel parameter
+    via <application>sysctl</application>, then restart the postmaster.
+    The parameter is variously named <varname>net.core.somaxconn</varname>
+    on Linux, <varname>kern.ipc.soacceptqueue</varname> on newer FreeBSD,
+    and <varname>kern.ipc.somaxconn</varname> on macOS and other BSD
+    variants.
+   </para>
   </sect2>
 
   <sect2 id="linux-memory-overcommit">
