Testing - eBPF Event Interceptor

The eBPF Event Interceptor includes test programs that demonstrate library usage and verify functionality. This guide covers building with tests, running the test programs, and understanding their output.

Building with Tests

Tests are disabled by default. Enable them with the SETUP_TESTS CMake option:

Configure build with tests

cd build
cmake -DSETUP_TESTS=ON ../

You’ll see confirmation in the output:

Found BCC
tcp Interceptor
Setting up Tests
test tcp Interceptor
udp Interceptor
Setting up Tests for UDP Tracer
test udp Interceptor

Build tests and libraries

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

Expected output:

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

Install tests and libraries

sudo make install

This installs:

Libraries to /opt/RealTimeKql/lib/
Test binaries to /tmp/

-- Installing: /opt/RealTimeKql/lib/libtcpEvent.so
-- Installing: /tmp/tcpEventTest
-- Installing: /opt/RealTimeKql/lib/libudpEvent.so
-- Installing: /tmp/udpEventTest

Test binaries are installed to /tmp by default. They will be removed on system reboot unless you move them to a persistent location.

Running TCP Tests

The TCP test program (tcpEventTest) monitors all TCP connections on the system.

Starting the Test

sudo /tmp/tcpEventTest

eBPF programs require root privileges or CAP_BPF capability to load and attach probes.

Expected Output

TCP mainer Ver 1.03a PID: 1234
dlopen: /opt/RealTimeKql/lib/libtcpEvent.so
dlopen OK!
About to AddProbe
AddProbe done!
Waiting on getStatus()..
Tracing, press "CtrlC" to terminate..

Once a TCP connection closes, you’ll see events:

                ---               
 ---> In main, DEQD at 0x7ffc1234abcd
 ---> 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
 ---> EventTime: 1628184562000000000
                ---

Understanding TCP Test Output

PID

Process ID that owned the TCP connection

UID

User ID of the process

rx_b

Total bytes received on this connection

tx_b

Total bytes transmitted (acknowledged)

tcpi_segs_out

Number of TCP segments sent

tcpi_segs_in

Number of TCP segments received

Command

Process name (e.g., ssh, curl, wget)

SPT/DPT

Source and destination ports

Generating TCP Test Traffic

To see events, generate TCP traffic:

# Make a simple HTTP request
curl http://example.com

TCP events are generated when connections close (transition to TCP_CLOSE state). Active connections won’t produce events until they terminate.

Running UDP Tests

The UDP test program (udpEventTest) monitors all UDP traffic on the system.

Starting the Test

sudo /tmp/udpEventTest

Expected Output

udp mainer ver 1.03b PID: 5678
dlopen: /opt/RealTimeKql/lib/libudpEvent.so
dlopen OK!
About to AddProbe
UDP Tracer Ver 1.04b with BCC 0.18.0
AddProbe done!
Attached: ip6_datagram_connect
Attached: ip4_datagram_connect
Attached: udp_recvmsg
Attached: udp_sendmsg
Attached: udp_destruct_sock
Attached: udpv6_sendmsg
Attached: udpv6_recvmsg
Attached: kretprobe__udpv6_recvmsg
--> bpf.open_perf_buffer OK
Tracing, press "CtrlC" to terminate..

When UDP traffic occurs:

                ---               
 ---> In main, DEQD at 0x7ffc9876dcba
 ---> PID: 1180210
 ---> UID: 1000
 ---> family: 10
 ---> rx_b: 0
 ---> tx_b: 32
 ---> rxPkts: 0
 ---> txPkts: 1
 ---> Command: udpTraffic.sh
 ---> SADDR: 2001:xxx:f0:5e:aaa:a627:f45f:9c0c
 ---> DADDR: 2001:xxx:f0:5e:bbb:8d6f:32ef:6180
 ---> SPT: 42486
 ---> DPT: 53
 ---> EventTime: 1628185427077225859
                ---

Understanding UDP Test Output

family

Address family: 2 = IPv4, 10 = IPv6

rx_b / tx_b

Bytes received and transmitted

rxPkts / txPkts

Number of packets received and sent

DPT

Destination port (53 = DNS, 123 = NTP, etc.)

Generating UDP Test Traffic

# Generate DNS traffic
dig example.com

Unlike TCP, UDP events can be generated for active sockets, not just when they close. You may see multiple events for the same socket as traffic flows.

Test Program Structure

Both test programs follow a similar pattern:

TCP Test (tcpEvent/Test/mainer.c)

