From 1941d8e5c24f38798edd6a63b68a9687511f349c Mon Sep 17 00:00:00 2001
From: "Jonathan S. Katz" <jonathan.katz@excoventures.com>
Date: Fri, 5 Apr 2019 12:02:40 -0400
Subject: [PATCH] Add a warning about the client authentication defaults that
 initdb provides.

This also provides advice on how to securely set up initial client connection
configurations, and removes the section that explains similar steps that is
below the directory setup. This information should be around where its explained
how initdb is first called, anyway.
---
 doc/src/sgml/runtime.sgml | 46 ++++++++++++++++++++++++----------------------
 1 file changed, 24 insertions(+), 22 deletions(-)

diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index fde9dbc134..dd1a8bc90f 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -85,6 +85,29 @@
    described in the previous section.
   </para>
 
+  <warning>
+    <para>
+      By default <command>initdb</command> sets up <literal>trust</literal>
+      client authentication for connecting to the database. This is not
+      recommended on multi-user systems where you do not trust all users, nor if
+      the database server will be made accessible to remote systems.
+    </para>
+    <para>
+      We recommend using the <option>-W</option>, <option>--pwprompt</option>,
+      or <option>--pwfile</option> flags to assign a password to the database
+      superuser, and to override the <filename>pg_hba.conf</filename> default
+      generation using <option>-auth-local peer</option> for local connections,
+      and <option>-auth-host scram-sha-256</option> for remote connections. See
+      <xref linkend="client-authentication"/> for more information on client
+      authentication methods.
+    </para>
+    <para>
+      If installing PostgreSQL from a distribution, we recommend you validate
+      your initially generated <filename>pg_hba.conf</filename> file to ensure
+      it meets your operational requirements.
+    </para>
+  </warning>
+
   <tip>
    <para>
     As an alternative to the <option>-D</option> option, you can set
@@ -155,27 +178,6 @@ postgres$ <userinput>initdb -D /usr/local/pgsql/data</userinput>
    for directories and <literal>0640</literal> for files.
   </para>
 
-  <para>
-   However, while the directory contents are secure, the default
-   client authentication setup allows any local user to connect to the
-   database and even become the database superuser. If you do not
-   trust other local users, we recommend you use one of
-   <command>initdb</command>'s <option>-W</option>, <option>--pwprompt</option>
-   or <option>--pwfile</option> options to assign a password to the
-   database superuser.<indexterm>
-     <primary>password</primary>
-     <secondary>of the superuser</secondary>
-   </indexterm>
-   Also, specify <option>-A md5</option> or
-   <option>-A password</option> so that the default <literal>trust</literal> authentication
-   mode is not used; or modify the generated <filename>pg_hba.conf</filename>
-   file after running <command>initdb</command>, but
-   <emphasis>before</emphasis> you start the server for the first time. (Other
-   reasonable approaches include using <literal>peer</literal> authentication
-   or file system permissions to restrict connections. See <xref
-   linkend="client-authentication"/> for more information.)
-  </para>
-
   <para>
    <command>initdb</command> also initializes the default
    locale<indexterm><primary>locale</primary></indexterm> for the database cluster.
@@ -643,7 +645,7 @@ psql: could not connect to server: No such file or directory
     amount of anonymous <function>mmap</function> shared memory.
     Alternatively, a single large System V shared memory region can be used
     (see <xref linkend="guc-shared-memory-type"/>).
-    
+
     In addition a significant number of semaphores, which can be either
     System V or POSIX style, are created at server startup.  Currently,
     POSIX semaphores are used on Linux and FreeBSD systems while other
-- 
2.14.3 (Apple Git-98)