B.2 环境准备与工具链

在宏观架构层面，eBPF 的运转机制清晰而自洽：一段经过形式化安全证明的内核态字节码，稳固挂接在内核的各类探针与链路钩子上，并在事件唤醒时就地提取数据，经由专有的内存通道与用户空间完成数据交互。然而，若要将这一优雅的架构图纸转化为一台真正能够随时动手调试的本地开发工作站，则必须在底层妥善配置好一整套精密的工具链组合。这套工具链涉及的组件往往分散在不同的系统层级：既包含运行内核自身的编译特性与类型导出开关，也涵盖了具备特殊目标后端的 clang/LLVM 编译器、标准用户态支撑库 libbpf，以及用于代码自省和脚手架生成的系统工具 bpftool。在系统编程实践中，如果缺少了其中任何一个关键环节，后续某个阶段的构建或加载便会毫无征兆地中断，而终端吐出的往往是诸如“找不到节区”或“无法解析符号”这样令人费解的底层报错。

这一节将以主流的 Debian 13 环境为基准，从零开始系统梳理现代 eBPF 开发环境的安装与深度自检流程。我们将依次核验运行内核对 BTF 的原生支持、部署具备完整 BPF 编译后端的 clang/LLVM 套件、配置标准开发库 libbpf-dev 与调试工具 bpftool，亲手从宿主机内核逆向导出庞大而精纯的类型定义文件 vmlinux.h，并深入 Linux Capabilities 特权模型剖析每一次系统调用拦截背后的权限边界。完成这些配置后，开发机便具备了独立编译字节码、自动化提炼 C 语言骨架以及向内核验证器发起装载请求的完备能力。相关工具链的基准版本参考为 Debian 13（运行 Linux 6.12 内核、LLVM/clang 19、libbpf 1.5 以及 bpftool 7.5）；使用 Ubuntu 24.04 的读者可以直接沿用完全相同的软件包名称与控制命令（其自带的 libbpf-dev 为 1.3.0 版本），针对 WSL2 环境与直接物理机虚拟化的微小差异也会在行文中逐一辨析。

1. 需要准备什么

将前述的完整开发流水线映射到具体的工具实体上，所需的基础组件其实非常聚焦，但每一款软件在体系中都承担着不可替代的专门职责。下表系统归纳了 Debian 13 软件仓库（trixie 存储库）中对应的标准软件包与版本基准，开发者在终端中可以随时借助 apt-cache policy 命令核实其在本机的安装状态。

核心组件	系统功能与核心职责	Debian 13 对应软件包	参考基准版本
宿主内核	提供统一的 bpf() 系统调用入口、静态验证器、JIT 即时编译器以及各类静态与动态追踪钩子	linux-image-amd64	6.12.113-1（本环境实测运行内核为 6.12.86+deb13-amd64）
内核 BTF 元数据	全景描述内核全部内部结构体、枚举与函数签名，作为自动化提取 vmlinux.h 与实施 CO-RE 跨版本重定位的权威数据源	紧随现代内核原生暴露于 sysfs，无须独立安装独立包	—
clang 编译器前端	负责将内核态 C 源码（.bpf.c）严谨编译为标准 BPF 目标二进制文件（.bpf.o）	clang、clang-19	1:19.0-63、19.1.7-3+b1
LLVM 体系工具链	包含 llc 静态编译器、llvm-objdump 字节码反汇编器与 llvm-readelf 节区检查器	llvm、llvm-19	1:19.0-63、19.1.7-3+b1
libbpf 开发库	官方标准用户态控制库，包含内核态开发头文件、用户态加载链接库以及 pkg-config 元数据描述	libbpf-dev	1:1.5.0-3
bpftool 工具	专用的 BPF 诊断与辅助工具，负责反编译内核 BTF 生成 vmlinux.h、自动化提取代码骨架并巡检内核驻留对象	bpftool	7.5.0+6.12.113-1
libelf 与 zlib	libbpf 的底层必要依赖，负责解析 ELF 格式文件与解压内核压缩元数据	libelf-dev、zlib1g-dev	0.192-4、1.3.1
GNU 构建套件	负责用户态管理程序及自动化流水线的编译与动态链接	make、gcc、pkg-config	4.4.1、14.2.0、1.8.1
bpftrace（可选）	基于高级专用语言的单行动态排查工具，用于快速验证探针与现场排障	bpftrace	0.23.2-1

这些离散的工程工具在代码构建与运行时的协同关系，可以通过如下结构图直观透视：最左侧的 clang 负责前端字节码生成，居中的 bpftool 负责将内核的内部结构体蓝图转化为项目可引用的头文件并提取骨架，而最右侧则由 libbpf 统揽生命周期，将编译产物安全注入内核沙箱中。

需要补充的是，BPF Map 键值通道与环形缓冲区事件流并未在图中做静态展开，它们属于程序激活后由内核态与用户态在运行时展开的高并发状态共享通道，相关技术机理将在 B.6 节 展开剖析。

四个部件各管一段

clang 编译器负责将内核态源码 .bpf.c 编译为规范的 BPF 目标文件，其输出中不仅包含经优化的字节码指令序列，还附带了完整的 BTF 类型描述与重定位节区。libbpf 作为一个纯粹的用户态原生库，在程序装载期间逐段解析该目标文件，参照当前运行内核的 BTF 实时修正各结构体字段偏移，再通过系统调用将指令递交给内核。bpftool 则是官方提供的瑞士军刀，既能通过 btf dump 将运行中内核的内部类型直接转化为通用的 vmlinux.h，又能利用 gen skeleton 将编译出的 ELF 文件压缩编码并生成强类型的 C 语言骨架头文件。而静卧在 /sys/kernel/btf/vmlinux 的内核 BTF 文件，则是宿主机在构建自身镜像时由内核源码自动提取生成的权威类型库，为上述三项工具提供了不可或缺的统一类型基准。

