Skip to content
Français
Account: not signed in, sync available My learning
Select theme
Français

Write and load your first eBPF program

By updated

Improve this page

By the end of this page, you will have checked that your kernel supports eBPF, loaded a real program into the kernel and watched, live, every command run on your machine. We start with the no-code route (bpftrace, one line is enough), then, for those who read C, we write a real program with BCC and look at what happens under the hood: compilation, verifier, loading, attachment. Audience: an administrator comfortable with the Linux terminal. No prior knowledge of eBPF is required, but reading What is eBPF first helps to place the terms.

What you will learn

  • Check that the kernel of your machine supports eBPF
  • Install the eBPF toolchain on a recent distribution
  • Trace program executions with a single line of bpftrace
  • Identify each step: compilation to bytecode, verification, loading, attachment
  • Decipher a verifier rejection and understand why it protects the machine

Prerequisites

  • A Linux VM with a recent kernel (5.x or 6.x). Here Ubuntu 24.04, kernel 6.8.0.
  • root or sudo access: loading an eBPF program is a privileged operation.
  • Something to generate a little activity (running commands) so that events go by.
  • For route 2 only: being able to read C (a function, a pointer, an if) and a bit of Python. Route 1 requires none.

Does your kernel support eBPF?

A kernel supports eBPF when it is compiled with CONFIG_BPF and CONFIG_BPF_SYSCALL, and it allows CO-RE portability when it exposes its BTF. Recent distributions (Ubuntu 24.04, Debian 13, RHEL 10) all enable it, but a minimal image or a custom kernel may go without. It is better to check before installing anything.

First test, the most telling: does the kernel expose its type description (the BTF, explained in the lesson CO-RE and BTF)? If this file exists, the kernel was compiled with CONFIG_DEBUG_INFO_BTF.

Terminal window
ls -l /sys/kernel/btf/vmlinux

The file must appear, read-only, with a size of several megabytes. A No such file or directory means that CO-RE-based tools will not work; bpftrace and BCC, for their part, keep working as long as the BPF options are present.

Second test, the kernel compilation options, which distributions publish in /boot:

Terminal window
grep -E '^CONFIG_(BPF|BPF_SYSCALL|DEBUG_INFO_BTF)=' /boot/config-$(uname -r)

You expect three lines ending in =y: CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y and CONFIG_DEBUG_INFO_BTF=y. An option is missing? The /boot/config-* file may also be absent on some images (container, cloud provider kernel); in that case, /proc/config.gz plays the same role when it exists.

Third test, once bpftool is installed (next step): it queries the kernel itself rather than its configuration.

Terminal window
sudo bpftool feature probe kernel | head -20

The command lists the program, map and helper types that this kernel really accepts. It is the most reliable source: a compiled option does not guarantee that the program type you need is available. Real output on AlmaLinux 10.2 (kernel 6.12, bpftool 7.7.0):

Scanning system configuration...
bpf() syscall restricted to privileged users (admin can change)
JIT compiler is enabled
JIT compiler hardening is enabled for unprivileged users
JIT compiler kallsyms exports are enabled for root
Global memory limit for JIT compiler for unprivileged users is 528482304 bytes
CONFIG_BPF is set to y
CONFIG_BPF_SYSCALL is set to y
CONFIG_HAVE_EBPF_JIT is set to y
CONFIG_BPF_JIT is set to y
CONFIG_BPF_JIT_ALWAYS_ON is set to y
CONFIG_DEBUG_INFO_BTF is set to y
CONFIG_DEBUG_INFO_BTF_MODULES is set to y
CONFIG_CGROUPS is set to y
CONFIG_CGROUP_BPF is set to y
CONFIG_CGROUP_NET_CLASSID is set to y
CONFIG_SOCK_CGROUP_DATA is set to y
CONFIG_BPF_EVENTS is set to y
CONFIG_KPROBE_EVENTS is set to y
CONFIG_UPROBE_EVENTS is set to y

On Ubuntu 24.04 (kernel 6.8, bpftool 7.4.0), the lines are the same, except JIT compiler hardening is disabled in place of JIT compiler hardening is enabled for unprivileged users. These first twenty lines only cover the configuration: the program types (eBPF program_type kprobe is available, for example) and helper types come further down in the full output.

How do you install the toolchain?

Three building blocks are enough to start: bpftrace (one-line tracing), BCC (BPF Compiler Collection, for writing C programs driven from Python) and bpftool (the official kernel inspection tool). We add clang and the kernel headers, because BCC compiles the C program directly on the target machine.

Terminal window
sudo apt update
sudo apt install -y bpftrace bpfcc-tools python3-bpfcc \
linux-headers-$(uname -r) linux-tools-$(uname -r) \
clang llvm libbpf-dev

Check that the versions respond. On the test VM:

Terminal window
bpftrace --version # bpftrace v0.20.2
clang --version # Ubuntu clang version 18.1.3
sudo bpftool version # bpftool v7.4.0

Route 1: how do you trace without writing a line of C?

