Installation

The qatlib library can be installed by either:

  • Installing from pre-built packages

  • Installing from source code

Distributions such as Fedora 34+, RHEL 9.1+, CentOS 9 Stream, and Ubunutu 24.04 each include qatlib packages within their repositories.

Tip

At the time of writing this user’s guide, the steps in this section were accurate.

If any issues are encountered, refer to latest installation instructions available at the qatlib GitHub repository.

Installing from Packages

This section outlines the installation of qatlib using package managers.

Instructions cover:

  • Ubuntu 24.04

  • RPM (RPM Package Manager)

Ubuntu 24.04

The following steps can be used to install qatlib packages on Ubuntu 24.04.

Note

To install qatlib on older versions of Ubuntu, you must manually compile and install it from the source code.

See the Installing from Sources section for instructions on installing from source.

  1. Update list of available packages and then upgrade the installed packages to their latest versions.

    sudo apt update
sudo apt upgrade -y

  2. Install the qatlib library by running the following command:

    sudo -E apt install -y libqat4 libqat-dev qatlib-service qatlib-examples libusdm-dev

Update QAT Libraries via PPA

The following commands allows users to update the qatlib version in Ubuntu24.04 using PPA (Personal Package Archive).

sudo add-apt-repository ppa:intelqat/qatlib
sudo apt update

RPM

The following steps can be used to install qatlib packages on Linux distributions such as Fedora 34+, RHEL 9.1+, or CentOS 9 Stream.

  1. Install the qatlib library by running the following command:

    sudo dnf -y install qatlib

  2. Install the qatlib-devel package by running the following command. This package is required for custom applications that call the Intel® QAT APIs directly.

    sudo dnf -y install qatlib-devel

Important

If this package is not available we can build all qatlib packages from source files.

Prior to building the library, uninstall qatlib package using the following command:

sudo dnf remove qatlib

See the Installing from Sources section for instructions on installing from source.

System Updates

Note

This section is required for both on Ubunutu24.04 and RPM installations.

  1. Add your user to the qat group by running the below command, and re-login to make the change effective. This is necessary for non-root users to use qat services.

    sudo usermod -a -G qat `whoami`
sudo su -l $USER

  2. Enable the qat service and make it persistent after reboot by running the following commands:

    sudo systemctl enable qat
sudo systemctl start qat

  3. Increase the amount of locked memory for your user by running the below command:

    Note

    The amount of memory depends upon the needs of your application. For example, the cpa_sample_code requires a minimum of 500MB. The following commands set the amount of locked memory to 500MB.

    sudo cp /etc/security/limits.conf /etc/security/limits.conf.qatlib_bak
echo `whoami` - memlock 500000  | sudo tee -a /etc/security/limits.conf > /dev/null
sudo su -l $USER

Installing from Sources

The following steps explain how to verify and build the qatlib package from source.

Step 1 walks through optional verification of the signed qatlib-26.02.0 tarball from the QATlib GitHub releases page, followed by the build steps that assume the artifact was verified or otherwise trusted.

  1. Verify the source package (Optional).

    Use this step whenever you download qatlib-26.02.0.tar.gz directly from the release page and want to confirm the artifact is authentic before compiling.

    • Download the qatlib-26.02.0.tar.gz and 26.02.0.tar.gz.asc files from the release.

    • Import the public signing key:

      curl -sSfL https://github.com/Ahsan-atta.gpg | gpg --import

    • Verify the key fingerprint matches 928F94F0ADA52F3778D340E85755001BD60500F4:

      gpg --fingerprint 928F94F0ADA52F3778D340E85755001BD60500F4

    • Check the tarball checksum to ensure the download is complete:

      sha256sum qatlib-26.02.0.tar.gz

      The value returned must match 7c68bf05f196153b1b1669a7d17e5bfba6253e7cafb69f67d30a0d17e7facecb.

    • Verify the signature:

      gpg --verify 26.02.0.tar.gz.asc qatlib-26.02.0.tar.gz

      A successful verification reports a good signature from the key above.

  2. Install the dependencies by running the following commands.

    For RPM-based distros:

    sudo dnf install -y gcc systemd-devel automake autoconf libtool make autoconf-archive
sudo dnf install -y openssl-devel zlib-devel numactl-devel
sudo dnf install -y nasm

    For Ubuntu and other Debian-based distros, install these dependencies:

    sudo apt-get install -y gcc libsystemd-dev automake autoconf libtool autoconf-archive
sudo apt-get install -y libssl-dev zlib1g-dev nasm libnuma-dev

    Tip

    • If using CentOS 9 Stream, you may need to run the following command to install nasm:

      sudo dnf --enablerepo=crb install -y nasm

    • If using CentOS 8 Stream, you may need run the following command to install nasm:

      sudo dnf --enablerepo=powertools install -y nasm

    • If using RHEL, you may need to run the following commands to install nasm:

      sudo subscription-manager repos --enable codeready-builder-for-rhel-9-x86_64-rpms
sudo dnf install -y nasm

    • If the nasm compiler is unavailable see the --disable-fast-crc-in-assembler option in the Configuration Options section.

  3. Uninstall existing libraries and clean-up (if upgrading from a previous version of qatlib) the environment.

    Note

    • These make commands should be run using the Makefiles that were generated by the original call to the configure script.

    • There is no need to call the ./configure script before uninstall and clean-up. If it is ever called again it must be called with exactly the same options as were originally used so whatever was installed can be correctly cleaned up.

    To uninstall:

    cd ~/qatlib