// 1. Load library
void *handle = dlopen("/opt/RealTimeKql/lib/libtcpEvent.so", RTLD_LAZY);

// 2. Resolve symbols
void (*AddProbe)(const char *) = dlsym(handle, "AddProbe");
struct tcp_event_t (*DequeuePerfEvent)() = dlsym(handle, "DequeuePerfEvent");
void (*cleanup)() = dlsym(handle, "cleanup");
unsigned (*getStatus)() = dlsym(handle, "getStatus");

// 3. Setup signal handler
signal(SIGINT, signalHandler);

// 4. Attach probe with BPF program
AddProbe(BPF_PROGRAM);

// 5. Wait for initialization
while (!getStatus()) { sleep(1); }

// 6. Event loop
while (1) {
    struct tcp_event_t event = DequeuePerfEvent();
    printEvent(&event);
}

UDP Test (udpEvent/Test/mainer.c)

// Similar structure, but:
// - AddProbe() takes no arguments (BPF program is embedded)
// - Event structure is udp_event_t
// - Includes packet counts (rxPkts, txPkts)

void (*AddProbe)() = dlsym(handle, "AddProbe");
AddProbe();  // No BPF program argument

while (1) {
    struct udp_event_t event = DequeuePerfEvent();
    printEvent(&event);
}

Creating Custom Test Scenarios

You can create custom test scenarios to validate specific behavior:

Testing TCP with Large Transfers

#!/bin/bash
# Start TCP test in background
sudo /tmp/tcpEventTest > tcp_results.log 2>&1 &
TEST_PID=$!

# Wait for initialization
sleep 2

# Download a large file to generate traffic
wget https://releases.ubuntu.com/20.04/ubuntu-20.04.6-live-server-amd64.iso

# Stop test
sudo kill -INT $TEST_PID

# Analyze results
grep "rx_b" tcp_results.log

Testing UDP with DNS Queries

#!/bin/bash
# Start UDP test
sudo /tmp/udpEventTest > udp_results.log 2>&1 &
TEST_PID=$!

sleep 2

# Generate various DNS queries
for domain in google.com microsoft.com github.com example.com; do
    dig $domain
    dig AAAA $domain  # IPv6 query
    sleep 1
done

# Stop and analyze
sudo kill -INT $TEST_PID
grep "DPT: 53" udp_results.log | wc -l

Testing Both Protocols

#!/bin/bash
# Test both TCP and UDP simultaneously
sudo /tmp/tcpEventTest > tcp.log 2>&1 &
TCP_PID=$!

sudo /tmp/udpEventTest > udp.log 2>&1 &
UDP_PID=$!

sleep 2

# Mixed traffic
curl http://example.com &  # TCP
dig example.com &          # UDP
wait

# Cleanup
sleep 2
sudo kill -INT $TCP_PID $UDP_PID

# Compare
echo "TCP events:"
grep -c "PID:" tcp.log
echo "UDP events:"
grep -c "PID:" udp.log

Understanding Test Locations

Source Code Structure

eBPF-Event-Interceptor/
├── tcpEvent/
│   ├── event.cc          # TCP tracer implementation
│   ├── event.h           # TCP API header
│   ├── common.h          # TCP structures
│   ├── CMakeLists.txt
│   └── Test/
│       ├── mainer.c      # TCP test program
│       └── CMakeLists.txt
├── udpEvent/
│   ├── udpTracer.cc      # UDP tracer implementation
│   ├── common.h          # UDP structures
│   ├── CMakeLists.txt
│   └── Test/
│       ├── mainer.c      # UDP test program
│       └── CMakeLists.txt
└── build/
    ├── tcpEvent/
    │   └── Test/
    │       └── tcpEventTest  # Built TCP test
    └── udpEvent/
        └── Test/
            └── udpEventTest  # Built UDP test

Installation Locations

After make install:

Libraries: /opt/RealTimeKql/lib/
- libtcpEvent.so
- libudpEvent.so
Tests: /tmp/
- tcpEventTest
- udpEventTest

Test binaries in /tmp are deleted on reboot. Copy them to a permanent location if needed:

sudo cp /tmp/{tcp,udp}EventTest /usr/local/bin/

Troubleshooting Tests

Test binary not found

Error:

bash: /tmp/tcpEventTest: No such file or directory

Solution: Rebuild with tests enabled:

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

Permission denied

Error:

Operation not permitted

Solution: Run with sudo:

sudo /tmp/tcpEventTest

