0001-doc-Clean-up-references-to-obsolete-OS-versions.patch

From be61fe032a2b8ac3b6130c1f7a38c918d9423ec8 Mon Sep 17 00:00:00 2001
From: Thomas Munro <thomas.munro@gmail.com>
Date: Sat, 6 Jun 2020 15:20:14 +1200
Subject: [PATCH] doc: Clean up references to obsolete OS versions.

Modernize the documentation to remove insecure and/or obsolete
instructions about old operating systems.
---
 doc/src/sgml/runtime.sgml | 152 +++++---------------------------------
 1 file changed, 19 insertions(+), 133 deletions(-)

diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index a8bb85e6f5..c0d1860bf2 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -872,7 +872,7 @@ psql: could not connect to server: No such file or directory
       </term>
       <listitem>
        <para>
-        At least as of version 5.1, it should not be necessary to do
+        It should not be necessary to do
         any special configuration for such parameters as
         <varname>SHMMAX</varname>, as it appears this is configured to
         allow all memory to be used as shared memory.  That is the
@@ -907,41 +907,24 @@ psql: could not connect to server: No such file or directory
         <filename>/etc/sysctl.conf</filename>.
        </para>
 
-       <para>
-        These semaphore-related settings are read-only as far as
-        <command>sysctl</command> is concerned, but can be set in
-        <filename>/boot/loader.conf</filename>:
-<programlisting>
-kern.ipc.semmni=256
-kern.ipc.semmns=512
-</programlisting>
-        After modifying that file, a reboot is required for the new
-        settings to take effect.
-       </para>
-
-       <para>
-        You might also want to configure your kernel to lock System V shared
+      <para>
+        If you have set <literal>shared_memory_type</literal> to
+        <literal>sysv</literal> (not the default, see <xref linkend="sysvipc"/>),
+        you might also want to configure your kernel to lock System V shared
         memory into RAM and prevent it from being paged out to swap.
         This can be accomplished using the <command>sysctl</command>
         setting <literal>kern.ipc.shm_use_phys</literal>.
        </para>
 
        <para>
-        If running in FreeBSD jails by enabling <application>sysctl</application>'s
-        <literal>security.jail.sysvipc_allowed</literal>, <application>postmaster</application>s
-        running in different jails should be run by different operating system
-        users.  This improves security because it prevents non-root users
-        from interfering with shared memory or semaphores in different jails,
-        and it allows the PostgreSQL IPC cleanup code to function properly.
-        (In FreeBSD 6.0 and later the IPC cleanup code does not properly detect
-        processes in other jails, preventing the running of postmasters on the
-        same port in different jails.)
+        If running in a FreeBSD jail, you should set its
+        <literal>sysvshm</literal> parameter to <literal>new</literal>, so that
+        it has its own separate System V shared memory namespace.
+        (Before FreeBSD 11.0, it was necessary to enable shared access to
+        the host's IPC namespace from jails, and take measures to avoid
+        collisions.)
        </para>
 
-       <para>
-        <systemitem class="osname">FreeBSD</systemitem> versions before 4.0 work like
-        old <systemitem class="osname">OpenBSD</systemitem> (see below).
-       </para>
       </listitem>
      </varlistentry>
 
@@ -974,13 +957,6 @@ kern.ipc.semmns=512
         This can be accomplished using the <command>sysctl</command>
         setting <literal>kern.ipc.shm_use_phys</literal>.
        </para>
-
-       <para>
-        <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>
 
@@ -990,7 +966,7 @@ kern.ipc.semmns=512
       </term>
       <listitem>
        <para>
-        In <systemitem class="osname">OpenBSD</systemitem> 3.3 and later,
+        In <systemitem class="osname">OpenBSD</systemitem>,
         IPC parameters can be adjusted using <command>sysctl</command>,
         for example:
 <screen>
@@ -1008,25 +984,6 @@ kern.ipc.semmns=512
         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
-option        SHMSEG=256
-
-option        SYSVSEM
-option        SEMMNI=256
-option        SEMMNS=512
-option        SEMMNU=256
-</programlisting>
-       </para>
-
       </listitem>
      </varlistentry>
 
@@ -1037,9 +994,6 @@ option        SEMMNU=256
       <listitem>
        <para>
         The default settings tend to suffice for normal installations.
-        On <productname>HP-UX</productname> 10, the factory default for
-        <varname>SEMMNS</varname> is 128, which might be too low for larger
-        database sites.
        </para>
        <para>
         <acronym>IPC</acronym> parameters can be set in the <application>System
@@ -1078,9 +1032,7 @@ option        SEMMNU=256
        </para>
 
        <para>
-        Ancient distributions might not have the <command>sysctl</command> program,
-        but equivalent changes can be made by manipulating the
-        <filename>/proc</filename> file system:
+        Alternatively, the <filename>/proc</filename> file system can be used:
 <screen>
 <prompt>$</prompt> <userinput>echo 17179869184 &gt;/proc/sys/kernel/shmmax</userinput>
 <prompt>$</prompt> <userinput>echo 4194304 &gt;/proc/sys/kernel/shmall</userinput>
