DEV Community: Joseph Ligier

XDP: The Ultra-Fast Firewall Inside Linux

Joseph Ligier — Thu, 16 Oct 2025 12:59:38 +0000

In the previous episode, we took a detailed look at uProbes with eBPF. In hindsight, it was more of an in-depth exploration of what we had seen with Tracepoints. In particular, I discovered the great tool that is bpftrace, which allowed me to take a slightly different angle on eBPF programs.

For the next episode, I needed an eBPF program that was really different from anything related to tracing. There were two categories of eBPF programs left: network-oriented and security-oriented.

As its acronym suggests, eBPF (extended Berkeley Packet Filter) was originally designed for networking. It would have been a shame not to continue this journey into the world of eBPF without exploring this essential dimension. At first, I immediately ruled out XDP: too many examples, too many articles. It would have been difficult to stand out.

But after much thought:

“Cilium mainly uses the classifier, which can be quite useful.”
“XDP is still the ultimate eBPF program.”
“Were you familiar with the classifier before you became interested in eBPF?”
“XDP is the ultimate proof that it's more powerful than Iptables.”
“XDP is the gateway to networking in eBPF.”

I ended up changing my mind.

XDP

XDP stands for eXpress Data Path.

Why “express”?

Because this eBPF program reacts very quickly, even before the packet arrives in the Linux kernel network stack!

However, this advantage comes with some constraints: we have to do some sewing in the network packet...

The rest is in my article:

XDP: The Ultra-Fast Firewall Inside Linux · The Little Jo’s Blog

An introduction to XDP with Aya

blog.littlejo.link

uProbe: Observability for All Developers

Joseph Ligier — Mon, 08 Sep 2025 12:28:03 +0000

When I finished my introduction to eBPF with Aya, I was already happy to have started to understand eBPF a little better, but I felt like I still had a lot to learn. In fact, we had mainly looked at Tracepoints, but I had deliberately left out the other types of eBPF programs because I had to make a choice so as not to get sidetracked.

So where to start now? There are about thirty of them (and not yet fifty at the time of writing this article). So I looked for a type of eBPF program that could be useful not only for Linux kernel developers or network experts, and that wasn't too complex. I opted for uProbes.

uProbes

What are they used for? Let's take an example: you've written a program in Go. You'd like to know how long it takes to execute a function. Instead of adding your code with println, uProbes give you a very clean answer and allow you to profile a function in your program without modifying a single line of code...

Observability for All Developers with uProbes · The Little Jo’s Blog

An introduction to eBPF uProbes and uRetProbes with Aya

blog.littlejo.link

Tracing your syscalls with Aya

Joseph Ligier — Fri, 11 Apr 2025 13:36:00 +0000

I'm getting started with eBPF programming with Aya. The idea behind this series of articles is to get you started too.

In the previous part, we looked at a way to better structure an eBPF program by separating it into smaller eBPF programs. In this part, we'll put the finishing touches to that introduction by creating another eBPF program and having it communicate with the first one using eBPF maps.

This will allow us to learn tracing and review the basics of eBPF.

🇫🇷FYI, this is the English version of an article originally published in French.🇫🇷

Creation of a second eBPF program

Reminder

If you're jumping on the bandwagon, the initial program logs all binaries running on your computer. To do this, we used Tracepoint with the hook syscalls:sys_enter_execve. In part 3, we created a filter to prevent logging when certain binaries were executed. In the previous section, we used tail calls to better structure the code.

What are we going to do now?

We're going to create another Tracepoint program with the hook syscalls:sys_exit_execve. In the second part, we saw that Tracepoints in the syscalls category actually had two Tracepoints:

the input one: sys_enter_$syscall
the output one: sys_exit_$syscall

What this will allow us to do next:

Tracing: calculate the duration of each execve syscall.
Filtering: display only execve syscalls that have not had an error.

Project cloning

Although this follows on from part 4, I recommend that you retrieve the project:

git clone https://github.com/littlejo/aya-examples
cd aya-examples/tracepoint-binary-tail-calls/
RUST_LOG=info cargo run # Check it works before modification

You can also do the Killercoda lab, which follows step-by-step the creation of tracing:

Let's create a "hello world" program

We're going to create a "hello world" program which is attached to the Tracepoint of category syscalls and name sys_exit_execve.

We're already going to create the program in kernel space. We'll create a file in the tracepoint-binary-ebpf/src directory.

We'll copy the hook.rs file and add _exit :

cp tracepoint-binary-ebpf/src/hook.rs tracepoint-binary-ebpf/src/hook_exit.rs
sed -i 's/tracepoint_binary/tracepoint_binary_exit/' tracepoint-binary-ebpf/src/hook_exit.rs

We delete anything unrelated to the program for the sys_enter_execve syscall. We end up with :

use aya_ebpf::{
    macros::tracepoint, programs::TracePointContext,
};

use aya_log_ebpf::info;

#[tracepoint]
pub fn tracepoint_binary_exit(ctx: TracePointContext) -> u32 {
    match try_tracepoint_binary_exit(ctx) {
        Ok(ret) => ret,
        Err(ret) => ret as u32,
    }
}

fn try_tracepoint_binary_exit(ctx: TracePointContext) -> Result<u32, i64> {
    info!(&ctx, "tracepoint sys_exit_execve called.");
    Ok(0)
}

Then we'll add the line mod hook_exit; to the main.rs file so that cargo includes the file.
We're now going to modify the user space code to load this program. We therefore need to modify this file: tracepoint-binary/src/main.rs. We'll duplicate the Tracepoint loading and attachment code:

let program: &mut TracePoint = ebpf.program_mut("tracepoint_binary").unwrap().try_into()?;
program.load()?;
program.attach("syscalls", "sys_enter_execve")?;

You can insert it, for example, just after the copied code.
And we'll adapt it with the program name: tracepoint_binary_exit and the attachment point which is sys_exit_execve:

let program: &mut TracePoint = ebpf.program_mut("tracepoint_binary_exit").unwrap().try_into()?;
program.load()?;
program.attach("syscalls", "sys_exit_execve")?;

If it's not clear here's the modified code:

We've just created the “hello world” for the Tracepoint syscalls:sys_exit_execve. Let's test it:

RUST_LOG=info cargo run

The code we've just created isn't really rocket science: it's just copy-paste and value modification. We could create functions if we wanted to avoid duplicate code. We're done in user space until the end of the part. Now we're going to play in kernel space. So we'll only be modifying code in the tracepoint-binary-ebpf/src/ directory.

Return of the Jedi

As we saw in part 2, we can retrieve data from a tracepoint. Let's take a look at what the following command does:

cat /sys/kernel/debug/tracing/events/syscalls/sys_exit_execve/format

The only field I find interesting is ret. It is offset at 16. This gives the return code of the execve system call.
How to display it? We'll have to follow the example of the other hook program in unsafe mode:

let filename_src_addr = ctx.read_at::<*const u8>(FILENAME_OFFSET)?;

So we'll have something like :

let ret = unsafe { ctx.read_at::<????????>(16)? };

The problem is now to find the data type.

We had this for the previous example:

field:const char * filename;    offset:16;      size:8; signed:0;

const char * is a bit equivalent to *const u8 so it's consistent.

But here we have :

field:long ret; offset:16;      size:8; signed:1;

So we need to find the equivalent of long in Rust.
signed:1 so it's already an integer of type i?? .

According to this site, long corresponds to 8 bytes. So we'd have i64.
So for hook_exit.rs :

let ret = unsafe { ctx.read_at::<i64>(16)? };

This gives us :

fn try_tracepoint_binary_exit(ctx: TracePointContext) -> Result<u32, i64> {
    let ret = unsafe { ctx.read_at::<i64>(16)? };
    info!(&ctx, "tracepoint sys_exit_execve called. ret: {}", ret);
    Ok(0)
}

We can now test :

Note that the man command fails, but that syscall execve worked, which is normal:

execution of the binary was successful
man returns code 1 because it has no arguments

Code: Return

By the way, how do you get return codes for execve other than 0? I counted 3 cases of error:

The binary doesn't exist (code: -2):

The binary exists but is not executable (code: -13):

The binary is executable but doesn't have the right libraries, e.g. a binary from a Mac(code: -8):

Note that using i64 looks a bit like overkill 😅

Tracing execve syscall

Now that we've created a second eBPF program, let's play with the first. In part 1, I said it was possible to create programs for tracing, so let's take a look at how to calculate the time taken by a syscall execve between its input (sys_enter_execve) and its output (sys_exit_execve).

Creating timers

The first thing to find is a way to measure time at a given moment. In eBPF, there's a helper function for this: bpf_ktime_get_ns(). It displays the time in nanoseconds since the system was started (So it's not the unix time):

To use it in Rust, there is the Aya library which makes a binding :

So to use it, you need to add the library for each file it uses:

use aya_ebpf_bindings::helpers::bpf_ktime_get_ns;

We add the function at the beginning of each program starting with hook. For the file hook.rs :

