Getting Started
Resources and Prerequisites
This page lists all resources, reference projects, content sources, and target deliverables you will use throughout the learning path.
Content Sources
The exercises and reading materials in this roadmap are drawn from these primary sources:
| Source | What It Provides |
|---|---|
| eBPFHub exercises | Hands-on coding exercises with an in-browser editor and server-side runner |
| iximiuz labs | Interactive networking and Linux fundamentals courses (especially Computer Networking Fundamentals) |
| xdp-tutorial | Official XDP tutorial repo with progressive exercises from basic to advanced packet processing |
| Reading materials (listed below) | Papers, blog posts, and documentation referenced in each chapter |
Reference Projects
| Source | Description |
|---|---|
| Katran | Facebook L4 load balancer (XDP). Read README.md now; study xdp_root.c in later chapters. |
| lb-from-scratch | Liz Rice’s load balancer built from scratch - you must complete this |
| reuseport-ebpf-go | Read after completing lb-from-scratch |
| DnsTrace | DNS tracing project |
| eBPFeXPLOIT | eBPF exploit examples |
| bng | BNG project |
Reading Materials
These resources will be referenced again in the relevant chapters:
| Source | Related Chapter |
|---|---|
| Computer Networking Fundamentals | Byte Order + Network Tracing |
| XDP Paper | XDP Packet Processing |
| Cilium BPF Architecture | BPF Deep Dive |
| Cilium Network Concepts | XDP vs TC Program Types |
| Unimog Blog | Load Balancing |
| Facebook BPF Firewall | IP Blocklist |
| Cilium Performance Tuning | Advanced Topics |
Additional Resources
- Load Balancer Challenge - L4 LB eBPF-XDP load balancer
- Deep Dive into Cloudflare’s Cache Mechanism - Cloudflare cache internals
- Scratch to Success LB - Step-by-step LB build
- VLAN Filter Support - Bridge VLAN filtering
- Edge-FaaS Scheduling
xdp-tutorial Directory Guide
The xdp-tutorial repository is organized into progressive folders. Use this table to know which folder to study and when.
| Folder | What It Teaches | When to Use |
|---|---|---|
basic01-xdp-pass | Minimal XDP program that passes all packets | Start here; first XDP program |
basic02-prog-by-name | Loading and attaching XDP programs by section name | Right after basic01 |
basic03-map-counter | Using BPF maps to count packets | When learning maps (Chapter 2+) |
basic04-pinning-maps | Pinning maps to the BPF filesystem for persistence | After basic03, before multi-program setups |
packet01-parsing | Parsing Ethernet, IP, and TCP/UDP headers safely | Core skill; study before building any filter |
packet02-rewriting | Rewriting packet headers (MAC, IP) | Needed for load balancer and NAT projects |
packet03-redirecting | Redirecting packets between interfaces with bpf_redirect | Load balancer and forwarding use cases |
tracing01-xdp-simple | Tracing XDP events with bpf_printk | Debugging any XDP program |
tracing02-xdp-perf-event | Perf event output from XDP programs | When you need structured event output |
advanced01-xdp-load-balancer | Full XDP load balancer example | After completing packet01-03; compare with your own LB |
advanced03-AF_XDP | AF_XDP socket for user-space packet processing | Optional; only if you need user-space fast path |
Quick Reference
When you encounter a specific need, use this table to find the right BPF primitive or technique.
| Need | Solution | Notes |
|---|---|---|
| Block IPs from a list | BPF_MAP_TYPE_HASH with IP keys | Used in DDoS engine and IP blocklist |
| Count packets per source | BPF_MAP_TYPE_PERCPU_HASH or BPF_MAP_TYPE_LRU_HASH | Per-CPU variant avoids lock contention |
| Rate limiting | BPF_MAP_TYPE_HASH + token bucket in BPF | Store timestamp and token count per key |
| Round-robin backend selection | BPF_MAP_TYPE_ARRAY + atomic counter | Index into backend array with __sync_fetch_and_add |
| Consistent hashing | Hash 5-tuple, mod N backends | Use jhash or similar; see Katran for reference |
| DNS query inspection | Parse UDP payload after L3/L4 headers | Match on QNAME field in DNS wire format |
| Pass packet to kernel stack | Return XDP_PASS | Default when no action needed |
| Drop packet | Return XDP_DROP | Fastest discard path in the kernel |
| Redirect to another interface | bpf_redirect() + return XDP_REDIRECT | Needed for load balancer forwarding |
| Rewrite MAC addresses | Direct header modification via xdp_md->data | Required after redirect to set correct L2 header |
| Share state between XDP and user space | BPF_MAP_TYPE_HASH or BPF_MAP_TYPE_ARRAY | Pin maps to BPFFS for persistence across program reloads |
| Tail call to another BPF program | BPF_MAP_TYPE_PROG_ARRAY + bpf_tail_call() | Used in Katran’s xdp_root.c for program chaining |
| IP blocklist (CIDR ranges) | BPF_MAP_TYPE_LPM_TRIE | Longest prefix match for subnet-level blocking |
| DNS query log | BPF_MAP_TYPE_RINGBUF + Go consumer | Stream events to userspace without polling |
| Debug output | bpf_printk() + bpftool prog trace | Kernel trace pipe; use only during development |
| Routing lookup | bpf_fib_lookup() | Resolve next-hop MAC and interface from kernel FIB |
| String comparison | bpf_strncmp() | Compare variable string against a constant |
| Substring search | bpf_strstr() (kernel 6.x+) | Find a needle in a haystack buffer |
| Read kernel memory | bpf_probe_read_kernel_str() | Safe read from kernel address space |
| Read user memory | bpf_probe_read_user_str() | Safe read from user address space |
| Get process name | bpf_get_current_comm() | Returns the comm (name) of the running task |
| Convert port (network to host) | bpf_ntohs() | 16-bit network byte order to host byte order |
| Convert IP (network to host) | bpf_ntohl() | 32-bit network byte order to host byte order |
Study Order Summary
Follow these phases in order. Each phase builds on the previous one.
| Phase | Focus | Key Deliverable |
|---|---|---|
| Phase 1: Foundations | C basics, kernel data types, byte order, BPF verifier rules | Pass all Chapter 1 exercises |
| Phase 2: Packet Parsing | Ethernet/IP/UDP header parsing, bounds checking, XDP return codes | Parse and classify live packets |
| Phase 3: Maps and State | BPF map types, per-CPU maps, map pinning, user-space interaction | IP blocklist with dynamic updates |
| Phase 4: Core Projects | L4 Load Balancer, DDoS mitigation engine, DNS policy filter | Three working XDP programs |
| Phase 5: Polish and Extend | Performance tuning, metrics export, optional DNS resolver/forwarder | Production-ready code with documentation |
What to Skip
The following topics are common in general C or systems programming curricula but are not needed for eBPF/XDP development. Skip them to stay focused.
| Topic | Why It Is Not Needed |
|---|---|
time.h / date-time functions | BPF programs use bpf_ktime_get_ns() instead of libc time functions |
File I/O (fopen, fread, fwrite) | BPF programs cannot access the filesystem; all state goes through maps |
Dynamic memory (malloc, free) | The BPF verifier forbids dynamic allocation; all memory is stack or map-based |
| Recursion | BPF programs cannot recurse; the verifier rejects any backward jumps |
| Floating point arithmetic | BPF has no floating point support; use integer math |
Signal handling (signal.h) | Only relevant in user-space loader code, not in BPF programs |
Multi-threading (pthread) | BPF programs are single-threaded per invocation; concurrency is handled by per-CPU maps |
Standard I/O (printf, scanf) | Use bpf_printk() for debug output; no standard I/O in kernel context |
struct tm, strftime | Not available in BPF; timestamps are raw nanosecond values |
| Random number generation | BPF has bpf_get_prandom_u32(); no need for libc random functions |
| Binary search trees | Use BPF_MAP_TYPE_LPM_TRIE for prefix matching; BPF restricts custom tree structures |
| Linear/binary search algorithms | BPF maps provide O(1) hash lookup; no need to implement search manually |
| Complex data structures (linked lists, trees) | BPF maps provide hash tables and arrays; custom data structures are restricted by the verifier |
Optional but useful for pointer practice: Linked lists and stack/queue implementations. You will not use these in BPF, but they provide good struct + pointer practice.
Is TC Hook Needed?
Short answer: No. For the DDoS engine, DNS filter, and L4 load balancer projects in this roadmap, XDP is sufficient. You do not need to learn TC (Traffic Control) BPF hooks.
| Aspect | XDP | TC (cls_bpf) |
|---|---|---|
| Hook point | NIC driver, before SKB allocation | After SKB is created, in the qdisc layer |
| Direction | Ingress only | Both ingress and egress |
| Performance | Fastest possible; runs before the kernel network stack | Slower; SKB overhead is already paid |
| Use case fit | DDoS drop, DNS filtering, L4 LB forwarding | Egress shaping, container networking, policy after routing |
| SKB access | No SKB; works with raw xdp_md | Full SKB with metadata, mark, priority |
| When you need it | Whenever you want to filter or redirect at line rate | When you need egress hooks or SKB-level features (e.g., skb->mark) |
Why XDP is enough for this roadmap:
- DDoS mitigation needs fast ingress drop - XDP’s
XDP_DROPis the fastest path. - DNS filtering inspects inbound UDP queries - all ingress, no egress hook needed.
- L4 load balancing forwards packets with
bpf_redirectbefore the kernel allocates an SKB, which is the whole performance advantage. - TC becomes relevant when you need egress policies (e.g., Cilium’s container networking) or need to read SKB metadata. That is outside the scope of this roadmap.
If you later work on container networking or need egress filtering, revisit TC at that point. For now, focus entirely on XDP.
Target Deliverables
These are the projects you should produce by the end of this learning path: