Enhance hardening docs on trust and ident (#4155)

* Enhance hardening docs on trust and ident * Format source. No content changes.

Enhance hardening docs on trust and ident (#4155)
* Enhance hardening docs on trust and ident * Format source. No content changes.
9d0e8ef0 · Chuck Litzell · GitHub · f4de40b9 · 9d0e8ef0 · 9d0e8ef0
3 changed file
--- a/gpdb-doc/dita/admin_guide/client_auth.xml
+++ b/gpdb-doc/dita/admin_guide/client_auth.xml
@@ -10,9 +10,10 @@
        <i>superuser</i> role. This role will have the same name as the operating system user who
      initialized the Greenplum Database system. This role is referred to as
        <codeph>gpadmin</codeph>. By default, the system is configured to only allow local
-      connections to the database from the <codeph>gpadmin</codeph> role. To allow any other roles
-      to connect, or to allow connections from remote hosts, you configure Greenplum Database to
-      allow such connections. </p>
+      connections to the database from the <codeph>gpadmin</codeph> role. If you want to allow any
+      other roles to connect, or if you want to allow connections from remote hosts, you have to
+      configure Greenplum Database to allow such connections. This section explains how to configure
+      client connections and authentication to Greenplum Database.</p>
    <note>The PgBouncer connection pooler is bundled with Greenplum Database. PgBouncer can be
      configured to support LDAP or Active Directory authentication for users connecting to
      Greenplum Database through the connection pooler client connections to Greenplum Database. See
@@ -22,25 +23,23 @@
    <title id="ip142171">Allowing Connections to Greenplum Database</title>
    <body>
      <p>Client access and authentication is controlled by the standard PostgreSQL host-based
-        authentication file, <filepath>pg_hba.conf</filepath>. In Greenplum Database, the
-          <filepath>pg_hba.conf</filepath> file of the master instance controls client access and
-        authentication to your Greenplum Database system. Greenplum Database segments have
-          <filepath>pg_hba.conf</filepath> files that are configured to allow only client
-        connections from the master host and never accept client connections. Do not alter the
-          <filepath>pg_hba.conf</filepath> file on your segments.</p>
-      <p>See <xref href="https://www.postgresql.org/docs/9.0/static/auth-pg-hba-conf.html"
-          scope="external" format="html"><ph>The pg_hba.conf File</ph></xref> in the PostgreSQL
-        documentation for more information. </p>
+        authentication file, <filepath>pg_hba.conf</filepath>. For detailed information about this
+        file, see <xref href="http://www.postgresql.org/docs/9.0/interactive/auth-pg-hba-conf.html"
+          scope="external" format="html">The pg_hba.conf File</xref> in the PostgreSQL
+        documentation. </p>
+      <p>In Greenplum Database, the <filepath>pg_hba.conf</filepath> file of the master instance
+        controls client access and authentication to your Greenplum Database system. The Greenplum
+        Database segments also have <filepath>pg_hba.conf</filepath> files, but these are already
+        correctly configured to allow only client connections from the master host. The segments
+        never accept outside client connections, so there is no need to alter the
+          <codeph>pg_hba.conf</codeph> file on segments.</p>
      <p>The general format of the <filepath>pg_hba.conf</filepath> file is a set of records, one
-        per line. Blank lines and any text after the <codeph>#</codeph> comment character are ignored.
-        The first matching record is used for authentication. After the first match, the following
-        records are not evaluated. If the client cannot be authenticated using the method specified
-        in the first matching record, the connection is rejected. A record consists of a number of
-        fields that are separated by spaces and/or tabs. Fields can contain white space if the field
-        value is quoted. Records cannot be continued across multiple lines.
-        Each remote client access record has the following format:</p>
+        per line. Greenplum Database ignores blank lines and any text after the <codeph>#</codeph>
+        comment character. A record consists of a number of fields that are separated by spaces or
+        tabs. Fields can contain white space if the field value is quoted. Records cannot be
+        continued across lines. Each remote client access record has the following format:</p>
      <codeblock><i>host</i>   <i>database</i>   <i>role</i>   <i>CIDR-address</i>   <i>authentication-method</i></codeblock>
-      <p>Each UNIX-domain socket access record has the following format:</p>
+      <p>Each UNIX-domain socket access record is in this format:</p>
      <codeblock><i>local</i>   <i>database</i>   <i>role</i>   <i>authentication-method</i></codeblock>
      <p>The following table describes meaning of each field. </p>
      <table id="ip141709">
@@ -64,13 +63,14 @@
              <entry colname="col1">host</entry>
              <entry colname="col2">Matches connection attempts made using TCP/IP. Remote TCP/IP
                connections will not be possible unless the server is started with an appropriate
-                value for the <ph>listen_addresses</ph> server configuration parameter.</entry>
+                value for the <codeph>listen_addresses</codeph> server configuration
+                parameter.</entry>
            </row>
            <row>
              <entry colname="col1">hostssl</entry>
              <entry colname="col2">Matches connection attempts made using TCP/IP, but only when the
                connection is made with SSL encryption. SSL must be enabled at server start time by
-                setting the <ph>ssl</ph> configuration parameter</entry>
+                setting the <codeph>ssl</codeph> server configuration parameter. </entry>
            </row>
            <row>
              <entry colname="col1">hostnossl</entry>
@@ -101,41 +101,57 @@
                names. The mask length indicates the number of high-order bits of the client IP
                address that must match. Bits to the right of this must be zero in the given IP
                address. There must not be any white space between the IP address, the /, and the
-                CIDR mask length. <p>Typical examples of a CIDR-address are 192.0.2.89/32 for a
-                  single host, or 192.0.2.0/24 for a small network, or 10.6.0.0/16 for a larger one.
-                  To specify a single host, use a CIDR mask of 32 for IPv4 or 128 for IPv6. In a
-                  network address, do not omit trailing zeroes.</p></entry>
+                CIDR mask length. <p>Typical examples of a CIDR-address are 172.20.143.89/32 for a
+                  single host, or 172.20.143.0/24 for a small network, or 10.6.0.0/16 for a larger
+                  one. To specify a single host, use a CIDR mask of 32 for IPv4 or 128 for IPv6. In
+                  a network address, do not omit trailing zeroes.</p></entry>
            </row>
            <row>
              <entry colname="col1">IP-address<p>IP-mask</p></entry>
              <entry colname="col2">These fields can be used as an alternative to the CIDR-address
                notation. Instead of specifying the mask length, the actual mask is specified in a
-                separate column. For example, 255.255.255.255 represents a CIDR mask length of 32.
-                These fields only apply to host, hostssl, and hostnossl records. </entry>
+                separate column. For example, 255.0.0.0 represents an IPv4 CIDR mask length of 8,
+                and 255.255.255.255 represents a CIDR mask length of 32. These fields only apply to
+                and 255.255.255.255 represents a CIDR mask length of 32. These fields only apply to
+                host, hostssl, and hostnossl records. </entry>
            </row>
            <row>
              <entry colname="col1">authentication-method</entry>
              <entry colname="col2">Specifies the authentication method to use when connecting.
                Greenplum supports the <xref
-                  href="https://www.postgresql.org/docs/9.0/static/auth-methods.html"
-                  scope="external" format="html"><ph>authentication methods</ph></xref> supported by
+                  href="http://www.postgresql.org/docs/9.0/static/auth-methods.html"
+                  scope="external" format="html">authentication methods</xref> supported by
                PostgreSQL 9.0.</entry>
            </row>
          </tbody>
        </tgroup>
      </table>
+      <note type="caution">For a more secure system, consider removing records for remote
+        connections that use trust authentication from the <codeph>pg_hba.conf</codeph> file. Trust
+        authentication grants any user who can connect to the server access to the database using
+        any role they specify. You can safely replace trust authentication with ident authentication
+        for local UNIX-socket connections. You can also use ident authentication for local and
+        remote TCP clients, but the client host must be running an ident service and you must trust
+        the integrity of that machine.</note>
    </body>
    <topic id="topic3" xml:lang="en">
      <title id="ip141322">Editing the pg_hba.conf File</title>
      <body>
+        <p>Initially, the <codeph>pg_hba.conf</codeph> file is set up with generous permissions for
+          the gpadmin user and no database access for other Greenplum Database roles. You will need
+          to edit the <codeph>pg_hba.conf</codeph> file to enable users' access to databases and to
+          secure the gpadmin user. Consider removing entries that have trust authentication, since
+          they allow anyone with access to the server to connect with any role they choose. For
+          local (UNIX socket) connections, use ident authentication, which requires the operating
+          system user to match the role specified. For local and remote TCP connections, ident
+          authentication requires the client's host to run an indent service. You can install an
+          ident service on the master host and then use ident authentication for local TCP
+          connections, for example 127.0.0.1/28. Using ident authentication for remote TCP
+          connections is less secure because it requires you to trust the integrity of the ident
+          service on the client's host.</p>
        <p>This example shows how to edit the <filepath>pg_hba.conf</filepath> file of the master to
          allow remote client access to all databases from all roles using encrypted password
          authentication.</p>
-        <note type="note">For a more secure system, consider removing all connections that use trust
-          authentication from your master <filepath>pg_hba.conf</filepath>. Trust authentication
-          means the role is granted access without any authentication, therefore bypassing all
-          security. Replace trust entries with ident authentication if your system has an ident
-          service available.</note>
        <section id="ip144328">
          <title>Editing pg_hba.conf</title>
          <ol id="ol_xz4_x15_jp">
@@ -186,8 +202,8 @@ ldapsuffix=",ou=People,dc=company,dc=com"</codeblock></li>
        can configure the <codeph>max_connections</codeph> server configuration parameter. This is a
          <i>local</i> parameter, meaning that you must set it in the
          <codeph>postgresql.conf</codeph> file of the master, the standby master, and each segment
-        instance (primary and mirror). The value of <codeph>max_connections</codeph> on segments
-        should be 5-10 times the value on the master.</p>
+        instance (primary and mirror). The recommended value of <codeph>max_connections</codeph> on
+        segments is 5-10 times the value on the master.</p>
      <p>When you set <codeph>max_connections</codeph>, you must also set the dependent parameter
          <codeph>max_prepared_transactions</codeph>. This value must be at least as large as the
        value of <codeph>max_connections</codeph> on the master, and segment instances should be set
@@ -227,9 +243,9 @@ max_prepared_transactions=100
            on the master to 200.<p>
              <codeblock>$ gpconfig -c max_connections -v 1000 -m 200
 </codeblock>
-            </p><p>The value on the segments must be greater than the value on the master. The value
-              of <codeph>max_connections</codeph> on segments should be 5-10 times the value on the
-              master. </p></li>
+            </p><p>The value on the segments must be greater than the value on the master. The
+              recommended value of <codeph>max_connections</codeph> on segments is 5-10 times the
+              value on the master. </p></li>
          <li id="ip146502">Set the value of the <codeph>max_prepared_transactions</codeph>
            parameter. This <codeph>gpconfig</codeph> command sets the value to 200 on the master
            and all segments.<p>

--- a/gpdb-doc/dita/security-guide/topics/Authenticate.xml
+++ b/gpdb-doc/dita/security-guide/topics/Authenticate.xml
@@ -40,10 +40,10 @@
        client access record is in this format:
        <codeblock>host   database   role   CIDR-address   authentication-method
 </codeblock></p>
-      <p>Each UNIX-domain socket access record is in this format:
+      <p>A UNIX-domain socket access record is in this format:
        <codeblock>local   database   role   authentication-method
 </codeblock></p>
-      <p>The meaning of the <codeph>pg_hba_conf</codeph> fields is as follows: <parml>
+      <p>The meaning of the <codeph>pg_hba.conf</codeph> fields is as follows: <parml>
          <plentry>
            <pt>local</pt>
            <pd> Matches connection attempts using UNIX-domain sockets. Without a record of this
@@ -110,21 +110,35 @@
          <plentry>
            <pt> authentication-method </pt>
            <pd> Specifies the authentication method to use when connecting. See <xref
-                href="#topic_nyh_gwd_jr" format="dita"/> for more details. </pd>
+                href="#topic_nyh_gwd_jr" format="dita"/> for options. </pd>
          </plentry>
        </parml></p>
+      <note type="caution">For a more secure system, consider removing records for remote
+        connections that use trust authentication from the <codeph>pg_hba.conf</codeph> file. Trust
+        authentication grants any user who can connect to the server access to the database using
+        any role they specify. You can safely replace trust authentication with ident authentication
+        for local UNIX-socket connections. You can also use ident authentication for local and
+        remote TCP clients, but the client host must be running an ident service and you must trust
+        the integrity of that machine.</note>
    </body>
  </topic>
  <topic id="topic_xwr_rvd_jr">
    <title>Editing the pg_hba.conf File</title>
    <body>
+      <p>Initially, the <codeph>pg_hba.conf</codeph> file is set up with generous permissions for
+        the gpadmin user and no database access for other Greenplum Database roles. You will need to
+        edit the <codeph>pg_hba.conf</codeph> file to enable users' access to databases and to
+        secure the gpadmin user. Consider removing entries that have trust authentication, since
+        they allow anyone with access to the server to connect with any role they choose. For local
+        (UNIX socket) connections, use ident authentication, which requires the operating system
+        user to match the role specified. For local and remote TCP connections, ident authentication
+        requires the client's host to run an indent service. You could install an ident service on
+        the master host and then use ident authentication for local TCP connections, for example
+        127.0.0.1/28. Using ident authentication for remote TCP connections is less secure because
+        it requires you to trust the integrity of the ident service on the client's host. </p>
      <p>This example shows how to edit the <codeph>pg_hba.conf</codeph> file of the master to allow
        remote client access to all databases from all roles using encrypted password
        authentication. </p>
-      <note>For a more secure system, consider removing all connections that use trust
-        authentication from your master <codeph>pg_hba.conf</codeph>. Trust authentication means the
-        role is granted access without any authentication, therefore bypassing all security. Replace
-        trust entries with ident authentication if your system has an ident service available. </note>
      <p>To edit <codeph>pg_hba.conf</codeph>:<ol id="ol_krz_zvd_jr">
          <li>Open the file <codeph>$MASTER_DATA_DIRECTORY/pg_hba.conf</codeph> in a text
            editor.</li>
@@ -190,8 +204,10 @@ host    all   dba   192.168.0.0/32  md5
            </plentry>
            <plentry>
              <pt>Ident</pt>
-              <pd>Authenticates based on the client's operating system user name. You should only
-                use this for local connections.</pd>
+              <pd>Authenticates based on the client's operating system user name. This is secure for
+                local socket connections. Using ident for TCP connections from remote hosts requires
+                that the client's host is running an ident service. The ident authentication method
+                should only be used with remote hosts on a trusted, closed network. </pd>
            </plentry>
          </parml></p>
        <p>Following are some sample <codeph>pg_hba.conf</codeph> basic authentication

--- a/gpdb-doc/dita/utility_guide/client_utilities/psql.xml
+++ b/gpdb-doc/dita/utility_guide/client_utilities/psql.xml
@@ -178,6 +178,8 @@
            <pd>The host name of the machine on which the Greenplum master database server is
              running. If not specified, reads from the environment variable <codeph>PGHOST</codeph>
              or defaults to localhost.</pd> 
+             <pd>When starting <codeph>psql</codeph> on the master host, if the <varname>host</varname> 
+              value begins with a slash, it is used as the directory for the UNIX-domain socket.</pd>
          </plentry>
          <plentry>
            <pt>-p <varname>port</varname> | --port <varname>port</varname></pt>