Rust Aya 編寫 eBPF 程式

本文地址：https://www.ebpf.top/post/ebpf_rust_aya

1. 前言

Linux 核心 6.1 版本中有一個非常引人注意的變化：引入了對 Rust 程式語言的支援。Rust 是一種系統程式語言，Rust 通過提供非常強大的編譯時保證和對記憶體生命週期的明確控制。在核心開發中引入 Rust 語言，將會為核心開發的早期帶來更多的安全保障。eBPF 是在核心中基於事件執行使用者自定義程式的技術，其驗證器機制可以保障執行在核心中 eBPF 程式的安全性。

Rust 與 eBPF 有著一個共同的目標：保證核心安全，只是兩者側重的維度有所不同。

儘管使用 Rust 編寫 eBPF 程式多數情況下都需要通過不安全的方式在核心進行記憶體讀寫，但是基於 Rust 和 Aya ，的確能夠給我們帶來一個快速和高效的開發體驗，這包括自動生成整個程式框架（eBPF 程式及對應的使用者空間程式碼）、引數檢查確認、錯誤處理、統一的相關構建和管理方式等等。

Aya 是一個以可操作性和開發者體驗為重點的 eBPF 庫，完全是在 Rust 基礎上建立的，只使用 libc 包來執行系統呼叫。Aya 官方倉庫地址為 https://github.com/aya-rs/aya/，當前版本為 v0.1.11，專案還處於偏早期。基於 Aya 庫開發 eBPF 程式可以給我們帶來以下的便利：

基於 Rust 的 Cargo 工具來管理、構建和測試專案；
支援 CO-RE 直接生成與 Rust 與核心檔案的繫結；
使用者工具程式碼（Rust）與執行在的核心中的 eBPF 程式碼輕鬆共用程式碼；
對於 LLVM、libbpf、bcc 等完全沒有任何依賴；

本文僅是基於 Aya 編寫 eBPF 程式及使用者空間程式的生成和測試的過程記錄，不涉及到對於生成 Rust 程式碼的詳細解讀。

2. Rust 開發環境搭建

2.1 建立 VM 虛擬機器器

為了使用 Rust 進行 eBPF 程式編寫，那麼我們首先需要在本地搭建一個 Rust 開發環境。這裡我仍然採用 multipass 工具快速搭建一個 Ubuntu 22.04 LTS 的環境。

$ multipass launch --name rust-aya -d 20G

預設磁碟為 5G，比較容易造成磁碟空間滿，因此這裡將磁碟空間大小設定為 20G，你可以根據自己的情況調整。

對於已經建立的 mulipass 範例可以在建立後進行調整，則需要 multipass 版本大於 1.10，而且需要調整的範例處於停止狀態，詳細可參見調整範例設定，例如 multipass set local.rust-aya.cpus=4 或 multipass set local.rust-aya.memory=8G 分別用於調整範例的 CPU 和 MEM 大小。

2.2 安裝 Rust 開發環境

通常情況下，Rust 開發環境推薦通過 rustup 工具管理，我們可以通過以下命令快速安裝該工具：

$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

一般情況下我們選擇預設選項安裝。整個安裝過程會下載一個指令碼完成 rustup 工具安裝，同時也會安裝最新的 Rust 穩定版本。如果安裝順利，我們可以在最後看到如下的資訊：

...
	stable-x86_64-unknown-linux-gnu installed - rustc 1.65.0 (897e37553 2022-11-02)

Rust is installed now. Great!

To get started you may need to restart your current shell.
This would reload your PATH environment variable to include
Cargo's bin directory ($HOME/.cargo/bin).

To configure your current shell, run:
source "$HOME/.cargo/env"

在 rustup 工具安裝完成後，我們可以使用其安裝 Rust 穩定版（實際上預設已經安裝）和 nightly ，其中 nightly 為開發者體驗新功能的釋出通道，Rust 2021 年開始支援編譯 eBPF，當前使用 Aya 需要基於 Rust Nightly 版本。

Rust 有 3 個釋出通道：

Nightly

Beta

Stable（穩定版）

大部分 Rust 開發者主要採用穩定版通道，不過希望實驗新功能的開發者可能會使用 nightly 或 beta 版。詳情參見附錄 G：Rust 是如何開發的與「Nightly Rust」

$ source "$HOME/.cargo/env"
$ rustup install stable  # rustup 命令已經預設安裝
info: syncing channel updates for 'stable-x86_64-unknown-linux-gnu'

  stable-x86_64-unknown-linux-gnu unchanged - rustc 1.65.0 (897e37553 2022-11-02)

info: checking for self-updates
$ rustup toolchain install nightly --component rust-src
...
info: installing component 'rustfmt'

  nightly-x86_64-unknown-linux-gnu installed - rustc 1.67.0-nightly (09508489e 2022-11-04)

