Installation

Install BCC dependencies and build eBPF Event Interceptor from source

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.

Ubuntu 20.04 / 18.04

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)

Other Distributions

For other Linux distributions, follow the official BCC installation guide.

Ensure you install both the BCC runtime library and development headers.

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:

   Standard Build

   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:

Option	Description	Default
-DSETUP_TESTS=ON	Build test executables	OFF

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