From d610f4e575b6ee634b94dc6cb9125c4dbaedc305 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, 25 insertions(+), 21 deletions(-)

diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index e053e2ee34..040aacf87f 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -85,6 +85,31 @@
    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,
+      (except on Windows, use <option>-auth-local scram-sha-256</option> as
+      peer authentication is not supported) 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 +180,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.
-- 
2.14.3 (Apple Git-98)