Library not found

Error:

Failed dlopen
/opt/RealTimeKql/lib/libtcpEvent.so: cannot open shared object file

Solution: Install libraries first:

sudo make install

Or check library path:

ls -l /opt/RealTimeKql/lib/

No events appearing

For TCP:

Events only appear when connections close
Generate test traffic: curl http://example.com
Check if processes are creating connections: ss -t

For UDP:

Events appear for send/receive operations
Generate test traffic: dig example.com
Try IPv6 traffic: dig AAAA example.com

Probe attachment failed

Error in output:

Failed to attach kprobe: ...

Solution:

Check kernel version: uname -r
Ensure kernel headers are installed: sudo apt install linux-headers-$(uname -r)
Verify BCC is working: sudo python3 -c "from bcc import BPF"

Memory leaks or crashes

If tests crash or leak memory:

# Run with valgrind
sudo valgrind --leak-check=full /tmp/tcpEventTest

Check kernel logs:

sudo dmesg | tail -50

Automated Testing

Create an automated test suite:

#!/bin/bash
# test_suite.sh

set -e

echo "=== eBPF Event Interceptor Test Suite ==="

# Build with tests
echo "Building with tests..."
cd build
cmake -DSETUP_TESTS=ON ../ > /dev/null
make -j$(nproc --ignore=1) > /dev/null
sudo make install > /dev/null

# Test TCP
echo "Testing TCP tracer..."
sudo timeout 10 /tmp/tcpEventTest > /tmp/tcp_test.log 2>&1 &
TCP_PID=$!
sleep 2
curl -s http://example.com > /dev/null
sleep 3
sudo kill -INT $TCP_PID 2>/dev/null || true
wait $TCP_PID 2>/dev/null || true

if grep -q "PID:" /tmp/tcp_test.log; then
    echo "✓ TCP test passed"
else
    echo "✗ TCP test failed"
    exit 1
fi

# Test UDP
echo "Testing UDP tracer..."
sudo timeout 10 /tmp/udpEventTest > /tmp/udp_test.log 2>&1 &
UDP_PID=$!
sleep 2
dig example.com > /dev/null
sleep 3
sudo kill -INT $UDP_PID 2>/dev/null || true
wait $UDP_PID 2>/dev/null || true

if grep -q "PID:" /tmp/udp_test.log; then
    echo "✓ UDP test passed"
else
    echo "✗ UDP test failed"
    exit 1
fi

echo "=== All tests passed ==="

Run it:

chmod +x test_suite.sh
./test_suite.sh

Next Steps

TCP Monitoring

Deep dive into TCP monitoring features

UDP Monitoring

Explore UDP monitoring capabilities

Building from Source

Customize and rebuild the interceptor

TCP API Reference

Complete TCP API documentation

Get Started

Core Concepts

Guides

​Building with Tests

​Running TCP Tests

​Starting the Test

​Expected Output

​Understanding TCP Test Output

PID

UID

rx_b

tx_b

tcpi_segs_out

tcpi_segs_in

Command

SPT/DPT

​Generating TCP Test Traffic

​Running UDP Tests

​Starting the Test

​Expected Output

​Understanding UDP Test Output

family

rx_b / tx_b

rxPkts / txPkts

DPT

​Generating UDP Test Traffic

​Test Program Structure

​TCP Test (tcpEvent/Test/mainer.c)

​UDP Test (udpEvent/Test/mainer.c)

​Creating Custom Test Scenarios

​Testing TCP with Large Transfers

​Testing UDP with DNS Queries

​Testing Both Protocols

​Understanding Test Locations

​Source Code Structure

​Installation Locations

​Troubleshooting Tests

​Automated Testing

​Next Steps

TCP Monitoring

UDP Monitoring

Building from Source

TCP API Reference

Build docs developers (and LLMs) love

Building with Tests

Running TCP Tests

Starting the Test

Expected Output

Understanding TCP Test Output

Generating TCP Test Traffic

Running UDP Tests

Starting the Test

Expected Output

Understanding UDP Test Output

Generating UDP Test Traffic

Test Program Structure

TCP Test (tcpEvent/Test/mainer.c)

UDP Test (udpEvent/Test/mainer.c)

Creating Custom Test Scenarios

Testing TCP with Large Transfers

Testing UDP with DNS Queries

Testing Both Protocols

Understanding Test Locations

Source Code Structure

Installation Locations

Troubleshooting Tests

Automated Testing

Next Steps