info: checking for self-updates

$ rustup toolchain list
stable-x86_64-unknown-linux-gnu (default)
nightly-x86_64-unknown-linux-gnu

安裝 nightly 以後我們可以使用 rustup toolchain list 檢視本地開發環境的開發工具鏈。

2.3 安裝 bpf-linker 依賴和 bpftool 工具

為了使用 Aya，我們還需要安裝依賴包 bpf-linker，但其依賴與 LLVM/Clang 等工具，因此我們也需要提前安裝：

$ sudo apt-get update
$ sudo apt-get install llvm clang -y
$ cargo install bpf-linker

最後，為了生成核心資料結構的繫結，我們還必須安裝 bpftool，可以從發行版中安裝或從原始碼中構建，這裡我選用發行版安裝方式（基於 Ubuntu 22.04），原始碼安裝可參考 bpftool 倉庫說明檔案：

$ sudo apt install linux-tools-common linux-tools-5.15.0-52-generic linux-cloud-tools-5.15.0-52-generic -y

支援我們完成了基於 Aya 開發的整個環境及依賴的安裝。

3. Aya 嚮導建立 eBPF 程式

3.1 使用嚮導建立專案

Aya 提供了一套模版嚮導用於建立 eBPF 對應的程式型別，嚮導建立依賴於 cargo-generate，因此我們需要在執行程式嚮導前提前安裝：

$ cargo install cargo-generate

我在安裝 cargo-generate 過程中遇到了如下的錯誤，主要是由於依賴 openssl 庫問題導致，如果你也遇到類似問題可參考 cargo-generate 安裝指南和 Rust OpenSSL 檔案，如果一切順利，則可忽略此處的提示。
...
warning: build failed, waiting for other jobs to finish...
error: failed to compile `cargo-generate v0.16.0`, intermediate artifacts can be found at `/tmp/cargo-install8NrREg
...

$ sudo apt install openssl pkg-config libssl-dev gcc m4 ca-certificates make perl -y
# 重新安裝即可

在完成依賴後，我們就可以使用嚮導來建立 eBPF 專案，這裡以 XDP 型別程式為例：

$ cargo generate https://github.com/aya-rs/aya-template

這裡我們輸入專案名稱 myapp，eBPF 程式型別選擇 xdp，完成相關設定後，嚮導會自動幫我們建立一個名為 myapp 的 Rust 專案，專案包括了一個最簡單的 XDP 型別的 eBPF 程式及相對應的使用者空間程式。 myapp 目錄的整體夾頭如下所示：

├── Cargo.lock
├── Cargo.toml
├── README.md
├── myapp  # 使用者空間程式
│   ├── Cargo.toml
│   └── src
│       └── main.rs
├── myapp-common  # eBPF 程式與使用者空間程式複用的程式碼庫
│   ├── Cargo.toml
│   └── src
│       └── lib.rs
├── myapp-ebpf  # eBPF 程式
│   ├── Cargo.lock
│   ├── Cargo.toml
│   ├── rust-toolchain.toml
│   └── src
│       └── main.rs
└── xtask  # build 相關的程式碼
    ├── Cargo.toml
    └── src
        ├── build_ebpf.rs
        ├── main.rs
        └── run.rs

8 directories, 15 files

生成的 eBPF 程式位於 myapp-ebpf/src 目錄下，檔名為 main.rs，完整內容如下所示：

$ cat myapp-ebpf/src/main.rs
#![no_std]
#![no_main]

use aya_bpf::{
    bindings::xdp_action,
    macros::xdp,
    programs::XdpContext,
};
use aya_log_ebpf::info;

#[xdp(name="myapp")]
pub fn myapp(ctx: XdpContext) -> u32 {
    match try_myapp(ctx) {
        Ok(ret) => ret,
        Err(_) => xdp_action::XDP_ABORTED,
    }
}

fn try_myapp(ctx: XdpContext) -> Result<u32, u32> {
    info!(&ctx, "received a packet"); // 每接受到一個封包則列印一個紀錄檔
    Ok(xdp_action::XDP_PASS)
}

#[panic_handler]
fn panic(_info: &core::panic::PanicInfo) -> ! {
    unsafe { core::hint::unreachable_unchecked() }
}

3.2 編譯 eBPF 程式

首先，我們使用 cargo 工具編譯 eBPF 對應的程式：

$ cd myapp
$ cargo xtask build-ebpf
...
   Compiling myapp-ebpf v0.1.0 (/home/ubuntu/myapp/myapp-ebpf)
     Running `rustc --crate-name myapp --edition=2021 src/main.rs --error-format=json \
     --json=diagnostic-rendered-ansi,artifacts,future-incompat --crate-type bin \
     --emit=dep-info,link -C opt-level=3 -C panic=abort -C lto -C codegen-units=1 
     -C metadata=dd6140d48c387b43 -C extra-filename=-dd6140d48c387b43 \
     --out-dir \
		...
     -Z unstable-options \
    Finished dev [optimized] target(s) in 11.76s

