bpftool is a mirror of the kernel's own BPF command line tool

This repository is a copy, and the copy is the point

The repository description is unusually candid for a project with a release history. It is an automated upstream mirror for a bpftool stand-alone build, and the README says this is the official home for bpftool, with a request to use this GitHub repository for building and packaging bpftool and for using it in projects through git submodule. The authoritative source code of bpftool is developed as part of the bpf-next Linux source tree under the tools/bpf/bpftool subdirectory and is periodically synced to this repository. The practical consequence is that this is where you get a bpftool you can build and ship, not where you develop one. All changes for bpftool should be sent to the BPF mailing list, and the README asks that pull requests are not opened here unless they change GitHub specific components. That is the division of labour in a kernel-adjacent project, and it means the commit history here is a mirror of someone else's decisions rather than a record of discussion.

The sync is semi automated and runs every few weeks

The synchronisation section explains how the mirror stays current. This repository mirrors the bpf-next Linux source tree's tools/bpf/bpftool directory, plus its few dependencies from under kernel/bpf/ and its supporting header files, and some of those header files, the include/linux/*.h files in the current repository, are reduced versions of their counterparts at bpf-next's tools/include/linux to make compilation successful. That reduction is a small but telling detail, because it means the mirror is not byte-identical to upstream and carries local edits to get the standalone build to work. Synchronisation happens every few weeks or so, and because bpftool remains aligned on libbpf's version, its repository tends to follow libbpf's, and when the libbpf repo syncs up with bpf-next, the bpftool repo usually follows within the next few days. The process itself is semi-automated: a script in scripts/sync-kernel.sh cherry-picks, adjusts and commits all changes from bpf-next into a local version of the repository, and then maintainers run that script manually and create a pull request to merge the resulting commits. So the merge history in this repository is a series of cherry-picks rather than an organic development log.

Building is a make in src, and the submodule matters

The build instructions are short. The repository uses libbpf as a submodule, and the recommended clone pulls it in directly:

$ git clone --recurse-submodules https://github.com/libbpf/bpftool.git

If the repository is already cloned, the submodule is initialised from within it with git submodule update --init. The build itself is a make in the src directory, and installation is a make install, with the install line commented out in the documentation so you can see what it would do before running it. Out of tree builds are supported through an OUTPUT variable, so you can point the build somewhere other than the source tree with a directory of your choosing. Most build output is suppressed by default, and passing V=1 gives detailed build logs, which is what you want when a compile is failing on a specific dependency. Additional compilation flags can be passed on the command line, and the example given is a static build with EXTRA_LDFLAGS=-static. The man pages have their own build in the docs directory with its own make and make install, and the repository also carries bash-completion/ for the shell completion.

Dependencies are few, and the optional ones unlock features

The required dependencies are short. libelf, libssl-dev and zlib. The optional ones are more interesting because each one buys a specific capability. libbfd is for dumping JIT-compiled program instructions, which is how you see what the JIT produced rather than the original bytecode. libcap is for better feature probing. Kernel BTF information is needed for profiling programs or showing PIDs of processes referencing BPF objects, and clang/LLVM is for the same purpose. The BTF requirement is the one to understand, because it is not a library you install but data the kernel exposes, and without it the profiling and process reference features simply do not work. The build is Linux only, and the note says so plainly. Building bpftool is only supported on Linux, since the build process relies on Linux-specific headers and tools, and it is not expected to work on macOS or other non-Linux systems.

A container image is provided, and it needs privileges

The Dockerfile at the root produces a container image, and its comments give the usage directly. You build it with a docker build command and run it with docker run passing --privileged and --pid=host, with the example being a bpftool prog invocation. The privileges are not optional decoration. bpftool loads and inspects BPF programs and interacts with the kernel's BPF subsystem, so a container without those capabilities cannot do most of what the tool is for. The image is a two stage build on ubuntu:22.04, where the builder installs build-essential, the libelf, zlib, libcap and libssl development packages, clang, llvm, llvm-dev, lld, binutils-dev and pkg-config, and then builds the tool with a parallel make, and the runtime stage keeps only libelf1, llvm and the binary itself, with the entrypoint set to the bpftool binary directly. The result is a small image that still has the LLVM libraries, which is what the disassembler needs.

Where to ask questions, and the licence choice

The support model is unusually well defined, and for a kernel project it is worth reading before you file anything. All general BPF questions, including kernel functionality, bpftool features and usage, should be sent to the bpf mailing list at [email protected], where the list is monitored by many more people than this repository, and the archives are searchable on lore. The repository's own issues and pull requests should be opened only for components specific to the bpftool mirror repository, such as the synchronisation script or the CI workflows, though the maintainers do use GitHub issues as a generic tracker for bpftool, with the mailing list recommended first. The licence is a dual licence, and the README explains the choice in terms of reuse. This work is dual-licensed under the GNU GPL v2.0, only, license and the BSD 2-clause license, and you can select either of them if you reuse the work, with the SPDX identifier given as GPL-2.0-only OR BSD-2-Clause and the two licence files present in the tree. For a tool you intend to ship in a distribution or vendor into a product, picking BSD-2-Clause is the pragmatic route.

Editorial conclusion

Adopt bpftool from this repository when you want to build a standalone bpftool, package it for your own distribution, or vendor it as a git submodule, and when you need a version that matches a particular kernel. Do not send patches here, since the authoritative source is in the kernel tree and changes belong on the BPF mailing list. Verify first that you are on a Linux system, since the build relies on Linux specific headers and tools, that libelf, libssl-dev and zlib are present, and that the sync between this mirror and bpf-next has not left the copy behind the kernel you are running.

Frequently asked questions

Official sources

1. Issues
2. libbpf/bpftool on GitHub
3. README
4. Releases