Releases: libbpf/bpftool
bpftool v7.5
New features
- Add support for attaching and detaching tcx programs with
bpftool net
, along with relevant documentation and bash completion. (388bca8, 07c984a, 00e7019) - When dumping BTF information, support dumping kfunc prototypes. Users willing to use kfunc no longer have to define the prototypes themselves, then can use the generated header file. This is also convenient to check what kfuncs are available in the running kernel. (3e0251a, 7cbe3da)
- Sort the output from the dump, in C format, of BTF objects. Sorting the output helps applying diff tools on the generated header files, and helps generate a more natural ordering in the header. (0c50be2, 6ffd3af, f333f55)
- Print richer information when dumping
sockmap
links. (bfdb1e5) - In BPF skeletons, auto-attach
struct_ops
BPF maps as part of<skeleton>__attach()
, defineBPF_SKEL_SUPPORTS_MAP_AUTO_ATTACH
accordingly. (5f63dbb, aa95345) - Improvements in libbpf bring the ability to open and work with object files in either endianness for some operations like object linking or light BPF skeleton creation. (libbpf/libbpf@5ae8432d15e7, libbpf/libbpf@628b21dbcd61, libbpf/libbpf@6ac8762ecd1c, libbpf/libbpf@8244006267a5)
Bug fixes
- Bpftool automatically mounts the BPF virtual file system (bpffs) when necessary, for example to pin programs. This bpffs was mounted on the parent directory for the provided path under certain circumstances. Now bpftool mounts the bpffs on the provided path instead, as expected. (54bcb7c)
- When loading programs and trying to pin the maps, attempt to mount the bpffs when the provided path for the maps is not under an existing bpffs already, as bpftool usually does for other similar commands. (6bcdeb8)
- Use
__typeof__()
rather thantypeof()
in BPF skeleton, to improve compatibility with C++. (9fd551e) - Fix cgroup-related queries to avoid trying to dump (inaccessible) Netkit-related information. (1a70a53)
- Fix backward compatibility issue related to
struct_ops
maps handling for BPF skeletons used with older versions of libbpf. (1b935a7) - Fix various build issues, some of them only affecting the GitHub mirror repository:
- Unset
DESTDIR
before passing it to libbpf, to avoid header files to be installed at an unexpected location. (06c61ec) - Fix clang warnings produced by unnecessary library flags in
CFLAGS
. (119fc2c) - Fix make dependencies for vmlinux.h. (5cd336c)
- Fix silent mode detection (
-s
) for descending into bpftool's documentation Makefile in the GitHub mirror repository. With make 4.4+, the test would pass anytime we pass a string containing the letters
to make. (b3d4318) - Define PACKAGE at build time when trying to detect libbfd, in the GitHub mirror repository, to accommodate with some systems expecting the macro to be defined for using bfd.h or dis-asm.h. (bf9e060)
- Always disable unused CLI arguments warning for feature probe in the GitHub mirror repository, to avoid such warnings to make the probe fail. (3be8ac3)
- Unset
- Many trivial improvements to bpftool's documentation and bash completion, such as formatting fixes, typo fixes, or minor clarifications. (0451298, 214eb3e, 4ce420d, e540cc6, 4d5ad13, 05f5422, f09e341, 3f68270)
- Fix typos in error message and usage help message. (0cad6b8, a44a93b)
Other internal changes
- Update internal BPF program to adjust support for BPF links that support
epoll
, when collecting information for process holding information on a link. (820fac6) - Use BTF field iterator when generating minimized BTF. (9204347)
- Add a
.mailmap
file to the GitHub repository. This file is used to map author's names and addresses from Git history to their preferred form (for example, it replaces the previous email address of a given author with their current address when displaying Git logs). It is kept in sync with the one from the kernel for all contributors to bpftool (starting from the creation of the mirror repository). (744e0cd) - Fix an incorrect format specifier used when dumping non-JITed program instructions. (cb035aa)
- Fix undefined behavior caused by shifting into the sign bit, when internally listing program flags to show tc programs attached to each interface. (a0f887b)
- Fix undefined behavior in
qsort(NULL, 0, ...)
when there is no netfilter program to list, reported by UBSan. (37e304d)
Known bugs
- Static builds on Ubuntu 24.04 may fail because of a missing linker flag to add the zstd library. (#152)
Full Changelog: v7.4.0...v7.5.0
bpftool v7.4
Breaking change
- Kernel configuration options related to bpfilter (namely:
CONFIG_BPFILTER
andCONFIG_BPFILTER_UMH
) are no longer checked withbpftool feature probe
, following bpfilter's removal in recent kernels. (e725e62)
New features
The information displayed for BPF links (bpftool link list
) keeps getting enriched:
- Display
uprobe_multi
links. (dd0b761) - Display cookie for perf event link probes. (25df69b)
- Display cookie for
kprobe_multi
links. (4263cc0)
Other features:
-
Generate shadow variables for
struct_ops
maps in program skeletons. Shadow types allow skeleton users to easily access the fields ofstruct_ops
maps at runtime. An example program using shadow types is also added to thebpftool-gen
manual page. (fc0ad76, 579d6b0) -
Mark orphaned programs as such when listing programs. Orphaned programs are programs removed in IRQ context, on their way to be unloaded from kernel memory, but possibly passing through audit hooks. Such programs would only be listed on recent kernels. (5b0a3a4)
-
Recognize
arena
map types (a09e203) and global variables (73a2c7e), and support theaddr_space_cast
instruction in the disassembler for translated programs, used for working with arena maps (c305ebf).
Bug fixes
- In the mirror repository, fix the detection of
clang-bpf-co-re
(for skeletons support) for some clang versions. (515739f) - Displaying PIDs for processes holding references to BPF links when listing links with
bpftool link list
on older kernels broke in v7.3.0, because the internal programpid_iter
would fail to load. Fix the program to ensure thatpid_iter
loads and PIDs are displayed. (3214350) - When loading the internal
pid_iter
program for displaying PIDs of processes holding file descriptors to BPF programs, we would suppress the logs from libbpf. Display them when running bpftool in debug mode (--debug
). (0cb4aaf)
Other internal changes
- Silence build warning from
calloc()
appearing with recent versions of GCC (supporting-Wcalloc-transposed-args
). (c4cc180) - Use POSIX's version of
basename()
for more portability. (6e0d7d0) - Improve bpftool's bootstrap build by skipping compilation for some unnecessary object files (3dc1ac6) and passing more relevant values in
HOST_CFLAGS
andHOST_LDFLAGS
(c1adf4a). This also results in more accurate results when listing features withbpftool version
for the boostrap bpftool binary.
Known bugs
- Command
bpftool cgroup tree
may be broken when running with kernels under v6.1. (#41) - When loading multiple programs with
bpftool prog loadall
and passing a directory name for pinning them that is not located under an existing bpffs, bpftool attempts to mount a new bpffs on the parent of the directory rather than on the directory itself, possibly leading to a portion of the file arborescence to be unexpectedly hidden by the mount. (#100)
Full Changelog: v7.3.0...v7.4.0
bpftool v7.3
We now have a logo for bpftool!
Deprecation
- Keyword
dev
for specifying an interface name to use for program and map offload withbpftool prog load ... dev <ifname>
andbpftool map create ... dev <ifname>
is deprecated. Useoffload_dev
instead. (3270b21) - When loading programs, the type can be inferred from the ELF section name containing the data. Libbpf v1.3.0, used in this release, considers the following
SEC
definitions legacy:SEC("tc")
,SEC("action")
,SEC("classifier")
. Refer to the libbpf release notes for details.
New features
Libbpf v1.3.0 supports the following ELF section definitions for loading programs (refer to the libbpf release notes for details):
SEC("netfilter")
SEC("tc/egress")
SEC("tc/ingress")
SEC("tcx/egress")
SEC("tcx/ingress")
SEC("uprobe.multi")
SEC("uprobe.multi.s")
SEC("uretprobe.multi")
SEC("uretprobe.multi.s")
SEC("cgroup/connect_unix")
SEC("cgroup/sendmsg_unix")
SEC("cgroup/recvmsg_unix")
SEC("cgroup/getpeername_unix")
SEC("cgroup/getsockname_unix")
The objective for the dev
keyword deprecation is to avoid confusion with a new interface-related keyword:
- Support passing an interface name with
xdpmeta_dev <ifname>
for resolving XDP hints kfuncs when loading programs withbpftool prog load
. (3270b21)
The information displayed for BPF links (bpftool link list
) has been enriched:
- Show map IDs along with
struct_ops
links. (d89768b) - Show
target_obj_id
andtarget_btf_id
along with tracing links information. (57fc1ef) - Show details for multi-kprobes links. (b65dc7b)
- Show details for perf event links. (bd2f4d6, 7561b06)
- Show details for netfilter links. (103f441)
- Show details (interface, attach types) for tcx links. (b76b36e)
- Show details (interface) for XDP links. (9f6d353)
- Show details (interface, attach types) for netkit links. (0fcd8de)
- Show the count of missed kprobes for multi-kprobes links and perf event links. (aa4f5fb, 58046e2)
Several new networking program types also get their information displayed with bpftool net list
:
- Print information on netfilter programs. (103f441)
- Print information on tcx programs. (4294230)
- Print information on netkit programs. (d712a3e)
Other features:
- Support the new cgroup UNIX socket attach points for attaching programs with
bpftool prog attach
. These attach points are:connect_unix
,sendmsg_unix
,recvmsg_unix
,getpeername_unix
,getsockname_unix
. (087d22a) - For
struct_ops
, support registering structs in the.struct_ops.link
ELF section (in addition to.struct_ops
), and also create a link for structs in that section. Accept an optional directory path when registeringstruct_ops
(bpftool struct_ops register OBJ [LINK_DIR]
), to indicate where to pin such links. (9d58b65, 6b24c3e) - Dump inner map IDs instead of raw values when dumping maps of maps with
bpftool map dump
. (e552682) - Display kernel module name when relevant for symbols printed as part of a program dump (
bpftool prog dump xlated
). (eb8a15a) - Support LLVM's
v4
instructions in the disassembler. (ad25b69)
Bug fixes
- Fix the long-standing bug (#17) what would prevent from building bpftool with features requiring the use of “skeletons” (
feature-clang-bpf-co-re
compilation option) with kernels older than 5.15 or withoutCONFIG_PERF_EVENTS
set. (1f5829e, 0773871, fc96090, b00d0c5) - On aarch64, when probing features (
bpftool feature probe
), fix the value of the global memory limit for JIT compiler for unprivileged users, which was previously reported as a negative value (expecting anint
instead of along
). (b2489e0) - When passing a directory to pin programs to
bpftool prog loadall
, avoid re-mounting accidentally the bpffs to the parent of that directory. (fb96eed) - Fix a warning (
-Wcast-qual
) that might appear when compiling skeletons generated withbpftool gen
. (24f4661) - When generating skeletons, align on a 8-byte boundary the data retrieved from ELF files to avoid potential alignment issues and errors from libbpf. (e8b7df5, f12f538)
- When printing pointers in JSON, for example as part of a
struct_ops
dump withbpftool -j struct_ops dump
, enquote the pointer address (or(nil)
value) to avoid breaking JSON. (5978b98) - Fix JSON for
struct_ops
dumps from an ID withbpftool -j struct_ops dump id <id>
by wrapping the information for the structs in an array. (b9530de) - Fix a subcommand name (
prog
instead ofprogram
) inbpftool.8
manual page. (fa46ebb) - Fix the interactive help message for
bpftool perf
. (dc53c79)
Known bugs
- Command
bpftool cgroup tree
may be broken when running with kernels under v6.1 (#41).
Full Changelog: v7.2.0...v7.3.0
bpftool v7.2
Breaking change
- When trying to dump the control flow graph (CFG) for a BPF program (
bpftool prog dump xlated <program> visual
), return an error if the user passed one of the--json
or--pretty
options, instead of simply ignoring the option.
New features
- Support printing the C source code (inline annotations), if available, in the CFGs for programs. Also support line numbers and opcodes in the CFGs with the
linum
andopcodes
keywords, just like for regular program dumps. - In the Makefile's feature detection for the mirror repository, output the name, results, and stderr when probing features with
V=1
.
Bug fixes
- Fix linkage with statically built LLVM libraries for the disassembler for JIT-compiled BPF programs. Some flags and libraries were missing.
- With
bpftool prog profile
, profile online CPUs instead of “possible” CPUs, given that some of the latter may not be online and hence not available for profiling. - In BPF-related feature probing, avoid marking kernel config option as not set if the kernel configuration file is not found.
- In the Makefile, add missing quotes to libbpf bootstrap submake variables, to fix use cases where
$(HOSTCC)
is set to/usr/bin/ccache /usr/bin/gcc
, for example. - Fix a bug in the JSON writer, which would produce an escaped line break instead of escaped backslash for a
\
character. - Fix another bug in the JSON writer, about an invalid JSON escape for
\'
. - Fix bug for long instructions (such as loading a 64-bit long immediate into a register) not displayed properly in program CFG dumps.
- Fix documentation about line information display for program dumps: the document hinted that displaying the source line could be turn off, and that the file name would be printed “on top of” the source line, but these indications were not accurate.
- Ignore
$(CFLAGS)
, use$(EXTRA_CFLAGS)
in the Makefile's feature detection framework, thus mirroring the behavior of the kernel version. On top of that, fix feature detection for static builds. - Fix the feature detection system to account for
$(FEATURE_TESTS)
defined in the main Makefile.
Other internal changes
- Add static build instructions for bpftool in the README.md of the mirror repository.
- Use
bpf_{btf,link,map,prog}_get_info_by_fd()
(wrappers aroundbpf_obj_get_info_by_fd()
), to improve type safety in the code, and to help with the Memory Sanitizer. - Always disable stack protection for building BPF programs used by bpftool. If present, as is the default on Gentoo for example, stack protection for the clang toolchain would produce errors when trying to compile the relevant object files, but stack protection is not relevant in the case of BPF programs and it is safe to turn it off.
CI
- Add a release workflow to build and ship static binaries for amd64 and arm64 (and SHA256 sums) on releases (the workflow creates a draft release when tags are pushed, and attaches the assets). Also use this workflow to ship a tarball containing all sources required to compile (bpftool, plus libbpf submodule). Add a script to update GitHub labels for some of these release assets.
- Add a workflow for static builds with both LLVM and libbfd disassemblers. The early version for the LLVM disassembler would include compiling the LLVM libraries and take around 80 minutes to complete, but later we switched to downloading libraries compatible with static linking from LLVM's CI, cutting down the duration for the workflow to about 2 minutes.
- Remove deprecated Ubuntu 18.04 GitHub runner from the CI in the matrix for the build workflow.
- In workflow definitions, add concurrency groups to cancel outdated runs.
- Add path filters to workflow definitions, to avoid running all workflows if some are not relevant for a given Pull Request.
- Add a CI workflow to make sure GitHub mirror commits have valid prefixes (
mirror:
orsync:
orci:
only, so we can easily distinguish them from the commits coming from the kernel repository). - Switch to the Hadolint linter for checking the Dockerfile, and improve the related workflow.
Known bugs
- Some features requiring the use of “skeletons” (
feature-clang-bpf-co-re
compilation option) require kernel 5.15 or more recent, withCONFIG_PERF_EVENTS
set, to compile bpftool (#17). - Command
bpftool cgroup tree
may be broken when running with kernels under v6.1 (#41).
Full Changelog: v7.1.0...v7.2.0
bpftool v7.2.0-snapshot.0
This is a snapshot release, before we reach v7.2.0.
This snapshot was created to validate the release workflow introduced in recent Pull Requests (#84, #85), and to publish statically-compiled binaries for users to pick up.
Changelog: v7.1.0...v7.2.0-snapshot.0
bpftool v7.1
New features
- Add support for disassembling JIT-compiled programs with the LLVM library (instead of libbfd), and switch to LLVM by default. Disassembling with libbfd is still supported as a fallback if the LLVM library is not present when building bpftool. This is to help with packaging, and in response to several API changes from libbfd that we've had to handle.
- Add an
autoattach
feature tobpftool prog (load|loadall)
, to tell bpftool to attach as BPF links some tracing programs immediately after loading them, using the information found in the ELF object file, provided this information is sufficient. - Add support for cgroup local storage, and user ring buffer maps.
- Show parameters of BPF task iterators (
tid
,pid
) when listing them. - Support dumping more information for cgroup iterator links, such as the cgroup ID and the order for walking the cgroup hierarchy.
- Add
boostrap
feature to version output, to tell if thebpftool
binary is a “bootstrap” version (limited in features, used as an intermediary build step for compiling BPF skeletons used by bpftool) or not. - Set binary name in interactive help output to
bpftool
instead ofargv[0]
, for more consistency accross installations (and with other tools like iproute2). - Add a Dockerfile to the current repository to easily run bpftool from a Docker image.
Bug fixes
- When displaying a cgroup tree, with some programs from a sub-cgroup overriding those of a parent cgroup, remove attach flags for those effective sub-cgroup programs, given that these flags do not make sense in that case (they only do for the programs attached to the parent cgroup) .
- Fix a null pointer dereferencing when attempting to pin a BPF object without providing a file name.
- Fix a wrong type cast in the code in charge of dumping BTF objects.
- Fix some error messages that would produce
unknown error
s, when we do in fact know the nature of the error. - Fix a typo in an error message of the disassembler for JIT-compiled programs.
- Fix display of libbfd-related features as detected by the Makefiles of the mirror repository, at build time.
Other internal changes
- Turn asserts in the disassembler for JIT-compiled programs into error handling, for consistency with the rest of the code.
- Enable verbose builds in CI.
- Add CI linters for the synchronisation script and the Dockerfile, clean up issues reported by the linters.
- Add a
README.md
file underscripts/
to explain howsync-kernel.sh
works.
Known bugs
- Some features requiring the use of “skeletons” (
feature-clang-bpf-co-re
compilation option) require kernel 5.15 or more recent, withCONFIG_PERF_EVENTS
set, to compile bpftool (#17). - Command
bpftool cgroup tree
may be broken when running with kernels under v6.1 (#41).
Full Changelog: v7.0.0...v7.1.0.
bpftool v7.0
Note
Bpftool's version number is aligned on libbpf's version number (with an offset). The change of major version number for the current release reflects libbpf's bump (v1.0.0), but is not necessarily synonym of breaking changes in bpftool - although we do have one in this release.
Breaking change
- Given that bpftool now relies on libbpf to provide the string names for various BPF objects, the names of cgroup attach types as displayed with
bpftool cgroup show
may have changed. The former names were defined in bpftool here, now they come from libbpf, here.
New features
- Implement
bpftool cgroup tree
forBPF_LSM_CGROUP
- Use strings provided by libbpf for program types, map types, attach types, link types, instead of redefining them in bpftool, including for parsing these types from the command line
- Add
bpftool feature list_builtins
to list program, map, attach, or link types known to libbpf (but independent from what the system supports), to allow iterating on these types in scripts, and use this in bash completion - Support passing longer strings for referencing programs by name on the command line, now that the kernel can use longer names with BTF
- Add support for
BTF_KIND_ENUM64
in BTF - Add support for
BTF_KIND_RESTRICT
forbpftool gen min_core_btf
- Support
BPF_CORE_TYPE_MATCHES
relocations, forbpftool gen min_core_btf
- Indicate that a pinned object is a BPF link (when relevant) instead of “unknown” when passing a pinned path to an incorrect object type on the command line
Bug fixes
- Fix compilation with libbfd 2.39 and newer, following a change of interface of the function used to initialise the context for the disassembler and which needs an additional printer for styled output
- Fix
feature-libbfd-liberty-z
detection in the mirror's Makefile - Fix bootstrap for cross-compilation, by passing down the host
ar
to libbpf's Makefile - Clean
errno
at the beginning of the program execution to clean up after the checks performed by libcap < 2.63 and avoid breaking the batch mode - Check for
NULL
pointer incodegen_asserts()
to avoid aNULL
pointer dereference on skeleton generation - Revert the switch to libbpf's API to lift the memlock rlimit restriction, as detection for cgroup-based memory accounting would fail in some corner cases, and implement instead a more thorough probe in bpftool to check whether we need to lift the rlimit
- Do not return value from void function in skeleton, which would produce a warning
Other internal changes
- Remove zlib feature test from Makefile
- Do not print the result of the
disassembler-four-args
feature test when building bpftool - Replace the use of multiple
sizeof()
byARRAY_SIZE()
on the array of metrics in prog.c - Remove outdated
attach_type_name
forward declaration in main.h - Fix a typo in a comment, which would reference the wrong library (libpcap/libcap)
- CI: Build on several runners (Ubuntu 18.04, 20.04, 22.04)
- README.md: Fix a broken link
Known bugs
- Some features requiring the use of “skeletons” (
feature-clang-bpf-co-re
compilation option) require kernel 5.15 or more recent, withCONFIG_PERF_EVENTS
set, to compile bpftool (#17). - Map dumps with BTF information may print erroneous values for
bool
fields inside of a struct (#38).
Full Changelog: v6.8.0...v7.0.0
bpftool v6.8
New features
- Implement
bpftool gen min_core_btf
to generate the minimal BTF file necessary to load a program - Add C++-specific skeleton wrappers
- Restore support for probing BPF features on hardware (such as Netronome SmartNICs)
- Add
bpf_cookie
tobpftool link
output - Add support for generating sub-skeletons for “incomplete” BPF object files
- Defaults to sysfs vmlinux when dumping BTF objects and no base BTF was specified
- Extend skeletons for LSM programs to create links
- Add name for
trace_kprobe_multi
attach type - Add name for
syscall
program types - Add names for
xdp
,perf_event
,kprobe_multi
link types - Add distinction, for feature probes, between reversible or permanent disabling of
bpf()
syscall for unprivileged users - Handle better the probing of BPF helpers for programs types that are not available
- Assert type sizes in BPF skeletons
- Expand autogeneration warnings in skeletons by mentioning bpftool
Bug fixes
- Fix error when looking up for keys in map with no associated BTF information
- Fix pretty-print dump for maps with no associated BTF information
- Fix formatting of
bytes_memlock
for JSON map listing - Show process PIDs for BPF maps even if there is no associated BTF id or the map is frozen
- Add the description of missing commands in the top-level
bpftool.8
man page - Handle
libbpf_probe_prog_type()
andlibbpf_probe_bpf_helper()
errors correctly in feature probing
Other internal changes
- Switch to libbpf's API to lift the rlimit restriction, on legacy systems without memcg-based memory accounting for BPF
- Replace the use of libc's
reallocarray()
with the implementation from libbpf - Remove redundant slashes in Makefile
Known bugs
- Some features requiring the use of “skeletons” (
feature-clang-bpf-co-re
compilation option) require kernel 5.15 or more recent, withCONFIG_PERF_EVENTS
set, to compile bpftool (#17).
Full Changelog: v6.7.0...v6.8.0
bpftool v6.7
First tagged release in the mirror repository.
The history for the sources of bpftool so far can be found in Linux kernel's Git history.