Skip to content

README.md

Latest commit

 

History

History
274 lines (205 loc) · 7.71 KB

README.md

File metadata and controls

274 lines (205 loc) · 7.71 KB

TCP Connection Tracker (eBPF/XDP)

Platform Language eBPF Course

Table of Contents

Overview

This repository contains a simplified connection tracker implemented with eBPF/XDP for the Network Computing (2024/2025) course at the Politecnico di Milano.

The tracker inspects packets at XDP hook, keeps per-flow state in BPF maps, and decides whether to forward or drop traffic based on protocol state and policy rules.

Project origin and attribution

This project is based on the course template provided in the Network Computing labs repository:

This repository contains custom modifications and extensions made for project submission.

Assignment context

The project requirements ask:

  1. Understand the TCP state machine logic.
  2. Identify bugs/inconsistencies in state transitions and flags.
  3. Improve the state machine.
  4. Extend support for missing scenarios (example: RST handling).
  5. Suggest potential enhancements (example: connection timeout).
  6. Optionally extend tracking to UDP flows.

Implemented features

TCP conntrack improvements

  • Stricter TCP control-flag validation (SYN-only / SYN+ACK / ACK checks).
  • Handshake transition fixes using correct ACK expectations.
  • Improved close-path handling with additional states:
    • CLOSE_WAIT
    • CLOSING
  • Direction-aware close behavior using finInitiator metadata.
  • Better invalid-transition rejection.

Missing-scenario coverage

  • Explicit RST handling:
    • in-flow RST tears down the flow entry,
    • unsolicited RST is treated as invalid.
  • Lazy timeout expiration: expired entries are evicted on lookup.

Optional protocol extensions

  • UDP flow tracking (NEW $\to$ ESTABLISHED based on bidirectional traffic).
  • ICMP policy support (IPv4 echo request/reply tracking).
  • IPv6 policy support (pass/drop policy mode, currently pass-through by default).

Parser reliability fixes

  • Correct L4 offset calculation with VLAN/IPv4 options.
  • Host-order conversion for ports/seq/ack fields.

Repository structure

  • ebpf/conntrack.bpf.c: main XDP conntrack program.
  • ebpf/conntrack_parser.h: packet parser.
  • ebpf/conntrack_structs.h: shared state structs and enums.
  • ebpf/conntrack_common.h: constants, timeouts, policy switches.
  • conntrack.c: userspace loader for conntrack XDP program.
  • xdp_loader.c: helper loader used by topology script.
  • create-topo.sh: lab namespace/veth setup.
  • docs/main.tex: project report (LaTeX).

Platform requirements

Operating system

  • Linux only (XDP/eBPF requires Linux kernel support).

Kernel and privileges

  • Kernel with eBPF + XDP enabled.
  • Root privileges (sudo) to:
    • create namespaces/veth,
    • attach XDP programs,
    • configure interfaces.

Toolchain and runtime dependencies

Typical required packages (Debian/Ubuntu):

sudo apt install clang \
                 llvm \
                 libelf-dev \
                 libpcap-dev \
                 gcc-multilib \
                 build-essential \
                 linux-headers-$(uname -r) \
                 linux-tools-common \
                 linux-tools-generic \
                 tcpdump

The build also uses lab libraries under ../libs/ (libbpf, bpftool, libargparse, etc.), expected by this repository layout. They can be found in the Course Labs Repository: @Polimi-NetClasses/058172-network-computing-labs/ebpf-labs/libs.

Build

From project root:

make

If build fails with missing libelf/libnl, install the corresponding development packages listed above and rebuild.

Topology setup

Create the test topology (2 namespaces, veth pairs, ARP entries, helper XDP loaders):

./create-topo.sh

This script creates:

  • ns1 with veth1_ and IP 10.0.0.1/24
  • ns2 with veth2_ and IP 10.0.0.2/24
  • root-side peers veth1 and veth2

Run conntrack program

Attach conntrack XDP program on root-side interfaces:

sudo ./conntrack -1 veth1 -2 veth2 -l 5

Where:

  • -1 first interface in root namespace
  • -2 second interface in root namespace
  • -l log verbosity (0..5)

Functional testing

1) Valid TCP forwarding

Server:

sudo ip netns exec ns2 nc -lv 12345

Client:

sudo ip netns exec ns1 nc 10.0.0.2 12345

Type text from one side and verify reception on the other side.

2) Invalid TCP transitions (should be dropped)

ACK-first test:

sudo ip netns exec ns1 hping3 -A -p 12345 -c 1 10.0.0.2

SYN+ACK-first test:

sudo ip netns exec ns1 hping3 -S -A -p 12345 -c 1 10.0.0.2

Expected: no valid response / packets dropped.

3) RST teardown/reconnect

  • Open TCP session with nc.
  • Interrupt client (Ctrl+C).
  • Reconnect immediately.

Expected: reconnect succeeds without stale-state issues.

4) UDP tracking

Receiver:

sudo ip netns exec ns2 socat -u UDP-RECVFROM:9999,fork -

Sender:

sudo ip netns exec ns1 sh -c 'echo hello-udp | socat - UDP:10.0.0.2:9999'

Expected: datagram delivered.

5) IPv6 policy pass-through

Configure addresses:

sudo ip -n ns1 -6 addr add fd00::1/64 dev veth1_
sudo ip -n ns2 -6 addr add fd00::2/64 dev veth2_

Test:

sudo ip netns exec ns1 ping6 -c 2 fd00::2

Expected: success when IPv6 pass policy is enabled.

Policy switches

Policy and timeout constants are in ebpf/conntrack_common.h.

Relevant switches:

  • POLICY_IPV6_PASS
    • 1: pass IPv6 traffic (untracked)
    • 0: drop IPv6 traffic
  • POLICY_ICMP_TRACK
    • 1: apply ICMP echo tracking policy
    • 0: treat ICMP as invalid in conntrack path

Timeouts can be tuned via:

  • TCP_*
  • UDP_*
  • ICMP_TIMEOUT

Cleanup

If needed, remove topology manually:

sudo ip link del veth1 2>/dev/null || true
sudo ip link del veth2 2>/dev/null || true
sudo ip netns del ns1 2>/dev/null || true
sudo ip netns del ns2 2>/dev/null || true

Known limitations and disclaimer

  • This is a student project delivery, not production software.
  • It may contain logic bugs, edge-case gaps, and incomplete protocol coverage.
  • IPv6 is currently policy-based pass/drop, not full IPv6 conntrack.
  • ICMP handling focuses on echo request/reply policy behavior.
  • Validation has been performed on the lab topology and common test cases, not exhaustive real-world workloads.

Report

The accompanying report is in:

  • docs/main.tex
  • compiled output: docs/main.pdf