From e76111291e743c67f8c780f5f33d7a6064d9b836 Mon Sep 17 00:00:00 2001 From: Alina Derkach Date: Fri, 20 Dec 2024 18:45:55 +0100 Subject: [PATCH] PXC-4584 [DOCS] Add info on Pro builds for PXC 8.4.3 new file: docs/fips.md new file: docs/install-pro.md new file: docs/pro-files.md new file: docs/pxc-pro.md modified: mkdocs-base.yml new file: snippets/pro-build-announcement.md --- docs/fips.md | 72 +++++++++++++++++ docs/install-pro.md | 122 +++++++++++++++++++++++++++++ docs/pro-files.md | 30 +++++++ docs/pxc-pro.md | 20 +++++ mkdocs-base.yml | 6 ++ snippets/pro-build-announcement.md | 3 + 6 files changed, 253 insertions(+) create mode 100644 docs/fips.md create mode 100644 docs/install-pro.md create mode 100644 docs/pro-files.md create mode 100644 docs/pxc-pro.md create mode 100644 snippets/pro-build-announcement.md diff --git a/docs/fips.md b/docs/fips.md new file mode 100644 index 00000000..49fa2aa5 --- /dev/null +++ b/docs/fips.md @@ -0,0 +1,72 @@ +# 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 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} + diff --git a/docs/install-pro.md b/docs/install-pro.md new file mode 100644 index 00000000..bdd1faa0 --- /dev/null +++ b/docs/install-pro.md @@ -0,0 +1,122 @@ +# 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" + + 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= --repo_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 Red Hat 7" + + ```{.bash data-prompt="$"} + $ sudo yum install https://repo.percona.com/yum/percona-release-latest.noarch.rpm + $ sudo percona-release enable-only pxc-84-pro release --user_name= --repo_token= + $ sudo percona-release enable tools release + $ sudo yum install percona-xtradb-cluster-pro-84 + ``` + + === "On Red Hat 8 or later" + + ```{.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= --repo_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} diff --git a/docs/pro-files.md b/docs/pro-files.md new file mode 100644 index 00000000..9afbc162 --- /dev/null +++ b/docs/pro-files.md @@ -0,0 +1,30 @@ +# Files in packages built for Percona XtraDB Cluster Pro + +--8<--- "pro-build-announcement.md" + +## Files in the DEB package + +| Package | Contains | +|------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| | | +| | | +| | | +| | | +| | | +| | | +| | | +| | | + +## Files in the RPM package + +| Package | Contains | +|------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| | | +| | | +| | | +| | | +| | | +| | | +| | | +| | | + diff --git a/docs/pxc-pro.md b/docs/pxc-pro.md new file mode 100644 index 00000000..6f4a75c0 --- /dev/null +++ b/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.4.3-3 | 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). \ No newline at end of file diff --git a/mkdocs-base.yml b/mkdocs-base.yml index 98c2c53d..371df0c8 100644 --- a/mkdocs-base.yml +++ b/mkdocs-base.yml @@ -145,6 +145,7 @@ extra: nav: - Home: index.md + - pxc-pro.md - Release notes: - Release notes index: release-notes/release-notes_index.md - release-notes/8.4.2-2.md @@ -158,6 +159,8 @@ nav: - strict-mode.md - online-schema-upgrade.md - nbo.md + - Pro build features: + - fips.md - Quickstart guide: - quickstart-overview.md - get-started-cluster.md @@ -172,6 +175,9 @@ nav: - bootstrap.md - add-node.md - verify-replication.md + - Install Percona Server for MySQL Pro: + - install-pro.md + - pro-files.md - Upgrade: - upgrade-guide.md - upgrade-from-backup.md diff --git a/snippets/pro-build-announcement.md b/snippets/pro-build-announcement.md new file mode 100644 index 00000000..52d27490 --- /dev/null +++ b/snippets/pro-build-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}