Skip to content
XDP tutorial
Branch: master
Clone or download
tohojo loader: Fix --force mode for cross-native/generic loading
Just unsetting the XDP_FLAGS_UPDATE_IF_NOEXIST is not enough to force-load
a new XDP program, if the program already loaded is a different type (i.e,
loading a generic XDP program won't unload a native mode program). Handle
this, by reacting to the EEXIST error code when --force is set, by
unloading the opposite program type.

Fixes #26.

Signed-off-by: Toke Høiland-Jørgensen <>
Latest commit 0e5fe28 Apr 15, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
advanced01-xdp-tc-interact advanced01: README fix link Mar 16, 2019
basic01-xdp-pass loader: Fix --force mode for cross-native/generic loading Apr 15, 2019
basic02-prog-by-name Fix some typos Mar 20, 2019
basic04-pinning-maps Fix some typos Mar 20, 2019
headers Add directory headers/ and a number of header files Feb 25, 2019
libbpf @ 7a43190 Update git submodule for libbpf Mar 5, 2019
packet01-parsing packet01: Mention stats program in packet01 README Mar 18, 2019
packet03-redirecting packet03-redirecting: add Makefile Mar 17, 2019
setup-testlab Merge branch 'master' of Mar 17, 2019
testenv testenv: Increase ulimit -l if it's too low Mar 20, 2019
.gitignore .gitignore: Add .s and .ll files and the xdp_loader program Mar 12, 2019
.gitmodules Add libbpf as git submodule Feb 25, 2019
Makefile Add top-level Makefile to build/clean all subdirs Mar 8, 2019 setup_dependencies: We also need the perf tool Mar 20, 2019

XDP Hands-On Tutorial

This repository contains a tutorial that aims to introduce you to the basic steps needed to effectively write programs for the eXpress Data Path (XDP) system in the Linux kernel, which offers high-performance programmable packet processing integrated with the kernel.

The tutorial is composed of a number of lessons, each of which has its own repository. Start with the lessons starting with “basicXX”, and read the file in each repository for instructions for that lesson.

Keep reading below for an introduction to XDP and an overview of what you will learn in this tutorial, or jump straight to the first lesson.

Table of Contents


XDP is a part of the upstream Linux kernel, and enables users to install packet processing programs into the kernel, that will be executed for each arriving packet, before the kernel does any other processing on the data. The programs are written in restricted C, and compiled into the eBPF byte code format that is executed and JIT-compiled in the kernel, after being verified for safety. This approach offers great flexibility and high performance, and integrates well with the rest of the system. For a general introduction to XDP, read the academic paper (pdf), or the Cilium BPF reference guide.

This tutorial aims to be a practical introduction to the different steps needed to successfully write useful programs using the XDP system. We assume you have a basic understanding of Linux networking and how to configure it with the iproute2 suite of tools, but assume no prior experience with eBPF or XDP.

The tutorial is a work in progress, and will be trial-run at the Netdev Conference in Prague in March 2019. However, we intend for it to (eventually) be self-contained and something that anyone can go through to learn the XDP basics. Input and contributions to advance towards this goal are very welcome; just open issues or pull requests in the Github repository.

First step: Setup dependencies

Before you can start completing step in this tutorial, you will need to install a few dependencies on your system. These are are described in

We also provide a helper script that will set up a test environment with virtual interfaces for you to test your code on. This is introduced in the basic lessons, and also has it’s own README file.

How the lessons are organised

The tutorial is organised into a number of lessons; each lesson has its own subdirectory, and the lessons are grouped by category:

  • Basic setup (directories starting with basicXX)
  • Packet processing (directories starting with packetXX)
  • Advanced topics (directories starting with advancedXX)

We recommend you start with the “basic” lessons, and follow the lessons in each category in numerical order. Read the file in each lesson directory for instructions on how to complete the lesson.

Basic setup lessons

We recommend you start with these lessons, as they will teach you how to compile and inspect the eBPF programs that will implement your packet processing code, how to load them into the kernel, and how to inspect the state afterwards. As part of the basic lessons you will also be writing an eBPF program loader that you will need in subsequent lessons.

Packet processing lessons

Once you have the basics figured out and know how to load programs into the kernel, you are ready to start processing some packets. The lessons in the packet progressing category will teach you about the different steps needed to process data packets, including parsing, rewriting, instructing the kernel about what to do with the packet after processing, and how to use helpers to access existing kernel functionality.

Advanced lessons

After having completed the lessons in the basic and packet processing categories, you should be all set to write your first real XDP program that will do useful processing of the packets coming into the system. However, there are some slightly more advanced topics that will probably be useful once you start expanding your program to do more things.

The topics covered in the advanced lessons include how to make eBPF programs in other parts of the kernel interact with your XDP program, passing metadata between programs, best practices for interacting with userspace and kernel features, and how to run multiple XDP programs on a single interface.

You can’t perform that action at this time.