Building from Source

This guide walks through building the eBPF Event Interceptor from source, including setting up dependencies, configuring build options, and troubleshooting common issues.

Prerequisites

Before building, ensure you have the required dependencies installed.

System Requirements

Linux Kernel: 4.1 or newer with eBPF support
Build Tools: gcc, g++, make, cmake (3.10+)
BCC: BPF Compiler Collection (version varies by distribution)

Installing Build Dependencies

On Ubuntu 20.04 or newer:

sudo apt install -y build-essential cmake

CMake 3.10 or higher is required. Check your version with cmake --version.

Setting Up BCC

The BPF Compiler Collection (BCC) is required to compile eBPF programs.

Automatic Setup (Ubuntu)

The build system can automatically install BCC for Ubuntu systems:

cmake ../
make -j$(nproc --ignore=1)

If BCC is not found, the build system will run scripts/extended.sh to install it.

Manual BCC Installation

For other distributions or manual installation:

Ubuntu 20.04
Ubuntu 18.04
Other Distributions

sudo apt-get -y install bison build-essential cmake flex git \
  libedit-dev libllvm7 llvm-7-dev libclang-7-dev python \
  zlib1g-dev libelf-dev libfl-dev

sudo apt-get -y install bison build-essential cmake flex git \
  libedit-dev libllvm6.0 llvm-6.0-dev libclang-6.0-dev python \
  zlib1g-dev libelf-dev libfl-dev

sudo apt-get -y install bison build-essential cmake flex git \
  libedit-dev libllvm3.7 llvm-3.7-dev libclang-3.7-dev python \
  zlib1g-dev libelf-dev

Then build and install BCC from source:

cd /tmp
git clone https://github.com/iovisor/bcc.git
mkdir bcc/build && cd bcc/build
cmake ../
make -j$(nproc --ignore=1)
sudo make install

For detailed BCC installation instructions for your specific distribution, see the official BCC installation guide.

Building the Project

Clone the repository

git clone https://github.com/microsoft/eBPF-Event-Interceptor.git
cd eBPF-Event-Interceptor

Create build directory

mkdir build && cd build

Configure with CMake

Run CMake to configure the build:

cmake ../

You should see output like:

Found BCC
tcp Interceptor
udp Interceptor
-- Configuring done
-- Generating done
-- Build files have been written to: /path/to/eBPF-Event-Interceptor/build

Build the libraries

Compile using all available CPU cores:

make -j$(nproc --ignore=1)

This builds:

libtcpEvent.so - TCP event interceptor
libudpEvent.so - UDP event interceptor

Install the libraries

Install to the default location (/opt/RealTimeKql/lib):

sudo make install

Output:

Install the project...
-- Install configuration: ""
-- Installing: /opt/RealTimeKql/lib/libtcpEvent.so
-- Installing: /opt/RealTimeKql/lib/libudpEvent.so

CMake Build Options

The build system supports several configuration options:

SETUP_TESTS

Enable building test programs:

cmake -DSETUP_TESTS=ON ../
make -j$(nproc --ignore=1)
sudo make install

With tests enabled, the build produces:

[ 50%] Built target tcpEvent
[ 50%] Built target udpEvent
[100%] Built target udpEventTest
[100%] Built target tcpEventTest

Test binaries are installed to /tmp:

/tmp/tcpEventTest
/tmp/udpEventTest

Tests are disabled by default (SETUP_TESTS=OFF). Enable them for development and testing.

Custom Installation Paths

To change installation directories, modify the CMakeLists.txt:

set(SO_FOLDER /opt/RealTimeKql/lib)  # Library installation path
set(BIN_FOLDER /opt/RealTimeKql/bin) # Binary installation path

Or override during CMake configuration:

cmake -DCMAKE_INSTALL_PREFIX=/usr/local ../

Build Output Structure

After a successful build, your build directory contains:

build/
├── tcpEvent/
│   ├── libtcpEvent.so
│   └── Test/
│       └── tcpEventTest (if SETUP_TESTS=ON)
├── udpEvent/
│   ├── libudpEvent.so
│   └── Test/
│       └── udpEventTest (if SETUP_TESTS=ON)
└── CMakeFiles/

Compilation Flags

The build system uses strict compiler flags:

add_compile_options(-Wall -Wextra -Werror -D_FILE_OFFSET_BITS=64)

-Wall -Wextra: Enable comprehensive warnings
-Werror: Treat warnings as errors
-D_FILE_OFFSET_BITS=64: Enable large file support
-pthread: Enable POSIX threads

The -Werror flag means any compiler warnings will fail the build. This ensures code quality but may require fixes when using different compiler versions.

Build Troubleshooting

BCC not found

Error:

BCC not found
Setting up bcc and pre-requisite packages

Solution: The build system will attempt automatic installation. If it fails:

Install BCC manually (see Manual BCC Installation)
Ensure BCC is in the system library path: ldconfig -p | grep bcc

If installed to a custom location, set the library path:

export LD_LIBRARY_PATH=/path/to/bcc/lib:$LD_LIBRARY_PATH