深入审视 libbpf-dev 软件包在系统文件系统中的真实排布，有助于在后续工程配置中消除对路径的神秘感。在标准的 Debian 13 环境中，该安装包会在 /usr/include/bpf/ 目录下释放一整套功能丰富的 C 语言头文件，包括定义基础 API 的 bpf.h 与 libbpf.h、供内核态程序调用的辅助函数封装 bpf_helpers.h、探针上下文声明 bpf_tracing.h，以及支撑 CO-RE 安全内存解引用的核心宏库 bpf_core_read.h。在库文件方面，它在架构专用目录 /usr/lib/x86_64-linux-gnu/ 中部署了静态归档 libbpf.a 与动态共享对象 libbpf.so，并同时注册了规范的 pkgconfig/libbpf.pc 描述项。相比之下，bpftool 软件包的布局则非常紧凑，主要向操作系统注入单一的可执行文件 /usr/sbin/bpftool 及其手册文档。

bpftool 装在 /usr/sbin

在绝大多数类 Unix 发行版的默认设计中，非特权普通用户的搜索路径 PATH 并未包含管理目录 /usr/sbin。因此，如果在普通终端会话中直接键入 bpftool，往往会收到找不到命令的警告。读者可以通过输入完整绝对路径 /usr/sbin/bpftool 进行调用，或者遵循生产管理惯例，在每次调用时显式加上特权前缀 sudo bpftool 执行。

2. 选择运行环境

由于 eBPF 程序最终是直接注入并深度运行在 Linux 内核特权地址空间中的，展开实验的第一前提，便是拥有一台具备完整 root 管理权限的 x86-64 架构 Linux 主机。在学习与验证阶段，首选的理想载体莫过于搭建一台运行 Debian 13 的本地独立虚拟机：其系统的基础环境非常纯净，预装内核版本与官方源中的软件工具链与本书示例完全一致，即使在实验早期因编写了不恰当的过滤规则导致网络短暂失联或内核假死，也能够随时通过虚拟机快照进行秒级回滚。在物理机上直接开发同样完全可行，但若主机的内核版本低于 6.6，后续在 B.12 节 涉及的现代流量控制（tcx）挂载模式将无法得到原生支持。

对于日常以 Windows 作为主力宿主机的读者，工程实践中存在两条兼具可行性的路径。其一是利用微软深度优化的 WSL2 环境。现代 WSL2 的 Linux 内核实际上是微软专门维护并开源构建的定制版 6.6 内核，在其出厂编译配置中，包括 CONFIG_BPF_SYSCALL、CONFIG_BPF_JIT、CONFIG_DEBUG_INFO_BTF、CONFIG_BPF_LSM、CONFIG_KPROBES、CONFIG_UPROBE_EVENTS 以及 CONFIG_BPF_EVENTS 在内的关键配置项均被默认显式开启为 y。这意味着全书绝大多数观测、网络与安全案例均能直接在 WSL2 的 Ubuntu/Debian 子系统中平稳运行，唯一的细微差异仅在于进程命名空间的视界隔离，我们在 B.3 节 会专门指出其实际表现。另一条更加彻底的路径则是在 Hyper-V 或 VirtualBox 等虚拟化软件中创建一台原汁原味的 Debian 13 虚拟机。至于传统的 Docker 容器环境，由于容器内部默认剥离了绝大部分敏感特权，要运行 BPF 程序不仅需要为容器赋予特殊的特权模式（--privileged），还必须繁琐地向容器内挂载宿主机的 BTF 虚拟文件，在初学阶段并不推荐将过多精力耗费在容器沙箱的调试上。

练习不要用生产服务器

向操作系统内核动态注入并激活 BPF 程序，会直接改变宿主机内核在全局或局部钩子上的行为特征。在代码编写与探索阶段，一个由于边界判断失误或过滤条件写反的测试程序，极有可能在特定高频系统调用上引发持续的上下文抢占，甚至在网络设备接口处意外把合法的业务流量就地全量丢弃。请务必在独立的本地沙箱、虚拟机或测试开发机上进行一切编码实践，切莫直接在承载重要业务的生产集群节点上尝试加载未经充分验证的试写程序。

单选

在 WSL2 里能运行本章的 CO-RE 程序吗？依据是什么？

不能，WSL2 的内核是微软定制的，去掉了 BPF

能，WSL2 内核配置里 CONFIG_DEBUG_INFO_BTF 等选项都已开启

能，但必须先自己编译一个带 BTF 的内核

不能，WSL2 里没有 root 权限

3. 检查内核

在着手构建任何程序之前，首先应当在终端中核查当前运行环境的内核版本。内核的版本号直接划定了系统底层特性的开放疆界：

bash - uname

$ uname -r
6.12.86+deb13-amd64

要快速判定当前操作系统内核是否原生集成了现代 eBPF 所必需的 BTF 类型元数据，只需在终端中检查一个特殊的 sysfs 虚拟文件节点：ls -l /sys/kernel/btf/vmlinux。