@@ -1134,65 +1086,15 @@ kern.sysv.shmall=1024
         kept across reboots.
        </para>
 
-       <para>
-        The file <filename>/etc/sysctl.conf</filename> is only honored in macOS
-        10.3.9 and later.  If you are running a previous 10.3.x release,
-        you must edit the file <filename>/etc/rc</filename>
-        and change the values in the following commands:
-<programlisting>
-sysctl -w kern.sysv.shmmax
-sysctl -w kern.sysv.shmmin
-sysctl -w kern.sysv.shmmni
-sysctl -w kern.sysv.shmseg
-sysctl -w kern.sysv.shmall
-</programlisting>
-        Note that
-        <filename>/etc/rc</filename> is usually overwritten by macOS system updates,
-        so you should expect to have to redo these edits after each update.
-       </para>
-
-       <para>
-        In macOS 10.2 and earlier, instead edit these commands in the file
-        <filename>/System/Library/StartupItems/SystemTuning/SystemTuning</filename>.
-       </para>
-      </listitem>
-     </varlistentry>
-
-
-     <varlistentry>
-      <term><systemitem class="osname">Solaris</systemitem> 2.6 to 2.9 (Solaris
-      6 to Solaris 9)
-      <indexterm><primary>Solaris</primary><secondary>IPC configuration</secondary></indexterm>
-      </term>
-      <listitem>
-       <para>
-        The relevant settings can be changed in
-        <filename>/etc/system</filename>, for example:
-<programlisting>
-set shmsys:shminfo_shmmax=0x2000000
-set shmsys:shminfo_shmmin=1
-set shmsys:shminfo_shmmni=256
-set shmsys:shminfo_shmseg=256
-
-set semsys:seminfo_semmap=256
-set semsys:seminfo_semmni=512
-set semsys:seminfo_semmns=512
-set semsys:seminfo_semmsl=32
-</programlisting>
-        You need to reboot for the changes to take effect.  See also
-        <ulink url="http://sunsite.uakom.sk/sunworldonline/swol-09-1997/swol-09-insidesolaris.html"></ulink>
-        for information on shared memory under older versions of Solaris.
-       </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><systemitem class="osname">Solaris</systemitem> 2.10 (Solaris
-      10) and later</term>
-      <term><systemitem class="osname">OpenSolaris</systemitem></term>
+      <term><systemitem class="osname">Solaris</systemitem></term>
+      <term><systemitem class="osname">illumos</systemitem></term>
       <listitem>
        <para>
-        In Solaris 10 and later, and OpenSolaris, the default shared memory and
+        In Solaris 10 and later, and illumos, the default shared memory and
         semaphore settings are good enough for most
         <productname>PostgreSQL</productname> applications.  Solaris now defaults
         to a <varname>SHMMAX</varname> of one-quarter of system <acronym>RAM</acronym>.
@@ -1415,7 +1317,7 @@ default:\
    </indexterm>
 
    <para>
-    In Linux 2.4 and later, the default virtual memory behavior is not
+    The default virtual memory behavior is not
     optimal for <productname>PostgreSQL</productname>. Because of the
     way that the kernel implements memory overcommit, the kernel might
     terminate the <productname>PostgreSQL</productname> postmaster (the
@@ -1462,7 +1364,7 @@ Out of Memory: Killed process 12345 (postgres).
    </para>
 
    <para>
-    On Linux 2.6 and later, it is possible to modify the
+    It is possible to modify the
     kernel's behavior so that it will not <quote>overcommit</quote> memory.
     Although this setting will not prevent the <ulink
     url="https://lwn.net/Articles/104179/">OOM killer</ulink> from being invoked
@@ -1508,28 +1410,12 @@ export PG_OOM_ADJUST_VALUE=0
    </para>
 
    <para>
-    Older Linux kernels do not offer <filename>/proc/self/oom_score_adj</filename>,
+    Very old Linux kernels do not offer <filename>/proc/self/oom_score_adj</filename>,
     but may have a previous version of the same functionality called
     <filename>/proc/self/oom_adj</filename>.  This works the same except the disable
     value is <literal>-17</literal> not <literal>-1000</literal>.
    </para>
 
-   <note>
-   <para>
-    Some vendors' Linux 2.4 kernels are reported to have early versions
-    of the 2.6 overcommit <command>sysctl</command> parameter.  However, setting
-    <literal>vm.overcommit_memory</literal> to 2
-    on a 2.4 kernel that does not have the relevant code will make
-    things worse, not better.  It is recommended that you inspect
-    the actual kernel source code (see the function
-    <function>vm_enough_memory</function> in the file <filename>mm/mmap.c</filename>)
-    to verify what is supported in your kernel before you try this in a 2.4
-    installation.  The presence of the <filename>overcommit-accounting</filename>
-    documentation file should <emphasis>not</emphasis> be taken as evidence that the
-    feature is there.  If in any doubt, consult a kernel expert or your
-    kernel vendor.
-   </para>
-   </note>
   </sect2>
 
   <sect2 id="linux-huge-pages">
-- 
2.20.1