Skip to main content

​
Prerequisites

​
BPF Compiler Collection (BCC)

eBPF Event Interceptor requires the BCC framework to compile and run eBPF programs. The CMake build system can automatically set up BCC on Ubuntu, or you can install it manually.
The included CMake configuration will automatically install BCC if not found:
# BCC will be installed automatically during the build process
# No manual installation required
If you prefer to install BCC manually:
sudo apt-get update
sudo apt-get install -y bpfcc-tools linux-headers-$(uname -r)

​
Build Dependencies

Install the required build tools: 
sudo apt install -y build-essential cmake
Minimum versions:
  • CMake 3.10 or later
  • GCC with C++11 support

​
Build and Install

1

Clone the repository

Download the eBPF Event Interceptor source code:
git clone https://github.com/microsoft/eBPF-Event-Interceptor.git
cd eBPF-Event-Interceptor
2

Create build directory

Set up a dedicated build directory:
mkdir build && cd build
3

Configure with CMake

Generate build files. Add -DSETUP_TESTS=ON to build test executables:
cmake ../
Expected output:
Found BCC
tcp Interceptor
udp Interceptor
-- Configuring done
-- Generating done
-- Build files have been written to: .../build
If BCC is not found, the build system will automatically run installation scripts for Ubuntu. This requires an internet connection and may take several minutes.
4

Compile the libraries

Build using all available CPU cores:
make -j$(nproc --ignore=1)
This compiles:
  • libtcpEvent.so - TCP event interceptor library
  • libudpEvent.so - UDP event interceptor library
  • Test executables (if SETUP_TESTS=ON)
Build output:
[ 50%] Built target tcpEvent
[ 75%] Built target udpEvent
[100%] Built target tcpEventTest
[100%] Built target udpEventTest
5

Install the libraries

Install the compiled libraries to the system:
sudo make install
Installation paths:
  • Libraries: /opt/RealTimeKql/lib/
    • libtcpEvent.so
    • libudpEvent.so
  • Test binaries: /tmp/
    • tcpEventTest
    • udpEventTest
The libraries are installed to /opt/RealTimeKql/lib/ by default. Ensure this path is in your library search path or use LD_LIBRARY_PATH when running applications.

​
Build Options

Customize the build with CMake options:
OptionDescriptionDefault
-DSETUP_TESTS=ONBuild test executablesOFF

​
Example: Full Build with Tests

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

​
Verify Installation

1

Check library files

Verify the libraries were installed:
ls -lh /opt/RealTimeKql/lib/
You should see:
libtcpEvent.so
libudpEvent.so
2

Run test programs (optional)

If you built with tests, run the test executables:
sudo /tmp/tcpEventTest
You should see TCP events from active connections on your system:
 ---> PID: 1177932
 ---> UID: 1000
 ---> rx_b: 2988
 ---> tx_b: 3301
 ---> tcpi_segs_out: 20
 ---> tcpi_segs_in: 18
 ---> Command: ssh
 ---> SADDR: 2001:aaa:fff:eee:ccc:a627:f45f:9c0c
 ---> DADDR: 2601:xxx:yyy:zzz:aaa:db60:46cd:971c
 ---> SPT: 58532
 ---> DPT: 22
For UDP monitoring:
sudo /tmp/udpEventTest
Test programs run indefinitely and print events in real-time. Press Ctrl+C to exit.
3

Check for errors

If you encounter errors, verify:
  • BCC is properly installed: dpkg -l | grep bcc
  • Kernel headers are available: ls /lib/modules/$(uname -r)/build
  • You’re running with root privileges: sudo -v

​
Troubleshooting

​
BCC Not Found

Error: BCC not found Solution: The build system will attempt automatic installation on Ubuntu. For other distributions, install BCC manually following the official guide.

​
Missing Kernel Headers

Error: fatal error: linux/bpf.h: No such file or directory Solution: Install kernel headers: 
sudo apt-get install linux-headers-$(uname -r)

​
Permission Denied

Error: Operation not permitted when running test programs Solution: eBPF operations require root privileges. Run with sudo: 
sudo /tmp/tcpEventTest

​
Library Not Found at Runtime

Error: error while loading shared libraries: libtcpEvent.so Solution: Add the installation path to your library search path: 
export LD_LIBRARY_PATH=/opt/RealTimeKql/lib:$LD_LIBRARY_PATH
Or add it permanently by creating /etc/ld.so.conf.d/realtimekql.conf: 
echo "/opt/RealTimeKql/lib" | sudo tee /etc/ld.so.conf.d/realtimekql.conf
sudo ldconfig

​
Next Steps

Quick Start Guide

Learn how to use the libraries in your own applications

Build docs developers (and LLMs) love

Get started for freeTalk to us