The quickest way to see eBPF at work is bpftrace. You describe what you want to observe in a short language, and bpftrace takes care of producing the eBPF program, verifying it, loading it and displaying the result. No manual compilation.

The canonical example: display every time a program starts another one. On Linux, launching a program goes through the execve system call (it is what replaces the content of a process with a new program). We attach to the matching tracepoint, a stable observation point provided by the kernel:

Terminal window
sudo bpftrace -e 'tracepoint:syscalls:sys_enter_execve { printf("%-16s -> %s\n", comm, str(args->filename)); }'

Let us break the line down:

  • tracepoint:syscalls:sys_enter_execve: the trigger point. "On entry to the execve system call".
  • comm: a variable provided by bpftrace, the name of the current process (comm = command, 16 characters).
  • args->filename: the argument of the call, here the path of the program launched.
  • str(...): converts the pointer into a readable string.

While this command runs, launch a few commands in another terminal. The real output, captured on the VM:

bash -> /usr/bin/uname
bash -> /usr/bin/id
bash -> /usr/bin/sleep
bash -> /usr/bin/uname
bash -> /usr/bin/id
bash -> /usr/bin/sleep

You have just observed, from the kernel, every program launched on the machine, without modifying either bash or the traced commands. This is the whole promise of eBPF, in one line. The bpftrace lesson explores this language in detail.

Route 2 (optional): how do you write a real program in C?

This route is optional for an administrator. Writing and loading a C program yourself is a tool developer's gesture, like the CO-RE lesson: it requires reading C and Python, and you can skip it without losing the thread of the module. It remains useful to understand what bpftrace hides, and to recognize the compile, verify, load cycle when it appears in the logs of your tools.

To follow it, let us write the same kind of probe "by hand" with BCC. The principle of BCC: the eBPF program is written in C, embedded in a string, and a Python script drives its compilation, its loading and the reading of the results.

Create the file hello.py:

#!/usr/bin/env python3
from bcc import BPF
# The eBPF program, in C, embedded in a Python string.
program = r"""
int on_execve_enter(void *ctx) {
char name[16];
bpf_get_current_comm(&name, sizeof(name));
bpf_trace_printk("execve called by %s\n", name);
return 0;
}
"""
b = BPF(text=program) # compile + verify + load
b.attach_kprobe(event=b.get_syscall_fnname("execve"), # attach at the entry of execve
fn_name="on_execve_enter")
print("Listening. Every command run on the machine appears below.\n")
for _ in range(5): # capture 5 events, then exit
(task, pid, cpu, flags, ts, msg) = b.trace_fields()
print(f"{ts:14.6f} PID {pid:<6d} {msg.decode()}")

Each term of the C program deserves an explanation:

  • int on_execve_enter(void *ctx): the eBPF function. Its ctx (context) argument is the context provided by the kernel at the attachment point; here we do not use it.
  • bpf_get_current_comm: a helper function, a function that the kernel makes available to eBPF programs. This one copies the name of the current process into a variable.
  • bpf_trace_printk: another helper, which writes a line of text to a kernel tracing channel named trace_pipe. It is the "printf" of the eBPF world, handy to get started, not to be used in production (see the security section).
  • return 0: an eBPF program always returns a value; here it has no effect.

On the Python side:

  • b.attach_kprobe(...) attaches our function to a kprobe on execve. A kprobe (kernel probe) is a dynamic attachment point on any kernel function, at its entry. get_syscall_fnname("execve") retrieves the exact name of the kernel function behind execve, which varies with the architecture.
  • b.trace_fields() reads a line from trace_pipe.

Run it (root required) while causing a little activity alongside:

Terminal window
sudo python3 hello.py

Real output captured on the VM:

Listening. Every command run on the machine appears below.
422.733187 PID 22427 execve called by bash
422.733882 PID 22428 execve called by bash
422.734436 PID 22429 execve called by bash
422.935559 PID 22430 execve called by bash
422.936251 PID 22431 execve called by bash

The first number is the kernel timestamp (seconds since boot), followed by the PID (Process IDentifier, the process number) and our message. You have written, compiled, loaded and run a kernel program, and each line confirms that it was attached.

What happens when you load a program?

The BPF(text=program) call chained, in a fraction of a second, the whole life cycle described in What is eBPF. bpftrace follows exactly the same steps, without you seeing them.

  1. Compilation: clang translates the C into eBPF bytecode, an instruction set specific to the kernel's virtual machine (not ordinary machine code).

  2. Verification: the kernel hands the bytecode to the verifier, which proves that the program is safe before accepting it. If it fails, nothing is loaded.

  3. JIT compilation: once accepted, the bytecode is translated into native machine code by the kernel's JIT (Just-In-Time) compiler, to run at full speed.

  4. Attachment: attach_kprobe links the program to the kprobe on execve. From then on, each execve triggers our code.

While a BCC or bpftrace program runs, you can list the eBPF programs actually loaded with bpftool, the inspection tool shipped with the kernel:

Terminal window
sudo bpftool prog show

Real excerpt (the system already loads several, here those of systemd):

