Docs pgbouncer update 6x (#10608)

* Update libevent requirement for RHEL/CentOS 6

* Add new features introduced in 1.9.x

* Add 1.11.x features

* Add 1.12.x feature

* Add 1.13.x features

* Update version in doc notice

gpdb-doc/dita/admin_guide/access_db/topics/pgbouncer.xml

@@ -114,21 +114,45 @@ admin_users = gpadmin</codeblock></p>
           password information for users that are not in the authentication file. </p>
       <section id="pgb_auth">
         <title>PgBouncer Authentication File Format</title>
-        <p>PgBouncer requires its own user authentication file. You specify the name of this file 
-          in the <codeph>auth_file</codeph> property of the <codeph>pgbouncer.ini</codeph> configuration
-           file. <codeph>auth_file</codeph> is a text file in the following format:</p>
+        <p>PgBouncer requires its own user authentication file. You specify the name of this file in
+          the <codeph>auth_file</codeph> property of the <codeph>pgbouncer.ini</codeph>
+          configuration file. <codeph>auth_file</codeph> is a text file in the following format:</p>
         <codeblock>"username1" "password" ...
-"username2" "md5abcdef012342345" ...</codeblock>
-        <p><codeph>auth_file</codeph> contains one line per user. Each line must have at least two fields,
-          both of which are enclosed in double quotes (<codeph>" "</codeph>). The first
-          field identifies the Greenplum Database user name. The second field is
-          either a plain-text or an MD5-encoded password. PgBouncer ignores the remainder of the line.</p>
-        <p>(The format of <codeph>auth_file</codeph> is similar to that of the <codeph>pg_auth</codeph>
-          text file that Greenplum Database uses for authentication information. PgBouncer
-          can work directly with this Greenplum Database authentication file.)</p>
-        <p>Use an MD5 encoded password. The format of an MD5 encoded password is: 
-        <codeblock>"md5" + MD5_encoded(<varname>&lt;password>&lt;username></varname>)</codeblock></p>
-        <p>You can also obtain the MD5-encoded passwords of all Greenplum Database users from the <codeph>pg_shadow</codeph> view.</p>
+"username2" "md5abcdef012342345" ...
+"username2" "SCRAM-SHA-256$&lt;iterations>:&lt;salt>$&lt;storedkey>:&lt;serverkey>"</codeblock>
+        <p><codeph>auth_file</codeph> contains one line per user. Each line must have at least two
+          fields, both of which are enclosed in double quotes (<codeph>" "</codeph>). The first
+          field identifies the Greenplum Database user name. The second field is either a plain-text
+          password, an MD5-encoded password, or or a SCRAM secret. PgBouncer ignores the remainder
+          of the line.</p>
+        <p>(The format of <codeph>auth_file</codeph> is similar to that of the
+            <codeph>pg_auth</codeph> text file that Greenplum Database uses for authentication
+          information. PgBouncer can work directly with this Greenplum Database authentication
+          file.)</p>
+        <p>Use an MD5 encoded password. The format of an MD5 encoded password is:
+          <codeblock>"md5" + MD5_encoded(<varname>&lt;password>&lt;username></varname>)</codeblock></p>
+        <p>You can also obtain the MD5-encoded passwords of all Greenplum Database users from the
+            <codeph>pg_shadow</codeph> view.</p>
+        <p>PostgreSQL SCRAM secret
+          format:<codeblock>SCRAM-SHA-256$&lt;iterations>:&lt;salt>$&lt;storedkey>:&lt;serverkey></codeblock></p>
+        <p>See the PostgreSQL documentation and RFC 5803 for details on this.</p>
+        <p>The passwords or secrets stored in the authentication file serve two purposes. First,
+          they are used to verify the passwords of incoming client connections, if a password-based
+          authentication method is configured. Second, they are used as the passwords for outgoing
+          connections to the backend server, if the backend server requires password-based
+          authentication (unless the password is specified directly in the database’s connection
+          string). The latter works if the password is stored in plain text or MD5-hashed. SCRAM
+          secrets can only be used for logging into a server if the client authentication also uses
+          SCRAM, the PgBouncer database definition does not specify a user name, and the SCRAM
+          secrets are identical in PgBouncer and the PostgreSQL server (same salt and iterations,
+          not merely the same password). This is due to an inherent security property of SCRAM: The
+          stored SCRAM secret cannot by itself be used for deriving login credentials.</p>
+        <p>The authentication file can be written by hand, but it’s also useful to generate it from
+          some other list of users and passwords. See <codeph>./etc/mkauth.py</codeph> for a
+          sample script to generate the authentication file from the
+          <codeph>pg_shadow</codeph> system table. Alternatively, use
+          <codeblock>auth_query</codeblock> instead of <codeph>auth_file</codeph> to avoid
+          having to maintain a separate authentication file.\u0000</p>
       </section>
       <section id="pgb_hba">
         <title>Configuring HBA-based Authentication for PgBouncer</title>

gpdb-doc/dita/install_guide/install_gpdb.xml

@@ -91,9 +91,13 @@ $ sudo chgrp -R gpadmin /usr/local/greenplum*</codeblock></li>
           systems, or <codeph>greenplum-db-&lt;version>-&lt;platform>.deb</codeph> for Ubuntu
           systems, where <codeph>&lt;platform></codeph> is similar to <codeph>rhel7-x86_64</codeph>
           (Red Hat 7 64-bit).</li>
-        <li>Manually install the Greenplum Database dependencies to each host
-          system:<codeblock>$ sudo yum install apr apr-util bash bzip2 curl krb5 libcurl libevent \
-libxml2 libyaml zlib openldap openssh openssl openssl-libs perl readline rsync R sed tar zip</codeblock>
+        <li>Manually install the Greenplum Database dependencies to each host system. For
+          RHEL/CentOS
+            7:<codeblock>$ sudo yum install apr apr-util bash bzip2 curl krb5 libcurl libevent \
+libxml2 libyaml zlib openldap openssh openssl openssl-libs perl readline rsync R sed tar zip</codeblock><p>For
+            RHEL/CentOS
+            6:<codeblock>$ sudo yum install apr apr-util bash bzip2 curl krb5 libcurl libevent2 \
+libxml2 libyaml zlib openldap openssh openssl openssl-libs perl readline rsync R sed tar zip</codeblock></p>
         </li>
         <li>Use <codeph>rpm</codeph> with the <codeph>--prefix</codeph> option to install the
           Greenplum Database package to your chosen installation directory on each host machine:

gpdb-doc/dita/install_guide/platform-requirements.xml

@@ -69,7 +69,7 @@
             <li>curl</li>
             <li>krb5</li>
             <li>libcurl</li>
-            <li>libevent</li>
+            <li>libevent (or libevent2 on RHEL/CentOS 6)</li>
             <li>libxml2</li>
             <li>libyaml</li>
             <li>zlib</li>

gpdb-doc/dita/utility_guide/ref/pgbouncer-admin.xml

@@ -96,11 +96,40 @@ DETAIL:
           <pd>Stop PgBouncer process. To exit from the <codeph>psql</codeph> command line
             session, enter <codeph>\q</codeph>.</pd>
         </plentry>
+        <plentry>
+          <pt>RECONNECT</pt>
+          <pd>Close each open server connection for the given database, or all databases, after it
+            is released (according to the pooling mode), even if its lifetime is not up yet. New
+            server connections can be made immediately and will connect as necessary according to
+            the pool size settings.</pd>
+          <pd>This command is useful when the server connection setup has changed, for example to
+            perform a gradual switchover to a new server. It is <i>not</i> necessary to run this
+            command when the connection string in pgbouncer.ini has been changed and reloaded (see
+              <codeph>RELOAD</codeph>) or when DNS resolution has changed, because then the
+            equivalent of this command will be run automatically. This command is only necessary if
+            something downstream of PgBouncer routes the connections.</pd>
+          <pd>After this command is run, there could be an extended period where some server
+            connections go to an old destination and some server connections go to a new
+            destination. This is likely only sensible when switching read-only traffic between
+            read-only replicas, or when switching between nodes of a multimaster replication setup.
+            If all connections need to be switched at the same time, <codeph>PAUSE</codeph> is
+            recommended instead. To close server connections without waiting (for example, in
+            emergency failover rather than gradual switchover scenarios), also consider
+              <codeph>KILL</codeph>.</pd>
+        </plentry>
         <plentry>
           <pt>RELOAD</pt>
           <pd>The PgBouncer process reloads the current configuration file and updates the
             changeable settings.</pd>
         </plentry>
+        <plentry>
+          <pt>WAIT_CLOSE [ <varname>db</varname> ]</pt>
+          <pd>Wait until all server connections, either of the specified database or of all
+            databases, have cleared the “close_needed” state (see <codeph>SHOW SERVERS</codeph>). This can be
+            called after a <codeph>RECONNECT</codeph> or <codeph>RELOAD</codeph> to wait until the respective
+            configuration change has been fully activated, for example in switchover
+            scripts.</pd>
+        </plentry>
         <plentry>
           <pt>SET <varname>key</varname> = <varname>value</varname></pt>
           <pd>Override specified configuration setting. See the <xref href="#CONFIG"
@@ -854,6 +883,12 @@ DETAIL:
                 <entry>wait_us</entry>
                 <entry>Time waiting (microseconds).</entry>
               </row>
+              <row>
+                <entry>close_needed</entry>
+                <entry>1 if the connection will be closed as soon as possible, because a
+                  configuration file reload or DNS update changed the connection information or
+                    <codeph>RECONNECT</codeph> was issued.</entry>
+              </row>
               <row>
                 <entry>ptr</entry>
                 <entry>Address of the internal object for this connection. Used as unique
@@ -1009,7 +1044,7 @@ DETAIL:
       <title>VERSION</title>
       <body>
         <p>Display PgBouncer version information.</p>
-        <note>This reference documentation is based on the PgBouncer 1.8.1 documentation.</note>
+        <note>This reference documentation is based on the PgBouncer 1.13 documentation.</note>
       </body>
     </topic>
   </topic>

gpdb-doc/dita/utility_guide/ref/pgbouncer-ini.xml

@@ -414,6 +414,13 @@ db = ...
             <pt>log_pooler_errors</pt>
             <pd>Log error messages that the pooler sends to clients.<p>Default: 1</p></pd>
           </plentry>
+          <plentry>
+            <pt>log_stats</pt>
+            <pd>Write aggregated statistics into the log, every <codeph>stats_period</codeph>. This
+              can be disabled if external monitoring tools are used to grab the same data from
+                <codeph>SHOW</codeph> commands.<p>Default: 1</p>
+            </pd>
+          </plentry>
           <plentry>
             <pt>stats_period</pt>
             <pd>How often to write aggregated statistics to the log. <p>Default: 60</p></pd>
@@ -479,6 +486,23 @@ db = ...
             <pd>A simple do-nothing query to test the server connection.<p>If an empty string,
                 then sanity checking is disabled.</p><p>Default: SELECT 1;</p></pd>
           </plentry>
+          <plentry>
+            <pt>server_fast_close</pt>
+            <pd>Disconnect a server in session pooling mode immediately or after the end of the
+              current transaction if it is in “close_needed” mode (set by
+              <codeph>RECONNECT</codeph>, <codeph>RELOAD</codeph> that changes connection settings,
+              or DNS change), rather than waiting for the session end. In statement or transaction
+              pooling mode, this has no effect since that is the default behavior there.<p>If
+                because of this setting a server connection is closed before the end of the client
+                session, the client connection is also closed. This ensures that the client notices
+                that the session has been interrupted.</p><p>This setting makes connection
+                configuration changes take effect sooner if session pooling and long-running
+                sessions are used. The downside is that client sessions are liable to be interrupted
+                by a configuration change, so client applications will need logic to reconnect and
+                reestablish session state. But note that no transactions will be lost, because
+                running transactions are not interrupted, only idle sessions.</p><p>Default:
+              0</p></pd>
+          </plentry>
           <plentry>
             <pt>server_lifetime</pt>
             <pd>The pooler tries to close server connections that have been connected longer
@@ -552,7 +576,7 @@ db = ...
           <plentry><pt>client_tls_cert_file</pt><pd>Root certificate file to validate client certificates.</pd><pd><p>Default: unset</p></pd>
           </plentry>
           <plentry><pt>client_tls_ca_file</pt><pd>Root certificate to validate client certificates.</pd><pd><p>Default: unset</p></pd></plentry>
-          <plentry><pt>client_tls_protocols</pt><pd>Which TLS protocol versions are allowed. </pd><pd>Valid values: are <codeph>tlsv1.0</codeph>, <codeph>tlsv1.1</codeph>, <codeph>tlsv1.2</codeph>. </pd><pd>Shortcuts: <codeph>all</codeph> (<codeph>tlsv1.0</codeph>,<codeph>tlsv1.1</codeph>,<codeph>tlsv1.2</codeph>), <codeph>secure</codeph> (<codeph>tlsv1.2</codeph>), <codeph>legacy</codeph> (<codeph>all</codeph>).</pd><pd><p>Default: <codeph>all</codeph></p></pd>
+          <plentry><pt>client_tls_protocols</pt><pd>Which TLS protocol versions are allowed. </pd><pd>Valid values: are <codeph>tlsv1.0</codeph>, <codeph>tlsv1.1</codeph>, <codeph>tlsv1.2</codeph>. </pd><pd>Shortcuts: <codeph>all</codeph> (<codeph>tlsv1.0</codeph>,<codeph>tlsv1.1</codeph>,<codeph>tlsv1.2</codeph>), <codeph>secure</codeph> (<codeph>tlsv1.2</codeph>), <codeph>legacy</codeph> (<codeph>all</codeph>).</pd><pd><p>Default: <codeph>secure</codeph></p></pd>
           </plentry>
           <plentry><pt>client_tls_ciphers</pt><pd><p>Default: <codeph>fast</codeph></p></pd>
           </plentry>
@@ -574,7 +598,7 @@ db = ...
           </plentry>
           <plentry><pt>server_tls_cert_file</pt><pd>Certificate for private key. Greenplum Database or PostgreSQL servers can validate it.</pd><pd><p>Default: not set</p></pd>
           </plentry>
-          <plentry><pt>server_tls_protocols</pt><pd>Which TLS protocol versions are allowed. </pd><pd>Valid values are: <codeph>tlsv1.0</codeph>, <codeph>tlsv1.1</codeph>, <codeph>tlsv1.2</codeph>. </pd><pd>Shortcuts: <codeph>all</codeph> (<codeph>tlsv1.0</codeph>, <codeph>tlsv1.1</codeph>, <codeph>tlsv1.2</codeph>); <codeph>secure</codeph> (<codeph>tlsv1.2</codeph>); <codeph>legacy</codeph> (<codeph>all</codeph>).</pd><pd><p>Default: <codeph>all</codeph></p></pd>
+          <plentry><pt>server_tls_protocols</pt><pd>Which TLS protocol versions are allowed. </pd><pd>Valid values are: <codeph>tlsv1.0</codeph>, <codeph>tlsv1.1</codeph>, <codeph>tlsv1.2</codeph>. </pd><pd>Shortcuts: <codeph>all</codeph> (<codeph>tlsv1.0</codeph>, <codeph>tlsv1.1</codeph>, <codeph>tlsv1.2</codeph>); <codeph>secure</codeph> (<codeph>tlsv1.2</codeph>); <codeph>legacy</codeph> (<codeph>all</codeph>).</pd><pd><p>Default: <codeph>secure</codeph></p></pd>
           </plentry>
           <plentry><pt>server_tls_ciphers</pt><pd><p>Default: <codeph>fast</codeph></p></pd>
           </plentry>
@@ -639,6 +663,23 @@ db = ...
               time. One loop processes one <codeph>pkt_buf</codeph> amount of data. 0 means no
                 limit.<p>Default: 5</p></pd>
           </plentry>
+          <plentry>
+            <pt>SO_REUSEPORT</pt>
+            <pd>Specifies whether to set the socket option <codeph>SO_REUSEPORT</codeph> on TCP
+              listening sockets. On some operating systems, this allows running multiple PgBouncer
+              instances on the same host listening on the same port and having the kernel distribute
+              the connections automatically. This option is a way to get PgBouncer to use more CPU
+              cores. (PgBouncer is single-threaded and uses one CPU core per instance.)<p>The
+                behavior in detail depends on the operating system kernel. As of this writing, this
+                setting has the desired effect on recent versions of Linux. On systems that don’t
+                support the socket option at all, turning this setting on will result in an
+                error.</p><p>Each PgBouncer instance on the same host needs different settings for
+                at least <codeph>unix_socket_dir</codeph> and <codeph>pidfile</codeph>, as well as
+                  <codeph>logfile</codeph> if that is used. Also note that if you make use of this
+                option, you can no longer connect to a specific PgBouncer instance via TCP/IP, which
+                might have implications for monitoring and metrics collection.</p><p>Default:
+              0</p></pd>
+          </plentry>
           <plentry>
             <pt>suspend_timeout</pt>
             <pd>How many seconds to wait for buffer flush during <codeph>SUSPEND</codeph> or
@@ -672,6 +713,14 @@ db = ...
             <pt>tcp_keepintvl</pt>
             <pd><p>Default: not set</p></pd>
           </plentry>
+          <plentry>
+            <pt>tcp_user_timeout</pt>
+            <pd>Sets the <codeph>TCP_USER_TIMEOUT</codeph> socket option. This specifies the maximum
+              amount of time in milliseconds that transmitted data may remain unacknowledged before
+              the TCP connection is forcibly closed. If set to 0, then operating system’s default is
+                used.<p>Default: 0</p>
+            </pd>
+          </plentry>
         </parml>
       </section>
     </body>