eBPF

Awesome eBPF Awesome

A curated list of awesome projects related to eBPF.

BPF, as in Berkeley Packet Filter, is an in-kernel virtual machine running programs passed from user space. Initially implemented on BSD, then Linux, the (now legacy) "classic BPF" or cBPF machine would be used with tools like tcpdump for filtering packets in the kernel to avoid useless copies to user space. More recently, the BPF infrastructure in Linux has been completely reworked and gave life to the "extended BPF", or eBPF, which gained new features (safety and termination checks, JIT-compiling for programs, persistent maps, a standard library, hardware offload support, etc.) and is now used for many tasks. Processing packets at a very low level (XDP), tracing and monitoring events on the system, or enforcing access control over cgroups are but a few examples to which eBPF brings performance, programmability and flexibility.

Note: eBPF is an exciting piece of technology, and its ecosystem is constantly evolving. We'd love help from you to keep this awesome list up to date, and improve its signal-to-noise ratio in anyway we can. Please feel free to leave any feedback.

Reference Documentation

Cilium Guide

Kernel Documentation

Manual Pages

  • bpf(2) - Manual page about the bpf() system call, used to manage BPF programs and maps from userspace.
  • tc-bpf(8) - Manual page about using BPF with tc, including example commands and samples of code.
  • bpf-helpers(7) man page - Description of the in-kernel helper functions forming the BPF standard library.

Other

Articles and Presentations

Generic eBPF presentations

If you are new to eBPF, you may want to try the links described as "introductions" in this section.

BPF Internals

Kernel Tracing

XDP

AF_XDP

bpfilter

BTF

cBPF

Hardware Offload

Tutorials

Examples

  • linux/samples/bpf/ - In the kernel tree: some sample eBPF programs.
  • linux/tools/testing/selftests/bpf - In the kernel tree: Linux BPF selftests, with many eBPF programs.
  • prototype-kernel/kernel/samples/bpf - Jesper Dangaard Brouer's prototype-kernel repository contains some additional examples that can be compiled outside of kernel infrastructure.
  • iproute2/examples/bpf/ - Some networking programs to attach to the TC interface.
  • Netronome sample network applications - Provides basic but complete examples of eBPF applications also compatible with hardware offload.
  • bcc/examples - Examples coming along with the bcc tools, mostly about tracing.
  • bcc/tools - These tools themselves can be seen as example use cases for BPF programs, mostly for tracing and monitoring. bcc tools have been packaged for some Linux distributions.
  • MPLSinIP sample - A heavily commented sample demonstrating how to encapsulate & decapsulate MPLS within IP. The code is commented for those new to BPF development.
  • ebpf-samples - A collection of compiled (as ELF object files) samples gathered from several projects, primarily intended to serve as test cases for user space verifiers.

eBPF Workflow: Tools and Utilities

bcc

  • bcc - Framework and set of tools - One way to handle BPF programs, in particular for tracing and monitoring. Also includes some utilities that may help inspect maps or programs on the system.
  • P4 compiler for BPF targets for bcc - An alternative to the restricted C.
  • Lua front-end for BCC - Another alternative to C, and even to most of the Python code used in bcc.

iproute2

  • iproute2 - Package containing tools for network management on Linux. In particular, it contains tc, used to manage eBPF filters and actions, and ip, used to manage XDP programs. Most of the code related to BPF is in lib/bpf.c.
  • iproute2-next - The development tree, synchronised with net-next.

LLVM

  • LLVM - Contains several tools used in eBPF workflows. Snapshots of the latest versions for Ubuntu/Debian can be retrieved from here.

  • clang is used to compile C to eBPF object file under the ELF format (clang v3.7.1+). The BPF backend was added with this commit.

  • llvm-objdump is used to dump the content of an object file in human-readable format, possibly with the initial C source code (llvm-objdump v4.0+).
  • llvm-mc is used to compile from LLVM intermediate representation to eBPF object file, so that one can compile from C to eBPF assembly, tinker with assembly, then compile to ELF file.

libbpf

  • libbpf - A C library used for handling BPF objects (programs and maps), and manipulating ELF object files containing them. It is shipped with the kernel and mirrored on GitHub.

bpftool and Other Tools from the Kernel Tree

  • bpftool - Also some other tools in the kernel tree, under linux/tools/net/ for versions earlier than 4.15, or linux/tools/bpf/ after that:

  • bpftool - A generic utility that can be used to interact with eBPF programs and maps from userspace, for example to show, dump, load, disassemble, pin programs, or to show, create, pin, update, delete maps, or to attach and detach programs to cgroups.

  • bpf_asm - A minimal cBPF assembler.
  • bpf_dbg - A small debugger for cBPF programs.
  • bpf_jit_disasm - A disassembler for both BPF flavors and could be highly useful for JIT debugging.

User Space eBPF

Testing in Virtual Environments

The Code

Development and Community

Other Lists of Resources on eBPF

Acknowledgement

Thank you to Quentin Monnet and Daniel Borkmann for their original work on Dive into BPF: A List of Reading Material which became the basis for this list.

Contributing

Contributions welcome! Read the contribution guidelines first.

License

CC0

To the extent possible under law, zoidbergwill has waived all copyright and related or neighboring rights to this work.