Repository files navigation

This is the official home for bpftool.Please use this Github repository forbuilding and packaging bpftool and when using it in your projects through Gitsubmodule.

Theauthoritative source code of bpftool is developed as part of thebpf-next Linux source tree underthetools/bpf/bpftoolsubdirectory and is periodically synced tohttps://github.com/libbpf/bpftool on Github. As such, all changes for bpftoolshould be sent to theBPF mailing list,please don't open PRshere unless you are changing some Github-specific components.

Check outthe manual pages for documentation about bpftool. A number ofexample invocations are also displayed inthis blogpost.

All general BPF questions, including kernel functionality, bpftool features andusage, should be sent tobpf@vger.kernel.org mailing list. You can subscribe toithere and search its archiveshere.

The mailing list is monitored by many more people than this repo and they willhappily try to help you with whatever issue you encounter. This repository'sPRs and issues should be opened only for dealing with issues related tocomponents specific to the bpftool mirror repository (such as thesynchronization script or the CI workflows). The project maintainers also useGitHub issues as a generic tracker for bpftool, but issues should first bereported on the mailing list nonetheless.

Required:

• libelf
• zlib

Optional:

• libbfd (for dumping JIT-compiled program instructions)
• libcap (for better feature probing)
• kernel BTF information (for profiling programs or showing PIDs of processesreferencing BPF objects)
• clang/LLVM (idem)

This repository uses libbpf as a submodule. You can initialize it when cloningbpftool:

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

Alternatively, if you have already cloned the repository, you can initializethe submodule by running the following command from within the repository:

$git submodule update --init

To build bpftool:

$cd src$make

To build and install bpftool on the system:

$cd src#make install

Building bpftool in a separate directory is supported via theOUTPUT variable:

$mkdir /tmp/bpftool$cd src$OUTPUT=/tmp/bpftool make

Most of the output is suppressed by default, but detailed building logs can bedisplayed by passingV=1:

$cd src$make V=1

Additional compilation flags can be passed to the command line if required. Forexample, we can create a static build with the following commands:

$cd src$EXTRA_LDFLAGS=-static make

Note that to use the LLVM disassembler with static builds, we need a staticversion of the LLVM library installed on the system:

1. Download a precompiled LLVM release or build it locally.

   • Download the appropriaterelease of LLVM for yourplatform, for example on x86_64 with LLVM 15.0.0:

     $curl -LO https://github.com/llvm/llvm-project/releases/download/llvmorg-15.0.0/clang+llvm-15.0.0-x86_64-linux-gnu-rhel-8.4.tar.xz$tar xvf clang+llvm-15.0.0-x86_64-linux-gnu-rhel-8.4.tar.xz$mv clang+llvm-15.0.0-x86_64-linux-gnu-rhel-8.4 llvm_build

   • Alternatively, clone and build the LLVM libraries locally.

     $git clone https://github.com/llvm/llvm-project.git$mkdir llvm_build$cmake -S llvm-project/llvm -B llvm_build -DCMAKE_BUILD_TYPE=Release$make -j -C llvm_build llvm-config llvm-libraries

2. Build bpftool withEXTRA_LDFLAGS set to-static, and by passing thepath to the relevantllvm-config.

   $cd bpftool$LLVM_CONFIG=../../llvm_build/bin/llvm-config EXTRA_LDFLAGS=-static make -j -C src

The man pages for bpftool can be built with:

$cd docs$make

They can be installed on the system with:

$cd docs#make install

This repository mirrorsbpf-next Linux source tree'stools/bpf/bpftool directory, plus its few dependenciesfrom underkernel/bpf/, and its supporting header files. Some of these headerfiles,include/linux/*.h on the current repository, are reduced versions oftheir counterpart files atbpf-next'stools/include/linux/*.h tomake compilation successful.

Synchronization between the two repositories happens every few weeks or so.Given that bpftool remains aligned on libbpf's version, its repository tends tofollow libbpf's. When the libbpf repo syncs up with bpf-next, bpftool's repousually follows within the next few days.

The synchronization process is semi-automated: the script inscripts/sync-kernel.sh cherry-picks, adjusts and commits all changes frombpf-next to a local version of the bpftool repository. However, maintainersrun this script manually and then create a pull request to merge the resultingcommits.

Take a look atthe script for the technical details of the process. See also the documentation inthe accompanying README.md

This work is dual-licensed under the GNU GPL v2.0 (only) license and the BSD2-clause license. You can select either of them if you reuse this work.

SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)