xdp-tools, the libxdp library and the tools built on it

A library and the tools that justify it

The xdp-tools repository contains the libxdp library for working with the eXpress Data Path facility of the Linux kernel, and a collection of utilities and example code that uses the library.

That structure is the point. libxdp is the piece that does the real work of loading and managing XDP programs, and the seven tools are both useful in their own right and worked examples of how to use the library. The library itself can be built on its own, with make libxdp, which matters if you want to link against it rather than install the command line tools.

XDP itself is the kernel facility that lets a program run at the earliest point in the packet path, before the stack has done work the program does not need. The README points readers who want a general introduction to the XDP tutorial, and to the bpf-examples repository for more BPF and XDP examples.

The project is C, the primary language of the repository, and the tree shows a conventional GNU-style layout with a top level Makefile, a configure script, a version.mk, a mkarchive.sh script, a headers/ directory, a lib/ directory and one directory per utility. There is also a .clang-format file, so the formatting is enforced by tooling rather than by convention, and a LICENSES/ directory alongside the LICENSE file, which is the usual pattern for a project that needs to record per-file licensing.

Seven utilities, each in its own directory

The utilities cover the ground you would expect from a toolbox around a kernel facility.

xdp-loader is a command-line utility for loading XDP programs using libxdp, which is the entry point for everything else. xdp-dump is a tcpdump-like tool for capturing packets at the XDP layer, which is the one people reach for when they want to see what an XDP program sees rather than what the stack sees. xdp-filter is a simple packet filtering utility powered by XDP, and xdp-forward is an XDP forwarding plane, which is where XDP earned its reputation as a way to move packets in and out of a box with minimal per-packet overhead.

The remaining three are measurement and diagnostic tools. xdp-bench is an XDP benchmarking tool. xdp-monitor is a simple XDP tracepoint monitoring tool, which is how you watch what a program is doing without attaching a debugger. xdp-trafficgen is an XDP-based packet generator, the companion to xdp-forward for testing.

Two supporting directories matter as much as the tools. headers/xdp/ holds reusable eBPF code snippets for XDP, installed into /usr/include/xdp by make install, so a program written against them can be compiled outside this tree. lib/util/ holds the common code shared between the different utilities.

The packaging/ directory holds the files used for distro packaging, and lib/libbpf/ is a git submodule with the libbpf project, used when the system version is not recent enough.

Configure, then make, and the libbpf question

The build is a configure step followed by a plain make. The README is brief about it:

./configure
make

What configure produces is config.mk, and the top level Makefile includes both version.mk and config.mk, so the configuration is a generated make fragment rather than a separate build system.

The dependency to get right is libbpf. You need either a sufficiently recent libbpf installed on your system, or the bundled git submodule, which is initialised with:

git submodule init && git submodule update

The build actually checks this. There is a check_submodule target that inspects the submodule status and prints a warning if the submodule SHA-1 is out of sync, telling you to consider running git submodule update. That check runs as a prerequisite of the lib and clean targets, so an out-of-date submodule produces a warning at the start of a build rather than a mysterious link error later.

The make targets are the standard set. The help target prints them: all to build the binaries, clean to remove build products, distclean to remove configuration and the build, install and uninstall, test to run the test suite, and archive to create a tarball of all the sources. There is also a V argument, V=1 for build verbosity, since the default build silences the directory printing.

Five of the seven tools need bpftool

The Makefile decides what to build based on whether bpftool is present. The core list is UTILS := xdp-filter xdp-loader xdp-dump, and then the remaining four are added only when BPFTOOL is not empty:

ifneq ($(BPFTOOL),)
UTILS += xdp-bench xdp-forward xdp-monitor xdp-trafficgen
endif

So xdp-bench, xdp-forward, xdp-monitor and xdp-trafficgen are conditional on the build finding bpftool, and xdp-filter, xdp-loader and xdp-dump are not.

That is a sensible division rather than an arbitrary one. The loader, the dumper and the filter are the tools you need to work with XDP programs on a machine, while the benchmark, the forwarding plane, the monitor and the traffic generator exist to exercise programs and are therefore more demanding to build and to use.

The practical consequence is that a build on a machine without bpftool succeeds and quietly produces three binaries instead of seven. Nothing warns you about the four that are missing beyond their absence, so if you need the forwarding plane or the traffic generator, check for bpftool before you build rather than after.

The subdirectory structure follows the same split. lib is always built, and each utility directory is built from the top level, with the library as its prerequisite.

What XDP gives you and where this repository stops

The value of the tools is that they work at the XDP layer rather than at the packet socket layer. A program attached to an interface through XDP sees the packet as the driver hands it over, which is earlier than the point at which a conventional capture tool sees it, and earlier than the stack processing that most filtering and routing software depends on.

That is the reason xdp-dump exists separately from a general capture tool, and the reason xdp-forward is a separate program rather than a rule in a firewall. The whole point of the design is to let a program drop, pass or redirect packets with as little work per packet as the hardware allows.

Where the repository stops is the boundary of a userspace toolkit. It does not implement the kernel facility itself, it does not replace the kernel's BPF verifier, and it does not ship an XDP program library for general use beyond the reusable snippets in headers/xdp/. It is a way to load, observe, test and drive XDP programs.

The practical limits follow from that. Everything here needs a kernel with XDP support and the privileges to attach a program to an interface, which in practice means root or CAP_NET_ADMIN, and the debugging story depends on tracepoints and the tracepoint monitoring tool rather than on a source-level debugger.

The release history shows steady work rather than a burst: v1.6.1, v1.6.2 and v1.6.3 in February and March 2026, with the last push to the repository on 2026-10-14.

Where libbpf or the kernel tools fit instead

There are two alternatives, and they sit at different levels.

The first is libbpf itself, which is the userspace library for loading BPF programs. xdp-tools bundles it as a submodule precisely so that it does not have to depend on the system version, and the build lets you choose. If you are writing your own XDP application in C or another language, linking libbpf directly is usually the answer, and xdp-tools becomes a source of examples rather than a dependency. The library directory in this repository is for the case where you want the XDP-specific handling libxdp adds on top of plain libbpf.

The second alternative is the ordinary packet capture path. For most troubleshooting, a mature, widely documented capture tool is the better choice, because it handles the things xdp-dump does not try to handle: name resolution, protocol decoding into human-readable output, writing pcap files that other tools can read, and filtering with a familiar expression language. xdp-dump is a tcpdump-like tool, and the README describes it in exactly those terms, which is a hint about how deep its feature set goes.

So the decision is about what layer your question lives at. If you need to know what your XDP program sees, use xdp-dump. If you need to know what the machine received, use a conventional capture tool. If you are building your own XDP program, use libxdp or libbpf and take the examples from headers/xdp/.

Editorial conclusion

xdp-tools suits a kernel or network engineer who needs to load XDP programs, watch what they do and generate traffic against them, and who wants a C library to build their own tool on. It does not suit a general packet analyst, since the capture tool competes with mature, widely documented alternatives. Before you build it, decide whether you want the system libbpf or the bundled submodule, because the build picks one, and note that five of the seven utilities only build when bpftool is found, so an incomplete checkout silently produces a smaller set of binaries.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. xdp-project/xdp-tools on GitHub