fn try_tracepoint_binary(ctx: TracePointContext) -> Result<u32, i64> {
    let t = unsafe{ bpf_ktime_get_ns() };
    debug!(&ctx, "hook {}", t); //we modify to have the timestamp
[...]

and for the file hook_exit.rs :

fn try_tracepoint_binary_exit(ctx: TracePointContext) -> Result<u32, i64> {
    let t = unsafe{ bpf_ktime_get_ns() };
    debug!(&ctx, "exit {}", t);
[...]

Now let's test:

RUST_LOG=debug cargo run

We forgot to tell Cargo to download the aya_ebpf_binding library.
So we need to modify the file: tracepoint-binary-ebpf/Cargo.toml :

[package]
name = "tracepoint-binary-ebpf"
version = "0.1.0"
edition = "2021"

[dependencies]
tracepoint-binary-common = { path = "../tracepoint-binary-common" }
aya-ebpf = { workspace = true }
aya-log-ebpf = { workspace = true }
aya-ebpf-bindings = "0.1.1" #You just need to add this line
[build-dependencies]
which = { workspace = true }

[[bin]]
name = "tracepoint-binary"
path = "src/main.rs"

Let's test again:

RUST_LOG=debug cargo run

Typing ls then man in another console finds :

Transmission between eBPF programs

Now that we have the timestamp of the two Tracepoints, all we have to do is calculate the difference. We could imagine user processing afterwards, but that's not interesting. Instead, we'll use an eBPF map to transmit the timestamp to the other eBPF program.

What type of eBPF map? We could imagine a map with array type with a single value. But if there are two binaries running at almost the same time, aren't we running the risk of false tracings?

A map with per cpu array type may seem attractive. But what if the input Tracepoint isn't on the same CPU as the output one? I tried. Now I have a comment in the code that says never again.

So we need to find another type of map to communicate between two separate eBPF programs.

One solution would be to create a dictionary with a single entry for the sys_enter_execve and sys_exit_execve tracepoint. That way, there would be no possibility of stepping on each other's toes.

But what could possibly link them? The process identifier (the famous PID) which executes the program.

To retrieve the PID, use the helper function bpf_get_current_pid_tgid() :

Please note: this function does not retrieve the pid/tgid of the eBPF program, but rather the program being executed.

For the rest, I arbitrarily use tgid but it's not necessarily the right choice.

If you want to know the difference between tgid and pid, there's this excellent blog article by Yuki Nakamura (I've looked into it: he's not Aya's brother):

So we go with a HashMap with the tgid as input? It might work in the short term, but remember that eBPF maps have a fixed size. It would therefore fill up pretty quickly. So we'd need a way of purging at the end of processing to avoid this. Another solution would be to find a map that would do the job: LruHashMap. As we saw in the section on maps, it automatically deletes the least recent dictionary entries.

In the common.rs file, add the following map:

#[map]
pub static T_ENTER: LruHashMap<u32, u64> = LruHashMap::with_max_entries(16, 0);

Don't forget to update the libraries to be used:

use aya_ebpf::{
    macros::map,
    maps::{HashMap, PerCpuArray, ProgramArray, LruHashMap},
    programs::TracePointContext,
};

To fill the map, in the hook.rs file, simply add to the try_tracepoint_binary() function:

let tgid = (bpf_get_current_pid_tgid() >> 32) as u32;
T_ENTER.insert(&tgid, &t, 0)?;

This gives us :

fn try_tracepoint_binary(ctx: TracePointContext) -> Result<u32, i64> {
    let t = unsafe{ bpf_ktime_get_ns() };
    debug!(&ctx, "main {}", t);
    let buf = BUF.get_ptr_mut(0).ok_or(0)?;
    let tgid = (bpf_get_current_pid_tgid() >> 32) as u32;
    T_ENTER.insert(&tgid, &t, 0)?;
    unsafe {
        *buf = ZEROED_ARRAY;
        let filename_src_addr = ctx.read_at::<*const u8>(FILENAME_OFFSET)?;
        bpf_probe_read_user_str_bytes(filename_src_addr, &mut *buf)?;
    };

    try_tail_call(&ctx, 0);

    Ok(0)
}

Don't forget to add the library :

use aya_ebpf::helpers::bpf_get_current_pid_tgid;

To retrieve the map from the hook_exit.rs file on the try_tracepoint_binary_exit() function side:

let tgid = (bpf_get_current_pid_tgid() >> 32) as u32;
let t_enter = unsafe { T_ENTER.get(&tgid).ok_or(0)? };

You can easily tell the difference now:

fn try_tracepoint_binary_exit(ctx: TracePointContext) -> Result<u32, i64> {
    let t = unsafe{ bpf_ktime_get_ns() };
    let tgid = (bpf_get_current_pid_tgid() >> 32) as u32;
    let t_enter = unsafe { T_ENTER.get(&tgid).ok_or(0)? };
    debug!(&ctx, "exit {}", t);
    let ret :i64 = unsafe { ctx.read_at(16)? };
    info!(&ctx, "tracepoint sys_exit_execve called. ret: {}, duration: {}", ret, t - t_enter);
    Ok(0)
}

Add dependency recovery:

use aya_ebpf::helpers::bpf_get_current_pid_tgid;
use crate::common::*;

We can now test:

RUST_LOG=info cargo run

Merge logs

eBPF map type problem

Now that we've managed to retrieve the duration of the execve syscall, it would be nice to have everything on the same line: binary name, duration and return code. The output tracepoint program must therefore be able to retrieve the buffer filled by the input tracepoint program. The problem is the map type BUF : PerCpuArray. As we saw in the previous section, the two different eBPF programs may not point to the same CPU. So we need to change the map type. We'll take the same type of map as before: LruHashMap with tgid as the common value. In the common.rs file, we replace :

#[map]
pub static BUF: PerCpuArray<[u8; MAX_PATH_LEN]> = PerCpuArray::with_max_entries(1, 0);

by:

#[map]
pub static BUF: LruHashMap<u32, [u8; MAX_PATH_LEN]> = LruHashMap::with_max_entries(16, 0);

We'll need to modify all the code that uses the BUF map.

Hook file conversion

Let's start by modifying the hook.rs file:

fn try_tracepoint_binary(ctx: TracePointContext) -> Result<u32, i64> {
    let t = unsafe{ bpf_ktime_get_ns() };
    debug!(&ctx, "main {}", t);
    let buf = BUF.get_ptr_mut(0).ok_or(0)?; //TO_CHANGE
    let tgid = (bpf_get_current_pid_tgid() >> 32) as u32;
    T_ENTER.insert(&tgid, &t, 0)?;
    unsafe {
        *buf = ZEROED_ARRAY; //TO_CHANGE
        let filename_src_addr = ctx.read_at::<*const u8>(FILENAME_OFFSET)?;
        bpf_probe_read_user_str_bytes(filename_src_addr, &mut *buf)?;
    };

    try_tail_call(&ctx, 0);

    Ok(0)
}

To replace let buf = BUF.get_ptr_mut(0).ok_or(0)?;, we'll use the equivalent function for Hash :

This gives us :

let buf = BUF.get_ptr_mut(&tgid).ok_or(0)?;

To reset the buffer, we'll use the function to add a key and a value to a hash map:

We'll then have :

BUF.insert(&tgid, &ZEROED_ARRAY, 0)?;

Which gives us :

fn try_tracepoint_binary(ctx: TracePointContext) -> Result<u32, i64> {
    let t = unsafe{ bpf_ktime_get_ns() };
    debug!(&ctx, "main {}", t);
    let tgid = (bpf_get_current_pid_tgid() >> 32) as u32;
    T_ENTER.insert(&tgid, &t, 0)?;
    BUF.insert(&tgid, &ZEROED_ARRAY, 0)?; //CHANGED
    let buf = BUF.get_ptr_mut(&tgid).ok_or(0)?; //CHANGED
    unsafe {
        let filename_src_addr = ctx.read_at::<*const u8>(FILENAME_OFFSET)?;
        bpf_probe_read_user_str_bytes(filename_src_addr, &mut *buf)?;
    };

    try_tail_call(&ctx, 0);

    Ok(0)
}

Converting the filter file

The main code of the filter.rs file to be modified:

fn try_tracepoint_binary_filter(ctx: TracePointContext) -> Result<u32, i64> {
    debug!(&ctx, "filter");
    let buf = BUF.get(0).ok_or(0)?; //TO_CHANGE

    let is_excluded = unsafe { EXCLUDED_CMDS.get(buf).is_some() };

    if is_excluded {
        debug!(&ctx, "No log for this Binary");
        return Ok(0);
    }
    try_tail_call(&ctx, 1);

    Ok(0)
}

To retrieve the buffer, use the get function:

This must be replaced by :

let tgid = (bpf_get_current_pid_tgid() >> 32) as u32; //we retrieve the tgid
let buf = unsafe { BUF.get(&tgid).ok_or(0)? }; //we access to the data using tgid

The main code of filter.rs thus becomes :

use aya_ebpf::helpers::bpf_get_current_pid_tgid; //Don't forget library

[...]

fn try_tracepoint_binary_filter(ctx: TracePointContext) -> Result<u32, i64> {
    debug!(&ctx, "filter");
    let tgid = (bpf_get_current_pid_tgid() >> 32) as u32; //ADD
    let buf = unsafe { BUF.get(&tgid).ok_or(0)? }; //CHANGED

    let is_excluded = unsafe { EXCLUDED_CMDS.get(buf).is_some() };

    if is_excluded {
        debug!(&ctx, "No log for this Binary");
        return Ok(0);
    }

    try_tail_call(&ctx, 1);

    Ok(0)
}

Converting the display file

The main code of display.rs to be modified :

fn try_tracepoint_binary_display(ctx: TracePointContext) -> Result<u32, i64> {
    debug!(&ctx, "display");
    let buf = BUF.get(0).ok_or(0)?; //TO_CHANGE
    let cmd = &buf[..];
    let filename = unsafe { from_utf8_unchecked(cmd) };
    info!(
        &ctx,
        "tracepoint sys_enter_execve called. Binary: {}", filename
    );
    Ok(0)
}

In a similar way to filter.rs, you'll get :

use aya_ebpf::helpers::bpf_get_current_pid_tgid; //Don't forget the library

fn try_tracepoint_binary_display(ctx: TracePointContext) -> Result<u32, i64> {
    debug!(&ctx, "display");
    let tgid = (bpf_get_current_pid_tgid() >> 32) as u32; //ADD
    let buf = unsafe { BUF.get(&tgid).ok_or(0)? }; //CHANGED
    let cmd = &buf[..];
    let filename = unsafe { from_utf8_unchecked(cmd) };

    info!(
        &ctx,
        "tracepoint sys_enter_execve called. Binary: {}", filename
    );
    Ok(0)
}

You can recompile now, it works.
As you can see, converting an eBPF map isn't terribly complicated, but it's still best to get the right type right from the start.

Retrieving a map in the `hook_exit.rs` program

Now that we've converted the eBPF map, we can retrieve the data in the hook_exit.rs program:

fn try_tracepoint_binary_exit(ctx: TracePointContext) -> Result<u32, i64> {
    let t = unsafe{ bpf_ktime_get_ns() };
    let tgid = (bpf_get_current_pid_tgid() >> 32) as u32;
    let t_enter = unsafe { T_ENTER.get(&tgid).ok_or(0)? };
    debug!(&ctx, "exit {}", t);
    let ret :i64 = unsafe { ctx.read_at(16)? };
    info!(&ctx, "tracepoint sys_exit_execve called. ret: {}, duration: {}", ret, t - t_enter); //TO_CHANGE
    Ok(0)
}

Just copy the right lines from the display.rs program:

let buf = unsafe { BUF.get(&tgid).ok_or(0)? };
let cmd = &buf[..];
let filename = unsafe { from_utf8_unchecked(cmd) };

And modify info! accordingly.

The end result is:

use core::str::from_utf8_unchecked; // Don't forget the library

fn try_tracepoint_binary_exit(ctx: TracePointContext) -> Result<u32, i64> {
    let t = unsafe{ bpf_ktime_get_ns() };
    let tgid = (bpf_get_current_pid_tgid() >> 32) as u32;
    let t_enter = unsafe { T_ENTER.get(&tgid).ok_or(0)? };
    let buf = unsafe { BUF.get(&tgid).ok_or(0)? }; //PASTE
    let cmd = &buf[..]; //PASTE
    let filename = unsafe { from_utf8_unchecked(cmd) }; //PASTE
    let ret :i64 = unsafe { ctx.read_at(16)? };
    debug!(&ctx, "exit {}", t);
    info!(&ctx, "tracepoint sys_exit_execve called. Binary: {}, ret: {}, duration: {}", filename, ret, t - t_enter); //CHANGED
    Ok(0)
}

Let's test:

RUST_LOG=info cargo run

After an ssh connection, we see that it launches binaries that don't exist.

But that's a bit of a shame, we've already created an eBPF program that displays this. And I'm not interested in the commands we've filtered and those with return codes other than 0. Why don't we reuse the filter and display programs instead?

Code enhancement

Grouping eBPF maps

To reuse the various eBPF programs, simply add this line :

try_tail_call(&ctx, 0);

to the hook_exit.rs program. But the display program has no access to the duration or return code. So you need to create new eBPF maps:

#[map]
pub static DURATION: LruHashMap<u32, u64> = LruHashMap::with_max_entries(16, 0);

#[map]
pub static RET: LruHashMap<u32, i64> = LruHashMap::with_max_entries(16, 0);

Uhh, isn’t that starting to be a lot of maps?

Accessing an eBPF map has a cost that could end up degrading the computer's performance. For our little program, it's transparent, but if the program continues to grow with more eBPF maps, it's going to show. The BUF, T_ENTER, DURATION and RET maps are structurally identical. Why not create a PROGRAM map to centralize the state of the eBPF program and replace these maps? To do this, we'll create a structure:

struct ProgramState {
    t_enter: u64, //Entry hook know that
    t_exit: u64, //Exit hook know that
    buffer: [u8; MAX_PATH_LEN], //Entry hook know that
    ret: i64, //Exit hook know that
}

I didn't set duration but rather t_exit. This will be subtracted in the display program. The program doesn't have to do much, it can just do this 😝
If you remember from part 2, to stick to C, we need to use aligned structures. So we're going to put this in common.rs :

#[repr(C)]
pub struct ProgramState {
    pub t_enter: u64,
    pub t_exit: u64,
    pub buffer: [u8; MAX_PATH_LEN],
    pub ret: i64,
}

I've added pub everywhere so that other files can access the structure and its contents, but I haven't found anything better.
We'll now have just one eBPF map, as opposed to the 4 we had before:

#[map]
pub static PROGRAM: LruHashMap<u32, ProgramState> = LruHashMap::with_max_entries(16, 0);

Before deleting the “old” maps, I advise you to keep them to avoid compilation errors:

#[map]
pub static T_ENTER: LruHashMap<u32, u64> = LruHashMap::with_max_entries(16, 0);

#[map]
pub static BUF: LruHashMap<u32, [u8; MAX_PATH_LEN]> = LruHashMap::with_max_entries(16, 0);

To sum up what we want to do in this section, it's a map that will centralize all information:

Modifying hook entry

For the entry program, we have two things to do:

insert: initialize the entry with the tgid
fill: fill this entry with known values for entry time and buffer.

The main hook.rs code is currently as follows:

fn try_tracepoint_binary(ctx: TracePointContext) -> Result<u32, i64> {
    let t = unsafe{ bpf_ktime_get_ns() };
    debug!(&ctx, "hook {}", t);
    let tgid = (bpf_get_current_pid_tgid() >> 32) as u32;
    BUF.insert(&tgid, &ZEROED_ARRAY, 0)?; //TO_CHANGE
    T_ENTER.insert(&tgid, &t, 0)?; //TO_CHANGE
    let buf = BUF.get_ptr_mut(&tgid).ok_or(0)?; //TO_CHANGE
    unsafe {
        let filename_src_addr = ctx.read_at::<*const u8>(FILENAME_OFFSET)?;
        bpf_probe_read_user_str_bytes(filename_src_addr, &mut *buf)?; //TO_CHANGE
    }

    try_tail_call(&ctx, 0);

    Ok(0)
}

The first thing to do is to create the default entry in the map. We'll then modify the values we retrieve (t_enter and buffer).

We'll create a constant in hook.rs:

const INIT_STATE: ProgramState = ProgramState {
    t_enter: 0,
    t_exit: 0,
    buffer: ZEROED_ARRAY,
    ret: 0,
};

A constant must be created to prevent the 512-byte limit from being exceeded.
It is placed next to the FILENAME_OFFSET constant.
To initialize, we'll use the following function:

This gives :

PROGRAM.insert(&tgid, &INIT_STATE, 0)?;

Now we'll modify the values of the tgid key with the following function:

To retrieve *mut V :

let program_ptr = PROGRAM.get_ptr_mut(&tgid).ok_or(0)?;

We'll get :

let program_state = unsafe { &mut *PROGRAM.get_ptr_mut(&tgid).ok_or(0)? };

So, to modify the t_enter entry, we need to do :

program_state.t_enter = t;

Then, to modify the buffer, do :

bpf_probe_read_user_str_bytes(filename_src_addr, &mut program_state.buffer)?;

We end up with :

fn try_tracepoint_binary(ctx: TracePointContext) -> Result<u32, i64> {
    let t = unsafe{ bpf_ktime_get_ns() };
    debug!(&ctx, "main {}", t);
    let tgid = (bpf_get_current_pid_tgid() >> 32) as u32;
    PROGRAM.insert(&tgid, &INIT_STATE, 0)?; //CHANGED
    let program_state = unsafe { &mut *PROGRAM.get_ptr_mut(&tgid).ok_or(0)? }; //CHANGED
    program_state.t_enter = t; //CHANGED
    unsafe {
        let filename_src_addr = ctx.read_at::<*const u8>(FILENAME_OFFSET)?;
        bpf_probe_read_user_str_bytes(filename_src_addr, &mut program_state.buffer)?; //CHANGED
    };

    try_tail_call(&ctx, 0);

    Ok(0)
}

We have to do the same for the other eBPF programs.

filter

For the filter program, only the buffer needs to be retrieved from the PROGRAM map:

The main code of the filter program:

fn try_tracepoint_binary_filter(ctx: TracePointContext) -> Result<u32, i64> {
    debug!(&ctx, "filter");
    let tgid = (bpf_get_current_pid_tgid() >> 32) as u32;
    let buf = unsafe { BUF.get(&tgid).ok_or(0)? }; //TO_CHANGE

    let is_excluded = unsafe { EXCLUDED_CMDS.get(buf).is_some() }; //TO_CHANGE

    if is_excluded {
        debug!(&ctx, "No log for this Binary");
        return Ok(0);
    }
    try_tail_call(&ctx, 1);

    Ok(0)
}

Just replace the buf variable :

let buf = unsafe { BUF.get(&tgid).ok_or(0)? };

with :

let program = unsafe { PROGRAM.get(&tgid).ok_or(0)? };

and therefore modify the code :

let is_excluded = unsafe { EXCLUDED_CMDS.get(buf).is_some() };

with :

let is_excluded = unsafe { EXCLUDED_CMDS.get(&program.buffer).is_some() };

We end up with the code :

fn try_tracepoint_binary_filter(ctx: TracePointContext) -> Result<u32, i64> {
    debug!(&ctx, "filter");
    let tgid = (bpf_get_current_pid_tgid() >> 32) as u32;

    let is_excluded = unsafe {
        let program = PROGRAM.get(&tgid).ok_or(0)?; //CHANGED
        EXCLUDED_CMDS.get(&program.buffer).is_some() //CHANGED
    };

    if is_excluded {
        debug!(&ctx, "No log for this Binary");
        return Ok(0);
    }

    try_tail_call(&ctx, 1);

    Ok(0)
}

display

For the display program, as for the filter program, only the buffer needs to be retrieved from the PROGRAM map:

The main code of display :

fn try_tracepoint_binary_display(ctx: TracePointContext) -> Result<u32, i64> {
    debug!(&ctx, "display");
    let tgid = (bpf_get_current_pid_tgid() >> 32) as u32;
    let buf = unsafe { BUF.get(&tgid).ok_or(0)? }; //TO_CHANGE
    let cmd = &buf[..]; //TO_CHANGE
    let filename = unsafe { from_utf8_unchecked(cmd) };
    info!(
        &ctx,
        "tracepoint sys_enter_execve called. Binary: {}", filename
    );
    Ok(0)
}

In the same way as for the filter program, we end up with :

fn try_tracepoint_binary_display(ctx: TracePointContext) -> Result<u32, i64> {
    debug!(&ctx, "display");
    let tgid = (bpf_get_current_pid_tgid() >> 32) as u32;
    let program = unsafe { PROGRAM.get(&tgid).ok_or(0)? }; //CHANGED
    let cmd = &program.buffer[..]; //CHANGED
    let filename = unsafe { from_utf8_unchecked(cmd) };

    info!(
        &ctx,
        "tracepoint sys_enter_execve called. Binary: {}", filename
    );
    Ok(0)
}

exit

For the exit program, we need to fill in the map values: the exit time and its return. We're also going to clean up the code for the display part, as the display program will do the work.

The main hook_exit code :

fn try_tracepoint_binary_exit(ctx: TracePointContext) -> Result<u32, i64> {
    let t = unsafe{ bpf_ktime_get_ns() };
    let tgid = (bpf_get_current_pid_tgid() >> 32) as u32;
    let t_enter = unsafe { T_ENTER.get(&tgid).ok_or(0)? }; //TO_CLEAN
    let buf = unsafe { BUF.get(&tgid).ok_or(0)? }; //TO_CLEAN
    let cmd = &buf[..]; //TO_CLEAN
    let filename = unsafe { from_utf8_unchecked(cmd) }; //TO_CLEAN
    let ret :i64 = unsafe { ctx.read_at(16)? };
    debug!(&ctx, "exit {}", t);
    info!(&ctx, "tracepoint sys_exit_execve called. Binary: {}, ret: {}, duration: {}", filename, ret, t - t_enter); //TO_CHANGE
    Ok(0)
}

For hook_exit, you need to modify the map as follows:

let program_state = unsafe { &mut *PROGRAM.get_ptr_mut(&tgid).ok_or(0)? };
program_state.t_exit = t;
program_state.ret = ret;

And I've cleaned up everything that didn't concern data retrieval and map filling.
This gives :

fn try_tracepoint_binary_exit(ctx: TracePointContext) -> Result<u32, i64> {
    let t = unsafe{ bpf_ktime_get_ns() };
    let tgid = (bpf_get_current_pid_tgid() >> 32) as u32;
    debug!(&ctx, "exit {}", t);
    let ret :i64 = unsafe { ctx.read_at(16)? };

    let program_state = unsafe { &mut *PROGRAM.get_ptr_mut(&tgid).ok_or(0)? }; //ADDED
    program_state.t_exit = t; //ADDED
    program_state.ret = ret; //ADDED

    debug!(&ctx, "tracepoint sys_exit_execve called. ret: {}", ret);
    Ok(0)
}

Now all the maps are filled. The hardest part is done! All that's left now is to use the PROGRAM map.
Don't forget to clean up the maps:

#[map]
pub static T_ENTER: LruHashMap<u32, u64> = LruHashMap::with_max_entries(16, 0);

#[map]
pub static BUF: LruHashMap<u32, [u8; MAX_PATH_LEN]> = LruHashMap::with_max_entries(16, 0);

They're no longer useful.

Adding features

Now that we've grouped the maps together, let's see how easy it is to add new features.

Modifying tail calls

We currently have 4 programs:

hook
hook_exit
filter
display

The tail call workflow is :

hook ➡️ filter ➡️ display

It's not possible to keep this because you have to wait for hook_exit to finish if you want to get the return code.

So we need to change it to :

hook_exit ➡️ filter ➡️ display

In schematic form, this transformation looks like this:

Cut the following line from hook.rs and paste it into hook_exit.rs:

try_tail_call(&ctx, 0);

And paste it into hook_exit.rs.

Filter return code

Now we can make full use of the PROGRAM map.
In the filter.rs file, simply check whether the return code is different from 0 :

fn try_tracepoint_binary_filter(ctx: TracePointContext) -> Result<u32, i64> {
    debug!(&ctx, "filter");
    let tgid = (bpf_get_current_pid_tgid() >> 32) as u32;

    let program = unsafe { PROGRAM.get(&tgid).ok_or(0)? };

    let is_excluded = unsafe {
        EXCLUDED_CMDS.get(&program.buffer).is_some()
    };

    if is_excluded || program.ret != 0 { //CHANGED
        debug!(&ctx, "No log for this Binary");
        return Ok(0);
    }

    try_tail_call(&ctx, 1);

    Ok(0)
}

You can test in debug mode:

RUST_LOG=debug cargo run

Add duration to display

All that remains is to add the syscall duration. We need to modify the display.rs file. To do this, we'll calculate the duration:

let duration = program.t_exit - program.t_enter;

This gives :

fn try_tracepoint_binary_display(ctx: TracePointContext) -> Result<u32, i64> {
    debug!(&ctx, "display");
    let tgid = (bpf_get_current_pid_tgid() >> 32) as u32;
    let program = unsafe { PROGRAM.get(&tgid).ok_or(0)? };
    let cmd = &program.buffer[..];
    let filename = unsafe { from_utf8_unchecked(cmd) };
    let duration = program.t_exit - program.t_enter;

    info!(
        &ctx,
        "tracepoint sys_*_execve called. Binary: {}, Duration: {}ns", filename, duration
    );
    Ok(0)
}

We can test:

RUST_LOG=info cargo run

Schematically, here's what we've done in the end:

The git repo of the final code:

https://github.com/littlejo/aya-examples/tree/main/tracepoint-binary-final

The introduction to eBPF with Aya is over. Of course, there are still many paths to take to become an eBPF expert. I hope you've enjoyed it, and that you now have a clearer idea of what eBPF is and what it can do with a little more work.
To create this introduction, I used the following sources:

For many of the illustrations:

I strongly advise you to read them if you want to know more!

Modularizing your Aya program with tail calls

Joseph Ligier — Mon, 24 Mar 2025 08:31:13 +0000

I'm getting started with eBPF programming with Aya. The idea behind this series of articles is to get you started too.

In the previous parts, we created a single program. In this part, we'll take a look at the full power of eBPF. We're going to create eBPF programs and make them communicate with each other. We'll use tail calls, a mechanism for chaining eBPF programs together.

FYI, this is the English version of an article originally published in French.

Tail calls: Structuring the program

What is it?

As we saw in the previous section, eBPF programs have a stack memory limit. This is limited to 512 bytes. To get around this limit, we use eBPF maps. But this may still prove insufficient as the program grows. And we could certainly reach other limits...
So, instead of creating a monolith with a single program, we're going to divide this program into several smaller programs which will communicate via jumps. This is known as tail calling or program chaining.
Here's an outline of the possible change:

As has been the case from the outset, we have a single hook (the syscall:sys_enter_execve tracepoint, for example). In the input program, we'll define different programs that will continue the work, and so on. Thanks to eBPF maps, the various small eBPF programs will be able to retrieve output values created by another program.
Apart from the interest in going beyond imposed limits and staying within the Linux kernel, there is also a software engineering interest: to structure code better, to make it clearer and more extensible. In a large project, eBPF programs could also be managed by team.

A few limitations though...

Programs in tail calls have a memory stack limit of 256 bytes, except for the hook, which always has 512 bytes:

Edit: It's a bit more complicated than that. Thanks to Dylan Reimerink for his comment. This limitation only applies when using functions in parallel.

Another more anecdotal limitation: to avoid infinite tail call loops, we're limited to 32 jumps. So you can't write more than 33 programs. That's a lot of fun 😝

What's all this magic?

You're probably wondering how it works. To activate tail calls, you need a dedicated map. It's a Program Array type.

As its name suggests, it must be filled with a list of programs. Or, to be more precise, a list of program file descriptors (fd). When an eBPF program is loaded, a file descriptor is created. This is an integer that identifies the program.

Thanks to this map, you can start another eBPF program using the helper function bpf_tail_call :

To perform a jump, all you need to know is the index of the list corresponding to the program in question.

Let's see how to do this with our guiding program:

how to create the map
how to fill this map with program file descriptors
how to perform jumps using this map

Restructuring kernel-side code

Project cloning

If you follow the articles carefully, you can use the previous code, but I advise you to clone the repo and go to the dedicated directory to be able to follow what's coming next:

git clone https://github.com/littlejo/aya-examples
cd aya-examples/tracepoint-binary-maps/
cargo run # Checking if it works

You can also do the Killercoda lab, which follows step-by-step the creation and use of tail calls :

killercoda.com

Reminder

If you jump on the bandwagon, the initial program logs all binaries running on your computer. In the previous part, we also created a filter to prevent logging when certain binaries are executed, I externalized them in a tracepoint-binary/src/constant.rs file:

pub const EXCLUDE_LIST: [&str; 2] = ["/usr/bin/ls", "/usr/bin/top"];

You can test this with the command :

RUST_LOG=info cargo run

Divide and conquer

As you can imagine, we're going to start creating additional eBPF programs in kernel space. The code will start to grow. It becomes urgent to separate the tracepoint-binary-ebpf/src/main.rs file to prevent it from growing too quickly. The structure is fairly simple:

One file per kernel program.
A main.rs file containing the inclusions of the various files.
A common.rs file containing a catch-all (maps, constants, etc.).

At present, we have a single program, and we're going to put it in a file called hook.rs because it's the program's entry point.

Common People

So we'll create a common.rs file in the same directory as main.rs. We're already going to put the maps and constants in it:

const ZEROED_ARRAY: [u8; MAX_PATH_LEN] = [0u8; MAX_PATH_LEN];

#[map]
static BUF: PerCpuArray<[u8; MAX_PATH_LEN]> = PerCpuArray::with_max_entries(1, 0);

#[map]
static EXCLUDED_CMDS: HashMap<[u8; 512], u8> = HashMap::with_max_entries(10, 0);

We need to add the library for accessing MAX_PATH_LEN :

use tracepoint_binary_common::MAX_PATH_LEN;

We also need to add the #[map] macro and the PerCpuArray and HashMap maps:

use aya_ebpf::{
    macros::map,
    maps::{HashMap, PerCpuArray},
};

On the main.rs side, I've removed the constant and the maps that I put in common.rs and added :

mod common;
use crate::common::*;

This allows the common.rs file to be included in the main code.

I put a * so as not to bother with all the inclusions.

I test a cargo run. I get quite a few errors. I look at the first one:

The maps and the constant are not accessible. This means that they need to be made public. Here's what happens to the common.rs file:

use aya_ebpf::{
    macros::map,
    maps::{HashMap, PerCpuArray},
};

use tracepoint_binary_common::MAX_PATH_LEN;

pub const ZEROED_ARRAY: [u8; MAX_PATH_LEN] = [0u8; MAX_PATH_LEN];

#[map]
pub static BUF: PerCpuArray<[u8; MAX_PATH_LEN]> = PerCpuArray::with_max_entries(1, 0);

#[map]
pub static EXCLUDED_CMDS: HashMap<[u8; 512], u8> = HashMap::with_max_entries(10, 0);

We compile :

there are a few warnings, but it's no big deal. We'll clean it up at the end.

Hook

Now we'll create a hook.rs file in the same directory as main.rs, containing only the Tracepoint program:

#[tracepoint]
pub fn tracepoint_binary(ctx: TracePointContext) -> u32 {
    match try_tracepoint_binary(ctx) {
        Ok(ret) => ret,
        Err(ret) => ret as u32,
    }
}
fn try_tracepoint_binary(ctx: TracePointContext) -> Result<u32, i64> {
    let buf = BUF.get_ptr_mut(0).ok_or(0)?;
    let filename = unsafe {
        *buf = ZEROED_ARRAY;
        let filename_src_addr = ctx.read_at::<*const u8>(FILENAME_OFFSET)?;
        let filename_bytes = bpf_probe_read_user_str_bytes(filename_src_addr, &mut *buf)?;
        if EXCLUDED_CMDS.get(&*buf).is_some() {
            info!(&ctx, "No log for this Binary");
            return Ok(0);
        }
        from_utf8_unchecked(filename_bytes)
    };
    info!(
        &ctx,
        "tracepoint sys_enter_execve called. Binary: {}", filename
    );
    Ok(0)
}

In terms of libraries and constants, we now need everything in main.rs:

use aya_ebpf::{
    helpers::bpf_probe_read_user_str_bytes,
    macros::{map, tracepoint},
    maps::{HashMap, PerCpuArray},
    programs::TracePointContext,
};

use aya_log_ebpf::info;
use core::str::from_utf8_unchecked;
use tracepoint_binary_common::MAX_PATH_LEN;
use crate::common::*;

const FILENAME_OFFSET: usize = 16;

main.rs will be fairly empty, mainly to declare the hook.rs and common.rs files:

#![no_std]
#![no_main]

mod common;
mod hook;

#[cfg(not(test))]
#[panic_handler]
fn panic(_info: &core::panic::PanicInfo) -> ! {
    loop {}
}

This separates out everything that isn't useful for developers (panic, no_main and no_std) but is intended to make the program work at kernel level.
Attempt compilation:

With a little clean-up for hook.rs , we end up with :

use aya_ebpf::{
    helpers::bpf_probe_read_user_str_bytes,
    macros::tracepoint,
    programs::TracePointContext,
};

use aya_log_ebpf::info;
use core::str::from_utf8_unchecked;
use crate::common::*;
const FILENAME_OFFSET: usize = 16;

#[tracepoint]
pub fn tracepoint_binary(ctx: TracePointContext) -> u32 {
    match try_tracepoint_binary(ctx) {
        Ok(ret) => ret,
        Err(ret) => ret as u32,
    }
}

fn try_tracepoint_binary(ctx: TracePointContext) -> Result<u32, i64> {
    let buf = BUF.get_ptr_mut(0).ok_or(0)?;
    let filename = unsafe {
        *buf = ZEROED_ARRAY;
        let filename_src_addr = ctx.read_at::<*const u8>(FILENAME_OFFSET)?;
        let filename_bytes = bpf_probe_read_user_str_bytes(filename_src_addr, &mut *buf)?;
        if EXCLUDED_CMDS.get(&*buf).is_some() {
            info!(&ctx, "No log for this Binary");
            return Ok(0);
        }
        from_utf8_unchecked(filename_bytes)
    };
    info!(
        &ctx,
        "tracepoint sys_enter_execve called. Binary: {}", filename
    );
    Ok(0)
}

Now that we've structured the code better. Let's start the transition to programs with tail calls.

Let's create the foundations for tail calls

What are we going to do?

In part 2, we created a program that observes the various binaries that are executed in the computer. In part 3, we added a filter so as not to see certain binaries. Everything was in the same eBPF program.
We'll separate the different parts of the code into different eBPF programs:

data retrieval (hook)
data filtering (filter)
data display (display)

red: data retrieval
purple: data filtering
green: data display

What we're going to do as a transformation :

We'll have three eBPF programs.

In the “best” case, the programs will be linked as follows: hook ➡️ filter ➡️ display
If the data is filtered, the programs will be linked as follows: hook ➡️ filter

The global eBPF program will ultimately do the same thing, but in a segmented way. If you think you're using a sledgehammer to crack a nut, you're not wrong. But this code will allow us to be more flexible for the next part of the article series.

One last detail: if you've been following along, we need to create an eBPF map for tail calls. This has not been shown in the previous diagram, for simplicity's sake. By adding this map, we have the following diagram:

In user space, the program will fill in the JUMP_TABLE map, explaining that index 0 corresponds to the filter program and index 1 corresponds to the display program.
In kernel space, we'll use a tail call function to say: “I want to go to the program with such and such an index”.

Process

In this section, we're not going to do everything at once. We're already going to create the foundations.
In kernel space, we'll create :

the map dedicated to tail calls
the eBPF programs, which will all be identical (we'll just change the names)

In user space, we'll :

retrieve the map dedicated to tail calls
load the eBPF programs we've just created
fill the tail call map with the loaded programs.

The next section will be devoted to modifying the various eBPF programs and the famous jumps between programs.
This will ensure that the code is compilable and functional at every stage.

Creating an eBPF map dedicated to tail calls

We're going to create an eBPF map of type ProgramArray.
Here's the documentation:

This must be done in kernel space, in the file containing the eBPF maps, i.e. tracepoint-binary-ebpf/src/common.rs.
We'll create it as follows:

#[map]
pub static JUMP_TABLE: ProgramArray = ProgramArray::with_max_entries(2, 0);

We have 2 inputs:

Program filter: data filtering
Program display: data display

We'll set the flags to zero so as not to get bored.

Don't forget to add the library for this type of map:

use aya_ebpf::{
    macros::map,
    maps::{HashMap, PerCpuArray, ProgramArray},
};

Check that the code compiles with cargo run.

Creating eBPF programs

To create the eBPF programs, we'll carefully copy the tracepoint-binary-ebpf/src/hook.rs file.
For the filter program, we'll name it filter.rs:

cp tracepoint-binary-ebpf/src/hook.rs tracepoint-binary-ebpf/src/filter.rs

add _filter to the functions:

sed -i 's/tracepoint_binary/tracepoint_binary_filter/' tracepoint-binary-ebpf/src/filter.rs

Similarly, the display program is named display.rs :

cp tracepoint-binary-ebpf/src/hook.rs tracepoint-binary-ebpf/src/display.rs
sed -i 's/tracepoint_binary/tracepoint_binary_display/' tracepoint-binary-ebpf/src/display.rs

As you can see, the previous restructuring is very useful.
Don't forget to add these new files to the main.rs file:

#![no_std]
#![no_main]

mod common;
mod hook;
mod filter;
mod display;

#[cfg(not(test))]
#[panic_handler]
fn panic(_info: &core::panic::PanicInfo) -> ! {
    loop {}
}

Check that all 3 eBPF programs compile with cargo run.
So we've created the map dedicated to tail calls and we have 3 identical eBPF programs. We'll modify them later, just to have functional programs with a different nomenclature.

Retrieving the eBPF map from user space

We're now going to work in user space to load the programs and fill the eBPF map we've just created. We're going to modify the tracepoint-binary/src/main.rs file.
We need to add some code before the following line:

let ctrl_c = signal::ctrl_c();

We'll take a look at the user-side documentation for the ProgramArray map:

So we need to add :

let map = ebpf.take_map("JUMP_TABLE").unwrap();
let mut tail_call_map = ProgramArray::try_from(map)?;

I prefer to write this as two instructions, as I think it's easier to understand:

Retrieve the map
Convert it to ProgramArray

But you can also write :

let mut tail_call_map = ProgramArray::try_from(ebpf.take_map("JUMP_TABLE").unwrap())?;

Don't forget the library at the start of the program:

use aya::maps::ProgramArray;

Loading programs and eBPF map

We'll continue working in the tracepoint-binary/src/main.rs file. Now that we've retrieved the eBPF map, we'll load the eBPF programs we've just created and tell the eBPF map what index 0 and index 1 correspond to.

We'll continue to follow the example in the documentation:

Let's test this piece of code:

let prog_0: &TracePoint = ebpf.program("tracepoint_binary_filter").unwrap().try_into()?;
let prog_0_fd = prog_0.fd().unwrap();
tail_call_map.set(0, &prog_0_fd, 0);

With cargo run we get the following error:

Well, it doesn't work properly. The documentation is no good. I see the error:

thread 'main' panicked at tracepoint-binary/src/main.rs:58:33:
called `Result::unwrap()` on an `Err` value: NotLoaded

So it wants the programs to be loaded. So I test:

let prog_0: &TracePoint = ebpf.program("tracepoint_binary_filter").unwrap().try_into()?;
prog_0.load()?;
let prog_0_fd = prog_0.fd().unwrap();
tail_call_map.set(0, &prog_0_fd, 0);

prog_0 must be mutable:

let prog_0: &mut TracePoint = ebpf.program_mut("tracepoint_binary_filter").unwrap().try_into()?;
prog_0.load()?;
let prog_0_fd = prog_0.fd().unwrap();
tail_call_map.set(0, &prog_0_fd, 0);

It works!

Of course, you can copy and paste the previous code for the second program. But you can also make a small loop to make it a little more concise and readable:

let prg_list = ["tracepoint_binary_filter", "tracepoint_binary_display"];

for (i, prg) in prg_list.iter().enumerate() {
    {
        let program: &mut TracePoint = ebpf.program_mut(prg).unwrap().try_into()?;
        program.load()?;
        let fd = program.fd().unwrap();
        tail_call_map.set(i as u32, fd, 0)?;
    }
}

Things to remember about jumps:

index 0 of the map corresponds to the tracepoint_binary_filter program
index 1 of the map corresponds to the tracepoint_binary_display program.

For more complex tail calls, we'll have to find a simple way of finding our way around.
Now we can compile the code. It should work. If you test the program, only the hook program is launched. The filter and display programs won't do anything for the moment, but they are loaded and the tail calls map has been filled by these programs.

Here's what we've done schematically:

We've put all the building blocks in place, and all that's left is to modify the various programs so that :

do only what we ask them to do (retrieve data, filter or display)
create communication between each program

Let's set up the tails calls

We must therefore transform the previous diagram into:

Program modification data retrieval (hook)

The user-space code is now complete. We'll now concentrate on kernel space. In particular, the program that retrieves the binary name:

We therefore modify the tracepoint-binary-ebpf/src/hook.rs file.

The part of the hook program we're going to modify is :

fn try_tracepoint_binary(ctx: TracePointContext) -> Result<u32, i64> {
    let buf = BUF.get_ptr_mut(0).ok_or(0)?;

    let filename = unsafe {
        *buf = ZEROED_ARRAY;
        let filename_src_addr = ctx.read_at::<*const u8>(FILENAME_OFFSET)?;
        let filename_bytes = bpf_probe_read_user_str_bytes(filename_src_addr, &mut *buf)?;
        if EXCLUDED_CMDS.get(&*buf).is_some() {
            info!(&ctx, "No log for this Binary");
            return Ok(0);
        }
        from_utf8_unchecked(filename_bytes)
    };

    info!(
        &ctx,
        "tracepoint sys_enter_execve called. Binary: {}", filename
    );
    Ok(0)
}

We're going to remove the display (the display program will do this):

info!(
        &ctx,
        "tracepoint sys_enter_execve called. Binary: {}", filename
    );

We're also going to remove the filter (the filter program will do this):

if EXCLUDED_CMDS.get(&*buf).is_some() {
            info!(&ctx, "No log for this Binary");
            return Ok(0);
}

This gives us:

fn try_tracepoint_binary(ctx: TracePointContext) -> Result<u32, i64> {
    let buf = BUF.get_ptr_mut(0).ok_or(0)?;

    let filename = unsafe {
        *buf = ZEROED_ARRAY;
        let filename_src_addr = ctx.read_at::<*const u8>(FILENAME_OFFSET)?;
        let filename_bytes = bpf_probe_read_user_str_bytes(filename_src_addr, &mut *buf)?;
        from_utf8_unchecked(filename_bytes)
    };

    Ok(0)
}

the filename and filename_bytes variables are no longer used in this program, so we have:

fn try_tracepoint_binary(ctx: TracePointContext) -> Result<u32, i64> {
    debug!(&ctx, "hook");
    let buf = BUF.get_ptr_mut(0).ok_or(0)?;

    unsafe {
        *buf = ZEROED_ARRAY;
        let filename_src_addr = ctx.read_at::<*const u8>(FILENAME_OFFSET)?;
        bpf_probe_read_user_str_bytes(filename_src_addr, &mut *buf)?;
    }

    Ok(0)
}

We've added debugging to check that we're in the hook program. We now need to add the debugging library:

use aya_log_ebpf::debug;

Nothing extraordinary so far.
Now we'll see how to tell the hook program to go to the filter program. Following the example given in the documentation:

The example looks quite complicated... We'll add bpf_probe_read_user_str_bytes just after it:

JUMP_TABLE.tail_call(ctx, 0);

0 being the index of the JUMP_TABLE map which corresponds to the filter program defined in user space.

I see the following error:

So we need to set :

JUMP_TABLE.tail_call(&ctx, 0);

It works:

The hook program is passed to the filter program.
However, there's a warning:

I don't really like let _ =.
Let's look at the signature of the tail_call() method:

So it returns Result<!, c_long>. Not very clear. What we need to know is whether there's an error in Result<>. There's a method for that:

We'll add these lines here:

let res = unsafe { JUMP_TABLE.tail_call(&ctx, 0)};
if res.is_err() {
     error!(&ctx, "hook: tail_call failed");
}

0 is the first tail call program defined in user space, corresponding to the filter program.

the error macro is not imported, so we need to add this library:

use aya_log_ebpf::{debug,error};

The result is:

use aya_ebpf::{
    helpers::bpf_probe_read_user_str_bytes,
    macros::tracepoint,
    programs::TracePointContext,
};
use aya_log_ebpf::{debug,error};

use crate::common::*;

const FILENAME_OFFSET: usize = 16;

#[tracepoint]
pub fn tracepoint_binary(ctx: TracePointContext) -> u32 {
    match try_tracepoint_binary(ctx) {
        Ok(ret) => ret,
        Err(ret) => ret as u32,
    }
}

fn try_tracepoint_binary(ctx: TracePointContext) -> Result<u32, i64> {
    debug!(&ctx, "hook");
    let buf = BUF.get_ptr_mut(0).ok_or(0)?;

    unsafe {
        *buf = ZEROED_ARRAY;
        let filename_src_addr = ctx.read_at::<*const u8>(FILENAME_OFFSET)?;
        bpf_probe_read_user_str_bytes(filename_src_addr, &mut *buf)?;
    }
    let res = unsafe { JUMP_TABLE.tail_call(&ctx, 0)};
    if res.is_err() {
        error!(&ctx, "hook: tail_call failed");
    }

    Ok(0)
}

That's all for the hook program. You've done the hard part, the rest is the same.

Modifying the filter program

For filter, we need to retrieve the contents of the BUF map:

let buf = BUF.get(0).ok_or(0)?; //buf is a reference of a list of 512 entries

In the same way as for hook, we're going to remove the unnecessary stuff.

This results in the main filter.rs code:

fn try_tracepoint_binary_filter(ctx: TracePointContext) -> Result<u32, i64> {
    debug!(&ctx, "filter");
    let buf = BUF.get(0).ok_or(0)?;

    let is_excluded = unsafe {
        EXCLUDED_CMDS.get(buf).is_some()
    };

    if is_excluded {
        debug!(&ctx, "No log for this Binary");
        return Ok(0);
    }

    Ok(0)
}

To tell it to go to the display program, we must also add:

let res = unsafe { JUMP_TABLE.tail_call(&ctx, 1) };
if res.is_err() {
    error!(&ctx, "filter: tail_call failed");
}

1 being the index of the JUMP_TABLE map array, which corresponds to the display program defined in the user space.

To complicate things a little, we could imagine that if it's a filtered command, it would go to another program for further processing. Let your imagination run wild...
In the end, we end up with:

use aya_ebpf::{
    macros::tracepoint,
    programs::TracePointContext,
};

use aya_log_ebpf::{debug,error};

use crate::common::*;

#[tracepoint]
pub fn tracepoint_binary_filter(ctx: TracePointContext) -> u32 {
    match try_tracepoint_binary_filter(ctx) {
        Ok(ret) => ret,
        Err(ret) => ret as u32,
    }
}

fn try_tracepoint_binary_filter(ctx: TracePointContext) -> Result<u32, i64> {
    debug!(&ctx, "filter");
    let buf = BUF.get(0).ok_or(0)?;

    let is_excluded = unsafe {
        EXCLUDED_CMDS.get(buf).is_some()
    };

    if is_excluded {
        debug!(&ctx, "No log for this Binary");
        return Ok(0);
    }

    let res = unsafe { JUMP_TABLE.tail_call(&ctx, 1) };
    if res.is_err() {
        error!(&ctx, "filter: tail_call failed");
    }

    Ok(0)
}

Let's look at what we've done by testing in debug mode:

I ran the ls command: hook ➡️ filter
I ran the man command: hook ➡️ filter ➡️ display

This is exactly what we wanted!

Modifying the display program

For the last program, we'll just retrieve what's in the map buffer and transform it into &str as we saw in the previous section. We'll then modify the display.rs file:

fn try_tracepoint_binary_display(ctx: TracePointContext) -> Result<u32, i64> {
    debug!(&ctx, "display");
    let buf = BUF.get(0).ok_or(0)?;
    let cmd = &buf[..];
    let filename = unsafe { from_utf8_unchecked(cmd) };
    info!(&ctx, "tracepoint sys_enter_execve called. Binary: {}", filename);
    Ok(0)
}

Now we'll test in debug mode:

RUST_LOG=debug cargo run

Without debug mode, we wouldn't be able to see the difference with the program created in the previous section.

Inline function

Finally, we're going to factorize the code for the jumps:

let res = unsafe { JUMP_TABLE.tail_call(&ctx, 1) };
if res.is_err() {
     error!(&ctx, "filter: tail_call failed");
}

It's used twice (in hook.rs and in filter.rs ) and for another project it might be a good idea to already have this bit of code. Let's put it in the common.rs file.

What's an inline function?

For performance reasons, it's not advisable to create too many functions. It's a bit complicated, but when you call up a function, there's a JMP (Jump) at assembler level, so it's expensive if you're looking for performances (CPU cycle cost) and minimizing instructions, as is the case with eBPF. To solve this problem, you can inline your function. This allows the compiler to automatically replace the function in the main code, making it transparent to the developer.
To inline a function in Rust, simply add the following code above the function:

#[inline(always)]

Creating an inline function

What is the input to this function?

ctx: the Tracepoint context
index: the program index

This function returns nothing: res doesn't interest us.
So the signature is something like :

fn try_tail_call(ctx: TracePointContext, index: u32) {
   [...]
}

So we'd have :

fn try_tail_call(ctx: TracePointContext, index: u32) {
    let res = unsafe { JUMP_TABLE.tail_call(&ctx, index) };
    if res.is_err() {
        error!(&ctx, "tail_call failed");
    }
}

This function is totally valid. However, for borrowing problems, it's more interesting to use the TracePointContext reference:

As we want to inline the function for performance reasons, we'll have in the common.rs file :

#[inline(always)]
pub fn try_tail_call(ctx: &TracePointContext, index: u32) {
    let res = unsafe { JUMP_TABLE.tail_call(ctx, index) };
    if res.is_err() {
        error!(ctx, "exit: tail_call failed");
    }
}

The complete common.rs file with the libraries:

use aya_ebpf::{
    macros::map,
    maps::{HashMap, PerCpuArray, ProgramArray},
    programs::TracePointContext,
};
use aya_log_ebpf::error;

use tracepoint_binary_common::MAX_PATH_LEN;

pub const ZEROED_ARRAY: [u8; MAX_PATH_LEN] = [0u8; MAX_PATH_LEN];

#[map]
pub static BUF: PerCpuArray<[u8; MAX_PATH_LEN]> = PerCpuArray::with_max_entries(1, 0);

#[map]
pub static EXCLUDED_CMDS: HashMap<[u8; 512], u8> = HashMap::with_max_entries(10, 0);

#[map]
pub static JUMP_TABLE: ProgramArray = ProgramArray::with_max_entries(2, 0);

#[inline(always)]
pub fn try_tail_call(ctx: &TracePointContext, index: u32) {
    let res = unsafe { JUMP_TABLE.tail_call(ctx, index) };
    if res.is_err() {
        error!(ctx, "tail_call failed");
    }
}

In the hook program, we'll replace the code :

let res = unsafe { JUMP_TABLE.tail_call(&ctx, 0) };
if res.is_err() {
    error!(&ctx, "filter: tail_call failed");
}

with: try_tail_call(&ctx, 0);
This gives us :

fn try_tracepoint_binary(ctx: TracePointContext) -> Result<u32, i64> {
    debug!(&ctx, "hook");
    let buf = BUF.get_ptr_mut(0).ok_or(0)?;

    unsafe {
        *buf = ZEROED_ARRAY;
        let filename_src_addr = ctx.read_at::<*const u8>(FILENAME_OFFSET)?;
        bpf_probe_read_user_str_bytes(filename_src_addr, &mut *buf)?;
    }
    try_tail_call(&ctx, 0);

    Ok(0)
}

and in the filter program :

let res = unsafe { JUMP_TABLE.tail_call(&ctx, 1) };
if res.is_err() {
    error!(&ctx, "filter: tail_call failed");
}

by try_tail_call(&ctx, 1);
Which gives us :

fn try_tracepoint_binary_filter(ctx: TracePointContext) -> Result<u32, i64> {
    debug!(&ctx, "filter");
    let buf = BUF.get(0).ok_or(0)?;

    let is_excluded = unsafe {
        EXCLUDED_CMDS.get(buf).is_some()
    };

    if is_excluded {
        debug!(&ctx, "No log for this Binary");
        return Ok(0);
    }
    try_tail_call(&ctx, 1);

    Ok(0)
}

Don't forget to check that it continues to compile.

The hook and filter program code is still easier to read, and we've been able to see the creation of an inlined function 😆

The code

The code is in the usual git repo :

https://github.com/littlejo/aya-examples/tree/main/tracepoint-binary-tail-calls

That's all for this section. We've seen quite a lot in this tail calls eBPF section: creation and filling of the dedicated map, jumps and specialization of eBPF programs. We've also seen inline functions and a bit of Rust code restructuring.
In the last section, we'll introduce another eBPF program and see how to make it interact with the one we've created.

Enhancing your Aya program with eBPF maps

Joseph Ligier — Wed, 12 Mar 2025 09:08:04 +0000

I'm getting started with eBPF programming with Aya. The idea behind this series of articles is to get you started too.

This section is dedicated to eBPF maps. We'll learn how to create, use and differentiate them. As this is the most important concept in eBPF, it's well worth devoting a whole section to it.

We will first fix a bug in the Aya program from the previous section by introducing an eBPF map. This will explain what an eBPF map is. Then we'll improve the program with another map.

FYI, this is the English version of an article originally published in French.

My first eBPF map

We'll pick up where we left off in Part 2. If you want to skip it or start again cleanly, you can clone the dedicated repo and go to the tracepoint-binary directory:

git clone https://github.com/littlejo/aya-examples
cd aya-examples/tracepoint-binary

Check that it compiles correctly:

RUST_LOG=info cargo run #We're seeing binaries executed on the computer

You can also do the Killercoda lab, which follows step-by-step the creation and use of eBPF map :

killercoda.com

What's wrong with it?

As we saw in Part 2, the program that allows you to see which binaries are being executed works well. But we notice that the display is truncated:

Why? The answer can be found in these lines from the tracepoint-binary-ebpf/src/main.rs file:

const LEN_MAX_PATH: usize = 16;
[...]
     let mut buf = [0u8; LEN_MAX_PATH];

This creates an array of bytes with 16 entries. Remember that we're in UTF-8. For ASCII characters: a character is encoded on one byte. This is not always true, for example, for smileys (like this one: 🦀 or 🐝), which are encoded on 4 bytes. So, at best, you're limited to 16 characters (actually, it's 15 to be precise, as there's an end-of-string character \0).

Your first limit

The first intuition is to increase this array. For example, we're going to go wide, we're going to try: 512 bytes.

const LEN_MAX_PATH: usize = 512; //from 16 to 512

Compiled, we have a big failure:

Image is probably too small. So:

Looks like the BPF stack limit is exceeded. Please move large on stack variables into BPF per-cpu array map. For non-kernel uses, the stack can be increased using -mllvm -bpf-stack-size.

In fact, the memory stack for eBPF is limited to 512 bytes. In other words, the sum of all variables cannot exceed 512 bytes. As I mentioned in Part 2, variables with predefined sizes are stored in a stack at memory level, and dynamic data cannot be stored in kernel space.

One solution, of course, is to reduce the number of entries in the array. But as the program grows, it will eventually reach this limit again. So we need to find a long-term solution: the eBPF map.

How to create an eBPF map?

As the error message suggests, you need to create a “per-cpu array” eBPF map. How do I do this?

Let's see the documentation:

You can click on maps link and you see eBPF maps:

We choose PerCpuArray:

This map is not very well documented. We don't know what with_max_entries() or pinned() are used for, for example. All we can see is that it creates a map of type PerCpuArray. We've got a 50/50 chance 😃
Let's look at another map that's better documented: CpuMap.

This shows the difference between the two functions:

As we don't really want to store this map, I think the with_max_entries() function will suffice.
The aim is to replace a list of 512 bytes, so we'll create a list of integers (of type u8) of length 512:

#[map]
static BUF: PerCpuArray<u8> = PerCpuArray::with_max_entries(512, 0);

The first line is a macro for creating a map (fortunately, there was an example in the documentation - you can't make it up yourself!)
we want a static variable (we haven't really seen this notion, it's a variable that remains until the end of the program; see the Rust Book for more information, but it's not fundamental to the rest of the program)
BUF is the name of the variable and has the structure PerCpuArray<u8>.
the with_max_entries() method has two arguments: the number of inputs per CPU and a flag (set to 0, to be discussed later)

Schematically, we have this:

How to modify an eBPF map?

We've just created a map. But how do we replace this line :

let mut buf = [0u8; LEN_MAX_PATH];

So that the buf variable can be used here :

let filename_bytes = bpf_probe_read_user_str_bytes(filename_src_addr, &mut buf)?;

The methods available for the map are fairly limited:

So for example to access to the second entry:

There is no conversion to a list. So we're on the wrong track. The map we've created is not good. There is no spoon!

Let's see again the documentation:

How about changing <T>? With methods, you can have just one value. But if <T> is a list instead of an integer, we'll get the value of the list!

So instead of <T> = u8 we would have <T> =[u8; 512].

If we have only one entry, schematically, we have this:

In place of the other map, we'll replace it with the following line:

static BUF: PerCpuArray<[u8; LEN_MAX_PATH]> = PerCpuArray::with_max_entries(1, 0);

We only set one entry as we only have one list.

Don't forget to add libraries at the beginning of the code:

use aya_ebpf::maps::PerCpuArray; // To retrieve the structure map
use aya_ebpf::macros::map; //to be able to use map macros

Now that we've created this map, how do we use it in the main function code? Let's take a look at the different methods:

get() will provide the reference to the contents of a map index. This will give us the read-only value of the list.
get_ptr() provides the pointer to the contents of a map index. This will give the value of the list as a constant
get_ptr_mut() allows you to obtain the pointer to the contents of an index in the map, and modify its contents.

So we need get_ptr_mut() because buf is mutable.

In the main function, we will replace the variable buf :

let mut buf = [0u8; MAX_SMALL_PATH];

By:

let buf = BUF.get_ptr_mut(0).ok_or(0)?;

BUF.get_ptr_mut(0). Retrieves the first input (we only have one).
ok_or(0): converts an Option into a Result (remember this?).

buf is now of type *mut[u8;MAX_SMALL_PATH] . Whereas before it was of type mut[u8;MAX_SMALL_PATH]. We're not far off. We need to do something to remove this *.

To do this, you need to dereference the raw pointer. Simply add an asterisk on unsafe mode, i.e. instead of :

let filename_bytes = bpf_probe_read_user_str_bytes(filename_src_addr, &mut buf)?;

We get:

let filename_bytes = bpf_probe_read_user_str_bytes(filename_src_addr, &mut *buf)?;

To dereference a raw pointer, you must be in unsafe mode. For more information, see the Rust Book.

We end up with the following code:

#![no_std]
#![no_main]

use aya_ebpf::{
    macros::tracepoint,
    programs::TracePointContext,
    helpers::bpf_probe_read_user_str_bytes,
};
use aya_log_ebpf::info;

use core::str::from_utf8_unchecked;

use aya_ebpf::maps::PerCpuArray; //library for the map
use aya_ebpf::macros::map; //library for the macro

const LEN_MAX_PATH: usize = 512; //We set a size of 512 to show that we can use more than 512 bytes
const FILENAME_OFFSET: usize = 16;

#[map] //The macro
static BUF: PerCpuArray<[u8; LEN_MAX_PATH]> = PerCpuArray::with_max_entries(1, 0); //Declare the map

#[tracepoint]
pub fn tracepoint_binary(ctx: TracePointContext) -> u32 {
    match try_tracepoint_binary(ctx) {
        Ok(ret) => ret,
        Err(ret) => ret as u32,
    }
}

fn try_tracepoint_binary(ctx: TracePointContext) -> Result<u32, i64> {
    let buf = BUF.get_ptr_mut(0).ok_or(0)?; //Retrieve the map value
    let filename = unsafe {
        let filename_src_addr = ctx.read_at::<*const u8>(FILENAME_OFFSET)?;
        let filename_bytes = bpf_probe_read_user_str_bytes(filename_src_addr, &mut *buf)?; // filled the map
        from_utf8_unchecked(filename_bytes)
    };

    info!(&ctx, "tracepoint sys_enter_execve called. Binary: {}", filename);
    Ok(0)
}

#[cfg(not(test))]
#[panic_handler]
fn panic(_info: &core::panic::PanicInfo) -> ! {
    loop {}
}

I've put comments where we've made changes. There's not that much to change in the end!
And it works:

Now that we've seen a practical example of an eBPF map. Let's explain eBPF maps in a little more detail.

eBPF maps: benefits and limitations

Definition

An eBPF map is data that is accessible in both user space and kernel space. It is persistent until the end of the eBPF program, or until the machine is restarted in the event of pinning. Its main uses are :

go beyond the limits of kernel programs
communication between user space and kernel space
communication between eBPF kernel programs

Go beyond 512 bytes

In the previous example, we saw a use for the eBPF map: it allows you to go beyond the eBPF limitation and virtually have a variable stack of more than 512 bytes.

Input

To configure a program, we use, for example, a configuration file, or we put it as an argument to the command. An eBPF program cannot read a file directly. It has to go through an eBPF map. In this way, there is communication from user space to kernel space.

Output

To retrieve data processed in kernel space and make it available in user space via a file, an eBPF map must also be used. In this way, communication takes place in the other direction, from kernel space to user space.

Communication between eBPF programs

As you can imagine, kernel-space eBPF programs have certain limitations. For large-scale projects, however, it is possible to create several eBPF programs and have them communicate with each other via eBPF maps. This is known as tail calls. This will be the subject of the next part of the introduction.

What can you put in these maps?

As we saw when creating our first map, you can put integers and static arrays. But can you put anything else?

What can you replace by <T> ?

It's not magic: these variables cannot be dynamic arrays. Their size must be decided before compilation, as they are available in kernel space. Nor can strings. So that already limits things quite a bit 😃
However, aligned structures can also be used. Example:

#[repr(C)]
struct ProgramState {
    timestamp: u64,
    duration: u64,
    ret: i64,
}

#[map]
static TIME: PerCpuArray<ProgramState> = PerCpuArray::with_max_entries(1, 0);

As memory management in Rust is different for C structures, you must add #[repr(C)] before the structure to tell the Rust compiler to convert it to a C structure.

The different types of eBPF maps

Just as there are different types of eBPF program, there are also different types of eBPF map. All these maps are listed here. The map types have appeared with each Linux kernel release, and there will probably be new ones in future versions. Moreover, Aya does not yet support all these types. At the time of writing, about twenty are available. There's already plenty to play with.

Why are there different types? In fact, I think we need to draw an analogy with databases. There are different types of database, depending on the use case. For example, a redis database has nothing to do with the use case of an SQL database. So each type of map will have its own use cases. The wrong choice of type can lead to performance problems.

A little eBPF map sorting

When you look at the list of eBPF map types, you might feel lost, because there are so many of them. Which one to choose? Difficult to answer without knowing your needs.

Let's list the most common ones:

Array: list structure (fixed, limited size). Accessed and modified via an index.

Hashmap: dictionary structure (dynamic but limited size). Access and delete via key. An element can be added or updated via key/value.

Example of dictionary: max. 4 entries (including one not taken), keys are arrays of 8 entries and values are arrays of 4 values.

If I request the key selected in yellow, I get the list in green.

They may suffice, but if several CPUs are trying to modify the same map at the same time, this can cause problems. These maps are more suitable for data that doesn't move very often, such as configuration data. For more dynamic data, we'll opt for these maps instead:

PerCpuArray : list structure per CPU

PerCpuHashmap: dictionary structure per CPU

This creates one structure per CPU. When an eBPF program is started, only one CPU will be running, so it will be on a single structure. If two eBPF programs are started at the same time, one eBPF program will be on the first CPU and the other on the second. We chose this type of map for the buffer at the beginning of the article because it can be subject to joint writes.
Maps with dictionary structures have a limited size. What happens if the maximum size is reached and we try to add a new key to the dictionary? You won't be able to add any more without removing keys manually. These maps solve this problem:

LruHashMap: Least Recently Used
LruPerCpuHashMap: the same but per CPU

When the map is full, an algorithm will delete the least recently used key.
We've already seen 6 types of eBPF map. The others are a little more specialized, notably in networking.
I've tried to sort the different maps available in Aya into a table to give you an idea:

Flag on an exam

As we saw in the previous example, you can define a flag. We set it to zero because that's what the example said. This is the default behavior. These flags may differ according to the type of map.

This can be used, for example, to add security to the map. Thus, the BPF_F_RDONLY flag prevents user-space programs from writing. eBPF programs in kernel space, on the other hand, can do as they please. To use these flags in Rust, there's the aya_ebpf_bindings library. BPF_F_RDONLY has this constant.

Another slice of Rust?

Introduction

Before improving the program, we'll concentrate on Rust slices. They're very useful for eBPF programs. We've already used them in the previous section (without realizing it?).

Fixed-size array reference

As we've already seen, to avoid memory leakage problems for dynamic variables, Rust has the concept of possession. Because of this constraint, we use references to avoid dispossession.
For non-dynamic types such as fixed-size arrays, there's no such problem. Why use references at all? References mean you don't have to duplicate an object. For example, a slice, as its name suggests, allows you to retrieve part of an array, but is also a reference to that array: nothing is taken from memory.

Exercise

Write a function that retrieves the first 3 elements of an array.

Without slice or reference, how to do it?

fn retrieve_3(array: [i32; 5]) -> [i32; 3] {
    let sub_array: [i32; 3] = [array[1], array[2], array[3]];
    sub_tableau
}

fn main() {
    let array = [1, 3, 5, 56, 78];
    let sub_tableau = retrieve_3(array);

    println!("origin array : {:?}", array);
    println!("Sub array : {:?}", sub_array);
}

This function has a number of shortcomings. It will be difficult to reuse...
How do you use a slice?

fn retrieve_slice(len: usize, array: &[i32]) -> &[i32] {
    &array[..len]
}

fn main() {
    let array = [1, 3, 5, 56, 78];
    let slice = retrieve_slice(3, &array);

    println!("array original : {:?}", array);
    println!("Sub-array (slice) : {:?}", slice);
}

&array[..len] is equivalent to &array[0..len].

So with a slice, you don't need to create a second array. To manipulate an array, it's best to use a slice in eBPF.

Example with Aya

Let's take an interesting case for Aya. Let's go back to the previous code:

#[map]
static BUF: PerCpuArray<[u8; LEN_MAX_PATH]> = PerCpuArray::with_max_entries(1, 0);

fn try_tracepoint_binary(ctx: TracePointContext) -> Result<u32, i64> {
    let buf = BUF.get_ptr_mut(0).ok_or(0)?;
    let filename = unsafe {
        let filename_src_addr = ctx.read_at::<*const u8>(FILENAME_OFFSET)?;
        let filename_bytes = bpf_probe_read_user_str_bytes(filename_src_addr, &mut *buf)?; // Remplissage du contenu de la map
        from_utf8_unchecked(filename_bytes)
    };

    info!(&ctx, "tracepoint sys_enter_execve called. Binary: {}", filename);
    Ok(0)
}

I'd like to display the contents of the BUF map. How do I do this? We use the get() method:

To retrieve the content, add :

let buf_content = BUF.get(0).ok_or(0)?;

I created another name of variable to avoid conflict with buf.
To retrieve the first elements of this array:

info!(&ctx, "buf_0: {}", buf_content[0]);
info!(&ctx, "buf_1: {}", buf_content[1]);
info!(&ctx, "buf_2: {}", buf_content[2]);
info!(&ctx, "buf_3: {}", buf_content[3]);

But how do you get all the elements at once?

Let's try:

let buf_content = BUF.get(0).ok_or(0)?;
info!(&ctx, "buf_content: {}", buf_content);

You have to convert this array into slice:

let buf_content = BUF.get(0).ok_or(0)?;
info!(&ctx, "buf_content: {:x}", &buf_content[..]);

I prefer this version of code:

let buf_content = &BUF.get(0).ok_or(0)?[..];
info!(&ctx, "buf_new: {:x}", buf_content);

{:x} : to convert a slice into hexadecimal
It doesn't work with {}. To find {:x} I haven't found any documentation yet, so I had to look in the code 😝

If you want to display fewer zeros, you can reduce the slice:

let buf_content = &BUF.get(0).ok_or(0)?[..16];
info!(&ctx, "buf_content: {:x}", buf_content);

What if I want to convert my map into a string?

Do you remember ?

You need to add some code like that:

unsafe {
        info!(&ctx, "buf_str: {}", from_utf8_unchecked(buf_content));
}

Instead of using info!, it might be a good idea to use debug! 😜

Let's add a feature

Option to filter commands

At the beginning of this article, we saw a map that is only used in kernel space. We're going to create a configuration map that will be initialized in user space and used in kernel space. We'll filter out the names of binaries we don't want to be displayed. For example, we can imagine that a command like man, which allows you to read the documentation for a command, is not very useful for logging. This will give us a list of commands that we no longer wish to display in the user area.

How do we get organized?

As we're starting with the user area, it would be intuitive to create this map in the user area. Unfortunately, this is not yet possible. All maps must be created in kernel space with Aya.
When the user-space program loads the eBPF program, the maps are created. You will then need to retrieve it and fill it with this list of commands.
Once this has been done, all the work will be done at kernel level, checking that the file name is in the list and, if necessary, not logging.

Which type of map?

We've been talking about command lists all along. So we're going to make an Array?

This is obviously possible. However, you'll need to create a function (or find one) to check whether a file name is included. This function will necessarily have a loop to go through each element and check if it's included. The complexity will be in O(n). I haven't talked too much about loops in Rust for a good reason: it's best to avoid them in kernel-side eBPF programs, as the verifier doesn't like them. To find out more about loops, you can read the documentation. Anyway, there are better ways than O(n), you'll see!

So let's create a Hash. But how are we going to structure it? If we were in a “traditional” program, manipulating Strings as a key and any value, we'd have a map like : Map<&str, u8>.

And we'd check whether the command has the key: we'd then move on to O(1) complexity.
However, in eBPF, it's not possible to use Strings in maps. You have to use u8 integer arrays. So the map will be of the form : Map<[u8; 512], u8>.

Its key will be a list of bytes representing the name of the command, and its value will be an integer u8, which will serve only as a witness. All that's left is to choose the type of Hash. I've chosen a generic map: the HashMap, as it will never be modified except at the start of the program.

Schematically, it works like this:

There are certainly more optimal ways, but the aim of this exercise is to show how to transfer a map from user space to kernel space.

Creation of the map

As we've already seen, the map is declared in a very similar way to the previous one. We therefore need to add these lines to the tracepoint-binary-ebpf/src/main.rs file:

#[map]
static EXCLUDED_CMDS: HashMap<[u8; 512], u8> = HashMap::with_max_entries(10, 0);

We limit the Hash to 10 entries, so we can only exclude 10 commands.

Don't forget HashMap library at the beginning of the file:

use aya_ebpf::maps::{PerCpuArray, HashMap};

Input

To add values to this map, we're going to do it on the user side. We could imagine that we had a configuration file and that this program would retrieve the various filenames from this configuration file dynamically, but we'll keep it simple: we'll hard-code the whole thing. This is just a demonstration, the aim being to understand the transfer from user space to kernel space.
Once the kernel code is loaded, the eBPF maps will be automatically created. This is when you need to work on the tracepoint-binary/src/main.rs file:

let mut ebpf = aya::Ebpf::load(aya::include_bytes_aligned!(concat!(
        env!("OUT_DIR"),
        "/tracepoint-binary"
    )))?;
[...]
    let program: &mut TracePoint = ebpf.program_mut("tracepoint_binary").unwrap().try_into()?;
    program.load()?;
    program.attach("syscalls", "sys_enter_execve")?;
//It's here where you have to code

We'll add a list of commands that should not be logged. For example:

let exclude_list = ["/usr/bin/ls", "/usr/bin/top"];

Let's simplify: we've retrieved the absolute path of the command
No need to bother with a dictionary for input values.

Retrieve the map

To retrieve the map, look at the user-side documentation:

A priori, the map_mut() function should suffice:

let map = ebpf.map_mut("EXCLUDED_CMDS").unwrap();

This is the name of the map defined on the kernel side: EXCLUDED_CMDS.

Remember that since the map_mut() method returns the Option enumeration, and since we're on the user side, we can use the unwrap() method: we'll take advantage of this.
The map variable is then of type &mut Map. In fact, Map is a kind of interface structure. It needs to be converted into a more specific HashMap type.
Let's take a look at the documentation for this:

So i'm trying:

let mut excluded_cmds = HashMap::try_from(map)?;

So :

let mut excluded_cmds :HashMap<&mut MapData, [u8; 512], u8> = HashMap::try_from(map)?;

Don't forget to import HashMap et MapData library at the beginning of the file:

use aya::maps::{HashMap, MapData};

Filling the map

Now we have the right map. Now we need to fill it with shell commands.
First, we need to convert all strings into a fixed byte list, i.e. fill the end with zeros.

This function is designed to do just that:

fn cmd_to_bytes(cmd: &str) -> [u8; 512] {
    let mut cmd_zero = [0u8; 512];
    let cmd_bytes = cmd.as_bytes();
    let len = cmd_bytes.len();
    cmd_zero[..len].copy_from_slice(cmd_bytes);
    cmd_zero
}

Let's take a look at each step...

we create an array of 512 integers (type u8) all equal to 0. This is the function's output variable: let mut cmd_zero = [0u8; 512];
We convert commands (&str) into byte slice (&[8]): let cmd_bytes = cmd.as_bytes();

we take the length of the sliced command: let len = cmd_bytes.len();
The last instruction is hard to understand:
- cmd_zero[..len]: we create a slice of the same length as the command (as this is a prerequisite for copy_from_slice())
- cmd_zero[..len].copy_from_slice(cmd_bytes): we inject the sliced command into cmd_zero.

Here you can see the benefits of slices 😆
To add to the dictionary, use the insert function:

What is flags used for? The main purpose of flags is to tell the map what to do if the key already exists:

By looping over each command (we have the right here), we obtain:

for cmd in exclude_list.iter() {
        let cmd_zero = cmd_to_bytes(cmd);
        excluded_cmds.insert(cmd_zero, 1, 0)?;
}

cmd_zero represents the fixed byte array
value has been replaced by 1, a random number
flags is set to zero: default behavior

We've filled in the filename map: the user side is finished.
If you haven't been following along, I'll summarize what's been added:

#[rustfmt::skip]
 use log::{debug, warn};
 use tokio::signal;
+use aya::maps::{HashMap, MapData};

 #[tokio::main]
 async fn main() -> anyhow::Result<()> {
@@ -33,6 +34,13 @@ async fn main() -> anyhow::Result<()> {
     let program: &mut TracePoint = ebpf.program_mut("tracepoint_binary").unwrap().try_into()?;
     program.load()?;
     program.attach("syscalls", "sys_enter_execve")?;
+    let exclude_list = ["/usr/bin/ls", "/usr/bin/top"];
+    let map = ebpf.map_mut("EXCLUDED_CMDS").unwrap();
+    let mut excluded_cmds :HashMap<&mut MapData, [u8; 512], u8> = HashMap::try_from(map)?;
+    for cmd in exclude_list.iter() {
+        let cmd_zero = cmd_to_bytes(cmd);
+        excluded_cmds.insert(cmd_zero, 1, 0)?;
+    }

     let ctrl_c = signal::ctrl_c();
     println!("Waiting for Ctrl-C...");
@@ -41,3 +49,11 @@ async fn main() -> anyhow::Result<()> {

     Ok(())
 }
+
+fn cmd_to_bytes(cmd: &str) -> [u8; 512] {
+    let mut cmd_zero = [0u8; 512];
+    let cmd_bytes = cmd.as_bytes();
+    let len = cmd_bytes.len();
+    cmd_zero[..len].copy_from_slice(cmd_bytes);
+    cmd_zero
+}

You can test it: it compiles.

Let's test whether the file name is in this map

Now that we've filled in the map, we need to modify the kernel-side file: tracepoint-binary-ebpf/src/main.rs.

Let's recall the important parts of the eBPF program:

#[map]
static BUF: PerCpuArray<[u8; 512]> = PerCpuArray::with_max_entries(1, 0);

#[map]
static EXCLUDED_CMDS: HashMap<[u8; 512], u8> = HashMap::with_max_entries(10, 0);

fn try_tracepoint_binary(ctx: TracePointContext) -> Result<u32, i64> {
    let buf = BUF.get_ptr_mut(0).ok_or(0)?;

    let filename = unsafe {
        let filename_src_addr = ctx.read_at::<*const u8>(FILENAME_OFFSET)?;
        let filename_bytes = bpf_probe_read_user_str_bytes(filename_src_addr, &mut *buf)?;
        from_utf8_unchecked(filename_bytes)
    };

    info!(&ctx, "tracepoint sys_enter_execve called. Binary: {}", filename);
    Ok(0)
}

To retrieve the value of a map, we always have :

There's no need to modify it. So the get() method suffices. This method returns the Option enumeration: this is either Some() or None. There's a method for checking this:

Simply add the following code:

if EXCLUDED_CMDS.get(filename_bytes).is_some() {
           info!(&ctx, "No log for this Binary");
           return Ok(0);
}

Let's try:

There's a type problem: filename_bytes is a bytes slice (&[u8]) and the get() method expects type <T>, i.e. &[u8; 512] in our case. It would be “enough” to convert filename_bytes to &[u8; 512]. Easy to say 😝
In truth, this is not possible (easily) in eBPF. We need to find another solution. buf is of type *mut[u8;512]. As we saw in the section on slices, it contains the command with lots of zeros.

Simply dereference the variable by adding *: *buf is then of type [u8;512].
And add a reference: &*buf is then of type &[u8; 512] . This makes :

if EXCLUDED_CMDS.get(&*buf).is_some() {
           info!(&ctx, "No log for this Binary");
           return Ok(0);
}

The important parts of the program are here:

#[map]
static BUF: PerCpuArray<[u8; 512]> = PerCpuArray::with_max_entries(1, 0);

#[map]
static EXCLUDED_CMDS: HashMap<[u8; 512], u8> = HashMap::with_max_entries(10, 0);

fn try_tracepoint_binary(ctx: TracePointContext) -> Result<u32, i64> {
    let buf = BUF.get_ptr_mut(0).ok_or(0)?;
    let filename = unsafe {
        let filename_src_addr = ctx.read_at::<*const u8>(FILENAME_OFFSET)?;
        let filename_bytes = bpf_probe_read_user_str_bytes(filename_src_addr, &mut *buf)?;
        if EXCLUDED_CMDS.get(& *buf).is_some() {
           info!(&ctx, "No log for this Binary");
           return Ok(0);
        }
        from_utf8_unchecked(filename_bytes)
    };

    info!(&ctx, "tracepoint sys_enter_execve called. Binary: {}", filename);
    Ok(0)
}

You can test it! This code works:

Run the ls command :

Run the top command :

So for these two commands we go to the if condition:

We created a filter.

Run another command :

All is for the best in the best of all possible worlds?

Oh no! It doesn't work sometimes...

Let's fix the bug

What's wrong with it?

The key point of the problem is that the map (BUF) originally created is not necessarily “equal” to a command. Let me explain.
At map creation, BUF is a list of 0 :

static BUF: PerCpuArray<[u8; 512]> = PerCpuArray::with_max_entries(1, 0);

To be precise, a list of 0s per CPU. We'll assume for the sake of argument that there's only one CPU. More CPUs will only mask the problem without solving it.
At the first command run, the BUF map is the command and at the end of the zeros :

let filename_bytes = bpf_probe_read_user_str_bytes(filename_src_addr, &mut *buf)?;

It's what we want.

I've replaced the numbers with letters because otherwise it's hard to understand for a human.

But remember that the map is persistent. In other words, the second time the program is run, the BUF map is no longer a list of 0. But :

Now let's assume that this command contains a lot of characters:

If we run another command with a smaller number of characters, the BUF map will contain :

The command + the end of the previous command + a lot of zeros

So we'll never get back into the condition:

if EXCLUDED_CMDS.get(& *buf).is_some() {
           info!(&ctx, "No log for this Binary");
           return Ok(0);
}

Reset the map!

The solution is to reset the buffer map.
To do this, add : *buf = [0u8; 512]; just after the unsafe tag.
The code of the main function will then be :

fn try_tracepoint_binary(ctx: TracePointContext) -> Result<u32, i64> {
    let buf = BUF.get_ptr_mut(0).ok_or(0)?;

    let filename = unsafe {
        *buf = [0u8; 512]; //we reset the buffer to array of zeros
        let filename_src_addr = ctx.read_at::<*const u8>(FILENAME_OFFSET)?;
        let filename_bytes = bpf_probe_read_user_str_bytes(filename_src_addr, &mut *buf)?;
        if EXCLUDED_CMDS.get(&*buf).is_some() {
           info!(&ctx, "No log for this Binary");
           return Ok(0);
        }
        from_utf8_unchecked(filename_bytes)
    };

    info!(&ctx, "tracepoint sys_enter_execve called. Binary: {}", filename);
    Ok(0)
}

Bug correction limited to one additional line. You can find the code a little cleaner in github.

For example, I've added a constant to tracepoint-binary-common/src/lib.rs :

pub const MAX_PATH_LEN: usize = 512;

This avoids hard-coding the maximum PATH size in kernel and user space.

That's all for this section. We've seen quite a lot in this section eBPF Map: two different maps with a hash and an array. One is used in user space and kernel space, the other only in kernel space. In the next section, we'll look at a rather special map that allows different kernel eBPF programs to work together.

My first Aya program

Joseph Ligier — Tue, 18 Feb 2025 09:17:23 +0000

I'm getting started with eBPF programming with Aya. The idea behind this series of articles is to get you started too.

In this section, we'll create our first Aya program. We'll also see that there are different types of eBPF programs.

FYI, this is the English version of an article originally published in French.

Example of Hello world Program

I assume you have an operating environment as defined in Part 1. You can also follow this step-by-step lab on creating an Aya program:

killercoda.com

Types of eBPF programs

To generate an Aya program, we'll use cargo generate :

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

We're going to answer a few questions:

Project Name: the name of the project (I put test-aya)
The second question is more interesting:

In fact, there are different types of eBPF programs. As we saw in Part 1, I wrote that there are 3 types of eBPF software:

Network
Observability and Tracing
Security

The choices presented to generate the eBPF program are, in fact, parts of the Linux kernel that can be modified or supervised by eBPF. So you need to think carefully about this before jumping headlong into programming.

As I wrote in Part 1, Aya is not yet fully mature compared with other solutions. Here's one reason why: although it may seem as if there are already a lot of program types available, there are still quite a few missing:

Meta: Add Support For All BPF Program Types #205

dave-tucker posted on Jan 31, 2022

[x] BPF_PROG_TYPE_SOCKET_FILTER
[x] BPF_PROG_TYPE_KPROBE
[x] BPF_PROG_TYPE_SCHED_CLS
[ ] #206
[x] BPF_PROG_TYPE_TRACEPOINT
[x] BPF_PROG_TYPE_XDP
[x] #207
[x] BPF_PROG_TYPE_CGROUP_SKB
[x] #208
[ ] #209
[ ] #210
[ ] #211
[x] BPF_PROG_TYPE_SOCK_OPS
[x] BPF_PROG_TYPE_SK_SKB
[x] #212
[x] BPF_PROG_TYPE_SK_MSG
[x] BPF_PROG_TYPE_RAW_TRACEPOINT
[x] #213
[ ] #214
[x] BPF_PROG_TYPE_LIRC_MODE2
[ ] #215
[ ] #216
[x] #217
[ ] #218
[ ] #219
[x] BPF_PROG_TYPE_TRACING
[ ] #220
[x] BPF_PROG_TYPE_EXT
[x] BPF_PROG_TYPE_LSM
[x] #223
[ ] #221

View on GitHub

What's more, as the Linux kernel continues to evolve, there will certainly be other types of eBPF programs available in the near future.

Time to choose

I tested a few types of eBPF program with Aya before writing this article. To study each type, you can quickly spend days: "I don't understand, it doesn't work" is certainly the phrase I'm uttering the most at the moment. There aren't many similarities between eBPF program types. If you've already played with XDP programs, you'll have other problems with Kprobe programs, for example. For this article, we'll be looking at TracePoint eBPF programs.

TracePoint

Tracepoints are, as the name suggests, places in the Linux code that have been marked (see recommendations). They are mainly used for tracing and debugging the Linux kernel.

All these points are accessible in the /sys/kernel/debug/tracing/available_events file:

They are in the format:

[Category]:[Name]

Just in time, this is the supplementary question we ask:

We're going to choose syscalls because everyone knows what a syscall is. Does everyone?

Syscalls

When a program is run, it asks the kernel to perform primary functions called syscalls (system calls).

To view the syscalls performed when a command is run, you can use the strace program. For example, you can use:

Which syscall to use

To find available tracepoint names, simply issue this command:

grep syscalls: /sys/kernel/debug/tracing/available_events

We can see that they are of the : sys_(enter|exit)_$name_of_syscall

enter : starting of syscall
exit : closing of syscall

We'll arbitrarily choose execve, which is the syscall that executes a program and the one that starts the syscall. So we have sys_enter_execve.

Test

Now we're going to test the generated program directly:

cd test-aya
RUST_LOG=info cargo run

This will take a little while: the time it takes to download and compile all the dependencies. Now you can go and have a cup of coffee!

Once your program has been demarched, run commands on another terminal, e.g.: ls
On the cargo run terminal, you'll see the following message every time you type a command:

[INFO test_aya] tracepoint sys_enter_execve called

So every time the syscall execve is called, this message will be displayed. We've just created the "Hello World" of the Tracepoint eBPF program (syscall:sys_enter_execve). So, for an eBPF program to start up, it needs an event (event-driven) that tells it to run: this is what we call a hook.

Anatomy of a Hello world Aya program

Let's take a look at what the cargo generate command has generated. As we saw in part 1, there are two parts to an eBPF program: kernel space and user space.

Kernel space

The eBPF program source code can be found here: test-aya-ebpf/src/main.rs. It is compiled first.
Here are its contents:

#![no_std]
#![no_main]

use aya_ebpf::{macros::tracepoint, programs::TracePointContext};
use aya_log_ebpf::info;

#[tracepoint]
pub fn test_aya(ctx: TracePointContext) -> u32 {
    match try_test_aya(ctx) {
        Ok(ret) => ret,
        Err(ret) => ret,
    }
}

fn try_test_aya(ctx: TracePointContext) -> Result<u32, u32> {
    info!(&ctx, "tracepoint sys_enter_execve called");
    Ok(0)
}

#[cfg(not(test))]
#[panic_handler]
fn panic(_info: &core::panic::PanicInfo) -> ! {
    loop {}
}

If you've been following part 1, there's one thing that should already shock you about Rust code: there is no main() function. This is a prerequisite for writing an eBPF program. To overcome this problem, we use the notation: #![no_main]

Another more disturbing prerequisite is that the standard library (std) is forbidden. Only the core library and all libraries that use it are allowed. This means you can't use the println! macro. To tell Rust not to use the standard: #![no_std]

But then how are we going to display anything if println! isn't possible? That's where Aya comes to the rescue: use aya_log_ebpf::info;
This library can be used to display messages if the RUST_LOG environment variable is set. It also includes warn, error, debug and trace (see documentation).
Thanks to this library, you can display :
info!(&ctx, "tracepoint sys_enter_execve called");

We're going to discard this part of the program:

#[cfg(not(test))]
#[panic_handler]
fn panic(_info: &core::panic::PanicInfo) -> ! {
    loop {}
}

Don't panic! We'll never change it. It's the code that makes the program work.
All that's left is to explain :

use aya_ebpf::{macros::tracepoint, programs::TracePointContext};

#[tracepoint]
pub fn test_aya(ctx: TracePointContext) -> u32 {
    match try_test_aya(ctx) {
        Ok(ret) => ret,
        Err(ret) => ret,
    }
}

fn try_test_aya(ctx: TracePointContext) -> Result<u32, u32> {
    Ok(0)
}

Two aya_ebpf libraries are used, including one for the tracepoint macro:

#[tracepoint] //here
pub fn test_aya(ctx: TracePointContext) -> u32 {
...
}

In other words, we're going to create an eBPF tracepoint program with the function test_aya().

The pub keyword is to say that the function is public; it's not really “important”, it's just to make the Aya framework work. If we remove these unwanted elements:

use aya_ebpf::programs::TracePointContext;

fn test_aya(ctx: TracePointContext) -> u32 {
    match try_test_aya(ctx) {
        Ok(ret) => ret,
        Err(ret) => ret,
    }
}

fn try_test_aya(ctx: TracePointContext) -> Result<u32, u32> {
    Ok(0)
}

We're back to a few things we've already seen in part 1.
Things to remember:

the test_aya() function is attached to the tracepoint program.
All the work will be done in the try_test_aya() function.
ctx: this is the context variable that will enable us to go beyond a hello world program.

As you can see, there's no mention of syscalls for the moment. I want this Tracepoint program to be attached to an execve syscall. Good timing: let's take a look at the user-space code now.

User space

In this article, we won't be modifying the user space code. It can be found in this file: test-aya/src/main.rs.
I'll simplify its code for a better understanding:

use aya::programs::TracePoint;
use log::{debug, warn};
use tokio::signal;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let mut ebpf = aya::Ebpf::load(aya::include_bytes_aligned!(concat!(
        env!("OUT_DIR"),
        "/test-aya"
    )))?; //1
    if let Err(e) = aya_log::EbpfLogger::init(&mut ebpf) {
        warn!("failed to initialize eBPF logger: {}", e);
    } //2
    let program: &mut TracePoint = ebpf.program_mut("test_aya").unwrap().try_into()?; //3
    program.load()?; //4
    program.attach("syscalls", "sys_enter_execve")?; //5

    let ctrl_c = signal::ctrl_c();
    println!("Waiting for Ctrl-C...");
    ctrl_c.await?;
    println!("Exiting...");

    Ok(())
}

This Rust code is a little more traditional: you can use the standard library, as evidenced by the println! and the main() function.
I've commented out the important parts of the code with numbers:

1: We'll load the previously compiled eBPF code into an ebpf variable
2: We'll start displaying the eBPF logs (for example, the info! from the previous code) in the user space
3: Convert the main function of the eBPF code into Tracepoint code
4: Load the main program function (the test_aya() function)
5: Attach it to the tracepoint syscalls:sys_enter_execve

The rest of the code is for program operation, such as not quitting the program before the logs start.

If you're new to Rust, there are certainly some parts of the code that may seem obscure to you. That's a good thing! The next section is dedicated to Rust.

Rust, it's getting complicated!

Before modifying the code, I think it's worth reviewing the Rust language a little more theoretically. I didn't want to scare you too much in part 1 😃

Types

In Part 1, we looked at variable declaration and modification. But we didn't talk much about types. This is important because, for example, all functions must be filled in with the various types.
There are two types:

scalar types
compound types

Scalar types

Let's take a look at scalar types: for integers, for example, we can define very precisely how many bits they are encoded in:

It's often optional to declare the variable with its type, but to remove any ambiguity, we do it this way:

let my_variable :i64 = 2055;

With println!, you can display the contents in a different way, for example, you can convert to hexadecimal:

println!("{:x}", ma_variable);

That's the magic of the macro! There's also this kind of possibility with info! in Aya. For example, you can convert a number into an IP or MAC address: very useful for eBPF networking.

Let's finish with scalar types and talk about casting, i.e. modifying the type. Let's take a look at this example:

fn addition(x: u32, y: u32) -> u32 {
    x + y
}

fn main() {
    let a: u16 = 10;
    let b: u16 = 20;

    let res = addition(a, b); //❌ ERROR: u16 != u32
    println!("{}", res);
}

This program won't work because the arguments require u32 and not u16. It is of course possible to change the function directly, but you don't always have access to the function as you would in a library. How do I change the code? Use the keyword as:

fn addition(x: u32, y: u32) -> u32 {
    x + y
}

fn main() {
    let a: u16 = 10;
    let b: u16 = 20;

    let res = addition(a as u32, b as u32); // come as you are
    println!("{}", res);
}

Compound types

Now let's talk about compound types, for example how to represent integer arrays:

let _my_array: [i8; 2] = [0, 2]; // An array of 2 entries of type i8

An array has a fixed number of entries: you can't add a number after the fact. There are also dynamic arrays in Rust, such as Vec. However, eBPF programs (on the kernel side) cannot use them: they require arrays with a number of entries already defined before compilation. The strategy is therefore to evaluate the maximum number an array can have by filling it with 0.

let _zeros_array = [0u8; 256]; // An array of 256 entries of 0 of type u8

And what about strings?

The default string in Rust is an array (a slice, to be precise - I'll get a slap on the wrist if I don't) with a fixed number of u8 entries (and therefore UTF-8 encoding). It is not, as in other programming languages, an array of characters (char). The notation is &str.

Thus, it's not possible to concatenate in this way:

   let _toto = "aaaa";
   let _tutu = "bbbb";
   let _toto = _toto + _tutu;

However, if we convert _toto to String, it works:

   let _toto = "aaaa"; //_toto is of type &str
   let _tutu = "bbbb"; //_tutu is of type &str
   let _toto = _toto.to_owned() + _tutu; //_toto is of type String

String is the equivalent of Vec. This makes it possible to have arrays of u8 dynamically.

Structures

Structures are a mixture of different types. The keyword is struct. For example, to create a simple role-playing game :

struct Person {
    name: String,
    age: u32,
}

fn main() {
    let person = Person {
        name: String::from("Alice"),
        age: 30,
    };

    println!("Name: {}, Age: {}", person.name, person.age);
}

If you find initialization a little complicated, you can create methods with the impl keyword:

struct Person {
    name: String,
    age: u32,
}

impl Person {
    fn new(name: &str, age: u32) -> Person {
        Person { name: String::from(name), age }
    }

    fn old(&mut self) { //👴🏻
        self.age += 1;
    }

    fn change_name(&mut self, name: &str) {
        self.name = String::from(name);
    }
}

fn main() {
    let mut person = Person::new("Julia", 40);

    println!("Before: Name: {}, Age: {}", person.name, person.age);

    person.age();
    person.changer_name("Julian");

    println!("After: Name: {}, Age: {}", person.name, person.age);
}

As you can see, thanks to the structures, the programming language reads almost naturally. In a way, it's like an object language.
To give you a more realistic example, take a look at the code generated in the user area above:

let program: &mut TracePoint = ebpf.program_mut("test_aya").unwrap().try_into()?;
    program.load()?;
    program.attach("sys_enter_execve", "syscalls")?;

TracePoint is actually a structure. Let's read the documentation:

What can be deduced from the doc, the approximate code:

struct TracePoint {
[I don't know]
}

impl TracePoint {
    pub fn load(&mut self) -> Result<(), ProgramError> {
        [see the source code]
    }

    pub fn attach(&mut self, category: &str, name: &str) -> Result<...,...>{
        [see the source code]
    }
}

Generic Functions

Previously, we had to cast to have the same type:

fn addition(x: u32, y: u32) -> u32 {
    x + y
}

fn main() {
    let a: u16 = 10;
    let b: u16 = 20;

    let res = addition(a as u32, b as u32); //Here
    println!("{}", res);
}

Using generic function, we don't need to cast:

fn addition<T>(x: T, y: T) -> T
where
    T: std::ops::Add<Output = T>,
{
    x + y
}

fn main() {
    let a: u16 = 10;
    let b: u16 = 20;

    let res = addition(a, b);
    println!("{}", res);
}

This way, you won't have to think about which type you need to use the addition function.
The function is inevitably a little more complicated to write. We won't be writing any in this section. But for use via a library, it's pure bliss (I'm exaggerating a little bit).

Soon, we'll see a generic function:

Result

We've been seeing Result<...,...> a lot since part 1. Let's talk about it in a little more detail.
Result is an enumeration. We haven't seen what it is, but to put it simply: Result lets you create functions that can result in a success or an error. This is elegant when used with match or ? as we saw in Part 1.

As with generic functions, T and E can be of any type (within certain constraints).
As a reminder, here's a simple example of a function that returns Result :

fn get_some_value(value :u32) -> Result<u32, u32> {
    match value > 10 {
        true => Ok(value),
        false => Err(0),
    }
}

const NUM :u32 = 55;

fn main() -> Result<(), u32> {
   let v = get_some_value(NUM)?;
   println!("{}", v);
   Ok(())
}

In this example, only integers greater than 10 are displayed.

Option

Option is another enumeration quite similar to Result: the function returns either Some(T) or None. It's an optional value.

To retrieve the T value, there's no equivalent to the question mark with Result. However, a trick is to convert the Option type with ok_or(...) to Result and then add the question mark.
Here's an equivalent of the previous code with a function that returns Option<T> :

fn get_some_value(value :u32) -> Option<u32> {
    match value > 10 {
        true => Some(value),
        false => None,
    }
}

const NUM :u32 = 55;

fn main() -> Result<(), ()> {
   let v = get_some_value(NUM).ok_or(())?;
   println!("{}", v);
   Ok(())
}

Another solution to retrieve this value is to use unwrap() method:

fn get_some_value(value :u32) -> Option<u32> {
    match value > 10 {
        true => Some(value),
        false => None,
    }
}

const NUM :u32 = 55;

fn main() -> Result<(), ()> {
   let v = get_some_value(NUM).unwrap(); //No need of "?" now
   println!("{}", v);
   Ok(())
}

But there's a big BUT: it's not possible to use unwrap() in kernel space code. Why not? To cut a long story short: unwrap() can panic, and an eBPF program can't afford that:

The piece of code that we discarded in the kernel space above :

#[cfg(not(test))]
#[panic_handler]
fn panic(_info: &core::panic::PanicInfo) -> ! {
    loop {}
}

It can be used to manage the case of unwrap(), for example.

Memory Management

When a variable is created in a program, the compiler must take care of finding where in RAM to add the variable, as well as deleting it to avoid so-called memory leaks. For fixed variables such as integers or non-dynamic arrays, variables are stored in stacks, so there are no problems with releasing them. Thus, because of the restrictions in kernel space programs, there are no clean-up problems in eBPF. Dynamic variables, on the other hand, are stored in heaps, and that's where the problems come in.

In C, we let the developer do this with malloc and free. If he forgets to free memory, it often goes unnoticed, but is a potential source of bugs.

In other languages (such as Python or Go), the garbage collector takes care of cleaning up automatically, without developer intervention. However, this is done at the expense of performance.

In Rust, we use the notion of ownership to solve the problem.

Let's take an example:

fn main() {
    let s1 = String::from("Hello");
    let s2 = s1;

    println!("{}", s1);
}

s1 has the String type, which is dynamic

This program cannot compile. Why?

s1 will reserve memory space in the heap:let s1 = String::from("Hello");
s2 will retrieve the ownership of this memory space: let s2 = s1; Thus s1 has lost ownership of this memory space:

This means that no two (or more) variables can have the same memory space. Rust will automatically release a variable once it has left the scope.

Borrowing

The most elegant solution is to use a reference (Keyword: &). These references are also known as safe pointers:

fn main() {
    let s1 = String::from("Hello");
    let s2 = &s1;

    println!("{}", s1);
    println!("{}", s2);
}

This will display Hello twice.
We say that s2 borrows s1's value, but s1 retains its property.
Let's take one last example to show you that this isn't always obvious:

fn print_length(s: String) {
    println!("Length: {}", s.len());
}

fn main() {
    let s = String::from("Hello");
    print_length(s);

    println!("{}", s);
}

This code doesn't compile either. Why?
s will reserve a memory space in the heap:
let s = String::from("Hello");
The print_length() function will take the property of this memory space:
print_length(s);
At the end of this processing, Rust will delete this memory space:

fn print_length(s: String) {
 println!("Length: {}", s.len());
}

So the display of s crashes.

To solve this problem simply use this borrowing system:

fn print_length(s: &String) { // We add an "&"
   println!("Longueur: {}", s.len());
}

fn main() {
    let s = String::from("Hello");
    print_length(&s); // We don't forget to also add it

    println!("{}", s);
}

When you're not used to it, you often make the mistake. But the error messages are self-explanatory and therefore easy to correct.

Unsafe

The unsafe keyword is very useful when working at low level. It's the sysadmin equivalent of sudo. By default, Rust has protections, notably for reading memory. The unsafe keyword lets you tell Rust: "Don't worry, I know what I'm doing! If you set unsafe anywhere, Rust will remind you with a warning, or if you don't set unsafe anywhere, Rust will tell you to set it if that's what you really want to do.

Raw pointers

Let's finish this busy section with raw pointers. The notion is similar to the C pointer. It lets you know the address of the variable. There are two types of raw pointers:

If data of type T cannot change : *const T
If data of type T can change: *mut T

To convert to a raw pointer, use the as_ptr() function:

Let's give an example:

fn main() {
    let a = "toto";
    let memory_location = a.as_ptr() as usize;
    println!("toto is on the memory address: {:x}", memory_location);

    let a = 12;
    let memory_location = &a as *const i32 as usize;
    println!("12 is on the memory address {:x}", memory_location);
}

That's all for this Rust part. I hope it wasn't too complicated and dense to understand. If it was, don't worry: let us guide you through the rest, and we'll review each point for a concrete case.

Improving the program

What are we going to do?

We've already created a program that every time a binary is executed, it displays a few things in the logs. It would be nice to be able to see which binary is being executed. So we're going to create a little program that will log all the binaries that are executed on the machine. It might be handy to see this for security reasons.

Reminder

To do this, you'll need to modify the aya code in kernel space test-aya-ebpf/src/main.rs
This is the main part you'll need to modify:

fn try_test_aya(ctx: TracePointContext) -> Result<u32, u32> {
    info!(&ctx, "tracepoint sys_enter_execve called");
    Ok(0)
}

This is based on the ctx variable, which is a TracePointContext structure.
To do this, we'll take a look at the documentation:

The library is located at the program level:
use aya_ebpf::programs::TracePointContext;
This shows all the documentation for each type of eBPF program:

This shows the functions that can be used with TracePointContext:

We're not interested in the first function, which is used to create a TracePointContext. It's probably used in the macro. That leaves us with the second function: read_at(). This function reads the tracepoint at a certain offset. How do we find this offset?

You need to look in the syscall tracepoint file. To find it, go to: /sys/kernel/debug/tracing/events/[category]/[name]. And the file name is format.
So the file is here: /sys/kernel/debug/tracing/events/syscalls/sys_enter_execve/format.

We'll try to retrieve the filename with offset 16:

fn try_test_aya(ctx: TracePointContext) -> Result<u32, u32> {
    let filename = ctx.read_at::<u64>(16);
    info!(&ctx, "tracepoint sys_enter_execve called");
    Ok(0)
}

I wasn't sure what to put in place of T, so I arbitrarily set the type to u64.
If you try to compile :

It works better now with unsafe:

fn try_test_aya(ctx: TracePointContext) -> Result<u32, u32> {
    let filename = unsafe {ctx.read_at::<u64>(16)};
    info!(&ctx, "tracepoint sys_enter_execve called");
    Ok(0)
}

Now let's try using this variable. The result of the read_at function is Result(u64, i64). The aim is to retrieve u64. Just use the question mark (?).
So we'll get :

fn try_test_aya(ctx: TracePointContext) -> Result<u32, u32> {
    let filename = unsafe {ctx.read_at::<u64>(16)?};
    info!(&ctx, "tracepoint sys_enter_execve called");
    Ok(0)
}

Nevertheless, compilation won't work because if it makes an error, the read_at function returns an i64 and my final function returns a u32.

We have to change:

fn try_test_aya(ctx: TracePointContext) -> Result<u32, i64> { //u32 -> i64
    let filename = unsafe {ctx.read_at::<u64>(16)?};
    info!(&ctx, "tracepoint sys_enter_execve called");
    Ok(0)
}

Similarly, the Tracepoint function must always return a u32. We must therefore cast the type to u32 :

pub fn test_aya(ctx: TracePointContext) -> u32 {
    match try_test_aya(ctx) {
        Ok(ret) => ret,
        Err(ret) => ret as u32, //cast
    }
}

With these type-matching modifications, it should compile. Let's have a look at the contents of filename. Here's the whole file now if you're lost :

#![no_std]
#![no_main]

use aya_ebpf::{macros::tracepoint, programs::TracePointContext};
use aya_log_ebpf::info;

#[tracepoint]
pub fn test_aya(ctx: TracePointContext) -> u32 {
    match try_test_aya(ctx) {
        Ok(ret) => ret,
        Err(ret) => ret as u32,
    }
}

fn try_test_aya(ctx: TracePointContext) -> Result<u32, i64> {
    let filename = unsafe {ctx.read_at::<u64>(16)?};
    info!(&ctx, "tracepoint sys_enter_execve called {}", filename); // the modif
    Ok(0)
}

#[cfg(not(test))]
#[panic_handler]
fn panic(_info: &core::panic::PanicInfo) -> ! {
    loop {}
}

If we run a cargo run again, here's what we see:

[INFO  test_aya] tracepoint sys_enter_execve called 94803283704040
[INFO  test_aya] tracepoint sys_enter_execve called 94803283704112
[INFO  test_aya] tracepoint sys_enter_execve called 94173001563176
[INFO  test_aya] tracepoint sys_enter_execve called 824637710416
[INFO  test_aya] tracepoint sys_enter_execve called 94865232898256
[INFO  test_aya] tracepoint sys_enter_execve called 824638316624
[INFO  test_aya] tracepoint sys_enter_execve called 94865232898256

These numbers are not file names. This was to be expected, given that the type is u64. What I notice is that when I run a command: I'm always number 94865232898256 if it's the server it's the other numbers, if I change user I get a different number.
Well... that's not much help. Shall we give up? The documentation isn't complete, it doesn't say what it's really for.
I look at the source code of the read_at function:

pub unsafe fn read_at<T>(&self, offset: usize) -> Result<T, i64> {
        bpf_probe_read(self.ctx.add(offset) as *const T)
    }

And what does bpf_probe_read do?

In this way, an address in memory is accessed. Now we need to think about how to successfully read this address.
I'll take a look at the helper functions:

I have the feeling that this is this function that i need:

Let's add these lines and see what happens:

    let mut buf = [0u8; 16]; //let's create a array of u8
    let _my_str_bytes = unsafe { aya_ebpf::helpers::bpf_probe_read_user_str_bytes(filename, &mut buf)? };

So all we have to do is change the u64 type to *const u8 (a raw pointer) and we'll change the variable names to be consistent with the documentation:

    let filename_src_addr = unsafe {ctx.read_at::<*const u8>(16)?};
    let mut buf = [0u8; 16];
    let _filename_bytes :&[u8] = unsafe { aya_ebpf::helpers::bpf_probe_read_user_str_bytes(filename_src_addr, &mut buf)? };

    info!(&ctx, "tracepoint sys_enter_execve called {}", filename_src_addr as u64); //We also cast

The compilation works! Now we have a byte-coded file name. Now we need to figure out how to convert it to &str.

That's what I want, but as I said earlier, eBPF doesn't accept the standard library (std).
Miracle! It also exists in the core library :

So we add:
let _filename = core::str::from_utf8(_filename_bytes);
Let's see if it compiles:

So it compiled fine. But the eBPF verifier is not happy at all. The verifier is a kernel protection system that prevents an eBPF program from being launched if it considers it dangerous for the kernel. What we see in the screenshot is JIT code (Just In Time code).

The explanation is at the end:

In the documentation, there's another function that might suit us. Perhaps from_utf8 makes too many checks that are not compatible with the eBPF verifier?

Let's add _unchecked and unsafe:

let _filename = unsafe { core::str::from_utf8_unchecked(_filename_bytes) };

It compiles!
By modifying the log line:

info!(&ctx, "tracepoint sys_enter_execve called Binary: {}", _filename);

I connect with ssh on the server where the program is installed, I see all the binaries that are executed :

The code works, and if you clean it up afterwards, you'll get a code similar to this one

You can find the program in GitHub.

That's all for this part. I hope you enjoyed it. It was much more technical than the first part. In the next part, we'll be looking at a few things we've already mentioned: the eBPF map. This will, for example, solve the problem we have with the program: file names are truncated. With an eBPF map, we can solve the problem!

Let's introduce eBPF and Aya

Joseph Ligier — Mon, 10 Feb 2025 12:50:33 +0000

I'm getting started with eBPF programming with Aya. The idea behind this series of articles is to get you started too.

In this article, we'll explain what eBPF is, what Aya is and what you need to know to use Aya. Finally, we'll set up an environment for developing with Aya.

FYI, this is the English version of an article originally published in French.

Ready to learn eBPF with Aya?

What is eBPF?

Definition

I'll try to answer that question throughout the articles. In a few words, I'd say it's programming in the Linux kernel. It allows you to create a kernel program dynamically, i.e. without having to recompile it and reboot the computer to boot on this new kernel. So don't expect to easily create a video game like doom with eBPF.

The first advantage is that the development cycle is much shorter than if you had to modify the Linux kernel directly.

Origin Story

eBPF stands for extended Berkerley Packet Filter. Before eBPF, there was BPF. Berkerley is a university where BPF was founded in 1992, and was concerned solely with the network. You'll see that eBPF (which appeared in 2014 in linux kernel 3.18) allows you to go beyond the network in the kernel. It's a silent revolution on a par with the cgroups and namespaces that led to the creation of Docker and Kubernetes. To find out more about its history, take a look at eBPF's Wikipedia entry or the film:

Examples of simple programs

To give you a more concrete idea of what can be done with eBPF, let's give you a non-exhaustive list of small programs that could be done with eBPF:

The top or ps commands, which allow you to watch processes and what they occupy in terms of CPU and RAM
The tcpdump command, which allows you to watch network flows on a server
The strace command, which allows you to see a process's system calls
The iptables-type command, which allows you to manage network flows
fail2ban, which prevents brute force attacks

Examples of well-known software that use eBPF

It would be hard not to talk about eBPF without mentioning Cilium, a CNI plugin for Kubernetes that I've written about in numerous articles. Indeed, Cilium is based on eBPF. Its project is the driving force behind eBPF. Its main aim is to improve network flow performance: unlike other solutions based on iptables, which move back and forth between user space and kernel space, Cilium uses eBPF to stay in kernel space for as long as possible, thereby improving performance. But let's not forget Cilium's observability with the Hubble project, which allows you to see live all the flows between each pod: in a way, a tcpdump for Kubernetes. I could also talk about Cilium's security with Cilium Network Policy, but we're here to talk about eBPF.

Hubble GUI

There are also other programs you probably know that use eBPF, such as systemd, the initialization system, or falco, a security tool. Your Linux server or Android phone probably has eBPF programs already installed without you even knowing it! Speaking of operating systems, eBPF was originally designed to run exclusively on Linux. But there's a Microsoft-backed project that will enable eBPF to be used on Windows. When will Cilium run on a Windows server?

As you can see, a wide variety of programs can be created. There are three kinds of eBPF software:

Network (Cilium, load balancer)
Observability and tracing (top, ps, tcpdump, Hubble)
Security (fail2ban, falco, systemd)

How do you actually program the kernel?

In a traditional program, we have a source code. From this source code, we create the program, compiling it if it's a compiled language:

In eBPF, there is not one program but two:

an eBPF code that will be compiled in user space, but which can only run in kernel space
a user-space code that mainly loads the eBPF binary just compiled into the kernel

Next level

We'll see later that it's possible to communicate between kernel space and user space (via an eBPF map) and also to communicate between kernel space eBPF programs (via tail calls).

Let's talk about Aya

Aya is an eBPF framework that lets you write eBPF programs exclusively in Rust. This simplifies the creation of eBPF programs. For example, the program can be compiled and started from a single command line: everything is transparent.

If you don't know Rust, don't worry, I'll give you the basics for writing eBPF programs. I didn't know Rust at all before writing these articles. So I was at the same point not so long ago. Here are some nice programs written with Aya:

blixt: a level 4 load balancer created by the Kubernetes SIGs (Special Interest Groups) group ;
kunai: a security software program for threat management and security monitoring, similar to Falco or Tetragon;
mybee: a mySQL profiler

You can find more on the dedicated page.

Other choices than Aya

Before deciding which eBPF framework to choose for articles, I spent a long time thinking about which would be the most relevant.

There are two types of eBPF framework:

those that use two different programming languages: one for kernel space and another for user space
those that use a single language for both kernel and user space.

For example, Cilium uses the ebpf-go framework. It uses:

Golang for user space
C for kernel space

I've opted for the second type of eBPF framework, the one with a single language, to avoid having to teach you two different languages. Unfortunately, there aren't many to choose from:

libbpf: for C/C++ enthusiasts (first framework release: June 2019, v1: 2022)
Aya: for shellfish eaters 🦀 (first framework release: June 2021)
zbpf: for Zig adventurers (first framework version: December 2023)

I was more interested in learning a new language, so I ruled out C. I was tempted by the Zig language because I'd heard good things about it. But I was seduced by Aya because it's starting to mature and has a bigger community than zbpf. There are lots of examples of Aya code all over the Internet. That's important, especially when you're just starting out.

I think Aya is a good compromise between simplicity, modernity and maturity. I was just a little worried about the simplicity of the Rust language. Well, we're going to learn some Rust basics in the next section.

Rust: a complicated language?

In the technical part of this article, I assume you know at least one programming language (at least one like Python). I'm going to show you the syntax and some of its subtleties.

Installation and operation

I installed Rust with rustup.

To compile a file, just do:

rustc hello.rs

To run it:
./hello

Hello Rust

It's traditional when learning a language to see the “hello world”.

fn main(){
   println!("Hello World");
}

What's relevant in this program?

Functions have the identifier fn
Every program must have a main function
You can see an exclamation mark at the println “function”
Don't forget the semicolon at the end of each instruction

Variable in mutation

Now we'll see how to define a variable:

fn main(){
   let m = "World";
   println!("Hello {}", m);
}

This piece of code does exactly the same thing as before.

What's relevant in this program?

a variable is defined with the let keyword
you can add arguments to println!. In fact, println! isn't really a function, it's a macro from the standard library. These are identified by the exclamation mark.

Now we're going to try and change the value of variable m:

fn main(){
   let m = "World";
   m = "Aya";
   println!("Hello {}", m);
}

This code is incorrect, and the error message is as follows:

If you still don't understand, Rust offers documentation at the end:
rustc --explain E0384

In fact, by default, variables are immutable, i.e. their value cannot be changed. You need to add the mut keyword to make this possible:

fn main(){
   let mut m = "World";
   m = "Aya";
   println!("Hello {}", m);
}

This will now do “Hello Aya”. At compile time, there's a warning because Rust finds it odd to directly assign another value to m without doing a few things first. For example, there will be no warning with:

fn main(){
   let mut m = "World";
   println!("Hello {}", m);
   m = "Aya";
   println!("Hello {}", m);
}

There are also constants in Rust, identified by the keyword const. The difference between constants and non-mutable variables is that constants are evaluated at program compilation time, whereas variables are evaluated at program execution time, which is less efficient.

Cargo: the rusty Swiss Army knife

We rarely use rustc directly for “real” projects. Instead, we use cargo. It allows you to compile, download libraries (crates), launch the program, etc.: it's the Rust project manager.

cargo new project
cd project

In Cargo.toml, you can define Rust dependencies.

If you run:

cargo run
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 2.14s
     Running `target/debug/project`
Hello, world!

You end up with a “hello world” program. With this command, everything is done automatically: compilation and execution. It's almost as if you were coding in an interpreted language.

To find the binary you've created:

./target/debug/project
Hello, world!

Functions

It's hard to escape functions when you're trying to make clean code that goes beyond a “hello world”.

Here's an example of a function:

fn aya(m: &str){
    println!("Hello {}", m);
}

fn main() {
    let m = "aya";
    aya(m);
}

Note that it is essential to have the type of the arguments: variable_name: variable_type. This is usually the main difficulty when writing a function: “Oh yes, what's the type again?”.

Game, Set and

match is widely used in Rust and therefore in the Aya framework, as it makes conditions clearer than if conditions:

fn main() {
    let greeting = "bonjour";

    match greeting {
        "bonjour" => println!("Hello!"),
        "au revoir" => println!("Goodbye!"),
        _ => println!("I don't know what you mean."),
    }
}

The equivalent code with if:

fn main() {
    let greeting = "bonjour";

    if greeting == "bonjour" {
        println!("Hello!");
    } else if greeting == "au revoir" {
        println!("Goodbye!");
    } else {
        println!("I don't know what you mean.");
    }
}

The code can be made even more succinct by mixing match and variable:

fn main() {
    let greeting = "bonjour";

    let trad = match greeting {
        "bonjour" => "Hello!",
        "au revoir" => "Goodbye!",
        _ => "I don't know what you mean.",
    };

    println!("{}", trad);
}

Remix

Let's finish with a slightly more real-life example that mixes many of the concepts we've already seen with others: reading a text file.

The following code will read the contents of the example.txt file:

use std::fs::File;
use std::io::{self, Read};

fn read_file_contents(path: &str) -> Result<String, io::Error> {
    let mut file = File::open(path)?;
    let mut contents = String::new();
    file.read_to_string(&mut contents)?;
    Ok(contents)
}

fn main() {
    match read_file_contents("example.txt") {
        Ok(contents) => println!("File reading with success:\n{}", contents),
        Err(e) => eprintln!("Error during the reading: {}", e),
    }
}

the first two lines allow you to use the standard library. It's a condensed notation. It's equivalent to:

use std::fs::File;
use std::io;
use std::io::Read;

In the main function, we have the match we saw earlier, but with a function as parameter. This function will try to read the file. If it succeeds, it passes to Ok(...), otherwise to Err(e), for example if the example.txt file doesn't exist.

Let's look at the read_file_contents function: it returns a Result<String, io::Error>. In other words, it returns either an Ok(string (the file contents)) if ok, or an error. There's a little subtlety in this line:
let mut file = File::open(path)?;

The question mark. Equivalent to:

let mut file = match File::open(path) {
        Ok(f) => f,
        Err(e) => return Err(e),
};

We try to open the file, but if we can't, we return an error.

Same thing for:
file.read_to_string(&mut contents)?;
We'll try to convert the file to string and put it in the contents variable, otherwise we'll return an error.

One last subtlety:
Ok(contents)

Notice that there's no semicolon at the end, which isn't a mistake. It's idiomatic. It's the equivalent of:
return Ok(contents);

As you can see, with a 'simple' example, it's easy to read, but if you look a little deeper, there are a lot of Rust notions at play.

We've only partially seen the basics of Rust. We'll continue learning Rust in the next few parts. If you want to learn Rust for larger programs, I recommend you read the Rust book.

Development environment for Aya

We're now going to create our development environment for Aya.

Operating system

I assume you're running Linux (I installed Debian 12). If you're running MacOSX, I recommend lima to create a VM. Otherwise, I've created a lab that follows this tutorial on the Killercoda site:

killercoda.com

The basics

You already need to install Rust and all its software (especially cargo) with rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
. "$HOME/.cargo/env" #To have the good PATH

Since Aya is relatively new, we need to configure Rust to access features that are still in development (nightly):

rustup default stable
rustup toolchain add nightly
rustup component add rust-src --toolchain nightly

Libraries for Aya

We're now going to install some Rust libraries.

For the installation of cargo-generate (allowing to create an Aya environment from template), I already have to install ssl libraries:

apt install openssl libssl-dev pkg-config -y
cargo install cargo-generate

You also need to install bpf-linker:

cargo install bpf-linker

Testing your environment

We're now going to check that the installation went smoothly.

We'll clone a repo containing a few examples of Aya programs:

git clone https://github.com/littlejo/aya-examples
cd aya-examples/tracepoint-binary

Finally, we'll start the program:

RUST_LOG=info cargo run

the RUST_LOG environment variable is used to display information logs directly in the console
if you forget this environment variable, nothing will be displayed, which can be disturbing.

This will take quite some time: downloading the libraries, compiling them, and so on. Once it's done:

On another terminal, run shell commands such as ls.

At the terminal where the eBPF program was launched, you should see something similar:

This program allows you to observe all the programs running on the machine.

That's all for this part. I hope you've enjoyed the start of this journey into the world of eBPF with Aya.

In the next part, we'll get down to the nitty-gritty and write our first Aya program.

DEV Community: Joseph Ligier

XDP: The Ultra-Fast Firewall Inside Linux

XDP

XDP: The Ultra-Fast Firewall Inside Linux · The Little Jo’s Blog

uProbe: Observability for All Developers

uProbes

Observability for All Developers with uProbes · The Little Jo’s Blog

Tracing your syscalls with Aya

Creation of a second eBPF program

Reminder

What are we going to do now?

Project cloning

Let's create a "hello world" program

Return of the Jedi

Code: Return

Tracing execve syscall

Creating timers

Transmission between eBPF programs

Merge logs

eBPF map type problem

Hook file conversion

Converting the filter file

Converting the display file

Retrieving a map in the hook_exit.rs program

Code enhancement

Grouping eBPF maps

Modifying hook entry

filter

display

exit

Adding features

Modifying tail calls

Filter return code

Add duration to display

Modularizing your Aya program with tail calls

Tail calls: Structuring the program

What is it?

A few limitations though...

What's all this magic?

Restructuring kernel-side code

Project cloning

Reminder

Divide and conquer

Common People

Hook

Let's create the foundations for tail calls

What are we going to do?

Process

Creating an eBPF map dedicated to tail calls

Creating eBPF programs

Retrieving the eBPF map from user space

Loading programs and eBPF map

Let's set up the tails calls

Program modification data retrieval (hook)

Modifying the filter program

Modifying the display program

Inline function

What's an inline function?

Creating an inline function

The code

Enhancing your Aya program with eBPF maps

My first eBPF map

What's wrong with it?

Your first limit

How to create an eBPF map?

How to modify an eBPF map?

eBPF maps: benefits and limitations

Definition

Go beyond 512 bytes

Input

Output

Communication between eBPF programs

What can you put in these maps?

The different types of eBPF maps

A little eBPF map sorting

Flag on an exam

Another slice of Rust?

Introduction

Fixed-size array reference

Exercise

Retrieving a map in the `hook_exit.rs` program