CMake version too old

Error:

CMake 3.10 or higher is required. You are running version X.X

Solution: Install a newer CMake:

# Ubuntu 18.04+
sudo apt-get install cmake

# Or build from source
wget https://cmake.org/files/v3.20/cmake-3.20.0.tar.gz
tar xf cmake-3.20.0.tar.gz
cd cmake-3.20.0
./bootstrap && make -j$(nproc) && sudo make install

Missing pthread library

Error:

FATAL_ERROR "We need pthread!"

Solution: Install pthread development files:

sudo apt-get install libc6-dev

Compiler errors with -Werror

If you encounter warnings-as-errors:Option 1: Fix the warnings (recommended)Option 2: Temporarily disable -Werror in CMakeLists.txt:

# Comment out or remove -Werror
add_compile_options(-Wall -Wextra -D_FILE_OFFSET_BITS=64)

LLVM version mismatch

Error:

error: 'llvm::Error' has not been declared

Solution: Ensure BCC is built with the same LLVM version as your system:

llvm-config --version

Rebuild BCC if versions don’t match.

Permission denied during install

Error:

CMake Error at cmake_install.cmake:XX (file):
  file INSTALL cannot copy file

Solution: Use sudo for installation:

sudo make install

Or create the installation directory with appropriate permissions:

sudo mkdir -p /opt/RealTimeKql/lib
sudo chown $USER:$USER /opt/RealTimeKql/lib

Verifying the Build

After installation, verify the libraries are correctly installed:

ls -lh /opt/RealTimeKql/lib/

Expected output:

total 2.1M
-rwxr-xr-x 1 root root 1.1M Jan 15 10:30 libtcpEvent.so
-rwxr-xr-x 1 root root 1.0M Jan 15 10:30 libudpEvent.so

Check library dependencies:

ldd /opt/RealTimeKql/lib/libtcpEvent.so

Should show libbcc.so in the dependencies:

linux-vdso.so.1
libbcc.so.0 => /usr/lib/x86_64-linux-gnu/libbcc.so.0
libstdc++.so.6 => /usr/lib/x86_64-linux-gnu/libstdc++.so.6
...

Rebuilding

To rebuild after making changes:

cd build
make clean
make -j$(nproc --ignore=1)
sudo make install

For a complete rebuild:

cd ..
rm -rf build
mkdir build && cd build
cmake -DSETUP_TESTS=ON ../
make -j$(nproc --ignore=1)
sudo make install

Development Workflow

For active development:

Build with tests enabled

cmake -DSETUP_TESTS=ON ../

Make code changes

Edit source files in tcpEvent/ or udpEvent/

Rebuild incrementally

make -j$(nproc --ignore=1)

Test your changes

sudo make install
sudo /tmp/tcpEventTest  # or udpEventTest

Use make -j$(nproc) to use all CPU cores, or make -j$(nproc --ignore=1) to leave one core free for other tasks.

Cross-Platform Considerations

Kernel Headers

eBPF programs require kernel headers. Ensure they’re installed:

sudo apt-get install linux-headers-$(uname -r)

Architecture Support

The interceptor supports x86_64 architecture. For other architectures, you may need to:

Adjust struct alignment in common.h
Verify eBPF helper function compatibility
Test thoroughly on your target platform

Next Steps

Testing

Learn how to run and create tests

TCP Monitoring

Start monitoring TCP connections

UDP Monitoring

Start monitoring UDP traffic

Contributing

Contribute to the project

Get Started

Core Concepts

Guides

Prerequisites

System Requirements

Installing Build Dependencies

Setting Up BCC

Automatic Setup (Ubuntu)

Manual BCC Installation

Building the Project

CMake Build Options

SETUP_TESTS

Custom Installation Paths

Build Output Structure

Compilation Flags

Build Troubleshooting

Verifying the Build

Rebuilding

Development Workflow

Cross-Platform Considerations

Kernel Headers

Architecture Support

Next Steps

Testing

TCP Monitoring

UDP Monitoring

Contributing

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

​Prerequisites

​System Requirements

​Installing Build Dependencies

​Setting Up BCC

​Automatic Setup (Ubuntu)

​Manual BCC Installation

​Building the Project

​CMake Build Options

​SETUP_TESTS

​Custom Installation Paths

​Build Output Structure

​Compilation Flags

​Build Troubleshooting

​Verifying the Build

​Rebuilding

​Development Workflow

​Cross-Platform Considerations

​Kernel Headers

​Architecture Support

​Next Steps

Testing

TCP Monitoring

UDP Monitoring

Contributing

Build docs developers (and LLMs) love

Prerequisites

System Requirements

Installing Build Dependencies

Setting Up BCC

Automatic Setup (Ubuntu)

Manual BCC Installation

Building the Project

CMake Build Options

SETUP_TESTS

Custom Installation Paths

Build Output Structure

Compilation Flags

Build Troubleshooting

Verifying the Build

Rebuilding

Development Workflow

Cross-Platform Considerations

Kernel Headers

Architecture Support

Next Steps