Skip to content
Starting November 2023 Percona XtraBackup 2.4 has reached EOL status. If you have 5.7 databases, we encourage you to upgrade to 8.0 and then install Percona XtraBackup 8.0. Learn more

logo
Percona XtraBackup
Compiling and Installing from Source Code
Initializing search
    percona/pxb-docs
    percona/pxb-docs
    • Home
      • About Percona XtraBackup
      • How Percona XtraBackup Works
      • Understand version numbers
      • Installing Percona XtraBackup 2.4
      • Installing Percona XtraBackup on Debian and Ubuntu
      • Installing Percona XtraBackup on Red Hat Enterprise Linux and CentOS
      • Installing Percona XtraBackup from a Binary Tarball
      • Compiling and Installing from Source Code
        • Step 1: Installing prerequisites
          • Debian or Ubuntu using apt
          • CentOS or Red Hat using yum
        • Step 2: Generating the build pipeline
          • More information about parameters
        • Step 2: Compiling the source code
        • Step 3: Installing on the target system
          • Installing to a non-default location
        • Step 4: Running
      • Running Percona XtraBackup in a Docker container
      • Connection and Privileges Needed
      • Configuring xtrabackup
      • The Backup Cycle - Full Backups
      • Incremental Backup
      • Compressed Backup
      • Encrypted Backup
      • Percona XtraBackup User Manual
      • Throttling Backups
      • Lockless binary log information
      • Encrypted InnoDB Tablespace Backups
      • lock-ddl-per-table Option Improvements
      • How-tos and Recipes
        • Release notes index
        • Percona XtraBackup 2.4.29 (2023-12-18)
        • Percona XtraBackup 2.4.28 (2023-04-04)
        • Percona XtraBackup 2.4.27 (2022-12-06)
        • Percona XtraBackup 2.4.26
        • Percona XtraBackup 2.4.25
        • Percona XtraBackup 2.4.24
        • Percona XtraBackup 2.4.23
        • Percona XtraBackup 2.4.22
        • Percona XtraBackup 2.4.21
        • Percona XtraBackup 2.4.20
        • Percona XtraBackup 2.4.19
        • Percona XtraBackup 2.4.18
        • Percona XtraBackup 2.4.17
        • Percona XtraBackup 2.4.16
        • Percona XtraBackup 2.4.15
        • Percona XtraBackup 2.4.14
        • Percona XtraBackup 2.4.13
        • Percona XtraBackup 2.4.12
        • Percona XtraBackup 2.4.11
        • Percona XtraBackup 2.4.10
        • Percona XtraBackup 2.4.9
        • Percona XtraBackup 2.4.8
        • Percona XtraBackup 2.4.7-2
        • Percona XtraBackup 2.4.7
        • Percona XtraBackup 2.4.6
        • Percona XtraBackup 2.4.5
        • Percona XtraBackup 2.4.4
        • Percona XtraBackup 2.4.3
        • Percona XtraBackup 2.4.2
        • Percona XtraBackup 2.4.1
      • The xtrabackup Option Reference
      • The innobackupex Option Reference
      • The xbcloud Binary
      • Exponential Backoff
      • Using the xbcloud binary with Microsoft Azure Cloud Storage
      • The xbcrypt binary
      • The xbstream binary
      • Known issues and limitations
      • Frequently Asked Questions
      • Glossary
      • Index of files created by Percona XtraBackup
      • Trademark policy
      • Copyright and licensing information
      • Version Checking

    • Step 1: Installing prerequisites
      • Debian or Ubuntu using apt
      • CentOS or Red Hat using yum
    • Step 2: Generating the build pipeline
      • More information about parameters
    • Step 2: Compiling the source code
    • Step 3: Installing on the target system
      • Installing to a non-default location
    • Step 4: Running

    Compiling and Installing from Source Code¶

    Note

    The following instructions installs Percona XtraBackup 2.4 by compiling the source code. The instructions to run Percona XtraBackup 8.0 by the same method are available in the Percona XtraBackup 8.0 installation documentation.

    The source code is available from the Percona XtraBackup Github project. The easiest way to get the code is by using the git clone command. Then, switch to the release branch that you want to install, such as 2.4.

    $ git clone https://github.com/percona/percona-xtrabackup.git
    $ cd percona-xtrabackup
    $ git checkout 2.4
    

    Step 1: Installing prerequisites¶

    The following packages and tools must be installed to compile Percona XtraBackup from source. These might vary from system to system.

    Important

    In order to build Percona XtraBackup v8.0 from source, you need to use cmake version 3. In your distribution, it may be available either as a separate package cmake3 or as cmake. To check which version is installed, run cmake --version and if it does report a version 3, install cmake3 for your system.

    See also

    https://cmake.org/

    Debian or Ubuntu using apt¶

    $ sudo apt install build-essential flex bison automake autoconf \
    libtool cmake libaio-dev mysql-client libncurses-dev zlib1g-dev \
    libgcrypt11-dev libev-dev libcurl4-gnutls-dev vim-common
    

    To install the man pages, install the python3-sphinx package:

    $ sudo apt install python3-sphinx
    

    CentOS or Red Hat using yum¶

    Percona XtraBackup requires GCC version 5.3 or higher. If the version of GCC installed on your system is lower then you may need to install and enable the Developer Toolset on RPM-based distributions to make sure that you use the latest GCC compiler and development tools. Then, install cmake and other dependencies:

    $ sudo yum install cmake openssl-devel libaio libaio-devel automake autoconf \
    bison libtool ncurses-devel libgcrypt-devel libev-devel libcurl-devel zlib-devel \
    vim-common
    

    To install the man pages, install the python3-sphinx package:

    $ sudo yum install python3-sphinx
    

    Step 2: Generating the build pipeline¶

    At this step, you have cmake run the commands in the CMakeList.txt file to generate the build pipeline, i.e. a native build environment that will be used to compile the source code).

    1. Change to the directory where you cloned the Percona XtraBackup repository

      $ cd percona-xtrabackup
      
    2. Create a directory to store the compiled files and then change to that directory:

      $ mkdir build
      $ cd build
      
    3. Run cmake or cmake3. In either case, the options you need to use are the same.

    Note

    You can build Percona XtraBackup with man pages but this requires python-sphinx package which isn’t available from that main repositories for every distribution. If you installed the python-sphinx package you need to remove the -DWITH_MAN_PAGES=OFF from previous command.

    $ cmake -DWITH_BOOST=PATH-TO-BOOST-LIBRARY -DDOWNLOAD_BOOST=ON \
    -DBUILD_CONFIG=xtrabackup_release -DWITH_MAN_PAGES=OFF -B ..
    

    More information about parameters¶

    -DWITH_BOOST

    For the -DWITH_BOOST parameter, specify the name of a directory to download the boost library to. This directory will be created automatically in your current directory.

    -B (--build)

    Percona XtraBackup is configured to forbid generating the build pipeline for make in the same directory where you store your sources. The -B parameter refers to the directory that contains the source code. In this example we use the relative path to the parent directory (..).

    Important

    CMake Error at CMakeLists.txt:367 (MESSAGE): Please do not build in-source. Out-of source builds are highly recommended: you can have multiple builds for the same source, and there is an easy way to do cleanup, simply remove the build directory (note that ‘make clean’ or ‘make distclean’ does not work)

    You can force in-source build by invoking cmake with -DFORCE_INSOURCE_BUILD=1

    -DWITH_MAN_PAGES

    To build Percona XtraBackup man pages, use ON or remove this parameter from the command line (it is ON by default).

    To install the man pages, install the python3-sphinx package:

    Step 2: Compiling the source code¶

    To compile the source code in your build directory, use the make command.

    Important

    The computer where you intend to compile Percona XtraBackup 8.0 must have at least 2G of RAM available.

    1. Change to the build directory (created at Step 2: Generating the build pipeline).

    2. Run the make command. This command may take a long time to complete.

      $ make
      

    Step 3: Installing on the target system¶

    The following command installs all Percona XtraBackup binaries xtrabackup and tests to default location on the target system: /usr/local/xtrabackup.

    Run make install to install Percona XtraBackup to the default location.

    $ sudo make install
    

    Installing to a non-default location¶

    You may use the DESTDIR parameter with make install to install Percona XtraBackup to another location. Make sure that the effective user is able to write to the destination you choose.

    $ sudo make DESTDIR=<DIR_NAME> install
    

    In fact, the destination directory is determined by the installation layout (-DINSTALL_LAYOUT) that cmake applies (see Step 2: Generating the build pipeline). In addition to the installation directory, this parameter controls a number of other destinations that you can adjust for your system.

    By default, this parameter is set to STANDALONE, which implies the installation directory to be /usr/local/xtrabackup.

    See also

    MySQL Documentation: -DINSTALL_LAYOUT

    Step 4: Running¶

    After Percona XtraBackup is installed on your system, you may run it by using the full path to the xtrabackup command:

    $ /usr/local/xtrabackup/bin/xtrabackup
    

    Update your PATH environment variable if you would like to use the command on the command line directly.

    $# Setting $PATH on the command line
    $ PATH=$PATH:/usr/local/xtrabackup/bin/xtrabackup
    
    $# Run xtrabackup directly
    $ xtrabackup
    

    Alternatively, you may consider placing a soft link (using ln -s) to one of the locations listed in your PATH environment variable.

    See also

    man ln

    To view the documentation with man, update the MANPATH variable.

    Contact us

    For free technical help, visit the Percona Community Forum.

    To report bugs or submit feature requests, open a JIRA ticket.

    For paid support and managed or consulting services , contact Percona Sales.

    2022-12-06
    Percona LLC and/or its affiliates, © 2024 Cookie Preferences
    Made with Material for MkDocs