Building osquery - linux-on-ibm-z/docs GitHub Wiki

Building osquery

The instructions provided below specify the steps to build osquery version 5.23.0 on Linux on IBM Z for the following distributions:

  • RHEL (8.10, 9.6, 9.7, 10.0, 10.1)
  • Ubuntu (22.04, 24.04, 25.10)

General Notes:

  • When following the steps below please use a standard permission user unless otherwise specified.
  • A directory /<source_root>/ will be referred to in these instructions, this is a temporary writable directory anywhere you'd like to place it.
  • Docker is required for building the osquery-toolchain.

Note: osquery (5.23.0) was verified with docker version 29.4.1 at the time of creation of these instructions.

1. Build using script

If you want to build osquery using manual steps, go to STEP 2.

Use the following commands to build osquery using the build script. Please make sure wget is installed.

wget https://raw.githubusercontent.com/linux-on-ibm-z/scripts/master/osquery/5.23.0/build_osquery.sh

# Build osquery
bash build_osquery.sh [Provide -t option for executing build with tests]

If the build and tests complete successfully, go to STEP 7. In case of error, check the <source_root>/logs/ directory for more details or go to STEP 2 to follow the manual build steps.

2. Set environment variables

export SOURCE_ROOT=/<source_root>/
export TOOLCHAIN_BUILD=$SOURCE_ROOT/toolchain-build
export PATCH_URL="https://raw.githubusercontent.com/linux-on-ibm-z/scripts/master/osquery/5.23.0/patch"

3. Install Dependencies

3.1 Install Basic Dependencies

  • RHEL (8.10, 9.6, 9.7, 10.0, 10.1)

    sudo yum install -y git python3 python3-pip python3-setuptools python3-psutil python3-six python3-wheel python3-devel \
gcc-c++ gcc automake autoconf gettext bison flex unzip help2man libtool ncurses-devel make ninja-build curl \
patch texinfo gawk wget xz bzip2 cmake pkgconfig ca-certificates file perl rpm binutils

  • Ubuntu (22.04, 24.04, 25.10)

    sudo apt-get update
sudo DEBIAN_FRONTEND=noninteractive apt-get install -y git python3 python3-pip python3-setuptools python3-psutil \
python3-six python3-wheel g++ gcc automake autoconf gettext bison flex unzip help2man libtool-bin libncurses-dev \
make ninja-build patch texinfo gawk wget xz-utils bzip2 cmake pkg-config ca-certificates file perl rpm binutils curl

3.2. Install required Python packages

  • For Ubuntu 24.04 and 25.10:

    python3 -m pip install --user --break-system-packages timeout_decorator thrift==0.11.0 osquery pexpect==3.3 docker

  • For RHEL and Ubuntu 22.04:

    python3 -m pip install --user timeout_decorator thrift==0.11.0 osquery pexpect==3.3 docker

4. Build the osquery toolchain using Docker

  • The osquery-toolchain is built inside a Docker container to ensure a consistent build environment.

4.1. Build toolchain in Docker container

cd $SOURCE_ROOT
docker run --privileged=true -i --name osquery-toolchain-build ubuntu:22.04 bash -c \
"apt-get update; \
DEBIAN_FRONTEND=noninteractive apt-get install -y sudo vim git python3 python3-pip python3-setuptools python3-psutil \
python3-six python3-wheel g++ gcc automake autoconf gettext bison flex unzip help2man libtool-bin libncurses-dev \
make ninja-build patch texinfo gawk wget xz-utils bzip2 cmake pkg-config ca-certificates file perl rpm binutils curl; \
useradd -m test || true; \
usermod -aG sudo test; \
chown -R test:test /home/test; \
cd /home/test; \
git clone -b 1.3.0 https://github.com/osquery/osquery-toolchain.git; \
cd osquery-toolchain;
curl -sSL $PATCH_URL/toolchain_ubuntu.patch | git apply -
bash -n build.sh; 
sudo -u test bash -c 'cd /home/test/osquery-toolchain; ./build.sh /home/test/toolchain-build;'; \
cd /home/test/toolchain-build/final; \
mv sysroot osquery-toolchain; \
tar -pcvJf osquery-toolchain-1.3.0.tar.xz osquery-toolchain;
"

4.2. Extract osquery-toolchain tar.xz from container

cd $SOURCE_ROOT
docker cp osquery-toolchain-build:/home/test/toolchain-build/final/osquery-toolchain-1.3.0.tar.xz .
mkdir -p $TOOLCHAIN_BUILD
tar -xJvf osquery-toolchain-1.3.0.tar.xz -C $TOOLCHAIN_BUILD

4.3. Verification of osquery-toolchain

export OSQUERY_TOOLCHAIN_SYSROOT="$TOOLCHAIN_BUILD/osquery-toolchain"
$OSQUERY_TOOLCHAIN_SYSROOT/usr/bin/clang --version

The output should display the clang version information from the toolchain.

5. Configure and build osquery

5.1. Clone the osquery repository

cd $SOURCE_ROOT
git clone -b 5.23.0 https://github.com/osquery/osquery.git
cd osquery
git submodule update --init --recursive

5.2. Apply patches

  • Apply all required patches for osquery:

    curl -sSL ${PATCH_URL}/osquery_generated.patch | git apply -
curl -sSL ${PATCH_URL}/osquery_main.patch | git apply -
curl -sSL ${PATCH_URL}/ebpf_common.patch | git apply -
curl -sSL ${PATCH_URL}/ebpfpub.patch | git apply -
curl -sSL ${PATCH_URL}/rocksdb.patch | git apply -
curl -sSL ${PATCH_URL}/s2n.patch | git apply -
curl -sSL ${PATCH_URL}/test_cases.patch | git apply -

  • RHEL only:

    curl -sSL ${PATCH_URL}/linux_test_case_rhel.patch | git apply -

5.3. Build osquery

Create the build directory and compile osquery:

mkdir -p build
cd build
cmake -DOSQUERY_TOOLCHAIN_SYSROOT="$OSQUERY_TOOLCHAIN_SYSROOT" -DOSQUERY_BUILD_TESTS=ON ..
cmake --build . -j1

6. Testing (Optional)

6.1. Run the functional verification test suites

cd $SOURCE_ROOT/osquery/build
ctest --output-on-failure -j1

Note: The test case tools_tests_testfschangestable requires Docker to be installed and running.

7. Verification (Optional)

7.1. Verify osquery installation

cd $SOURCE_ROOT/osquery/build
./osquery/osqueryi --version

Expected output:

osqueryi version 5.23.0

7.2. Start osquery interactive shell

cd $SOURCE_ROOT/osquery/build
./osquery/osqueryi

7.3. Example queries

Run these SQL queries in osquery shell:

-- Get OS version
SELECT * FROM os_version;

-- List running processes
SELECT pid, name, path FROM processes LIMIT 10;

-- Check system uptime
SELECT * FROM uptime;

8. References: