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
sudoaccess: 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.
ls -l /sys/kernel/btf/vmlinuxThe 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:
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.
sudo bpftool feature probe kernel | head -20The 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 enabledJIT compiler hardening is enabled for unprivileged usersJIT compiler kallsyms exports are enabled for rootGlobal memory limit for JIT compiler for unprivileged users is 528482304 bytesCONFIG_BPF is set to yCONFIG_BPF_SYSCALL is set to yCONFIG_HAVE_EBPF_JIT is set to yCONFIG_BPF_JIT is set to yCONFIG_BPF_JIT_ALWAYS_ON is set to yCONFIG_DEBUG_INFO_BTF is set to yCONFIG_DEBUG_INFO_BTF_MODULES is set to yCONFIG_CGROUPS is set to yCONFIG_CGROUP_BPF is set to yCONFIG_CGROUP_NET_CLASSID is set to yCONFIG_SOCK_CGROUP_DATA is set to yCONFIG_BPF_EVENTS is set to yCONFIG_KPROBE_EVENTS is set to yCONFIG_UPROBE_EVENTS is set to yOn 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.
sudo apt updatesudo apt install -y bpftrace bpfcc-tools python3-bpfcc \ linux-headers-$(uname -r) linux-tools-$(uname -r) \ clang llvm libbpf-devsudo dnf install -y bpftrace bcc-tools python3-bcc \ kernel-devel-$(uname -r) bpftool clang llvm libbpf-develCheck that the versions respond. On the test VM:
bpftrace --version # bpftrace v0.20.2clang --version # Ubuntu clang version 18.1.3sudo bpftool version # bpftool v7.4.0Route 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:
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 theexecvesystem 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/unamebash -> /usr/bin/idbash -> /usr/bin/sleepbash -> /usr/bin/unamebash -> /usr/bin/idbash -> /usr/bin/sleepYou 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 python3from 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 + loadb.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. Itsctx(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 namedtrace_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 onexecve. 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 behindexecve, which varies with the architecture.b.trace_fields()reads a line fromtrace_pipe.
Run it (root required) while causing a little activity alongside:
sudo python3 hello.pyReal 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 bashThe 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.
-
Compilation: clang translates the C into eBPF bytecode, an instruction set specific to the kernel's virtual machine (not ordinary machine code).
-
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.
-
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.
-
Attachment:
attach_kprobelinks the program to the kprobe onexecve. From then on, eachexecvetriggers 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:
sudo bpftool prog showReal 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 4096B152: cgroup_skb name sd_fw_egress tag 6deef7357e7b4530 gpl loaded_at 2026-07-14T11:41:50+0000 uid 0 xlated 64B jited 56B memlock 4096BTwo 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#51: (05) goto pc-2...infinite loop detected at insn 1processed 10 insns (limit 1000000)
Failed to load BPF program 'endless_loop': Invalid argumentThree 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),bpftracerefuses to start for a non-root account, even one holdingCAP_BPFandCAP_PERFMON, and the BCC tools fail for lack of access to/sys/kernel/tracing. Since kernel 5.8, theCAP_BPFcapability (paired withCAP_PERFMONfor 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_printkis 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.
| Symptom | Likely cause | Solution |
|---|---|---|
Failed to compile BPF module | Kernel headers missing | Install linux-headers-$(uname -r) (or kernel-devel) |
Permission denied on loading | Program launched without privilege | Run with sudo (capabilities alone are not enough for bpftrace or BCC, measured in the lab) |
infinite loop detected / back-edge | Unbounded loop | Bound the loop (fixed counter) or remove it |
/sys/kernel/btf/vmlinux not found | Kernel without CONFIG_DEBUG_INFO_BTF | Use bpftrace or BCC, which do not need it; avoid CO-RE tools |
| No line is displayed | No event occurs | Cause the traced activity (run commands) |
bpftrace: command not found | Package not installed | Install bpftrace (see above) |
Key takeaways
- First of all, check the kernel:
/sys/kernel/btf/vmlinux,CONFIG_BPF,CONFIG_BPF_SYSCALL,CONFIG_DEBUG_INFO_BTFandbpftool 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:
bpftraceand BCC requireroot, andCAP_BPFis 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
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
Review
(0/0)Score by domain
A domain groups several guides and gets several questions, so its score is more reliable than a per-topic score, which often rests on a single question.
Summary
Strengths
No topic passed at 80% on at least two questions yet.
Weak areas
No topic below the pass mark.
Recommended next
Hints before you try again?
Continue the course: eBPF maps: communicating between kernel and user space
A new full quiz with random questions
Work again only on the questions you missed