RedBPF

A Rust eBPF 工具链。

概述

RedBPF 项目是一组用于使用 Rust 构建 eBPF 程序的工具和库。它包括

• redbpf - 一个用户空间库，可用于加载 eBPF 程序或访问 eBPF 映射。

• redbpf-probes - 一个用于编写可由 Linux 内核加载的 eBPF 程序的 Rust 风格的 API

• redbpf-macros - 是 redbpf-probes 的配套 crate，它提供了一些方便的进程宏，在编写 eBPF 程序时非常有用。例如，#[map] 用于定义映射，#[kprobe] 用于定义可以附加到内核函数的 BPF 程序。

• cargo-bpf - 一个 cargo 子命令，用于创建、构建和调试 eBPF 程序

功能

• 允许用户使用 Rust 编写 BPF 程序和用户空间程序
• 提供多种 BPF 映射类型
  1. HashMap、PerCpuHashMap、LruHashMap、LruPerCpuHashMap、Array、PerCpuArray、PerfMap、TcHashMap、StackTrace、ProgramArray、SockMap
• 提供多种 BPF 程序类型
  1. KProbe、KRetProbe、UProbe、URetProbe、SocketFilter、XDP、StreamParser、StreamVerdict、TaskIter、SkLookup
• 以声明式方式提供定义各种类型BPF程序和BPF映射的属性宏。
  1. #[kprobe]、#[kretprobe]、#[uprobe]、#[uretprobe]、#[xdp]、#[tc_action]、#[socket_filter]、#[stream_parser]、#[stream_verdict]、#[task_iter]
  2. #[映射]
• 可以从Linux内核头文件或从vmlinux的BTF中生成Rust绑定
• 为BPF程序和用户空间程序提供API，以帮助用户编写Rust风格代码
• 支持映射的BTF
• 支持固定映射和从固定中加载映射
• 支持对task的BPF迭代器
• 允许用户为tc操作编写BPF程序，RedBPF将这些程序编译成与tc命令兼容的ELF对象文件
• 提供BPF辅助函数的包装器
• 为用户空间程序提供perf events的异步流
• 支持多个LLVM版本
• 在加载BPF程序、BPF映射或BTF失败时显示BPF验证器日志
• 有几个示例程序，分为两部分：BPF程序和用户空间程序

要求

为了使用redBPF，您需要

• 系统上安装了LLVM 13、LLVM 12或LLVM 11
• Linux内核头文件或您想针对的vmlinux

当前在编译BPF程序时使用LLVM 12作为默认版本，但您可以指定其他LLVM版本，如下所示

• cargobuild --no-default-features --featuresllvm13
• cargobuild --no-default-features --featuresllvm11

如果您想使用其他LLVM版本安装cargo-bpf，则可以尝试以下命令

• cargoinstall cargo-bpf --no-default-features --features=llvm13,command-line
• cargoinstall cargo-bpf --no-default-features --features=llvm1,command-line

rust和LLVM版本的兼容组合

rustc使用它自己的LLVM版本。但RedBPF还需要在系统上安装LLVM。为了编译BPF程序，RedBPF首先使用rustc生成位码，然后通过直接调用LLVM API解析和优化位码。因此，在编译BPF程序时使用两个LLVM版本。

• rustc所依赖的LLVM版本
• 系统上安装的LLVM版本

两个版本应匹配。

第一个RedBPF执行rustc以生成位码，然后调用LLVM API来处理生成的位码。通常，LLVM可能会支持中间表示的向后兼容性。因此，使用与系统LLVM版本相同或低于的rustc是可行的。

• 编译redbpf所需的最小Rust版本是Rust 1.48

Linux内核

支持的最小内核版本为4.19。内核头文件将自动发现，或者您可以使用KERNEL_SOURCE环境变量指向特定位置。只要先运行make prepare，就可以支持针对Linux源树进行构建。

注意在容器内编译BPF程序。
您需要指定KERNEL_SOURCE或KERNEL_VERSION环境变量，以指示内核头文件。这些头文件应在容器内找到。例如，在包含Linux 5.11.0-25-generic内核头文件的Ubuntu 21.04容器中，您应按如下指定KERNEL_VERSION环境变量

# KERNEL_VERSION=5.11.0-25-generic cargo build --examples

如果您的容器有vmlinux，您可以使用它而不是Linux内核头文件。

# REDBPF_VMLINUX=/boot/vmlinux cargo build --examples

有关更多信息，请参阅build-test.sh。

在基于Debian的发行版上安装依赖项

在Debian、Ubuntu及其衍生版上，您可以通过运行以下命令来安装依赖项

sudo apt-get -y install build-essential zlib1g-dev \
		llvm-12-dev libclang-12-dev linux-headers-$(uname -r) \
		libelf-dev

如果您的发行版中没有LLVM 12，您可以将官方LLVM APT仓库添加到您的sources.list中。或者简单地运行您可以在llvm.sh中下载的脚本。请注意，此脚本仅适用于Debian或Ubuntu。

在基于RPM的发行版上安装依赖项

首先确保您的发行版包括LLVM 12

yum info llvm-devel | grep Version
Version      : 12.0.0

如果您没有版本12，您可以从Fedora 34仓库中获取。

然后运行以下命令安装依赖项

yum install clang llvm-devel zlib-devel kernel-devel

构建镜像

您可以参考包含构建RedBPF所需的最小必要软件包的各种Dockerfile：[RedBPF的Dockerfile](https://github.com/foniod/build-images/redbpf)

如果您想要准备构建foniod的Docker镜像，请参阅：[foniod的Dockerfile](https://github.com/foniod/build-images)

入门

开始的最简单方法是阅读基本教程。

您可以在此目录中找到几个示例。所有示例程序都被分成两部分：example-probes和example-userspace。`example-probes`包含在内核上下文中执行的BPF程序。`example-userspace`包括将BPF程序加载到内核空间并与BPF程序通过BPF映射进行通信的用户空间程序。

另请参阅 文档，其中包含 cargo-bpf 的说明。它提供了一个用于轻松编译 BPF 程序的 CLI 工具。

redbpf-tools 是一个由 cargo-bpf 生成的 crate，其中包含一些简单的示例，可以帮助您理解如何构建自己的程序。

最后，查看包含更多高级、具体生产就绪的 redbpf 程序示例的 foniod 项目。

从源代码构建

在克隆仓库后运行

git submodule sync
git submodule update --init

按照上述文档安装依赖项，然后像往常一样运行 cargo build。

许可证

此存储库包含以下目录中来自其他软件的代码，并按照它们各自的许可证进行许可：

• bpf-sys/libbpf：LGPL2 + BSD-2

“+” 表示它们是双许可的。

RedBPF 及其组件，除非另有说明，否则均根据以下任一许可证进行许可：

• Apache License 2.0，(LICENSE-APACHE 或 https://apache.ac.cn/licenses/LICENSE-2.0)
• MIT 许可证 (LICENSE-MIT 或 http://opensource.org/licenses/MIT)

任选其一。

贡献

该项目面向所有人。我们要求我们的用户和贡献者花几分钟时间审查我们的 行为准则。

除非您明确说明，否则任何有意提交以包含在您的工作中的贡献，如 Apache-2.0 许可证中定义的，均应按照上述方式双许可，而无需附加条款或条件。

有关入门的进一步建议，请参阅 贡献者指南。请注意，所有贡献都必须包含一个 开发者证书声明 签署行。