PXB-3366 Update installation documentation 8.0

On branch pxb-3366 modified: docs/apt-repo.md
percona · Sep 24, 2024 · 455739e · 455739e
1 parent 5730031
commit 455739e
Show file tree

Hide file tree

Showing 8 changed files with 511 additions and 69 deletions.
diff --git a/docs/apt-download-deb.md b/docs/apt-download-deb.md
@@ -1,19 +1,64 @@
-# Install Percona XtraBackup 8.0 using downloaded DEB packages
+# Install with DEB packages
 
-Download `DEB` packages of the desired series for your architecture from [Percona Product Downloads](https://www.percona.com/downloads). 
+This guide walks you through installing Percona XtraBackup 8.0 using DEB packages on Ubuntu-based systems.
+{.power-number}
 
-The following example downloads *Percona XtraBackup* 8.0.26-18 release package for Ubuntu 20.04:
+1. Download the DEB package
+
+    On the [Percona Software Downloads](https://www.percona.com/downloads) website, find the Percona XtraBackup 8.0 package for your system. 
+
+    For example, for Ubuntu 20.04, this command downloads the appropriate package:
+
+    ```{.bash data-prompt="$"}
+    $ wget https://downloads.percona.com/downloads/Percona-XtraBackup-LATEST/Percona-XtraBackup-8.0.26-18/binary/debian/focal/x86_64/percona-xtrabackup-80_8.0.26-18-1.focal_amd64.deb
+    ```
+
+2. Install the package
+
+    Use the dpkg command to install the downloaded package. You need root privileges for this:
+
+    ```{.bash data-prompt="$"}
+    $ sudo dpkg -i percona-xtrabackup-80_8.0.26-18-1.focal_amd64.deb
+    ```
+
+## Common dependencies for Percona XtraBackup
+
+| Library Name    | Description                                                                                              |
+|-----------------|----------------------------------------------------------------------------------------------------------|
+| libmysqlclient  | A client library for MySQL, providing essential functions for connecting to and communicating with MySQL databases. |
+| libssl          | A cryptographic library used for implementing SSL/TLS encryption, necessary for secure data transmission. |
+| libcurl         | A library that enables data transfer via various protocols such as HTTP, FTP, and others, commonly used for handling web requests. |
+| libev           | A high-performance event-loop library, often used in network applications for handling asynchronous events efficiently. |
+| libgcrypt       | A general-purpose cryptographic library that provides encryption, decryption, and cryptographic hashing algorithms. |
+| zlib            | A compression library used for data compression and decompression, supporting the popular DEFLATE compression algorithm. |
+
+## Identify and add missing dependencies
+
+If there are missing dependencies, dpkg shows error messages. Install any missing packages with the following command:
 
 ```{.bash data-prompt="$"}
-$ wget https://downloads.percona.com/downloads/Percona-XtraBackup-LATEST/Percona-XtraBackup-8.0.26-18/binary/debian/focal/x86_64/percona-xtrabackup-80_8.0.26-18-1.focal_amd64.deb
+$ sudo apt-get install -f
 ```
 
-Install Percona XtraBackup by using `dpkg`. Run this command as root or use the sudo command:
+Retry the Percona XtraBackup installation.
+
+## Verify the installation
+
+The following command returns the version information.
 
 ```{.bash data-prompt="$"}
-$ sudo dpkg -i percona-xtrabackup-80_8.0.26-18-1.focal_amd64.deb
+$ xtrabackup --version
 ```
 
-!!! warning
+## Troubleshoot the installation
+
+| Issue                         | Description                                                                 |
+|-------------------------------|-----------------------------------------------------------------------------|
+| Permission denied              | Ensure you're using sudo or have root access for installation commands.     |
+| Repository issues              | If packages are not found, check your yum repository configuration.         |
+| Incompatible OS version        | Double-check your OS version matches the package requirements.              |
+| Conflicts with existing packages | Consider removing conflicting packages or use a separate environment.     |
+
+If you encounter persistent issues, consult the Percona XtraBackup documentation or reach out to their support forums for assistance.
 
-    When installing packages manually like this, resolve all the dependencies and install missing packages yourself.
+Remember, when installing packages manually, you're responsible for managing dependencies and potential conflicts. Always back up your data before making significant system changes.
diff --git a/docs/apt-pinning.md b/docs/apt-pinning.md
@@ -1,15 +1,28 @@
-# Apt pinning the Percona XtraBackup 8.0 packages
+# Pin packages in Debian-based systems
 
-In some cases you might need to `pin` the selected packages to avoid the upgrades from the distribution repositories. 
+You may need to keep a specific package at a certain version and prevent it from being automatically updated by your package manager. This action is called "pinning" a package.
+{.power-number}
 
-The pinning takes place in the `preference` file. To pin a package, set the `Pin-Priority` to higher numbers.
+1. Create a preference file, `00percona.pref`, in the `/etc/apt/preferences.d/` directory.
 
-Make a new file `/etc/apt/preferences.d/00percona.pref`. For example, add the following to the preference file:
+2. Set the Pinning priority
 
-```
-Package:
-Pin: release o=Percona Development Team
-Pin-Priority: 1001
-```
+    To pin a package, set the `Pin-Priority` to a higher number than the default priority of the packages. This setting makes the packages higher priority over the other sources.
+
+    For example, add the following lines to the preference file:
+
+    ```
+    Package: <package_name>
+    Pin: release o=Percona Development Team
+    Pin-Priority: 1001
+    ```
+
+    Replace the `<package_name>` with the package's name. 
+
+3. Save the `00percona.pref` file.
+
+You can pin multiple packages by adding separate entries to the file.
+
+Remove the entry from the file if you no longer want to pin the package.
 
 For more information about the pinning, check the official [debian wiki](http://wiki.debian.org/AptPreferences).
diff --git a/docs/apt-repo.md b/docs/apt-repo.md
@@ -1,49 +1,204 @@
-# Use an APT repository to install Percona XtraBackup 8.0
+# Install Percona XtraBackup on Debian-based systems
 
 Ready-to-use packages are available from the Percona XtraBackup software
 repositories and the [download page](https://www.percona.com/downloads).
 
 Specific information on the supported platforms, products, and versions is
 described in [Percona Release Lifecycle Overview](https://www.percona.com/services/policies/percona-software-platform-lifecycle#mysql).
 
-!!! important
+To prevent intermittent backup failures, [update the curl utility in Debian 10](update-curl-utility.md).
 
-    To prevent intermittent backup failures, [update the curl utility in Debian 10](update-curl-utility.md).
+This guide walks you through the process of installing Percona XtraBackup 8.0 on Debian-based systems using the Percona-release tool.
 
-## Install Percona XtraBackup through percona-release
+## Version changes
 
-Percona XtraBackup, like many other Percona products, is installed with the *percona-release* package configuration tool.
+Starting with [Percona XtraBackup 8.0.35-31], the APT builds for the following platforms include ARM packages with the `arm64.deb` extension:
 
-1. Download a `DEB` package for *percona-release* the repository packages from Percona web:
+* Debian 12
+
+* Debian 11
+
+* Ubuntu 24.04
+
+* Ubuntu 22.04
+
+* Ubuntu 20.04
+
+This extension means Percona XtraBackup is now available for users on ARM-based systems.
+
+We recommend downloading Percona XtraBackup for the same platform as your MySQL-compatible server. For instance, if your server runs on an ARM64 platform, you should download and use the Percona XtraBackup with the `arm64.deb` extension for that operating system.
+
+## Prerequisites
+
+* Sudo or root access
+
+* Internet connection
+
+## Installation steps
+
+The following procedure installs Percona XtraBackup 8.0.
+{.power-number}
+
+1. Update the system package list
+
+    ```{.bash data-prompt="$"}
+    $ sudo apt update
+    ```
+
+    ??? example "Example output"
+
+        ```{.text .no-copy}
+        Get:1 http://ports.ubuntu.com/ubuntu-ports jammy InRelease [270 kB]
+        Get:2 http://ports.ubuntu.com/ubuntu-ports jammy-updates InRelease [128 kB]
+        Get:3 http://ports.ubuntu.com/ubuntu-ports jammy-backports InRelease [127 kB]
+        Get:4 http://ports.ubuntu.com/ubuntu-ports jammy-security InRelease [129 kB]
+        Get:5 http://ports.ubuntu.com/ubuntu-ports jammy/restricted arm64 Packages [24.2 kB]
+        Get:6 http://ports.ubuntu.com/ubuntu-ports jammy/multiverse arm64 Packages [224 kB]
+        Get:7 http://ports.ubuntu.com/ubuntu-ports jammy/universe arm64 Packages [17.2 MB]
+        Get:8 http://ports.ubuntu.com/ubuntu-ports jammy/main arm64 Packages [1758 kB]
+        Get:9 http://ports.ubuntu.com/ubuntu-ports jammy-updates/restricted arm64 Packages [2400 kB]
+        Get:10 http://ports.ubuntu.com/ubuntu-ports jammy-updates/multiverse arm64 Packages [29.5 kB]
+        Get:11 http://ports.ubuntu.com/ubuntu-ports jammy-updates/universe arm64 Packages [1379 kB]
+        Get:12 http://ports.ubuntu.com/ubuntu-ports jammy-updates/main arm64 Packages [2217 kB]
+        Get:13 http://ports.ubuntu.com/ubuntu-ports jammy-backports/universe arm64 Packages [31.8 kB]
+        Get:14 http://ports.ubuntu.com/ubuntu-ports jammy-backports/main arm64 Packages [81.0 kB]
+        Get:15 http://ports.ubuntu.com/ubuntu-ports jammy-security/main arm64 Packages [1949 kB]
+        Get:16 http://ports.ubuntu.com/ubuntu-ports jammy-security/restricted arm64 Packages [2330 kB]
+        Get:17 http://ports.ubuntu.com/ubuntu-ports jammy-security/multiverse arm64 Packages [24.1 kB]
+        Get:18 http://ports.ubuntu.com/ubuntu-ports jammy-security/universe arm64 Packages [1096 kB]
+        Fetched 31.4 MB in 7s (4264 kB/s)
+        Reading package lists... Done
+        Building dependency tree... Done
+        Reading state information... Done
+        9 packages can be upgraded. Run 'apt list --upgradable' to see them.
+        ```
+
+
+2. Install the curl download utility if it's not installed:
+
+    ```{.bash data-prompt="$"}
+    $ sudo apt install curl
+    ```
+
+    ??? example "Example output"
+
+        ```{.text .no-copy}
+        Reading package lists... Done
+        Building dependency tree... Done
+        Reading state information... Done
+        The following additional packages will be installed:
+          ca-certificates libbrotli1 libcurl4 libldap-2.5-0 libldap-common libnghttp2-14 libpsl5 librtmp1
+        Suggested packages:
+        ...
+        Updating certificates in /etc/ssl/certs...
+        0 added, 0 removed; done.######################################################################...]
+        Running hooks in /etc/ca-certificates/update.d...
+        done.
+        ```
+
+3. Download the percona-release the repository package:
+
+    ```{.bash data-prompt="$"}
+    $ curl -O https://repo.percona.com/apt/percona-release_latest.generic_all.deb
+    ```
+
+    ??? example "Example output"
+
+        ```{.text .no-copy}
+        % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
+                                        Dload  Upload   Total   Spent    Left Speed
+        100 16510  100 16510    0     0  31433      0 --:--:-- --:--:-- --:--:-- 31447
+        ```
+
+4. Install the downloaded package and its dependencies using apt:
 
     ```{.bash data-prompt="$"}
-    $ wget https://repo.percona.com/apt/percona-release_latest.$(lsb_release -sc)_all.deb
+    $ sudo apt install gnupg2 lsb-release ./percona-release_latest.generic_all.deb
     ```
 
-2. Install the downloaded package with **dpkg**. To do that, run the following commands as root or with **sudo**: `dpkg -i percona-release_latest.$(lsb_release -sc)_all.deb`
-
-    Once you install this package the Percona repositories should be added. You
-    can check the repository setup in the `/etc/apt/sources.list.d/percona-release.list` file.
+    ??? example "Example output"
 
-3. Enable the repository: `percona-release enable-only tools release`
+        ```{.text .no-copy}
+        Reading package lists... Done
+        Building dependency tree... Done
+        Reading state information... Done
+        Note, selecting 'percona-release' instead of './percona-release_latest.generic_all.deb'
+        The following additional packages will be installed:
+        ```
 
-    If *Percona XtraBackup* is intended to be used in combination with
-    the upstream MySQL Server, you only need to enable the `tools`
-    repository: `percona-release enable-only tools`.
 
-4. Refresh the local cache to update the package information:
+5. Refresh the local cache to update the package information:
 
     ```{.bash data-prompt="$"}
     $ sudo apt update
     ```
 
-5. Install the `percona-xtrabackup-80` package:
+    ??? example "Example output"
+
+        ```{.text .no-copy}
+        Hit:1 http://repo.percona.com/pmm2-client/apt jammy InRelease
+        Hit:2 http://ports.ubuntu.com/ubuntu-ports jammy InRelease
+        Hit:3 http://repo.percona.com/prel/apt jammy InRelease
+        ...
+        ```
+
+6. Enable the repository:
+
+    ```{.bash data-prompt="$"}
+    $ percona-release setup pxb-80
+    ```
+    ??? example "Example output"
+
+        ```{.text .no-copy}
+        * Disabling all Percona Repositories
+        * Enabling the Percona XtraBackup 8.0 repository
+        Hit:1 http://repo.percona.com/prel/apt jammy InRelease
+        Get:2 http://repo.percona.com/pxb-80/apt jammy InRelease [18.7 kB]
+        Hit:3 http://ports.ubuntu.com/ubuntu-ports jammy InRelease
+        Get:4 http://ports.ubuntu.com/ubuntu-ports jammy-updates InRelease [128 kB]
+        Hit:5 http://repo.percona.com/telemetry/apt jammy InRelease
+        Get:6 http://repo.percona.com/pxb-80/apt jammy/main Sources [3393 B]
+        Get:7 http://ports.ubuntu.com/ubuntu-ports jammy-backports InRelease [127 kB]
+        Get:8 http://ports.ubuntu.com/ubuntu-ports jammy-security InRelease [129 kB]
+        Fetched 406 kB in 1s (274 kB/s)
+        Reading package lists... Done
+        ```
+
+7. Install the package:
 
     ```{.bash data-prompt="$"}
     $ sudo apt install percona-xtrabackup-80
     ```
 
-6. To decompress backups made using `LZ4` or `ZSTD` compression algorithm, install the corresponding package:
+    ??? example "Example output"
+
+        ```{.text .no-copy}
+
+        Reading package lists... Done
+        Building dependency tree... Done
+        Reading state information... Done
+        The following additional packages will be installed:
+          libaio1 libcurl4-openssl-dev libdbd-mysql-perl libdbi-perl libev4 libgdbm-compat4 libgdbm6
+          libmysqlclient21 libperl5.34 libpopt0 mysql-common netbase perl perl-modules-5.34 rsync zstd
+        ...
+        Setting up libdbd-mysql-perl:amd64 (4.050-5ubuntu0.22.04.1) ...##########################.........]
+        Setting up percona-xtrabackup-80 (8.0.35-31-1.jammy) ...####################################......]
+        Processing triggers for libc-bin (2.35-0ubuntu3.8) ...########################################....]
+        ```
+
+9. Verify the installation:
+
+    ```{.bash data-prompt="$"}
+    $ xtrabackup --version
+    ```
+
+    ??? example "Example output"
+
+        ```{.text .no-copy}
+        xtrabackup version 8.0.35-31 based on MySQL server 8.0.35 Linux (x86_64) (revision id: 55ec21d7)
+        ```
+
+8. Install optional compression packages if you plan to use LZ4 or ZSTD compression:
 
     === "Install the `lz4` package"
 
@@ -57,14 +212,25 @@ Percona XtraBackup, like many other Percona products, is installed with the *per
         $ sudo apt install zstd
         ```
 
-!!! note
-
-    For AppArmor profile information, see [Working with AppArmor](work-with-apparmor.md).
+## Troubleshooting
+
+If you encounter any errors during the installation process, check your system's error logs:
+
+```{.bash data-prompt="$"}
+$ sudo tail -n 50 /var/log/syslog
+```
+
+Ensure your system meets the minimum requirements for Percona XtraBackup. 
+
+If you encounter permission errors, ensure you're running the commands with `sudo` or have root access.
+
+For AppArmor profile information, see [Working with AppArmor](work-with-apparmor.md).
 
 
-!!! admonition "See also"
+!!! admonition "Additional resources"
 
     To install Percona XtraBackup using downloaded deb packages, see [Install Percona XtraBackup 8.0](apt-download-deb.md).
 
     To uninstall Percona XtraBackup, see [Uninstall Percona XtraBackup 8.0](apt-uninstall-xtrabackup.md)
 
+[Percona XtraBackup 8.0.35-31]: release-notes/8.0/8.0.35-31.0.md