liminfoeBPF Reference
Free reference guide: eBPF Reference
About eBPF Reference
The eBPF Reference is a searchable guide to Extended Berkeley Packet Filter programming, covering the four main areas needed to write and deploy eBPF programs. The Programs category covers all major program types: kprobe and kretprobe for attaching to kernel function entry and return points, tracepoint for stable kernel trace event hooks (including syscall tracepoints like sys_enter_openat), XDP (eXpress Data Path) for high-performance packet processing at the network driver level, TC (Traffic Control) for kernel traffic shaping hooks, and socket_filter for socket-level packet filtering. Each entry uses the BPF_KPROBE and SEC() macros from libbpf-style development and shows realistic C code examples.
The Maps category covers the four most important BPF map types: BPF_MAP_TYPE_HASH for key-value hash storage with arbitrary key/value types, BPF_MAP_TYPE_ARRAY for fixed-index array storage, BPF_MAP_TYPE_RINGBUF for efficient kernel-to-userspace event delivery using bpf_ringbuf_output, and BPF_MAP_TYPE_PERF_EVENT_ARRAY with bpf_perf_event_output for per-CPU perf event streaming. All map definitions use the modern BTF-style map declaration with __uint and __type macros. The Tools category introduces the main eBPF development and observability tools: bpftrace for high-level one-liner tracing, BCC (BPF Compiler Collection) for Python-based eBPF program development, libbpf for production-grade C skeleton-based development, and bpftool for listing programs, dumping maps, and inspecting BTF.
The Concepts category explains three foundational ideas: CO-RE (Compile Once — Run Everywhere) which uses BPF_CORE_READ to safely access kernel struct fields across different kernel versions without recompilation, BTF (BPF Type Format) which provides kernel type metadata enabling CO-RE portability and richer introspection via vmlinux.h, and the eBPF Verifier which performs static analysis of every BPF program before loading to reject infinite loops, out-of-bounds memory accesses, and unsafe pointer arithmetic. This reference is organized into four filterable categories (Programs, Maps, Tools, Concepts) suitable for kernel developers, security researchers, and observability engineers.
Key Features
- Program types: kprobe, kretprobe, tracepoint (syscall hooks), XDP (driver-level packet processing), TC, socket_filter
- BPF map types: HASH, ARRAY, RINGBUF (kernel-to-user events), and PERF_EVENT_ARRAY with bpf_perf_event_output
- Modern BTF-style map declarations using __uint(type), __uint(max_entries), __type(key), __type(value) macros
- bpftrace one-liners for rapid kernel tracing with tracepoint and printf support
- BCC Python API: BPF() class, attach_kprobe(), and Python-side event polling
- libbpf skeleton API: open_and_load(), attach(), and CO-RE struct field access
- bpftool commands for listing programs, dumping map contents, and inspecting BTF type information
- Core concepts: CO-RE portability with BPF_CORE_READ, BTF vmlinux.h, and the eBPF verifier safety model
Frequently Asked Questions
What is the difference between kprobe and tracepoint program types?
kprobe attaches to arbitrary kernel function entry points by name (e.g., tcp_sendmsg), providing access to function arguments. kretprobe attaches at the return of a kernel function to capture the return value. Tracepoints attach to stable, explicitly defined hooks in the kernel (e.g., syscalls/sys_enter_openat) that are guaranteed not to change between kernel versions. Tracepoints are preferred when available because they are more stable than kprobes, which can break across kernel updates.
What is XDP and how is it different from TC?
XDP (eXpress Data Path) programs run at the earliest possible point in the network receive path — inside the network driver, before sk_buff allocation. This gives XDP the lowest latency and highest throughput, making it ideal for DDoS mitigation and load balancing. XDP programs return XDP_PASS, XDP_DROP, XDP_TX, or XDP_REDIRECT. TC (Traffic Control) programs run later in the stack on the tc ingress/egress hooks and have access to the sk_buff, making them more flexible but slightly slower.
When should I use BPF_MAP_TYPE_RINGBUF instead of PERF_EVENT_ARRAY?
BPF_MAP_TYPE_RINGBUF (available since Linux 5.8) is the modern replacement for PERF_EVENT_ARRAY for sending events from kernel to userspace. Ring buffer uses a single shared buffer across all CPUs, avoiding the per-CPU overhead of perf event arrays. It also supports variable-length records and provides better memory efficiency. Use RINGBUF for new programs targeting kernel 5.8+; use PERF_EVENT_ARRAY for compatibility with older kernels.
What is CO-RE and why does it matter?
CO-RE (Compile Once — Run Everywhere) solves the problem of eBPF programs that break when run on a different kernel version than they were compiled on, because kernel struct layouts change between versions. CO-RE uses BPF_CORE_READ() macros and BTF type information to automatically relocate struct field accesses at load time. This means a single compiled BPF object file can run on any kernel that exposes BTF, without recompilation.
What is BTF and how do I check if my kernel supports it?
BTF (BPF Type Format) is a compact binary format that encodes C type information (struct layouts, typedefs, function prototypes) for the kernel. It enables CO-RE portability and richer introspection. Check support with: ls /sys/kernel/btf/vmlinux. If the file exists, your kernel has BTF. You can then use vmlinux.h (generated with bpftool btf dump file vmlinux format c > vmlinux.h) instead of individual kernel headers.
What does the eBPF verifier do?
The eBPF verifier is a static analysis engine in the kernel that runs before any BPF program is loaded. It rejects programs that could crash or compromise the kernel: infinite or unbounded loops, out-of-bounds array accesses, null pointer dereferences, use of uninitialized values, and exceeding the instruction count limit. The verifier performs symbolic execution and tracks the type and range of every register to prove memory safety. Verification errors are logged to bpf_log_buf.
What is the difference between bpftrace, BCC, and libbpf?
bpftrace is a high-level scripting language for one-shot kernel tracing. BCC (BPF Compiler Collection) provides a Python (and Lua) API for writing eBPF programs as C strings, compiling them at runtime with LLVM, and attaching them from Python. libbpf is a low-level C library that uses pre-compiled BPF ELF objects and CO-RE for production deployments. bpftrace is best for quick investigations, BCC for prototyping, and libbpf for production tools and daemons.
How do I list loaded eBPF programs and inspect BPF maps?
Use bpftool prog list to see all loaded BPF programs with their IDs, types, and names. Use bpftool map dump name <map_name> to inspect the contents of a named BPF map. bpftool map show lists all maps with their types, key/value sizes, and max entries. You can also pin maps to the BPF filesystem (/sys/fs/bpf/) to share them between processes or persist them across program restarts.