Ebpf Rust

eBPF in Rust with Aya

Contract

Inputs

• Program type and attach point (required): tracepoint, kprobe, uprobe, XDP, TC, LSM, or another type from the table in step 4.
• Kernel (required): BTF at /sys/kernel/btf/vmlinux for portability. Grounded floor is Linux 7.2 mainline or 6.18 LTS; every kernel feature named here exists on both.
• Toolchain (required): stable Rust plus a nightly with rust-src, bpf-linker, cargo-generate, and bpftool. The grounded Rust edition is 2024.

Procedure

1. Set up the toolchain and generate the project. Done when: cargo build succeeds on the fresh template.

rustup toolchain install stable
rustup toolchain install nightly --component rust-src
cargo install bpf-linker
cargo install cargo-generate
cargo generate https://github.com/aya-rs/aya-template   # prompts for name and program type

The template lays out <name>/ (user-space crate), <name>-ebpf/ (kernel-side crate), and <name>-common/ (shared types). A build script compiles the eBPF crate and embeds the object, so ordinary cargo build, cargo check, and cargo run --release drive both sides; there is no separate build step.

2. Write the kernel side with aya-ebpf and aya-log-ebpf. Done when: the crate compiles for the BPF target.

// <name>-ebpf/src/main.rs
#![no_std]
#![no_main]

use aya_ebpf::{
    helpers::bpf_get_current_pid_tgid,
    macros::{map, tracepoint},
    maps::HashMap,
    programs::TracePointContext,
};
use aya_log_ebpf::info;

#[map]
static CALL_COUNT: HashMap<u32, u64> = HashMap::with_max_entries(1024, 0);

#[tracepoint]
pub fn trace_read(ctx: TracePointContext) -> u32 {
    let pid = (bpf_get_current_pid_tgid() >> 32) as u32;
    let next = match unsafe { CALL_COUNT.get(&pid) } {
        Some(count) => *count + 1,
        None => 1,
    };
    let _ = CALL_COUNT.insert(&pid, &next, 0);
    info!(&ctx, "read() called by pid {}", pid);
    0
}

#[panic_handler]
fn panic(_info: &core::panic::PanicInfo) -> ! {
    // The verifier never lets a panic path run; this satisfies no_std.
    unsafe { core::hint::unreachable_unchecked() }
}

3. Write the user-space loader on tokio. Done when: the loader attaches, prints log lines, and exits on Ctrl-C.

// <name>/src/main.rs
use aya::{include_bytes_aligned, maps::HashMap, programs::TracePoint, Ebpf};
use aya_log::EbpfLogger;
use tokio::signal;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let mut bpf = Ebpf::load(include_bytes_aligned!(concat!(env!("OUT_DIR"), "/<name>")))?;
    EbpfLogger::init(&mut bpf)?;

    let program: &mut TracePoint = bpf.program_mut("trace_read").unwrap().try_into()?;
    program.load()?;
    program.attach("syscalls", "sys_enter_read")?;

    let counts: HashMap<_, u32, u64> = HashMap::try_from(bpf.map("CALL_COUNT").unwrap())?;

    signal::ctrl_c().await?;
    for entry in counts.iter().filter_map(Result::ok) {
        let (pid, count) = entry;
        println!("pid {pid}: {count} reads");
    }
    Ok(())
}

The template's build script sets the object path; take it from the generated main.rs rather than hard-coding one.

4. Pick the program macro and the map type. Done when: both are chosen and the attach target is known.

Kernel-side maps live in aya_ebpf::maps: HashMap, LruHashMap, PerCpuHashMap, Array, PerCpuArray, RingBuf, PerfEventArray, LpmTrie, ProgramArray, XskMap, and others. Prefer RingBuf for events. RingBuf::reserve returns an Option, so the kernel side must handle a full buffer.

use aya_ebpf::maps::RingBuf;

#[map]
static EVENTS: RingBuf = RingBuf::with_byte_size(256 * 1024, 0);

if let Some(mut entry) = EVENTS.reserve::<MyEvent>(0) {
    entry.write(MyEvent { pid, ts });
    entry.submit(0);
}

// User space: poll the ring buffer through tokio's AsyncFd.
use aya::maps::RingBuf;
use tokio::io::unix::AsyncFd;

let ring = RingBuf::try_from(bpf.take_map("EVENTS").unwrap())?;
let mut ring = AsyncFd::new(ring)?;
loop {
    let mut guard = ring.readable_mut().await?;
    let rb = guard.get_inner_mut();
    while let Some(item) = rb.next() {
        let event: &MyEvent = unsafe { &*(item.as_ptr() as *const MyEvent) };
        println!("event from pid {}", event.pid);
    }
    guard.clear_ready();
}

5. Generate kernel type bindings when the program reads kernel structs. Done when: vmlinux.rs exists in the eBPF crate and the field read compiles.

cargo install bindgen-cli
cargo install --git https://github.com/aya-rs/aya -- aya-tool
aya-tool generate task_struct > <name>-ebpf/src/vmlinux.rs

Read fields through aya_ebpf::helpers::bpf_probe_read_kernel. The generated types carry BTF relocations, so the loader adjusts field offsets to the running kernel when that kernel has CONFIG_DEBUG_INFO_BTF.

6. Debug a load failure. Aya surfaces the verifier log as the error text. Done when: the error is mapped to its cause and the program loads.

RUST_LOG=debug cargo run --release 2>&1 | grep -A 20 verifier
bpftool btf dump file /sys/kernel/btf/vmlinux | grep task_struct
bpftool prog list
bpftool prog dump xlated name trace_read

For the C and libbpf side, use ebpf. For the tokio patterns in the loader, use rust-async-internals. For the raw pointer reads on the kernel side, use rust-unsafe.

Failure and recovery

Output

The kernel-side and user-space crates, the run command, the attach point, and evidence: log lines or map entries for a live event, or the verifier message mapped to its fix.