eBPF技术正在重塑Linux系统的可观测性与网络处理方式，但在Ubuntu上开发和部署eBPF程序时，调试环节往往是开发者最容易卡住的地方。程序加载失败、映射数据异常、挂载点不生效等问题频繁出现，而内核态代码又无法像用户态程序那样直接打断点单步调试。这时候，bpftool就成了连接开发者与内核BPF子系统之间最重要的桥梁。它由内核源码树直接维护，能够以用户态命令行的方式与BPF系统调用交互，查看当前系统中所有BPF程序的运行状态。
本文将围绕bpftool在Ubuntu上的实际使用场景，从安装配置、程序检查、映射操作到进阶调试技巧，系统性地讲解如何利用这个工具完成日常的eBPF调试工作。无论你是刚接触eBPF的初学者，还是已经有一定开发经验但苦于调试手段匮乏的工程师，都能从中找到可直接复用的操作方法。
一、bpftool的安装与基础环境准备
在Ubuntu上使用bpftool，首先需要区分两种安装方式。第一种是通过系统包管理器直接安装，这种方式最简单但版本可能滞后。Ubuntu 22.04及更高版本的官方仓库中已经包含了bpftool的独立软件包，可以直接通过apt命令安装。第二种方式是从内核源码编译，这种方式能确保bpftool版本与当前运行内核完全匹配，功能也最为完整。
对于大多数日常调试场景，推荐先使用包管理器安装，快速验证基本功能是否满足需求。打开终端执行以下命令即可完成安装：
sudo apt update sudo apt install linux-tools-common linux-tools-generic bpftool version
安装完成后，执行bpftool version命令应当输出工具版本号和使用的库信息。如果提示找不到命令，或者出现版本不匹配的警告，说明系统可能安装了错误架构的linux-tools包。此时需要确认当前内核版本，使用uname -r查看，然后安装对应版本的linux-tools包。例如内核版本为5.15.0-91-generic，则需要安装linux-tools-5.15.0-91-generic。
当包管理器安装的版本无法满足需求时，比如需要查看某些新特性或修复了特定bug的bpftool，就需要从源码编译。首先安装编译依赖：
sudo apt install build-essential libelf-dev libbfd-dev libcap-dev \
binutils-dev pkg-config
# 获取内核源码（以当前内核为例）
apt source linux-image-$(uname -r)
cd linux-*/tools/bpf/bpftool
make
sudo make install
从源码编译安装的bpftool通常位于/usr/local/bin/bpftool，可以通过which bpftool确认实际使用的路径。编译过程中如果遇到找不到头文件的错误，通常是linux-headers包未安装，执行sudo apt install linux-headers-$(uname -r)即可解决。安装完成后，建议执行几个基础命令验证功能是否正常，例如bpftool prog show列出当前系统中已加载的所有BPF程序，如果系统能够正常输出程序列表（即使为空），说明bpftool已经可以正常与内核BPF子系统通信。
还需要注意权限问题。BPF系统调用需要CAP_SYS_ADMIN或CAP_BPF能力，普通用户直接运行bpftool可能会遇到权限拒绝的错误。在生产环境中，建议通过sudo执行，或者为特定用户配置相应的capabilities。在Ubuntu上，如果启用了unprivileged BPF disabled内核参数（可通过cat /proc/sys/kernel/unprivileged_bpf_disabled查看），非root用户将无法加载BPF程序，但查看操作在部分版本中仍然允许。
二、使用bpftool检查BPF程序与映射状态
bpftool最核心的功能之一是查看系统中已加载的BPF程序。当你的eBPF程序加载后行为不符合预期，第一步就是确认程序是否真正加载成功、挂载到了正确的位置。使用bpftool prog show命令可以列出所有已加载的BPF程序，输出信息包括程序ID、类型、名称、 attached设备或挂载点等关键字段。
sudo bpftool prog show # 典型输出示例： # 123: kprobe name my_probe_func tag a1b2c3d4e5f6g7h8 gpl # loaded_at 2024-01-15T10:30:00+0000 uid 0 # xlated 128 insns (1024 bytes) jited 76 insns (608 bytes) memlock 4096B # btf_id 456 # pids my_app(7890)
上述输出中，几个字段需要特别关注。name是程序在C代码中定义的函数名，如果这里显示为空或与预期不符，说明程序可能没有正确编译或加载了错误的版本。tag是程序字节码的哈希值，可用于验证加载的程序是否与你编译的版本一致。pids字段显示了哪些用户态进程关联了这个BPF程序，如果程序加载后行为异常，检查这个字段可以确认是否有意外的进程在操作该程序。xlated和jited分别表示BPF指令经过验证器翻译后的指令数和JIT编译后的机器码指令数，如果JIT未启用，jited字段会显示为0，这可能导致性能问题。
如果需要查看某个具体程序的详细信息，包括完整的反汇编字节码，可以使用bpftool prog dump xlated id <ID>命令。这个命令会输出BPF指令的文本表示形式，每条指令包含操作码、寄存器操作数和立即数。对于调试程序逻辑错误非常有用，特别是当你怀疑编译器优化或验证器修改了你的原始逻辑时：
sudo bpftool prog dump xlated id 123 # 输出示例： // 0: (bf) r6 = r1 // 1: (61) r0 = *(u64 *)(r6 +0) // 2: (15) if r0 == 0x0 goto pc+3 // 3: (b7) r0 = 1 // 4: (95) exit
除了程序本身，BPF映射（map）是eBPF程序与用户态之间交换数据的核心机制。当程序逻辑看起来正确但数据传递出现问题时，检查映射内容是排查的关键步骤。使用bpftool map show可以列出所有映射的基本信息，包括映射ID、名称、类型、键值大小和条目数。要查看某个映射中存储的实际数据，使用bpftool map dump id <MAP_ID>命令，它会遍历映射中的所有键值对并输出。对于哈希映射和数组映射，输出格式会自动适配。如果映射中存储的是结构体数据，bpftool还能结合BTF信息以更友好的格式展示字段名称和值，前提是程序加载时附带了BTF调试信息。
在实际调试中，一个常见的需求是实时监控映射数据的变化。虽然bpftool本身不支持类似watch命令的持续刷新功能，但可以结合shell的循环来实现。例如，每隔一秒查看一次映射内容的变化：
while true; do
clear
sudo bpftool map dump id 456
sleep 1
done
这种方式虽然简单，但在排查事件触发型问题时非常实用。当映射中的数据突然变化或出现异常值时，你可以结合系统日志和应用日志来定位触发条件。需要注意的是，频繁读取映射内容在高并发场景下可能对性能产生影响，建议在非生产环境或低负载时段使用。
三、进阶调试技巧：结合内核日志与BTF信息定位问题
当基本的程序检查和映射查看无法定位问题时，需要借助更深层次的调试手段。eBPF验证器在加载程序时会进行严格的安全检查，如果程序被拒绝加载，验证器的日志是排查问题的第一手资料。使用libbpf或BCC框架加载程序时，可以通过设置环境变量或API参数来获取验证器日志。在bpftool层面，虽然它主要用于操作已加载的程序，但理解验证器日志的解读方法对于调试至关重要。
验证器日志会逐条分析BPF指令，指出潜在的安全问题，如未初始化的寄存器使用、越界访问、无限循环等。日志中每一行对应一条BPF指令，格式通常为指令编号、指令内容、以及验证器的分析结论。如果看到类似invalid access to map memory或unbounded variable-offset alu的错误信息，说明程序在指针操作或算术运算上存在验证器无法证明安全性的逻辑。这时候需要回到源码层面，添加边界检查或使用验证器能理解的约束提示。
BTF（BPF Type Format）信息是现代eBPF调试的重要辅助。当程序和映射都携带BTF信息时，bpftool能够以结构化的方式展示数据，而不是输出原始的字节流。要查看程序是否包含BTF信息，在bpftool prog show的输出中查找btf_id字段，非零值表示程序附带了BTF。对于映射，同样可以通过bpftool map show查看是否有BTF关联。启用BTF展示后，映射数据会按照结构体定义逐字段输出，极大提升了可读性：
sudo bpftool map dump id 456
# 无BTF时的输出：
// key: 01 00 00 00 value: 2a 00 00 00 00 00 00 00
# 有BTF时的输出：
// key:
// struct connection_key {
// protocol: 1,
// saddr: 0,
// daddr: 0,
// }
// value:
// struct connection_value {
// packets: 42,
// bytes: 0,
// }
在Ubuntu上，如果使用libbpf框架开发eBPF程序，BTF信息通常默认生成。但如果使用较旧的BCC框架或手写BPF C代码，可能需要显式启用BTF生成。在Clang编译时添加-g选项生成DWARF调试信息，然后使用bpftool gen子命令将DWARF转换为BTF格式并嵌入到目标文件中。这样加载程序时内核就能自动关联BTF信息，bpftool的输出也会更加友好。
另一个进阶技巧是使用bpftool的net子命令查看网络相关的BPF程序挂载情况。对于XDP、TC（Traffic Control）和cgroup网络程序，bpftool net show能够显示这些程序挂载在哪些网络接口或cgroup上。这在排查网络数据包处理逻辑问题时非常有用。例如，当你发现某个接口的XDP程序没有按预期丢弃或重定向数据包时，首先确认程序是否确实挂载到了正确的接口上：
sudo bpftool net show # 输出示例： // xdp: // eth0(2) prog id 123 // tc: // eth0(2) clsact ingress prog id 124 // eth0(2) clsact egress prog id 125
如果发现程序没有挂载到预期的接口上，需要检查加载代码中的接口索引获取逻辑是否正确。在Ubuntu上，可以使用ip link show查看接口索引，与BPF程序加载时使用的索引进行对比。此外，bpftool net dump命令还能以pcapng格式导出网络数据包，方便使用Wireshark等工具进行离线分析，这对于排查XDP或TC程序的数据包处理逻辑问题非常有效。
最后，在调试复杂的eBPF应用时，建议将bpftool的输出与dmesg内核日志结合使用。eBPF程序中使用bpf_trace_printk输出的调试信息会写入/sys/kernel/debug/tracing/trace_pipe文件，可以通过cat /sys/kernel/debug/tracing/trace_pipe实时查看。虽然这种方式性能开销较大不适合生产环境，但在开发调试阶段，它能够提供程序执行路径中最细粒度的信息。将trace_pipe中的输出时间戳与bpftool观察到的映射数据变化时间点对齐，可以快速建立程序执行逻辑与数据状态之间的因果关系，从而精确定位问题根因。