sudo make samples-uninstall
sudo systemctl stop qat
sudo make uninstall

    To clean-up:

    sudo make clean
sudo make distclean

  4. Clone the qatlib repository into ~/qatlib (i.e. current home directory) by running the below commands:

    cd ~
git clone https://github.com/intel/qatlib.git

  5. Configure the qatlib driver by running the following commands:

    cd qatlib
./autogen.sh

    A complete list of configuration options are listed Configuration Options section or can be obtained by running the following command:

    ./configure --help

    By default, libraries are installed into /usr/local/lib , however, use the ./configure flag --prefix=<path> to point to /usr/lib or /usr/lib64/ .

    Important

    By default the shared library files are placed in /usr/local/lib. Depending on your distribution, this directory may not be in the library path that ldconfig uses.

    This directory can be included by either adding entry to the file /etc/ld.so.conf or creating a file usr-local.conf (or name of your choice) in the /etc/ld.so.conf.d directory.

    Important

    With some OS distributions such as Ubuntu, the directory for qat.service is in a different location.

    To address potential issues, include additional configuration option: systemdsystemunitdir.

    Configure step would look like:

    ./configure --enable-service systemdsystemunitdir=/lib/systemd/system/ --prefix=/usr

    To run in Managed Mode, enable the qat service. This can be done automatically with the following command:

    ./configure --enable-service --prefix=/usr

    To run in Standalone Mode, disable the qat service. This is often preferable when running in containers to avoid dependency on systemd. This can be done with the following command:

    ./configure --enable-systemd=no --prefix=/usr

  6. Build and install the qatlib library by running the following commands:

    make -j
sudo make install

    If the service was not configured to start automatically using the --enable-service configuration option, then the service will need to be started. To start the qat service and make it persistent after reboot, use the following commands:

    sudo systemctl enable qat
sudo systemctl start qat

  7. Verify the qat service was started by running the below command:

    systemctl status qat

    The output should look like the following:

    qat.service - QAT service
Loaded: loaded (/usr/lib/systemd/system/qat.service; enabled; preset: disabled)
Active: active (running) since Sat 2023-05-13 12:08:26 PDT; 8s ago
Main PID: 1266135 (qatmgr)
   Tasks: 1 (limit: 1643873)
Memory: 7.0M
   CPU: 1.832s
CGroup: /system.slice/qat.service
         └─1266135 /usr/local/sbin/qatmgr --policy=0

May 13 12:08:17 SPR-QUANTA-Server-01 qat_init.sh[1264066]: /usr/local/sbin/qat_init.sh, device 0000:e8:00.0 configured with services: dc
May 13 12:08:17 SPR-QUANTA-Server-01 qat_init.sh[1264066]: /usr/local/sbin/qat_init.sh, device 0000:ed:00.0 configured with services: dc
May 13 12:08:17 SPR-QUANTA-Server-01 qat_init.sh[1264066]: /usr/local/sbin/qat_init.sh, device 0000:f2:00.0 configured with services: dc
May 13 12:08:17 SPR-QUANTA-Server-01 qat_init.sh[1264066]: /usr/local/sbin/qat_init.sh, device 0000:f7:00.0 configured with services: dc
May 13 12:08:26 SPR-QUANTA-Server-01 systemd[1]: Started QAT service.

  8. Add your user to the qat group by running the below command, and re-login to make the change effective. This is necessary for non-root users to use qat services.

    sudo usermod -a -G qat `whoami`
sudo su -l $USER

  9. Increase the amount of locked memory for your user by running the below command:

    Note

    The amount of memory depends upon the needs of your application. For example, the cpa_sample_code requires a minimum of 500MB. The following commands set the amount of locked memory to 500MB.

    sudo cp /etc/security/limits.conf /etc/security/limits.conf.qatlib_bak
echo `whoami` - memlock 500000  | sudo tee -a /etc/security/limits.conf > /dev/null
sudo su -l $USER

Note

On some distros like Ubuntu, it may be necessary to set $LD_LIBRARY_PATH to point to the path that contains libusdm.so, usually /usr/local/lib. Example:

export LD_LIBRARY_PATH=/usr/local/lib

Configuration Options

Note

  • After any change to ./configure flags, it is required to re-run the make and install commands.

Typical examples of how to update the configuration options are as follows:

./configure ICP_ANY_FLAG=value

or

./configure --enable-something

If it is required to use more than one flag at once use the following example:

./configure ICP_ANY_PATH=path ICP_ANY_NAME=name --enable-something

Confirm Current Version

  1. To confirm your current qatlib version, use one of the following:

    qatmgr -v

    Example return:

    qatmgr 26.02.0

  2. Use the package versionfile:

    In the example command below, it assumes the source directory for qatlib is ~/qatlib. Update this command if source directory is something different.

    cat ~/qatlib/versionfile

    Example return:

    PACKAGE_TYPE=QAT_UPSTREAM

PACKAGE_OS=L

PACKAGE_VERSION_MAJOR_NUMBER=26

PACKAGE_VERSION_MINOR_NUMBER=02

PACKAGE_VERSION_PATCH_NUMBER=0

PACKAGE_VERSION_BUILD_NUMBER=00024