如果该文件在文件系统中真实存在且内容大小非空，便无可辩驳地证明当前内核在编译打包阶段开启了 CONFIG_DEBUG_INFO_BTF 选项。内核构建系统在编译期利用 pahole 工具深度扫描了 DWARF 调试信息，将其高度压缩为 BTF 格式并直接嵌入到了内核二进制镜像中；当操作系统引导启动时，内核的 sysfs 驱动便会自动将其映射暴露为这个具有只读属性（权限固定为 0444）的虚拟文件，允许系统中所有用户态程序直接读取。假如此处提示文件不存在，那么后续无论是使用 bpftool btf dump 导出头文件，还是依赖 libbpf 展开 CO-RE 字段重定位，都将因缺乏基准类型数据源而彻底无法展开。该文件的大小取决于内核具体开启的功能模块与驱动规模，通常在几兆字节到十几兆字节的区间内。

若想进一步核实系统内核编译选项的全面配置，可以直接检索启动引导目录下的内核配置文件。在 Debian 13 系统中，与现代 eBPF 特性紧密相关的核心配置项如下：

CONFIG_BPF_SYSCALL=y
CONFIG_BPF_JIT=y
CONFIG_BPF_UNPRIV_DEFAULT_OFF=y
CONFIG_BPF_LSM=y
CONFIG_KPROBES=y
CONFIG_UPROBE_EVENTS=y
CONFIG_DEBUG_INFO_BTF=y

读者可以在自己的终端中运行下面的过滤命令，实地核查当前环境的编译项：grep -E "CONFIG_(BPF_SYSCALL|BPF_JIT|DEBUG_INFO_BTF|BPF_UNPRIV_DEFAULT_OFF)=" /boot/config-$(uname -r)。其中命令中的子表达式 $(uname -r) 会被 shell 自动展开为当前活动内核的版本字符串，回显输出应当与上述核心配置严格对齐。

在这批配置中，CONFIG_BPF_SYSCALL 开启了统揽全局的 bpf() 系统调用接口，它是用户态与内核 BPF 子系统展开一切交互的法定大门；CONFIG_BPF_JIT 确保了经审查的指令能够在内存中被即时翻译为宿主机的原生原生指令，若该项缺失，内核只能退化到低效的纯软件虚拟机解释执行模式；CONFIG_DEBUG_INFO_BTF 决定了前述 /sys/kernel/btf/vmlinux 文件的存亡；而 CONFIG_BPF_UNPRIV_DEFAULT_OFF 则直接将系统内核参数 kernel.unprivileged_bpf_disabled 的出厂预设值设定为 2，这意味着系统在默认状态下严格禁止非特权普通用户调用 BPF 设施，我们将在后续关于权限控制的一节中深入探讨这一安全策略。

tracefs 在哪

在早期的 Linux 系统资料与排障笔记中，很多文档习惯将探针的追踪输出重定向指向 /sys/kernel/debug/tracing/trace_pipe，这是挂载在 debugfs 文件系统之下的历史传统路径。随着内核对调试与追踪机制的规范解耦，现代主流发行版已经将专属的跟踪文件系统（tracefs）独立挂载至标准化路径 /sys/kernel/tracing 下。虽然为了保持向后兼容性，旧路径在很多宿主机上依然通过软链接维持可用，但在编写现代工程代码与构建脚本时，建议统一优先采用更为规范的标准路径 /sys/kernel/tracing/trace_pipe。

单选

哪个文件存在，就说明当前内核带有 BTF？

/boot/config-$(uname -r)

/sys/kernel/btf/vmlinux

/proc/kallsyms

/sys/fs/bpf

4. 安装工具链

在标准的 Debian 13 环境下，系统包管理器允许我们通过一条精简的指令一次性拉取全部核心工具链（其中 bpftrace 作为高级动态排查工具在初期为可选安装项，在后续 B.14 节 会深入展开）：

bash - apt install

$ sudo apt install clang llvm libbpf-dev bpftool libelf-dev zlib1g-dev make gcc pkg-config
$ sudo apt install bpftrace

在这套依赖清单中，clang 与 llvm 实际上是 Debian 系统中的元包（metapackage），在当前系统版本下它们会自动将底层依赖精准解析并重定向至 clang-19 与 llvm-19。编译器的核心可执行实体均统一妥善安置在 /usr/lib/llvm-19/bin 路径中，而系统级命令 /usr/bin/clang 与 /usr/bin/llc 则是指向它们的通用符号链接。值得特别说明的是，libelf-dev 与 zlib1g-dev 绝非可有可无的附属组件：libbpf 在底层深度依赖它们完成 ELF 格式解析与数据解压，这一点在 libbpf.pc 元数据描述文件的 Requires.private 字段中写得极为明确。当我们的用户态程序采取常规的动态链接模式时，pkg-config 默认仅输出 -lbpf，动态链接器会在运行时自动随 libbpf.so 依次拉入 libelf 与 zlib；唯有在需要输出全静态独立二进制（执行 pkg-config --static --libs libbpf）时，构建系统才会将 -lelf -lz 显式追加到链接参数末尾。

软件包安装完毕后，首先应当在终端中核验 clang 编译器的版本形态：

bash - clang --version

$ clang --version
Debian clang version 19.1.7
Target: x86_64-pc-linux-gnu
Thread model: posix
InstalledDir: /usr/lib/llvm-19/bin

clang 之所以能够将高级 C 语言代码编译为专属于 eBPF 虚拟机的指令，完全依托于其背后的 LLVM 体系所集成的 BPF 目标架构后端。我们可以直接调用底层工具 llc --version 核查系统当前已注册的目标平台列表：

bash - llc --version

