Merge pull request #196 from percona/pxc-4605

PXC-4605 [DOCS] - add information for Pro builds for PXC 8.0.40

docs/fips.md

@@ -0,0 +1,69 @@
+# 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 XtraDB Cluster implements the same level of FIPS support as MySQL. Percona XtraDB Cluster 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 XtraDB Cluster from source code](compile.md).
+
+## Prerequisites
+
+To prepare Percona XtraDB Cluster 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 XtraDB Cluster 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 XtraDB Cluster from the Pro build](pxc-pro.md), which is built and tested on operating systems with FIPS pre-approved OpenSSL packages.
+
+## The FIPS mode variables
+
+Percona XtraDB Cluster uses the same variables and values as Percona Server for MySQL. Percona XtraDB Cluster 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 XtraDB Cluster will load this module and run in FIPS mode.
+    ```
+## Next steps
+[Install Percona XtraDB Cluster Pro :material-arrow-right:](install-pro.md){.md-button}

docs/install-pro.md

@@ -0,0 +1,123 @@
+# Install Percona XtraDB Cluster Pro
+
+--8<--- "pro-build-announcement.md"
+
+This document provides guidelines how to install Pro packages of Percona XtraDB Cluster from Percona repositories. [Check files in packages built for Percona XtraDB Cluster Pro :material-arrow-right:](pro-files.md){.md-button}
+
+## Prerequisites
+
+* You need to have root access on the node where you will be installing Percona XtraDB Cluster (either logged in as a user with root privileges or be able to run commands with sudo).
+
+* Make sure that the following ports are not blocked by firewall or used by other software. Percona XtraDB Cluster requires them for communication.
+
+    * 3306
+
+
+    * 4444
+
+
+    * 4567
+
+
+    * 4568
+
+!!! admonition "See also"
+
+    For more information, see [Enabling AppArmor](apparmor.md#apparmor).
+
+## 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 XtraDB Cluster packages
+
+    === "On Debian or Ubuntu"
+
+        Use the following steps to install the PRO version of Percona XtraDB Cluster on Debian or Ubuntu.
+
+        1. Use the apt package manager to dowload `percona-release`
+
+            ```{.bash .data-prompt="$"}
+            $ sudo apt update
+            ```
+
+        2. Install the necessary packages
+
+            ```{.bash .data-prompt="$"}
+            $ sudo apt install -y wget gnupg2 lsb-release curl
+            ```
+        
+        3. Download the `percona-release` repository package
+
+            ```{.bash .data-prompt="$"}
+            $  wget https://repo.percona.com/apt/percona-release_latest.generic_all.deb
+            ```
+
+        4. Install the package with `dpkg`:
+
+            ```{.bash .data-prompt="$"}
+            $ sudo dpkg -i percona-release_latest.generic_all.deb
+            ```
+
+        5. Refresh the local cache to update the package information
+
+            ```{.bash .data-prompt="$"}
+            $ sudo apt update
+            ```
+        
+        6. Enable the specific percona-release product.
+
+            ```{.bash .data-prompt="$"}
+            $ sudo percona-release setup pxc-84-pro --user_name=<Your PRO repository user name> --repo_token=<Your PRO repository token>
+            ```
+
+        7.  Install the cluster:
+
+            ```{.bash .data-prompt="$"}
+            $ sudo apt install -y percona-xtradb-cluster-pro-84
+            ```
+
+        Install other required packages. [Check files in the DEB package built for Percona XtraDB Cluster 8.4](apt-files.md).
+
+    === "On RHEL or derivatives"
+
+        RHEL 8 and other EL8 systems enable the MySQL module by default. This module hides the Percona-provided packages, and the module must be disabled to make these packages visible. The following command disables the module:
+        
+        ```{.bash .data-prompt="$"}
+        $ sudo dnf module disable mysql
+        ```
+
+        Use the following commands to install on RHEL or derivatives.
+
+        ```{.bash data-prompt="$"}
+        $ sudo yum install https://repo.percona.com/yum/percona-release-latest.noarch.rpm
+        $ sudo percona-release setup pxc-84-pro --user_name=<Your PRO repository user name> --repo_token=<Your PRO repository token>
+        $ sudo yum install percona-xtradb-cluster-pro-84
+        ```
+
+## After installation
+
+After the installation, start the `mysql` service and find the temporary password using the `grep` command. 
+
+```{.bash data-prompt="$"}
+$ sudo service mysql start
+$ sudo grep 'temporary password' /var/log/mysqld.log
+```
+
+Use the temporary password to log into the server:
+
+```{.bash data-prompt="$"}
+$ mysql -u root -p
+```
+
+Run an `ALTER USER` statement to change the temporary password, exit the client, and stop the service.
+
+```{.bash data-prompt="$"}
+mysql> ALTER USER 'root'@'localhost' IDENTIFIED BY 'rootPass';
+mysql> exit
+$ sudo service mysql stop
+```
+
+## Next step
+
+[Enable the FIPS mode :material-arrow-right:](fips.md){.md-button}

docs/pro-files.md

@@ -0,0 +1,29 @@
+# Files in packages built for Percona XtraDB Cluster Pro
+
+--8<--- "pro-build-announcement.md"
+
+=== "DEB package files"
+
+    | Package                      | Contains                                                                                                                                                                        |
+    |------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+    |   |   |
+    |    |                            |
+    |     |                                              |
+    |      |                                             |
+    |    |                                                   |
+    |    |                                                    |
+    |   |                                 |
+    |       |                                                    |
+
+=== "RPM package files"
+
+    | Package                      | Contains                                                                                                                                                                        |
+    |------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+    |   |   |
+    |    |                            |
+    |     |                                              |
+    |      |                                             |
+    |    |                                                   |
+    |    |                                                    |
+    |   |                                 |
+    |       |                                                    |

docs/pxc-pro.md

@@ -0,0 +1,20 @@
+# Percona XtraDB Cluster Pro
+
+--8<--- "pro-build-announcement.md"
+
+## Capabilities
+
+Find the list of capabilities available in Percona XtraDB Cluster Pro:
+
+| Name                                | Version | Description  | 
+| ----------------------------------- | ------------- | -------------|
+| [FIPS compliance](fips.md)| 8.0.40-31 | FIPS compliance enables all commercial cloud service providers who want to sell and increase their presence 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 XtraDB Cluster Pro](install-pro.md){.md-button}
+
+Community users can receive all these capabilities by [building Percona XtraDB Cluster from the same source code](compile.md).

mkdocs-base.yml

@@ -144,6 +144,13 @@ extra:
 
 nav:
   - Home: index.md
+  - Percona XtraDB Cluster PRO:
+      - pxc-pro.md
+      - Install Percona XtraDB Cluster Pro:
+        - install-pro.md
+        - pro-files.md
+      - Pro build features:
+        - fips.md
   - get-help.md
   - Release notes:
       - Release notes index: release-notes/release-notes_index.md
@@ -181,7 +188,7 @@ nav:
   - Features:
       - high-availability.md
       - strict-mode.md
-     
+
   - Quickstart guide:
       - quickstart-overview.md
       - get-started-cluster.md
@@ -198,6 +205,7 @@ nav:
       - verify-replication.md
       - Troubleshoot install: 
           - timeoutstarts.md
+
   - Upgrade:
       - upgrade-guide.md
       - upgrade-from-backup.md

snippets/pro-buld-announcement.md

@@ -0,0 +1,3 @@
+Percona XtraDB Cluster Pro includes the [capabilities](pxc-pro.md#capabilities) that are typically requested by large enterprises. Percona XtraDB Cluster Pro contains packages created and tested by Percona. These packages are supported only for Percona Customers with a subscription.
+
+[Become a Percona Customer](https://www.percona.com/about/contact){.md-button}