Doc: update our docs about kernel IPC parameters on *BSD.

runtime.sgml said that you couldn't change SysV IPC parameters on OpenBSD
except by rebuilding the kernel.  That's definitely wrong in OpenBSD 6.x,
and excavation in their man pages says it changed in OpenBSD 3.3.

Update NetBSD and OpenBSD sections to recommend adjustment of the SEMMNI
and SEMMNS settings, which are painfully small by default on those
platforms.  (The discussion thread contemplated recommending that
people select POSIX semaphores instead, but the performance consequences
of that aren't really clear, so I'll refrain.)

Remove pointless discussion of SEMMNU and SEMMAP from the FreeBSD
section.  Minor other wordsmithing.

Discussion: https://postgr.es/m/27582.1546928073@sss.pgh.pa.us

diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 8d9d40664b44b7a6a8143b571749a313d465600d..333adda408695def7f927da00b51e9b5f20fdbee 100644 (file)
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -796,7 +796,8 @@ psql: could not connect to server: No such file or directory
    <para>
     In some cases it might also be necessary to increase
     <varname>SEMMAP</varname> to be at least on the order of
-    <varname>SEMMNS</varname>. This parameter defines the size of the semaphore
+    <varname>SEMMNS</varname>.  If the system has this parameter
+    (many do not), it defines the size of the semaphore
     resource map, in which each contiguous block of available semaphores
     needs an entry. When a semaphore set is freed it is either added to
     an existing entry that is adjacent to the freed block or it is
@@ -853,7 +854,7 @@ psql: could not connect to server: No such file or directory
       </term>
       <listitem>
        <para>
-        The default settings can be changed using
+        The default IPC settings can be changed using
         the <command>sysctl</command> or
         <command>loader</command> interfaces.  The following
         parameters can be set using <command>sysctl</command>:
@@ -872,13 +873,9 @@ psql: could not connect to server: No such file or directory
 <programlisting>
 kern.ipc.semmni=256
 kern.ipc.semmns=512
-kern.ipc.semmnu=256
 </programlisting>
-        After modifying these values a reboot is required for the new
+        After modifying that file, a reboot is required for the new
         settings to take effect.
-        (Note: FreeBSD does not use <varname>SEMMAP</varname>.  Older versions
-        would accept but ignore a setting for <literal>kern.ipc.semmap</literal>;
-        newer versions reject it altogether.)
        </para>
 
        <para>
@@ -902,7 +899,7 @@ kern.ipc.semmnu=256
 
        <para>
         <systemitem class="osname">FreeBSD</systemitem> versions before 4.0 work like
-        <systemitem class="osname">OpenBSD</systemitem> (see below).
+        old <systemitem class="osname">OpenBSD</systemitem> (see below).
        </para>
       </listitem>
      </varlistentry>
@@ -917,12 +914,19 @@ kern.ipc.semmnu=256
         IPC parameters can be adjusted using <command>sysctl</command>,
         for example:
 <screen>
-<prompt>$</prompt> <userinput>sysctl -w kern.ipc.shmmax=16777216</userinput>
+<prompt>#</prompt> <userinput>sysctl -w kern.ipc.semmni=100</userinput>
 </screen>
-        To have these settings persist over reboots, modify
+        To make these settings persist over reboots, modify
         <filename>/etc/sysctl.conf</filename>.
        </para>
 
+       <para>
+        You will usually want to increase <literal>kern.ipc.semmni</literal>
+        and <literal>kern.ipc.semmns</literal>,
+        as <systemitem class="osname">NetBSD</systemitem>'s default settings
+        for these are uncomfortably small.
+       </para>
+
        <para>
         You might also want to configure your kernel to lock shared
         memory into RAM and prevent it from being paged out to swap.
@@ -931,10 +935,10 @@ kern.ipc.semmnu=256
        </para>
 
        <para>
-        <systemitem class="osname">NetBSD</systemitem> versions before 5.0 work like
-        <systemitem class="osname">OpenBSD</systemitem> (see below), except that
-        parameters should be set with the keyword <literal>options</literal> not
-        <literal>option</literal>.
+        <systemitem class="osname">NetBSD</systemitem> versions before 5.0
+        work like old <systemitem class="osname">OpenBSD</systemitem>
+        (see below), except that kernel parameters should be set with the
+        keyword <literal>options</literal> not <literal>option</literal>.
        </para>
       </listitem>
      </varlistentry>
@@ -945,11 +949,31 @@ kern.ipc.semmnu=256
       </term>
       <listitem>
        <para>
-        The options <varname>SYSVSHM</varname> and <varname>SYSVSEM</varname> need
-        to be enabled when the kernel is compiled. (They are by
-        default.) The maximum size of shared memory is determined by
-        the option <varname>SHMMAXPGS</varname> (in pages). The following
-        shows an example of how to set the various parameters:
+        In <systemitem class="osname">OpenBSD</systemitem> 3.3 and later,
+        IPC parameters can be adjusted using <command>sysctl</command>,
+        for example:
+<screen>
+<prompt>#</prompt> <userinput>sysctl kern.seminfo.semmni=100</userinput>
+</screen>
+        To make these settings persist over reboots, modify
+        <filename>/etc/sysctl.conf</filename>.
+       </para>
+
+       <para>
+        You will usually want to
+        increase <literal>kern.seminfo.semmni</literal>
+        and <literal>kern.seminfo.semmns</literal>,
+        as <systemitem class="osname">OpenBSD</systemitem>'s default settings
+        for these are uncomfortably small.
+       </para>
+
+       <para>
+        In older <systemitem class="osname">OpenBSD</systemitem> versions,
+        you will need to build a custom kernel to change the IPC parameters.
+        Make sure that the options <varname>SYSVSHM</varname>
+        and <varname>SYSVSEM</varname> are enabled, too.  (They are by
+        default.)  The following shows an example of how to set the various
+        parameters in the kernel configuration file:
 <programlisting>
 option        SYSVSHM
 option        SHMMAXPGS=4096