$ llc --version
LLVM (http://llvm.org/):
  LLVM version 19.1.7
  Optimized build.
  Default target: x86_64-pc-linux-gnu
  Host CPU: skylake

  Registered Targets:
    aarch64    - AArch64 (little endian)
    ...
    bpf        - BPF (host endian)
    bpfeb      - BPF (big endian)
    bpfel      - BPF (little endian)
    ...
    x86-64     - 64-bit X86: EM64T and AMD64

只要在 Registered Targets 输出清单中清晰显式列出了 bpf（宿主机字节序）、bpfeb（大端字节序）与 bpfel（小端字节序）这三行条目，便足以证明当前的 clang/LLVM 工具链具备编译 BPF 目标二进制的完整能力。在 Debian 13 官方分发的动态库 libLLVM.so.19.1 中，这三个后端目标均被完整编译打包在内。

针对用户态核心开发库 libbpf 的安装状态，推荐使用标准的 pkg-config 工具进行自省查询：

bash - pkg-config

$ pkg-config --modversion libbpf
1.5.0

终端回显的这行简洁版本号，在工程层面同时印证了三项关键事实：首先，libbpf-dev 软件包已被正确解压安装；其次，描述其编译依赖特征的 libbpf.pc 文件已经平稳接入了系统的默认检索路径；最后，在后续编写项目 Makefile 时，我们可以完全放心地通过 $(shell pkg-config --cflags --libs libbpf) 这一标准范式，动态提取宿主机所需的头文件路径与链接标志。如果此处终端报错提示找不到模块，务必检查是否仅仅安装了基础的动态运行库 libbpf1，而遗漏了提供开发头文件与元数据描述的 libbpf-dev。

最后，我们通过 bpftool 自身的版本探针进一步确认系统自省工具的就绪情况：

bash - bpftool version

$ sudo bpftool version
bpftool v7.5.0
using libbpf v1.5
features: llvm, skeletons

在这三行输出中，第二行明确展示了当前工具所静态或动态链接的 libbpf 版本，而第三行输出的 features 特性标志更是重中之重：llvm 表明该工具具备调用 LLVM 接口反汇编内核中驻留 BPF 字节码的高阶能力，而 skeletons 标志则直接宣誓了其能够从目标二进制文件中逆向解析并自动化生成 C 语言骨架代码。这两项关键特性是后续在 B.3 节 及全书所有实战项目中不可或缺的底层支撑。

多选

关于 clang、libbpf 与 bpftool 的分工，下列哪些说法正确？

clang：把 .bpf.c 编译成 BPF 目标文件

libbpf：在运行时加载目标文件并完成重定位

bpftool：生成 vmlinux.h 与骨架，查看内核中的对象

libbpf：把 C 源码编译成 BPF 字节码

5. 生成 vmlinux.h

在编写内核态 eBPF 程序时，我们经常需要深入探查诸如进程描述符 task_struct、文件对象 file 以及系统调用追踪上下文 trace_event_raw_sys_enter 等复杂的内核数据结构。然而，在传统的 C 语言开发经验中，我们绝对无法通过在用户态代码中简单粗暴地书写 #include <linux/sched.h> 来达成目的。因为 Linux 原生内核头文件内部充斥着大量深度依赖内核构建上下文的特定宏定义、架构专有内联汇编以及复杂的配置依赖项，强行在普通编译单元中引入它们必然会引发灾难性的宏冲突与语法报错；更为严峻的是，直接在源码中写死特定版本头文件的声明，会使得编译产物丧失跨内核版本的可移植性。现代解决方案是借助 bpftool 从运行内核的 BTF 元数据中，逆向提取出一份纯净、自包含、剥离了一切宏与函数实现的纯 C 语言类型声明集合，这便是业界标准文件 vmlinux.h 的由来。

生成这份万能头文件只需要在终端中敲下一行优雅的命令：

bash - btf dump

$ sudo bpftool btf dump file /sys/kernel/btf/vmlinux format c > vmlinux.h

在标准的 Debian 13 环境下，生成的 vmlinux.h 包含了超过 12 万行纯粹的结构体、联合体与枚举类型定义，磁盘占用约为 2.6 MB。截取其文件开头的片段，可以观察到一个极其精巧的编译器指令声明：

#ifndef __VMLINUX_H__
#define __VMLINUX_H__

#ifndef BPF_NO_PRESERVE_ACCESS_INDEX
#pragma clang attribute push (__attribute__((preserve_access_index)), apply_to = record)
#endif

#ifndef __ksym
#define __ksym __attribute__((section(".ksyms")))
#endif

紧随文件头部的 #pragma clang attribute push 语句，在底层发挥着决定性的作用：它指示 clang 编译器为该头文件中声明的每一个结构体与联合体自动附加上 preserve_access_index 编译器属性。一旦启用了该属性，编译器在生成任何访问结构体成员的机器指令时，便不会再简单地将字段硬编码为一个固定的内存字节偏移量，而是在 ELF 文件的 .BTF.ext 节区中严谨地记录下一条专属的 CO-RE 重定位信息，清晰标明当前指令试图访问的具体结构体类型名称以及目标成员的符号名称。当该程序未来被复制到另一台物理机加载时，libbpf 就可以根据当前目标内核暴露的实际 BTF 定义，按名称重新动态反推该字段在新内核中的真实字节偏移，并即时对字节码指令展开原位修正。这也是现代 BPF 程序能够达成「一次编译、到处运行」的根本奥秘，相关底层细节将在 B.8 节 进行细致展开。

由于 vmlinux.h 的内容直接映射了当前宿主机内核的类型特征，在现代工程协作中，该文件绝不应当被直接提交进 Git 等代码版本仓库。它应当被明确视为编译期根据环境即时生成的中间构件。在项目的 Makefile 中，通常会定义如下标准规则：

BPFTOOL ?= bpftool
VMLINUX_BTF ?= /sys/kernel/btf/vmlinux

vmlinux.h: $(VMLINUX_BTF)
	$(BPFTOOL) btf dump file $(VMLINUX_BTF) format c > $@

通过执行 make -n vmlinux.h，可以预览构建系统推导出的执行步骤：

bash - make -n

$ make -n vmlinux.h
bpftool btf dump file /sys/kernel/btf/vmlinux format c > vmlinux.h

这种基于 Makefile 依赖关系的编排具备极佳的工程弹性：如果需要模拟针对外部内核版本的交叉验证，只需通过参数覆盖将 VMLINUX_BTF 重定向至目标内核的预存 BTF 二进制镜像即可。需要提醒的是，bpftool btf dump 接收的输入必须是具备 ELF 或标准 BTF 结构的二进制镜像本身，如果错误地将一份纯 C 头文件传递给它作为输入，工具便会因为无法解析出合法的 ELF 头部而抛出 failed to get EHDR 的格式错误。

6. 权限

向操作系统内核装载并激活 eBPF 探针，本质上是在重塑内核的执行路径，这种操作在类 Unix 系统的安全体系中属于极其敏感的特权行为。在传统的 Linux 权限模型中，这类操作通常被简单粗暴地全量绑定在超级用户 root 或无所不能的 CAP_SYS_ADMIN 特权之下。随着现代容器化与最小权限安全架构的演进，Linux 内核自 5.8 版本开始，正式将 BPF 相关的安全判定解耦为更加细粒度的能力（Capabilities）体系：

• 针对系统追踪与性能剖析类程序（如 kprobe、tracepoint、fentry、perf_event 以及 LSM 探针），内核明确要求发起调用的进程必须持有 CAP_PERFMON（能力编号 38）与 CAP_BPF（能力编号 39）；
• 针对网络数据链路控制类程序（如 XDP、tc 以及套接字链路钩子），内核则要求调用方必须兼备 CAP_NET_ADMIN 与 CAP_BPF；
• 作为向后兼容的历史遗留，传统的超级特权 CAP_SYS_ADMIN 在当下的实现中依然被视作上述细分能力的超集，持有它的进程仍然能够顺利穿透各项能力审查。

在普通非特权用户账号下，系统甚至严密禁止查询内核的底层能力细节。如果我们在没有使用 sudo 提权的普通会话中尝试执行功能自省，bpftool 会在第一道关卡前被直接阻断：

bash - feature probe

$ bpftool feature probe
Error: missing CAP_SYS_ADMIN, CAP_BPF, CAP_NET_ADMIN, CAP_PERFMON, required for full feature probing; run as root or use 'unprivileged'

除了进程自身的能力凭据之外，Linux 内核还在全局层面上设立了一道由 sysctl 集中管控的安全总闸：kernel.unprivileged_bpf_disabled。该参数支持三种离散的策略状态：设定为 0 代表允许非特权普通用户调用 BPF 的部分受限子集；设定为 1 代表彻底全局禁止非特权访问且在当前系统运行周期内不允许再向低权限回拨；而设定为 2 则代表系统默认禁止非特权操作，但允许具备管理员特权的进程随时动态修改该参数。在主流企业级发行版与 Debian 13 的官方内核配置中，由于前述 CONFIG_BPF_UNPRIV_DEFAULT_OFF 编译选项被显式激活，该参数在宿主机冷启动后便自动固化为 2，这意味着普通用户即使只是尝试在内核中申请建立一个基础的哈希 Map，也会被内核立刻驳回。

基于这一深层的安全现实，本拓展教程中所有涉及到向内核载入程序、初始化 Map 对象以及读取跟踪管道 trace_pipe 的终端指令，在开头均规范保留了 sudo 提权前缀。以 root 身份开展实验不仅能够免去初期对离散能力的排查困扰，更契合了底层系统编程的真实工业现实。在未来的生产环境服务部署中，若希望以非 root 运行的独立进程承载 BPF 工具，可以通过执行 setcap cap_bpf,cap_perfmon+ep ./tool 将特定的内核能力固化绑定在可执行二进制的文件元数据上，这部分进阶实践将在 B.15 节 的实战总结中集中展开。

7. 两种项目起点

全书各个小节的实战代码均统一存放在 code/系统编程/拓展B_eBPF/ 目录下，并以章节编号作为目录命名。在各工程目录内部，呈现出高度整齐划一的经典结构：

B_2_环境准备与工具链/
├── Makefile          # 生成 vmlinux.h、编译 .bpf.o、生成骨架、编译用户态程序
├── smoke.bpf.c       # 最小的内核态程序：一个空的 tracepoint 处理函数
├── btfstat.c         # 读 BTF 文件头的小工具，本页习题会用到
└── libbpfver.c       # 用 pkg-config 编译并打印 libbpf 版本

这种工程组织架构直接依托于宿主机环境已预装的系统级 libbpf 库：由 pkg-config 负责动态向 Makefile 供给严谨的编译包含路径与库链接标志，由系统预装的 bpftool 自动化提炼代码骨架，Makefile 则条理分明地编排每一道构建依赖。这种模式的最大优势在于软件依赖链条完全透明，每一道中间产物都可以独立在终端中手动调用与推演，极其契合深耕底层原理的学习诉求。完整的工程 Makefile 在 B.3 节 会完整给出，当前目录下的规则主要专注于环境检测与类型自省。

目录下的 libbpfver.c 代码非常凝练，其核心设计目的正是为了直观印证用户态宿主程序与底层 libbpf 库的动态链接流程：

#define _POSIX_C_SOURCE 200809L

#include <bpf/libbpf.h>
#include <stdio.h>

int main(void) {
    printf("libbpf %s\n", libbpf_version_string());
    return 0;
}

在已经正确配置 libbpf-dev 的开发机上，运行编译指令并执行程序，便会在终端打印出底层运行库的版本：libbpf v1.5。这段极简代码的精妙之处完全体现在其背后的链接命令上：Makefile 中的 $$(pkg-config --cflags --libs libbpf) 在展开后会为编译器精确注入 -lbpf 标志，而在程序拉起时，动态链接器必须能够在系统的标准库检索路径中准确定位到 libbpf.so 的物理文件。后续章节中所有的用户态常驻监控程序，均以此为范式展开构建。

除了这种依托发行版预装库的原生方案之外，开源社区中另一个被广泛采用的项目起点是由官方维护的脚手架项目 libbpf-bootstrap。该项目采取了一种高度自包含的交付策略：它将 libbpf、bpftool 以及预先提取好的 vmlinux.h 均作为 Git 子模块（Submodule）打包在同一个代码仓库内，在项目构建时会在本地就地编译出专属的静态 libbpf 归档，从而使得生成出的最终二进制不再要求宿主机预装特定版本的开发包：

bash - libbpf-bootstrap

$ git clone --recurse-submodules https://github.com/libbpf/libbpf-bootstrap
$ cd libbpf-bootstrap/examples/c
$ make
$ sudo ./minimal

当面对某些较为陈旧、其系统官方软件源中提供的 libbpf 版本严重滞后，或者需要将编译出的系统诊断工具整机复制到完全没有配置软件源的受限生产环境时，libbpf-bootstrap 这种将依赖全量就地消化的工程模板显然具备极高的实用价值。无论采取何种工程起点，其底层内核态代码的语法规范与骨架的使用逻辑完全保持统一，读者在掌握了原生构建流程后可以平滑迁移至任何现代工程脚手架中。

针对以 Windows 作为开发宿主机的跨平台场景，需要将编译构建与内核加载严格区分开来。由于现代 clang 本质上是一个功能完备的交叉编译器，指定 -target bpf 并不依赖任何当前宿主机的 Linux 内核组件，因此 BPF 目标二进制文件完全可以直接在 Windows 的 PowerShell 终端中成功编译产出：

PowerShell - bpf.o

PS> clang -target bpf -Werror -O2 -c bpf.c -o bpf.o
PS> llvm-objdump --triple=bpf -S bpf.o

bpf.o:  file format elf64-bpf

Disassembly of section .text:

0000000000000000 <func>:
       0:	b4 00 00 00 00 00 00 00	w0 = 0x0
       1:	95 00 00 00 00 00 00 00	exit

上述指令输出了清晰的汇编序列：w0 = 0x0（在较早的工具链中显示为 r0 = 0）将返回值寄存器规整清零，exit 指令结束执行。如果我们在编译选项中追加 -g 调试符号标志，随后执行带有源代码映射的混合反汇编 llvm-objdump -S，工具甚至能够在每一条 BPF 机器指令的上方精确标注出对应的高级语言源代码行：

PowerShell - bpf-d.o

PS> clang -target bpf -Werror -g -O2 -c bpf.c -o bpf-d.o
PS> llvm-objdump --triple=bpf -S -l bpf-d.o

bpf-d.o:	file format elf64-bpf

Disassembly of section .text:

0000000000000000 <func>:
; func():
; C:\Users\29728\AppData\Local\Temp\p118a\bpf.c:1
; int func(void) { return 0; }
       0:	b4 00 00 00 00 00 00 00	w0 = 0x0
       1:	95 00 00 00 00 00 00 00	exit

这种在 Windows 环境下交叉编译出的 .bpf.o 目标文件，其内部结构完全符合标准 ELF64 规范，将其复制到 Debian 13 环境下同样可以顺畅交由 bpftool gen skeleton 生成结构严谨的代码骨架：

struct smoke_bpf {
	struct bpf_object_skeleton *skeleton;
	struct bpf_object *obj;
	struct {
		struct bpf_program *handle_getpid;
	} progs;
	struct {
		struct bpf_link *handle_getpid;
	} links;

然而必须保持清醒的是，在 Windows 上编译出的以 Linux 内核为目标的 .bpf.o 文件，绝对无法直接注入 Windows 本身的内核中加载执行。微软主导的 eBPF for Windows 拥有专属的执行沙箱、挂载挂钩与验证器驱动，Linux 下的二进制探针无法直接跨系统搬移，相关的平台差异将在 B.16 节 展开系统比对。

在 Windows 本地探索交叉编译时，还有一个极易引发困惑的工程暗坑值得提前指出：LLVM 官方在早期分发的 Windows 预编译安装包中（版本 19 及更早之前），其默认的构建编译宏中仅包含了 AArch64、ARM 与 X86 三种架构后端，此时若直接执行 clang -target bpf，终端会立刻报出致命错误：

PowerShell - no BPF target

PS> clang -target bpf -c bpf.c -o bpf.o
error: unable to create target: 'No available targets are compatible with triple "bpf"'
1 error generated.

这并非开发者的命令行语法存在差错，而是当前 Windows 上的 clang 二进制内部根本没有编入 BPF 目标后端支持。这一情况自 LLVM 20 及更高版本开始得到了彻底扭转，其构建清单中全面补齐了 BPF 支持，现代 Visual Studio 2022 最新组件中所集成的 LLVM 工具链亦可完美支持 BPF 目标生成。在日常开发中，通过执行 clang --print-targets 快速审视回显列表中是否包含 bpf 条目，是排除编译器后端缺陷最为行之有效的手法。而在主流 Linux 发行版中，官方源打包的 LLVM 均默认开启了全架构支持，开发者无须担心这一后端缺失的问题。

8. 习题

8.1 巩固

#46201

⚡1⏳2

写一个 envcheck.sh，依次检查并打印：

1. uname -r 的内核版本；
2. /sys/kernel/btf/vmlinux 是否存在，存在时打印字节数；
3. /boot/config-$(uname -r) 中 CONFIG_BPF_SYSCALL、CONFIG_BPF_JIT、CONFIG_DEBUG_INFO_BTF 三项的值；
4. clang --version、bpftool version、pkg-config --modversion libbpf 的首行。

输出用「项名: 值」的固定格式，任一项缺失时打印 MISSING 并以非零状态退出。验收：在一台装好本章工具的 Debian 13 上全部有值、退出码为 0；把 PATH 设为空目录后再运行，脚本应报告缺工具而不是报语法错误。

#46202

⚡2⏳2

code/系统编程/拓展B_eBPF/B_2_环境准备与工具链/btfstat.c 读取 BTF 文件头，打印类型区与字符串区的长度。本机运行它，输入分别是：

1. 一个 .bpf.o 文件；
2. vmlinux.h；
3. 用 llvm-objcopy --dump-section .BTF=x.btf x.bpf.o 从目标文件里抽出来的 BTF。

三种输入分别输出什么？解释第 1、2 种为什么被拒绝，而第 3 种能通过。再把它当作 make btfstat 的依赖跑一遍，确认 Makefile 能正常工作。

#46203

⚡2⏳3

用本页 code/ 目录的 Makefile，把 VMLINUX_BTF 换成任意一份 BTF 文件（没有的话，用 llvm-objcopy 从自己编译的 .bpf.o 里抽 .BTF），执行 make vmlinux.h，确认生成的 vmlinux.h 能被 clang -target bpf 接受：写一个只包含它、不写任何函数的小程序，加上 -g -O2 -target bpf -mcpu=v3 编译通过。

然后回答：删掉 Makefile 里 vmlinux.h: $(VMLINUX_BTF) 这一行的依赖，只留规则体，第二次执行 make vmlinux.h 会发生什么？为什么依赖关系要写成对 BTF 文件的依赖？

8.2 编程

#46204

⚡3⏳3

写一个 C 程序 toolver.c，在不调用任何外部命令的前提下，输出本机的 libbpf 版本与内核 BTF 的规模：

1. 用 <bpf/libbpf.h> 的 libbpf_version_string() 打印 libbpf 版本；
2. 打开 /sys/kernel/btf/vmlinux，读 24 字节的头，校验魔数 0xeb9f 与版本号 1；
3. 打印类型区与字符串区的字节数，以及整个文件的大小；
4. 文件不存在时打印原因并返回 1。

编译命令写成 gcc -std=c17 -Wall -Wextra toolver.c -o toolver $(pkg-config --cflags --libs libbpf)，要求 -Wall -Wextra 无警告。验收：输出中的 libbpf 版本与 pkg-config --modversion libbpf 一致；文件大小与 stat -c %s /sys/kernel/btf/vmlinux 一致。

#46205

⚡3⏳4

扩展 toolver.c（或另写一个 objinfo.c），用 libbpf 打开一个 BPF 目标文件并列出内容，但不加载：

1. bpf_object__open_file() 打开 smoke.bpf.o；
2. 用 bpf_object__for_each_program 遍历，打印每个程序的 bpf_program__name() 与 bpf_program__section_name()；
3. 打印 map 的数量；
4. 关闭对象。

验收：对 smoke.bpf.c 编出的目标文件，输出中有 handle_getpid 与 tp/syscalls/sys_enter_getpid，map 数为 0。再把对象换成编译时去掉 -g 的版本，重跑一次：输出是不是一样？如果一样，说明打开与列举程序并不依赖 BTF；那么再对这两个文件分别执行 bpftool btf dump file x.bpf.o format c，解释后一个为什么失败。

#46206

⚡4⏳4

完成一次跨平台构建：

1. 在 Windows 上用带 BPF 后端的 clang 编译一个带 SEC("tp/syscalls/sys_enter_getpid") 的 .bpf.c，用 llvm-objdump --triple=bpf -h 记录节表；
2. 把 .o 复制到 Debian 13，用 bpftool gen skeleton 生成骨架，记录头文件行数与 struct 名；
3. 再编译一版去掉 -g 的，重复第 2 步，记录 bpftool btf dump file x.bpf.o 的报错。

回答：为什么去掉 -g 后骨架还能生成，但 btf dump 会失败？骨架里嵌入的是哪一段数据？如果只在 Linux 上编译，这两个命令的结果有什么不同？

提示：骨架子程序在 smoke_bpf__elf_bytes() 里用 static const char data[] 把整个目标文件按字节嵌了进去，open 时传的就是这段内容。

#46207

⚡5⏳4

下面是一台机器上的五条症状，逐个写出原因与修复命令：

1. bpftool: command not found，但 dpkg -l bpftool 显示已安装；
2. bpftool btf dump file /sys/kernel/btf/vmlinux format c 报 No such file or directory；
3. bpftool gen skeleton x.bpf.o 报 failed to find '.BTF' ELF section；
4. pkg-config --modversion libbpf 报找不到包，但 /usr/include/bpf/libbpf.h 存在；
5. clang -target bpf 报 No available targets are compatible with triple "bpf"。

其中第 3 条，用 llvm-objdump -h 验证你的判断：缺的是哪个节，补上哪种编译选项后出现。

8.3 综合与挑战

#46208

⚡6⏳5选做

写一个 btfdump.c，直接从 /sys/kernel/btf/vmlinux 解析类型区，统计每种 BTF 类型（INT、PTR、STRUCT、UNION、ENUM、FUNC、VAR、DATASEC 等）的数量，按数量从多到少输出：

1. 按 struct btf_header 读头，定位类型区与字符串区；
2. 逐条遍历 struct btf_type：每条 12 字节，info 的第 24～28 位是 kind，低 16 位是 vlen，按 kind 计算该条后面跟多少字节的附属数据（STRUCT 每条成员 12 字节，INT 多 4 字节，ARRAY 多 12 字节，ENUM 每条 8 字节，FUNC_PROTO 的参数每条 8 字节，VAR 多 4 字节，DATASEC 每条 12 字节，DECL_TAG 多 4 字节，ENUM64 每条 12 字节）；
3. 输出 kind 名称 数量 三列，按数量从多到少排列，最后打印总条数。

验收：总条数与 bpftool btf dump file /sys/kernel/btf/vmlinux format raw | grep -c '^\[' 的结果相同（或相差 1，取决于 libbpf 是否计入 void 类型）；程序对 /sys/kernel/btf/vmlinux 的两次运行结果一致。

#46209

⚡6⏳6

写一个 openskel.c，用 bpftool gen skeleton 生成的 smoke.skel.h 只做打开与检查：

1. smoke_bpf__open() 打开骨架，打印程序数量与每个程序的名字；
2. 调用 smoke_bpf__load()，打印返回值；以普通用户运行时预计返回负的 -EPERM，用 strerror(-err) 打印原因；
3. 无论成功与否都调用 smoke_bpf__destroy()。

以普通用户和 root 各运行一次，记录两次的差别，并结合第 6 节解释：为什么 open 不需要特权，load 需要？如果程序加载成功，destroy 之前必须先 attach 吗？

注意：只在你自己有 root 的虚拟机或本机上做加载实验，不要在共享或生产机器上运行。

9. 参考资料

• libbpf-bootstrap 项目与 README（克隆方式、依赖、minimal 示例）：https://github.com/libbpf/libbpf-bootstrap
• Andrii Nakryiko，libbpf-bootstrap 介绍（构建流程与工具分工）：https://nakryiko.com/posts/libbpf-bootstrap/
• 内核文档，libbpf 概览（bpftool btf dump file /sys/kernel/btf/vmlinux format c 的用法）：https://docs.kernel.org/bpf/libbpf/libbpf_overview.html
• 内核文档，BPF 开发常见问题（-mcpu 与 BPF 指令集版本）：https://docs.kernel.org/bpf/bpf_devel_QA.html
• 内核文档，kernel.unprivileged_bpf_disabled 的取值与默认值：https://docs.kernel.org/admin-guide/sysctl/kernel.html
• 内核文档，BTF（类型格式与 .BTF、.BTF.ext 节）：https://docs.kernel.org/bpf/btf.html
• Linux 内核源码，include/uapi/linux/capability.h（CAP_BPF、CAP_PERFMON 与程序类型的对应）：https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/capability.h
• Linux 内核源码，kernel/bpf/sysfs_btf.c（/sys/kernel/btf/vmlinux 的生成与权限）：https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/kernel/bpf/sysfs_btf.c
• Linux 内核源码，kernel/bpf/syscall.c（程序类型与能力检查）：https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/kernel/bpf/syscall.c
• man7，capabilities(7)（CAP_BPF、CAP_PERFMON 的引入版本与含义）：https://man7.org/linux/man-pages/man7/capabilities.7.html
• Debian 软件包信息，libbpf-dev（版本与文件列表）：https://packages.debian.org/trixie/libbpf-dev
• Debian 软件包信息，bpftool（版本与 /usr/sbin/bpftool）：https://packages.debian.org/trixie/bpftool
• Debian 软件包信息，bpftrace（版本 0.23.2）：https://packages.debian.org/trixie/bpftrace
• Cilium，BPF 工具链（llc --version 中 BPF 目标的检查方法）：https://docs.cilium.io/en/stable/reference-guides/bpf/toolchain/
• 微软，WSL2-Linux-Kernel 仓库（6.6 内核配置中的 BPF、BTF、kprobe、uprobe 选项）：https://github.com/microsoft/WSL2-Linux-Kernel
• eBPF for Windows 教程（Windows 上用 clang 编译 .bpf.o 与 llvm-objdump 的输出）：https://github.com/microsoft/ebpf-for-windows/blob/main/docs/tutorial.md
• LLVM 项目，Windows 发行版构建脚本（19 与 20 的 LLVM_TARGETS_TO_BUILD 差异）：https://github.com/llvm/llvm-project/blob/release/20.x/llvm/utils/release/build_llvm_release.bat
• LLVM 项目，CMake 选项 LLVM_TARGETS_TO_BUILD（Native 与目标列表的含义）：https://llvm.org/docs/CMake.html