147: cgroup_device name sd_devices tag fbee7646fdd03110 gpl
loaded_at 2026-07-14T11:41:50+0000 uid 0
xlated 184B jited 103B memlock 4096B
152: cgroup_skb name sd_fw_egress tag 6deef7357e7b4530 gpl
loaded_at 2026-07-14T11:41:50+0000 uid 0
xlated 64B jited 56B memlock 4096B

Two fields shed light on what we have just seen: xlated is the size of the verified bytecode (translated), jited that of the machine code produced by the JIT. The left column is the program type (cgroup_skb, tracing, etc.), which determines where it can attach.

What does the verifier do when it rejects a program?

What worries beginners is the verifier. Let us hear it say "no", to see that it protects without breaking anything. The most fundamental rule, documented by the kernel: an eBPF program must be provably finite. The verifier documentation puts it this way: "First step does DAG check to disallow loops". A loop with no exit condition is therefore rejected outright.

Let us deliberately write an infinite loop:

program = r"""
int endless_loop(void *ctx) {
#pragma clang loop unroll(disable)
for (;;) {
bpf_ktime_get_ns(); // kernel call: prevents the code from being optimized away
}
return 0;
}
"""

On loading, the kernel refuses, and it explains precisely why. Real verifier log:

0: (85) call bpf_ktime_get_ns#5
1: (05) goto pc-2
...
infinite loop detected at insn 1
processed 10 insns (limit 1000000)
Failed to load BPF program 'endless_loop': Invalid argument

Three things to remember from this output. First, infinite loop detected: the verifier spotted the backward jump (goto pc-2) and refused. Next, limit 1000000: the kernel bounds the analysis to one million instructions, which is its guarantee of finishing its own work. Finally, the machine did not flinch: the program was never loaded, the kernel is intact, you just get an Invalid argument error. The verifier is a bouncer, not a trap.

This is only one of its rules. The lesson the eBPF verifier explained details the others (bounded memory accesses, initialized stack, map values tested against NULL) and how to read its messages.

Security and points of attention

Loading an eBPF program is a privileged operation, and for good reasons: a program with bad intentions can observe sensitive data. A few reflexes from day one.

  • The tools on this page require root. Measured in the lab (Ubuntu 24.04 and AlmaLinux 10.2), bpftrace refuses to start for a non-root account, even one holding CAP_BPF and CAP_PERFMON, and the BCC tools fail for lack of access to /sys/kernel/tracing. Since kernel 5.8, the CAP_BPF capability (paired with CAP_PERFMON for tracing) lets an agent designed for it load programs without all the powers of the superuser, which limits the damage if it is compromised. This route was not replayed here; the lesson on hardening eBPF gives its limits.
  • bpf_trace_printk is reserved for debugging. It writes to a single shared channel (trace_pipe): handy for learning, unsuitable as soon as there is volume or several programs. In real life, data is passed through maps, described in maps: the kernel / user space bridge.
  • BCC compiles on the target. It is simple for learning, but it requires clang and the kernel headers on every machine. The production route, libbpf + CO-RE, compiles once and runs everywhere; see the BCC and libbpf lesson.

Troubleshooting

When the first program does not start, the error message almost always points to one of these causes, and the last column gives the gesture that fixes it.

SymptomLikely causeSolution
Failed to compile BPF moduleKernel headers missingInstall linux-headers-$(uname -r) (or kernel-devel)
Permission denied on loadingProgram launched without privilegeRun with sudo (capabilities alone are not enough for bpftrace or BCC, measured in the lab)
infinite loop detected / back-edgeUnbounded loopBound the loop (fixed counter) or remove it
/sys/kernel/btf/vmlinux not foundKernel without CONFIG_DEBUG_INFO_BTFUse bpftrace or BCC, which do not need it; avoid CO-RE tools
No line is displayedNo event occursCause the traced activity (run commands)
bpftrace: command not foundPackage not installedInstall bpftrace (see above)

Key takeaways

  • First of all, check the kernel: /sys/kernel/btf/vmlinux, CONFIG_BPF, CONFIG_BPF_SYSCALL, CONFIG_DEBUG_INFO_BTF and bpftool feature probe.
  • bpftrace traces in one line: ideal to see eBPF work without writing C.
  • BCC lets you write the program in C and drive it in Python; it is the optional route, that of a tool developer.
  • Loading a program chains compilation to bytecode, verification, JIT, attachment; it is instantaneous but very real.
  • A kprobe attaches to a kernel function, a tracepoint to a stable observation point.
  • The verifier cleanly rejects any program it cannot prove safe, without ever endangering the machine.
  • Loading eBPF is privileged: bpftrace and BCC require root, and CAP_BPF is a route only for agents designed for it.

Knowledge check

Check that the essentials of this lesson are in place. The questions only cover what has just been explained here.

Knowledge check

Check what you have learned with this interactive quiz

6 questions
6 min
70% to pass

How it works

  • The timer starts when you click Start
  • Multiple choice, true/false and short answer questions
  • You can move between questions
  • Detailed results are shown at the end

Starts the quiz and the timer