Merge pull request #1907 from EnterpriseDB/release/2021-10-06

Release/2021-10-06

Author: drothery-edb

product_docs/docs/edbcloud/beta/reference/index.mdx

@@ -8,15 +8,21 @@ The API reference documentation is available from the [EDB Cloud portal](https:/
 
 To access the API, you need a token. The high-level steps to obtain a token are:
 1. [Query the authentication endpoint](#query-the-authentication-endpoint).
-2. [Request the device code](#request-the-device-code).
+2. [Request the device code](#request-the-device-code-using-curl).
 3. [Authorize as a user](#authorize-as-a-user).
-4. [Request the token](#request-the-token).
+4. [Request the token](#request-the-token-using-curl).
 
 
+EDB provides an optional script to simplify getting your device code and getting and refreshing your tokens. See [Using the `get-token` Script](#using-the-get-token-script) for details.
+
 
 ## Query the Authentication Endpoint
 
-Use the following command to get the information returned by the authentication endpoint that you need later:
+This call returns the information that either:
+
+- you need later if you are using `curl` to request the device code and tokens, or 
+- the `get-token` script uses to generate the tokens for you
+
 
 ```
 curl https://portal.edbcloud.com/api/v1/auth/provider
@@ -32,19 +38,21 @@ The response returns the `clientId`, `issuerUri`, `scope`, and `audience`. For e
 }
 ```
 
-EDB recommends you store the output in environment variables to make including them in the following calls easier. For example,
+EDB recommends you store the output in environment variables to make including them in the following calls easier. For example:
 
 ```
 CLIENT_ID=pM8PRguGtW9yVnrsvrvpaPyyeS9fVvFh
 ISSUER_URL=https://auth.edbcloud.com
 SCOPE="openid profile email offline_access"
 AUDIENCE="https://portal.edbcloud.com/api"
 ```
-The following example calls show use these environment variables.
-
-## Request the Device code
+The following example calls use these environment variables.
 
-Use the following call to get a device code:
+## Request the Device Code Using `curl`
+!!!note
+   The `get-token` script executes this step. You don't need to make this call if you are using the script. 
+!!!   
+This call gets a device code:
 ```
 curl --request POST \
   --url "$ISSUER_URL/oauth/device/code" \
@@ -56,7 +64,7 @@ curl --request POST \
 
 The response returns:
 
-- `device_code` - the unique code for the device. When you go to the `verification_uri` in your browser-based device, this code is bound to your session. You use this code in your [request for a token](#request-the-token).
+- `device_code` - the unique code for the device. When you go to the `verification_uri` in your browser-based device, this code is bound to your session. You use this code in your [request for a token](#request-the-token-using-curl).
 - `user_code` - the code you input at the `verification_uri` to authorize the device. You use this code when you [authorize yourself as a user](#authorize-as-a-user).
 - `verification_uri` - the URL you use to authorize your device.
 - `verification_uri_complete` - the complete URL you use to authorize the device. You can use this URL to embed the user code in your app's URL.
@@ -75,26 +83,31 @@ For example:
 }
 ```
 
-Store the device_code in an environment variable for future use. For example;
+Store the device code in an environment variable for future use. For example:
 
 ```
 DEVICE_CODE=KEOY2_5YjuVsRuIrrR-aq5gs
 ```
 
 ## Authorize as a User
 
+To authorize as a user:
+
 1. Go to the `verification_uri` in your web browser, enter your `user_code`, and select **Continue**.
 
-4. Select **Confirm** on the Device Confirmation dialog.
+2. Select **Confirm** on the Device Confirmation dialog.
 
-5. Select **Continue with Microsoft Azure AD** on the EDB Cloud Welcome screen.
+3. Select **Continue with Microsoft Azure AD** on the EDB Cloud Welcome screen.
 
-6. Log in with your Azure AD credentials.
+4. Log in with your Azure AD credentials.
 
 
-## Request the Token
+## Request the Token Using `curl`
+!!!note
+   The `get-token` script executes this step. You don't need to make this call if you are using the script. See [Request Your Token Using `get-token`](#request-your-token-using-get-token).
+!!!   
 
-Use the `curl --request POST` command to request a token. For example,
+The `curl --request POST` call requests a token. For example:
 ```
 curl --request POST \
   --url "$ISSUER_URL/oauth/token" \
@@ -121,17 +134,17 @@ For example:
   "token_type": "Bearer"
 }
 ```
-Store the access_token and refresh_token in environment variables for future use. For example,
+Store the access token and refresh token in environment variables for future use. For example:
 
 ```
 ACCESS_TOKEN="eyJhbGc.......1Qtkaw2fyho"
 REFRESH_TOKEN="v1.MTvuZpu.......sbiionEhtTw"
 ```
 
 If not successful, you receive one of the following errors:
-- `authorization_pending` - continue polling using the suggested interval retrieved when you [requested the device code](#request-the-device-code).
+- `authorization_pending` - continue polling using the suggested interval retrieved when you [requested the device code](#request-the-device-code-using-curl).
 
-- `slow_down` - slow down and use the suggested interval retrieved when you [requested the device code](#request-the-device-code). To avoid receiving this error due to network latency, you should start counting each interval after receipt of the last polling request's response.
+- `slow_down` - slow down and use the suggested interval retrieved when you [requested the device code](#request-the-device-code-using-curl). To avoid receiving this error due to network latency, you should start counting each interval after receipt of the last polling request's response.
 - `expired_token` - you have not authorized the device quickly enough, so the `device_code` has expired. Your application should notify you that it has expired and to restore it.
 - `access_denied`
 
@@ -171,11 +184,16 @@ Example response:
 ```
 
 
-## Refreshing your Token
+## Refresh your Token
+
+You use the refresh token to get a new access token. Usually you need a new access token only after the previous one expires or when gaining access to a new resource for the first time. You shouldn't call the endpoint to get a new access token every time you call an API. There are rate limits that throttle the amount of requests to the endpoint that can be executed using the same token from the same IP.
 
-You can use the refresh token to get a new access token. Usually you need a new access token only after the previous one expires or when gaining access to a new resource for the first time. You shouldn't call the endpoint to get a new access token every time you call an API. There are rate limits that throttle the amount of requests to the endpoint that can be executed using the same token from the same IP.
+### Refresh your Token Using `curl`
+!!!note
+The `get-token` script has an option to execute this step. See [Refresh the Token Using `get-token`](#refresh-the-token-using-get-token).
+!!!
 
-To refresh your token, make a POST request to the `/oauth/token` endpoint in the Authentication API, using `grant_type=refresh_token`. For example:
+If you are not using the `get-token` script to refresh your token, make a POST request to the `/oauth/token` endpoint in the Authentication API, using `grant_type=refresh_token`. For example:
 ```
 curl --request POST \
   --url "$ISSUER_URL/oauth/token" \
@@ -201,14 +219,69 @@ The response of this API call includes the `access_token`. For example:
 ```
 
 !!! Note
-    You need to save the `refresh_token` retrieved from this response for the next refresh call. The `refresh_token` in the response when you originally [requested the token](#request-the-token) is obsoleted once it has been used.
+    You need to save the refresh token retrieved from this response for the next refresh call. The refresh token in the response when you originally [requested the token](#request-the-token) is obsoleted once it has been used.
 
 
 
+## Using the `get-token` Script
 
 
+To simplify the process of getting tokens, EDB provides the `get-token` script. You can download it [here](https://github.com/EnterpriseDB/cloud-utilities/tree/main/api).
 
+To use the script, install the [jq command-line JSON processor](https://stedolan.github.io/jq/) specific to your OS.
 
+Before running the script, [query the authentication endpoint](#query-the-authentication-endpoint).
 
+### get-token Usage
 
+```
+Usage:
+./get-token.sh [flags] [options]
+
+flags:
+--format (-o) json | plain   output format
+--refresh <refresh_token>    [optional] query for tokens
+                             again using  given <refresh_token>
+                             this revokes and rotates the refresh
+                             token. Please remember the newly
+                             returned refresh_token for the next use.
+
+```
+
+### Request Your Token Using `get-token` 
+To use the `get-token` script to get your tokens, use the script without the `--refresh` option. For example:
+
+```
+./get-token.sh -o plain
+Please login to
+https://edbcloud.us.auth0.com/activate?user_code=ZMNX-VVJT
+with your EDB Cloud account
+Have you finished the login successfully? (y/N) y
+
+####### Access Token ################
+eyxxxxxxxxxxxxxx
+
+####### Refresh Token ###############
+xxxxxxxxxx
+
+#######   ID Token    ###############
+xxxxxxxxxxxx
+
+#####   Expires In Seconds ##########
+86400
+```
+###  Refresh the Token Using `get-token` 
+ To use the `get-token` script to refresh your token, use the script with the `--refresh  <refresh_token>` option. For example:
+
+```
+./get-token.sh -o json --refresh v1.MVZ9_xxxxxxxx_FRs
+{
+  "access_token": "xxxxxxxxxx",
+  "refresh_token": "xxxxxxxxxxxx",
+  "id_token": "xxxxxxxx",
+  "scope": "openid profile email offline_access",
+  "expires_in": 86400,
+  "token_type": "Bearer"
+}
+```
 

product_docs/docs/pgbouncer/1.15/01_installation/01_installing_pgbouncer_on_a_linux_or_centos_host.mdx renamed to product_docs/docs/pgbouncer/1.16/01_installation/01_installing_pgbouncer_on_a_linux_or_centos_host.mdx

@@ -77,10 +77,10 @@ Follow the steps given below to install PgBouncer:
 
     Where <xx> is the PgBouncer version you want to install.
 
-    To install PgBouncer 1.15 on CentOS 8, the command is:
+    To install PgBouncer 1.16 on CentOS 8, the command is:
 
     ``` text
-    dnf -y install edb-pgbouncer115
+    dnf -y install edb-pgbouncer116
     ```
 
     When you install an RPM package that is signed by a source that is not recognized by your system, yum may ask for your permission to import the key to your local server. If prompted, and you are satisfied that the packages come from a trustworthy source, enter `y`, and press `Return` to continue.
@@ -169,10 +169,10 @@ Follow the steps given below to install PgBouncer:
 
     Where <xx> is the PgBouncer version you want to install.
 
-    To install PgBouncer 1.15 on RHEL 8, the command is:
+    To install PgBouncer 1.16 on RHEL 8, the command is:
 
     ``` text
-    dnf -y install edb-pgbouncer115
+    dnf -y install edb-pgbouncer116
     ```
 
     When you install an RPM package that is signed by a source that is not recognized by your system, yum may ask for your permission to import the key to your local server. If prompted, and you are satisfied that the packages come from a trustworthy source, enter `y`, and press `Return` to continue.

product_docs/docs/pgbouncer/1.15/01_installation/02_installing_pgbouncer_on_a_debian_or_ubuntu_host.mdx renamed to product_docs/docs/pgbouncer/1.16/01_installation/02_installing_pgbouncer_on_a_debian_or_ubuntu_host.mdx

@@ -67,10 +67,10 @@ The following steps will walk you through using the EnterpriseDB repository to i
 
     Where *<xx>* is the PgBouncer version you want to install.
 
-    For example, to install the PgBouncer 1.15 package for EDB Advanced Server 13, execute the following command:
+    For example, to install the PgBouncer 1.16 package for EDB Advanced Server 13, execute the following command:
 
     ``` text
-    apt-get -y install edb-pgbouncer115
+    apt-get -y install edb-pgbouncer116
     ```
 
 PgBouncer will be installed in the `/usr/edb/pgbouncer<x.x>` directory.

product_docs/docs/pgbouncer/1.15/01_installation/03_installing_pgbouncer_on_an_sles_host.mdx renamed to product_docs/docs/pgbouncer/1.16/01_installation/03_installing_pgbouncer_on_an_sles_host.mdx

@@ -9,7 +9,7 @@ legacyRedirectsGenerated:
 <div id="installing_on_an_sles12_host" class="registered_link"></div>
 
 
-Perform the following steps to install PgBouncer on a SLES 12 SP4 host using the zypper package manager.
+Perform the following steps to install PgBouncer on a SLES 12 SP5 host using the zypper package manager.
 
 1.  Assume superuser privileges and use the following command to add the EnterpriseDB repository configuration file to your SLES host:
 
@@ -35,29 +35,17 @@ Perform the following steps to install PgBouncer on a SLES 12 SP4 host using the
 
     ``` text
     SUSEConnect -r 'REGISTRATION_CODE' -e 'EMAIL'
-    SUSEConnect -p PackageHub/12.4/x86_64
-    SUSEConnect -p sle-sdk/12.4/x86_64
+    SUSEConnect -p PackageHub/12.5/x86_64
+    SUSEConnect -p sle-sdk/12.5/x86_64
     ```
 
-5.  Install the following repository for PEM dependencies:
-
-    ``` text
-    zypper addrepo https://download.opensuse.org/repositories/Apache:/Modules/SLE_12_SP4/Apache:Modules.repo
-    ```
-
-6.  Refresh the metadata:
+5.  Refresh the metadata:
 
     ``` text
     zypper refresh
     ```
 
-7.  Install OpenJDK (version 1.8) for Java based components:
-
-    ``` text
-    zypper -n install java-1_8_0-openjdk
-    ```
-
-8.  Use the zypper utility to install PgBouncer.
+6.  Use the zypper utility to install PgBouncer.
 
     ``` text
     zypper -n install edb-pgbouncer<xx>

product_docs/docs/pgbouncer/1.15/01_installation/04_installing_pgbouncer_on_a_windows_host.mdx renamed to product_docs/docs/pgbouncer/1.16/01_installation/04_installing_pgbouncer_on_a_windows_host.mdx

@@ -10,15 +10,15 @@ legacyRedirectsGenerated:
 
 Graphical installers for PgBouncer are available via StackBuilder Plus (for Advanced Server hosts) or Stack Builder (for PostgreSQL hosts).
 
-The following steps walk you through installing PgBouncer 1.15 by accessing StackBuilder Plus through Windows start menu
+The following steps walk you through installing PgBouncer 1.16 by accessing StackBuilder Plus through Windows start menu
 
 1.  Access StackBuilder Plus through the Windows start menu; on the `Welcome` window, select your Advanced Server installation from the drop-down list. Click `Next` to continue to the application selection page.
 
 ![The StackBuilder Plus Welcome window](../images/sbp_welcome.png)
 
 Fig. 1: The StackBuilder Plus Welcome window
 
-2.  Expand the `Add-ons, tools and utilities` node, and check the box next to the `PgBouncer v1.15.0.1-1`. Click `Next` to continue.
+2.  Expand the `Add-ons, tools and utilities` node, and check the box next to the `PgBouncer v1.16.0.1-1`. Click `Next` to continue.
 
 ![Expand Add-ons, Tools and Utilities](../images/add-ons.png)
 

product_docs/docs/pgbouncer/1.15/01_installation/index.mdx renamed to product_docs/docs/pgbouncer/1.16/01_installation/index.mdx

@@ -17,6 +17,10 @@ The PgBouncer version is version-specific, but the documented and supported func
 
 | **Pgpool Version** | **Advanced Server Version**                     | **Supported Platforms**                                                                                                                            |
 | ------------------ | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PgBouncer 1.16`   | PostgreSQL and Advanced Server 13               | RHEL/CentOS 7 - x86_64 and RHEL/CentOS 8 - x86_64 <br />RHEL/CentOS 7 - ppc64le  <br />Debian 9x Stretch and Debian 10x Buster <br />Ubuntu 18.04 Bionic Beaver and Ubuntu 20.04 LTS Focal Fossa <br /> Windows 86 x64 Interactive Installer|
+| `PgBouncer 1.16`   | PostgreSQL and Advanced Server 12               | RHEL/CentOS 7 - x86_64 and RHEL/CentOS 8 - x86_64 <br />RHEL/CentOS 7 - ppc64le  <br />Debian 9x Stretch and Debian 10x Buster <br />Ubuntu 18.04 Bionic Beaver <br /> Windows 86 x64 Interactive Installer <br />SUSE Linux Enterprise Server 12 SP5|
+| `PgBouncer 1.16`   | PostgreSQL and Advanced Server 11               | RHEL/CentOS 7 - x86_64 and RHEL/CentOS 8 - x86_64 <br />RHEL/CentOS 7 - ppc64le  <br />Debian 9x Stretch <br />Ubuntu 18.04 Bionic Beaver <br /> Windows 86 x64 Interactive Installer <br />SUSE Linux Enterprise Server 12 SP5|
+| `PgBouncer 1.16`   | PostgreSQL and Advanced Server 10 and 9.6       | RHEL/CentOS 7 - x86_64 <br />RHEL/CentOS 7 - ppc64le  <br /> Windows 86 x64 Interactive Installer|
 | `PgBouncer 1.15`   | PostgreSQL and Advanced Server 13               | RHEL/CentOS 7 - x86_64 and RHEL/CentOS 8 - x86_64 <br />RHEL/CentOS 7 - ppc64le  <br />Debian 9x Stretch and Debian 10x Buster <br />Ubuntu 18.04 Bionic Beaver and Ubuntu 20.04 LTS Focal Fossa <br /> Windows 86 x64 Interactive Installer|
 | `PgBouncer 1.15`   | PostgreSQL and Advanced Server 12               | RHEL/CentOS 7 - x86_64 and RHEL/CentOS 8 - x86_64 <br />RHEL/CentOS 7 - ppc64le  <br />Debian 9x Stretch and Debian 10x Buster <br />Ubuntu 18.04 Bionic Beaver <br /> Windows 86 x64 Interactive Installer <br />SUSE Linux Enterprise Server 12 SP4|
 | `PgBouncer 1.15`   | PostgreSQL and Advanced Server 11               | RHEL/CentOS 7 - x86_64 and RHEL/CentOS 8 - x86_64 <br />RHEL/CentOS 7 - ppc64le  <br />Debian 9x Stretch <br />Ubuntu 18.04 Bionic Beaver <br /> Windows 86 x64 Interactive Installer <br />SUSE Linux Enterprise Server 12 SP4|
@@ -29,10 +33,6 @@ The PgBouncer version is version-specific, but the documented and supported func
 | `PgBouncer 1.9`    | Advanced Server 11                              | RHEL/CentOS 7 - x86_64 <br />RHEL/CentOS 7 - ppc64le  <br />Debian 9x Stretch <br />Ubuntu 18.04 Bionic Beaver <br /> Windows 86 x64 Interactive Installer and Linux 86_64 Interactive Installer|
 | `PgBouncer 1.7`    | Advanced Server 10 and 9.6                      | RHEL/CentOS 7 - x86_64 <br />RHEL/CentOS 7 - ppc64le <br /> Windows 86 x64 Interactive Installer and Linux 86_64 Interactive Installer|
 
-!!! Note
-
-    PgBouncer 1.15 is no longer supported on CentOS/RHEL/OL 6.x platforms. It is strongly recommended that EDB products running on these platforms be migrated to a supported platform.
-
 <div class="toctree" maxdepth="3">
 
 installing\_pgbouncer\_on\_a\_linux\_or\_centos\_host installing\_pgbouncer\_on\_a\_debian\_or\_ubuntu\_host installing\_pgbouncer\_on\_an\_sles\_host installing\_pgbouncer\_on\_a\_windows\_host