PS-9539 [DOC] Add docs for Percona Server 8.4.0 - PRO release (#423)

new file: docs/downgrade-from-pro.md new file: docs/fips.md new file: docs/install-pro.md new file: docs/pro-files.md new file: docs/psmysql-pro.md new file: docs/upgrade-pro.md
percona · Nov 21, 2024 · 6f8b687 · 6f8b687
1 parent b8427c9
commit 6f8b687
Show file tree

Hide file tree

Showing 8 changed files with 373 additions and 0 deletions.
diff --git a/docs/downgrade-from-pro.md b/docs/downgrade-from-pro.md
@@ -0,0 +1,68 @@
+# Downgrade from Percona Server for MySQL Pro
+
+If you want to downgrade from Percona Server for MySQL Pro to the same version of Percona Server for MySQL, do the following:
+
+=== "On Debian and Ubuntu"
+
+    1. Set up the Percona Server for MySQL 8.4 repository
+
+        ```{.bash data-prompt="$"}
+        $ sudo percona-release setup ps84
+        ```
+
+    2. Stop the `mysql` server.
+       
+        ```{.bash data-prompt="$"}
+        $ sudo systemctl stop mysql
+        ```
+
+    3. Install the server package
+
+        ```{.bash data-prompt="$"}
+        $ sudo apt install percona-server-server
+        ```
+
+        Install other required packages. [Check files in the DEB package built for Percona Server for MySQL 8.4](apt-files.md).
+
+    4. Start the `mysql` server
+
+        ```{.bash data-prompt="$"}
+        $ sudo systemctl start mysql
+        ```
+
+    !!! note
+
+        On Debian 12, if you want to remove the Percona Server for MySQL after the downgrade, you must stop the 
+        server manually. This behavior will be fixed in future releases.
+       
+        ```{.bash data-prompt="$"}
+        $ sudo systemctl stop mysql
+        ```
+
+=== "On RHEL and derivatives"
+
+    1. Set up the Percona Server for MySQL 8.4 repository
+
+        ```{.bash data-prompt="$"}
+        $ sudo percona-release setup ps84
+        ```
+
+    2. Stop the `mysql` server.
+       
+        ```{.bash data-prompt="$"}
+        $ sudo systemctl stop mysql
+        ```
+
+    3. Install the server package
+
+        ```{.bash data-prompt="$"}
+        $ sudo yum --allowerasing install percona-server-server
+        ```
+
+        Install other required packages. [Check files in the RPM package built for Percona Server for MySQL 8.4](yum-files.md).
+
+    4. Start the `mysql` server
+
+        ```{.bash data-prompt="$"}
+        $ sudo systemctl start mysql
+        ```
diff --git a/docs/fips.md b/docs/fips.md
@@ -0,0 +1,75 @@
+# FIPS compliance
+
+--8<--- "pro-build-announcement.md"
+
+The Federal Information Processing Standards (FIPS) are a set of U.S. government standards that ensure the security of computer systems for non-military government agencies and contractors. These standards specify how to perform cryptographic operations, such as encryption, hashing, and digital signatures. FIPS mode is a mode of operation that enforces these standards and rejects any non-compliant algorithms or parameters.
+
+Percona Server for MySQL implements the same level of FIPS support as MySQL. Percona Server for MySQL can run in FIPS mode if a FIPS-enabled OpenSSL library and FIPS Object Module are available at runtime or if compiled using a FIPS-validated version of OpenSSL. You can also receive this functionality by [building Percona Server for MySQL from source code](compile-percona-server.md).
+
+## Prerequisites
+
+To prepare Percona Server for MySQL for FIPS certification, do the following:
+
+* Check that your operating system includes FIPS pre-approved OpenSSL library in version 3.0.x or higher. The following distributions includes FIPS pre-approved OpenSSL library in version 3.0.x or higher:
+
+    * RedHat Enterprise Linux 9 and derivatives
+
+    * Oracle Linux 9
+
+    The following distributions also includes OpenSSL library in version 3.0.x but do not have FIPS-approved crypto provider installed by default (you can build the crypto provider from the source for testing):
+
+    * Debian 12
+
+    * Ubuntu 22.04 Pro (the OpenSSL FIPS 140-3 certification is under implementation)
+
+        !!! note
+
+            If you enable FIPS on Ubuntu Pro with `$ sudo pro enable fips-updates` and then disable FIPS with `$ sudo pro disable fips-updates`, Percona Server for MySQL may stop operating properly. For example, if you disable FIPS on Ubuntu Pro with `$ sudo pro disable fips-updates` and enable the FIPS mode on Percona Server with `ssl-fips-mode=ON`, Percona Server may not load the SSL certificate.
+
+* Deploy [Percona Server for MySQL from the Pro build](psmysql-pro.md), which is built and tested on operating systems with FIPS pre-approved OpenSSL packages.
+
+## The FIPS mode variables
+
+Percona Server for MySQL uses the same variables and values as MySQL. Percona Server for MySQL enables control of FIPS mode on the server side and the client side:
+
+* The `ssl_fips_mode` system variable shows whether the server operates in FIPS mode. This variable is disabled by default.
+
+    The `ssl_fips_mode` system variable has these values:
+
+    * `0` - disables FIPS mode
+    * `1` - enables FIPS mode. The exact behavior of the enabled FIPS mode depends on the OpenSSL version. The server only specifies the FIPS value to OpenSSL.
+    * `2` - enables `strict` FIPS mode. This value provides more restrictions than the `1 ` value. The exact behavior of the `strict` FIPS mode depends on the OpenSSL version. The server only specifies the FIPS value to OpenSSL.
+
+* The `--ssl-fips-mode` client/server option controls whether a given client operates in FIPS mode. This setting does not change the server setting. This option is disabled by default.
+
+    The `--ssl-fips-mode` client/server option has these values:
+
+    * `OFF` - disables FIPS mode
+    * `ON` - enables FIPS mode. The exact behavior of the enabled FIPS mode depends on the OpenSSL version. The server only specifies the FIPS value to OpenSSL.
+    * `STRICT` - enables `strict` FIPS mode. This value provides more restrictions than the `ON` value. The exact behavior of the `strict` FIPS mode depends on the OpenSSL version. The server only specifies the FIPS value to OpenSSL.
+
+    The server operation in FIPS mode does not depend on which crypto module (regular or FIPS-approved) is set as the default in the OpenSSL configuration file. The server always respects the value of `--ssl-fips-mode` server command line option (`OFF`, `ON`, or `STRICT`). The `ssl_fips_mode` global system variable is read-only and cannot be changed at runtime.
+
+### Enable the FIPS mode
+
+To enable the FIPS mode, pass `--ssl-fips-mode=ON` or `--ssl-fips-mode=STRICT` to mysqld as a command line argument or add `ssl-fips-mode=ON` or `--ssl-fips-mode=STRICT` to the configuration file. Ignore the warning that the `--ssl-fips-mode` client/server option is deprecated.
+
+## Check that FIPS mode is enabled
+
+To ensure that the FIPS mode is enabled, do the following:
+
+* Pass `--log-error-verbosity=3` to mysqld as a command line argument or add `log-error-verbosity=3` to the configuration file.
+
+* Check that the error log contains the following message:
+
+    ```{.text .no-copy}
+    A FIPS-approved version of the OpenSSL cryptographic library has been detected in the operating system with a properly configured FIPS module available for loading. Percona Server for MySQL will load this module and run in FIPS mode.
+    ```
+
+## Next steps
+
+[Install Percona Server for MySQL Pro :material-arrow-right:](install-pro.md){.md-button}
+
+If you already use Percona Server for MySQL, you can
+
+[Upgrade to Percona Server for MySQL Pro :material-arrow-right:](upgrade-pro.md){.md-button}
diff --git a/docs/install-pro.md b/docs/install-pro.md
@@ -0,0 +1,77 @@
+# Install Percona Server for MySQL Pro
+
+--8<--- "pro-build-announcement.md"
+
+This document provides guidelines how to install Pro packages of Percona Server for MySQL from Percona repositories. [Check files in packages built for Percona Server for MySQL Pro :material-arrow-right:](pro-files.md){.md-button}
+
+## Procedure
+
+1. Request the access to the pro repository from Percona Support. You will receive the client ID and the access token which you use when downloading the packages.
+
+2. Configure the repository and install Percona Server for MySQL packages
+
+    === "On Debian and Ubuntu"
+
+        1. Download the Percona `gpg` key:
+
+            ```{.bash .data-prompt="$"}
+            $ wget https://github.com/percona/percona-repositories/raw/main/deb/percona-keyring.gpg 
+            ```
+
+        2. Add the Percona `gpg` key to `trusted.gpg.d` directory:
+
+            ```{.bash .data-prompt="$"}
+            $ sudo cp percona-keyring.gpg /etc/apt/trusted.gpg.d/
+            ```
+
+        3. Create the `/etc/apt/sources.list.d/psmysql-pro.list` configuration file with the following contents with your [CLIENTID] and [TOKEN].
+
+            To get the `OPERATING_SYSTEM` value, run `lsb_release -sc`.
+            
+            ```ini title="/etc/apt/sources.list.d/psmysql-pro.list"
+            deb http://repo.percona.com/private/[CLIENTID]-[TOKEN]/ps-84-pro/apt/ OPERATING_SYSTEM main
+            ```
+
+        4. Update the local cache
+
+            ```{.bash .data-prompt="$"}
+            $ sudo apt update
+            ```
+        
+        5. Install Percona Server for MySQL packages
+        
+            ```{.bash .data-prompt="$"}
+            $ sudo apt install -y percona-server-server-pro
+            ```
+
+            Install other required packages. [Check files in the DEB package built for Percona Server for MySQL 8.4](apt-files.md).
+
+    === "On RHEL and derivatives"
+
+        1. Create the `/etc/yum.repos.d/psmysql-pro.repo` configuration file with the following contents with your [CLIENTID] and [TOKEN].
+
+            ```ini title="/etc/yum.repos.d/psmysql-pro.repo"
+            [ps-8.4-pro]
+            name=PS_8.4_PRO
+            baseurl=http://repo.percona.com/private/[CLIENTID]-[TOKEN]/ps-84-pro/yum/release/$releasever/RPMS/x86_64
+            enabled=1
+            gpgkey = https://repo.percona.com/yum/PERCONA-PACKAGING-KEY
+            ```
+
+        2. Install Percona Server for MySQL packages
+        
+            ```{.bash .data-prompt="$"}
+            $ sudo yum install -y percona-server-server-pro
+            ```
+
+            Install other required packages. [Check files in the DEB package built for Percona Server for MySQL 8.4](apt-files.md).
+
+3. Start the server
+
+    ```{.bash .data-prompt="$"}
+    $ sudo systemctl start mysql
+    ```
+
+## Next step
+
+[Enable the FIPS mode :material-arrow-right:](fips.md){.md-button}
diff --git a/docs/pro-files.md b/docs/pro-files.md
@@ -0,0 +1,30 @@
+# Files in packages built for Percona Server for MySQL Pro
+
+--8<--- "pro-build-announcement.md"
+
+## Files in the DEB package
+
+| Package                      | Contains                                                                                                                                                                        |
+|------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| percona-server-server-pro    | The database server itself, the mysqld binary and associated files.  |
+| percona-server-pro-common    | The files common to the server and client.                           |
+| percona-server-client-pro    | The command line client.                                             |
+| percona-server-test-pro      | The database test suite.                                             |
+| percona-server-pro-source    | The server source.                                                   |
+| percona-mysql-router-pro     | The mysql router.                                                    |
+| percona-server-rocksdb-pro   | The files for rocksdb installation.                                  |
+| percona-server-pro-dbg       | The debug symbols.                                                   |
+
+## Files in the RPM package
+
+| Package                      | Contains                                                                                                                                                                        |
+|------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| percona-server-server-pro    | The database server itself, the mysqld binary and associated files.  |
+| percona-server-client-pro    | The command line client.                                             |
+| percona-server-test-pro      | The database test suite.                                             |
+| percona-server-rocksdb-pro   | The files for rocksdb installation.                                  |
+| percona-mysql-router-pro     | The mysql router.                                                    |
+| percona-server-shared-pro    | Client shared library.                                               |
+| percona-server-pro-debuginfo | The debug symbols.                                                   |
+| percona-server-devel-pro     | Header files needed to compile software using the client library.    |
+
diff --git a/docs/psmysql-pro.md b/docs/psmysql-pro.md
@@ -0,0 +1,24 @@
+# Percona Server for MySQL Pro
+
+--8<--- "pro-build-announcement.md"
+
+## Capabilities
+
+Find the list of capabilities available in Percona Server for MySQL Pro:
+
+| Name                                | Version | Description  | 
+| ----------------------------------- | ------------- | -------------|
+| [FIPS compliance](fips.md)| 8.4.0 | Enables all commercial cloud service providers who want to sell and expand their footprint for US government entities. |
+
+## What's in it for you?
+
+* Save on deploying and maintaining build infrastructure as we do the build and testing for you 
+* Longer support for older versions of operating systems.  
+
+[Install Percona Server for MySQL Pro](install-pro.md){.md-button}
+
+If you already use Percona Server for MySQL, you can
+
+[Upgrade to Percona Server for MySQL Pro](upgrade-pro.md){.md-button}
+
+Community users can receive all these capabilities by [building Percona Server for MySQL from the same source code](compile-percona-server.md).
diff --git a/docs/upgrade-pro.md b/docs/upgrade-pro.md
@@ -0,0 +1,89 @@
+# Upgrade to Percona Server for MySQL Pro
+
+--8<--- "pro-build-announcement.md"
+
+This document provides instructions on upgrading from Percona Server for MySQL to Percona Server for MySQL Pro.
+
+## Preconditions
+
+Request the access to the pro repository from Percona Support. You will receive the client ID and the access token which you use when downloading the packages.
+
+[Check files in packages built for Percona Server for MySQL Pro :material-arrow-right:](pro-files.md){.md-button}
+
+## Procedure
+
+1. Configure the repository
+
+    === "On Debian and Ubuntu"
+
+        1. Create the `/etc/apt/sources.list.d/psmysql-pro.list` configuration file with the following contents
+
+            To get the `OPERATING_SYSTEM` value, run `lsb_release -sc`.
+
+            ```ini title="/etc/apt/sources.list.d/psmysql-pro.list"
+            deb http://repo.percona.com/private/[CLIENTID]-[TOKEN]/ps-84-pro/apt/ OPERATING_SYSTEM main
+            ```
+
+        2. Update the local cache
+
+            ```{.bash .data-prompt="$"}
+            $ sudo apt update
+            ```
+
+    === "On RHEL and derivatives"
+
+        Create the `/etc/yum.repos.d/psmysql-pro.repo` configuration file with the following contents
+
+        ```ini title="/etc/yum.repos.d/psmysql-pro.repo"
+        [ps-8.4-pro]
+        name=PS_8.4_PRO
+        baseurl=http://repo.percona.com/private/[CLIENTID]-[TOKEN]/ps-84-pro/yum/main/$releasever/RPMS/x86_64
+        enabled=1
+        gpgkey = https://repo.percona.com/yum/PERCONA-PACKAGING-KEY
+        ```
+
+2. Stop the `mysql` server
+
+    ```{.bash data-prompt="$"}
+    $ sudo systemctl stop mysql
+    ```
+
+3. Install Percona Server for MySQL Pro packages
+
+    === "On Debian and Ubuntu"
+
+        ```{.bash .data-prompt="$"}
+        $ sudo apt install -y percona-server-server-pro
+        ```
+
+        Install other required packages. [Check files in the DEB package built for Percona Server for MySQL 8.4](apt-files.md).
+
+    === "On RHEL and derivatives"
+
+        ```{.bash .data-prompt="$"}
+        $ sudo yum install --allowerasing percona-server-server-pro
+        ```
+
+        Install other required packages. [Check files in the DEB package built for Percona Server for MySQL 8.4](apt-files.md).
+
+4. Start the server
+
+    ```{.bash .data-prompt="$"}
+    $ sudo systemct start mysql
+    ```
+
+!!! note
+
+    On Debian 12, you may receive the following warning after running `systemct` commands:
+
+    ```text
+    Warning: The unit file, source configuration file or drop-ins of mysql.service changed on disk. Run 'systemctl daemon-reload' to reload units.
+    ```
+
+    Run the following command to reload units:
+
+    ```{.bash .data-prompt="$"}
+    $ sudo systemctl daemon-reload
+    ```
+
+[Downgrade from Percona Server for MySQL Pro :material-arrow-right:](downgrade-from-pro.md){.md-button}