bpftool

List information about loaded eBPF programs

$ bpftool prog list

$ bpftool net list

$ bpftool link list

$ bpftool perf list

$ bpftool btf list

$ bpftool map list

$ bpftool feature probe dev [eth0]

$ bpftool batch file [myfile]

bpftool object command [options]
bpftool help
bpftool version

object
    Specifies the type of BPF object to interact with. Common objects include:
prog: BPF programs loaded into the kernel.
map: BPF maps, used for data sharing between programs and user space.
link: BPF links, connecting programs to specific events or data sources.
btf: BPF Type Format data, providing rich type information for BPF objects.
feature: Queries the kernel's BPF capabilities and supported features.
cgroup: Commands related to BPF programs attached to cgroups.
perf: Commands for BPF perf event integration.
net: Network-related BPF commands.
gen: BPF code generation and conversion utilities.
struct_ops: BPF struct operations.
iter: BPF iterators for kernel state introspection.

command
    Specifies the action to perform on the BPF object. Commands vary by object type but commonly include:
list: Enumerate all objects of a given type.
show: Display detailed information about a specific object (by ID, name, tag, or path).
dump: (For prog) Output the bytecode of a BPF program.
pin: Pin an object to the BPF filesystem (bpffs) for persistent access or identification.
getnext: Retrieve the ID of the next object in a sequence.
update: (For map) Add or update entries in a BPF map.
lookup: (For map) Retrieve specific entries from a BPF map.
delete: (For map) Remove entries from a BPF map.

[options]
    General or object/command-specific options that modify behavior. Some frequently used options include:
-f, --json: Output information in JSON format.
-p, --pretty: Pretty-print JSON output for readability.
-V, --version: Display the bpftool version.
-h, --help: Show help message for a specific object or command.
id ID: Specify an object using its kernel-assigned ID.
tag TAG: Specify a program using its unique tag.
name NAME: Specify an object using its assigned name.
pinned PATH: Specify an object by its path on the BPF filesystem.
force: Force an operation that might otherwise fail (e.g., overwriting a pinned file).
-m, --map-path: Specify the path to a map file.

bpftool is a powerful command-line utility for interacting with eBPF (extended Berkeley Packet Filter) programs and maps within the Linux kernel. It serves as an essential tool for developers and administrators working with BPF, allowing them to inspect, debug, and manage BPF objects directly.

The utility provides various sub-commands to list and show details about loaded BPF programs, BPF maps, BPF links, BTF (BPF Type Format) data, and more. It can dump bytecode, retrieve map entries, pin objects to the BPF filesystem (bpffs) for persistence, and query kernel BPF features.

bpftool is indispensable for understanding the runtime state of BPF applications, verifying program behavior, and automating BPF object management.

Most operations performed by bpftool require root privileges because they involve direct interaction with the Linux kernel's BPF subsystem.
The exact set of available commands and options, as well as their behavior, can depend significantly on the Linux kernel version. Newer kernels typically introduce more BPF features and thus more bpftool capabilities.
Incorrect usage of bpftool, especially when modifying BPF maps or programs, can lead to system instability or security vulnerabilities.

A fundamental concept for advanced bpftool usage is the BPF filesystem, typically mounted at /sys/fs/bpf. This pseudo-filesystem allows BPF objects (programs, maps, links) to be 'pinned' or named and made persistent. Pinning objects enables them to be accessed by path across different user-space applications or even after the application that created them exits, which is crucial for building complex and robust BPF-driven systems.

bpftool's support for JSON output (using the -f or --json options, optionally with -p or --pretty) is a key feature for automation. This structured output format makes it straightforward to parse bpftool's results with scripting languages like Python or Bash, enabling seamless integration into monitoring tools, CI/CD pipelines, and automated debugging workflows for BPF applications.

The history of bpftool is inextricably linked to the rapid evolution of eBPF. While BPF originated as a simple packet filter in the early 1990s, the 'extended' BPF (eBPF) was introduced into the Linux kernel (version 3.18, in 2014) primarily by Alexei Starovoitov. This extension dramatically broadened BPF's scope beyond networking to encompass system tracing, security, observability, and more.

As eBPF's capabilities grew, a dedicated and robust user-space utility became essential for inspecting, managing, and debugging the kernel's BPF objects. bpftool was developed to fulfill this role and is distributed as part of the Linux kernel source tree itself (under tools/bpf/bpftool). Its development closely tracks new BPF features in the kernel, ensuring it remains the authoritative and feature-rich interface for eBPF developers and administrators.

bpf(2), mount(8), ip-link(8), perf(1), tc(8), lsmod(8)