編譯完成後，對應的程式儲存在 target 目錄下：

~/myapp$ ls -hl target/bpfel-unknown-none/debug/
...
-rw-rw-r-- 2 ubuntu ubuntu 3.5K Nov  6 22:24 myapp

~/myapp$ file target/bpfel-unknown-none/debug/myapp
target/bpfel-unknown-none/debug/myapp: ELF 64-bit LSB relocatable, eBPF, version 1 (SYSV), not stripped

/myapp$ llvm-objdump -S target/bpfel-unknown-none/debug/myapp

target/bpfel-unknown-none/debug/myapp:	file format elf64-bpf

Disassembly of section xdp/myapp:

0000000000000000 <myapp>:
...
     242:	bf 61 00 00 00 00 00 00	r1 = r6
     243:	18 02 00 00 00 00 00 00 00 00 00 00 00 00 00 00	r2 = 0 ll
     245:	18 03 00 00 ff ff ff ff 00 00 00 00 00 00 00 00	r3 = 4294967295 ll
     247:	bf 04 00 00 00 00 00 00	r4 = r0
     248:	b7 05 00 00 aa 00 00 00	r5 = 170
     249:	85 00 00 00 19 00 00 00	call 25

至此，已經完成了 eBPF 程式的編譯工作，接著我們需要繼續編譯使用者空間程式碼。

3.3 執行使用者空間程式

我們可以直接使用 cargo 命令來執行使用者空間程式：

$ RUST_LOG=info cargo xtask run
...
    Finished dev [unoptimized + debuginfo] target(s) in 8.38s
Error: failed to attach the XDP program with default flags - try changing XdpFlags::default() to XdpFlags::SKB_MODE

Caused by:
    unknown network interface eth0

RUST_LOG=info 為設定紀錄檔級別的環境變數，預設為 warn，但嚮導生成的程式碼列印的紀錄檔級別預設為 info，因此需要執行時制定，否則可能會出現程式執行檢視不到紀錄檔的情況。

cargo xtask run 命令會直接編譯使用者空間程式碼並執行，但是執行過程中我們發現出現錯誤 unknown network interface eth0，這是因為預設生成的程式指定將 XDP 程式載入到 eth0 網路卡，而我們的 VM 預設網路卡不為 eth0 導致，這裡我們明確制定網路卡使用 lo 測試，再次執行結果如下：

$ RUST_LOG=info cargo xtask run -- --iface lo
...
    Finished dev [optimized] target(s) in 0.19s
    Finished dev [unoptimized + debuginfo] target(s) in 0.12s
[2022-11-05T16:25:27Z INFO  myapp] Waiting for Ctrl-C...

這次可以發現使用者空間程式已經正常執行，並且將對應的 eBPF 程式載入至核心中。

$ sudo bpftool prog list
42: xdp  name myapp  tag 2929f83b3be0f64b  gpl
	loaded_at 2022-11-06T22:42:54+0800  uid 0
	xlated 2016B  jited 1151B  memlock 4096B  map_ids 14,13,15
	
$ ip link show
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 xdpgeneric qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
    prog/xdp id 42 # <=== 載入的 eBPF 程式 id 42

我們啟動網路卡在 lo 網路卡的 ping 包驗證：

我們可以看到當我們在另外一個視窗在本地埠執行 ping -c 1 127.0.0.1 命令的同時，在執行使用者空間 myapp 的程式紀錄檔中列印了對應的紀錄檔 received a packet。

至此，我們就完成了整個基於 Aya 最簡單 XDP 程式的驗證，如果你打算進階一步列印報文紀錄檔或者對特定包進行對齊，則可以參考 Aya Book 中對應的章節。

4. 總結

通過對於 Aya 整個過程中的使用，我們可以發現使用 Aya 開發 eBPF 程式的確給我們帶來了諸多的便利，通過嚮導搭建了整個專案的基本框架，並且實現了編譯、載入等相關的管理工作，特別是對於新手入門更加友好。預設生成的使用者空間程式碼與 eBPF 程式碼實現了一定程度的程式碼複用，特別是紀錄檔相關的列印更加便捷。同時，該專案當前的檔案還不是特別完整，諸如 Probe/Tracepoint/XDP 等程式型別的檔案還在完善中，如果你有興趣也歡迎投入到相關的建設中。更多介紹可參考 Aya: Rust 風格的 eBPF 夥伴。

同時，也期待 libbpf-bootstrap 專案能夠早日實現 Aya 嚮導式的 eBPF 程式程式碼建立，這對於編寫 eBPF 相關的程式的確提供了快速上手的體驗。