Before you can start completing the steps in this XDP-tutorial, go through this document and install the needed software packages.
This XDP-tutorial leverages libxdp to load and manage XDP programs. The libxdp library is maintained as part of the XDP Project. The tutorial also leverages libbpf to ease development and loading of BPF programs. The libbpf library is part of the kernel tree under tools/lib/bpf, but Facebook engineers maintain a stand-alone build on GitHub under https://github.com/libbpf/libbpf.
This repository uses both libxdp and libbpf as git-submodules.
We will start by cloning this repository:
git clone --recurse-submodules https://github.com/xdp-project/xdp-tutorial.git
Note: If you missed the –recurse-submodules option in the previous step or you already cloned it earlier without the submodules you can use the following command:
git submodule update --init
If you need to add the submodules to your own project, you can use the command:
git submodule add https://github.com/xdp-project/xdp-tools/ xdp-tools git submodule add https://github.com/libbpf/libbpf/ libbpf
The main dependencies are libxdp, libbpf, llvm, clang and
libelf. LLVM+clang compiles our restricted-C programs into BPF-byte-code,
which is stored in an ELF object file (libelf), that is loaded by libbpf
into the kernel via the bpf syscall. XDP programs are managed by libxdp
which implements the XDP multi-dispatch protocol. Some of the lessons also
use the perf utility to track the kernel behaviour through tracepoints.
The Makefiles in this repo will try to detect if you are missing some dependencies, and give you some pointers.
On a machine running the Fedora Linux distribution, install the packages:
sudo dnf install clang llvm sudo dnf install elfutils-libelf-devel libpcap-devel perf glibc-devel.i686
Note also that Fedora by default sets a limit on the amount of locked memory
the kernel will allow, which can interfere with loading BPF maps. The
testenv.sh script will adjust this for you, but if you’re not using that
you will probably run into problems. Use this command to raise the limit:
# ulimit -l 1024
Note that you need to do this in the shell you are using to load programs
(in particular, it won’t work with sudo).
On Debian and Ubuntu installations, install the dependencies like this:
sudo apt install clang llvm libelf-dev libpcap-dev build-essential libc6-dev-i386
To install the ‘perf’ utility, run this on Debian:
sudo apt install linux-perf
or this on Ubuntu:
sudo apt install linux-tools-$(uname -r)
On a machine running the openSUSE distribution, install the packages:
sudo zypper install clang llvm libelf-devel libpcap-devel perf linux-glibc-devel
The Linux kernel provides a number of header files, which are usually installed
in /usr/include/linux. The different Linux distributions usually provide a
software package with these headers.
Some of the header files (we depend on) are located in the kernel tree under
include/uapi/linux/ (e.g. include/uapi/linux/bpf.h), but you should not include
those files as they go through a conversion process when exported/installed into
distros’ /usr/include/linux directory. In the kernel git tree you can run the
command: make headers_install which will create a lot of headers files in
directory “usr/”.
For now, this tutorial depends on kernel headers package provided by your distro. We may choose to shadow some of these later.
On a machine running the Fedora Linux distribution, install the package:
sudo dnf install kernel-headers
On Debian and Ubuntu installations, install the headers like this
sudo apt install linux-headers-$(uname -r)
On a machine running the openSUSE distribution, install the package:
sudo zypper install kernel-devel
The bpftool is the recommended tool for inspecting BPF programs running on
your system. It also offers simple manipulation of eBPF programs and maps.
The bpftool is part of the Linux kernel tree under tools/bpf/bpftool/, but
some Linux distributions also ship the tool as a software package.
If you are planning on working through the packet processing examples you should also install tcpdump.
On a machine running the Fedora Linux distribution, install package:
sudo dnf install bpftool sudo dnf install tcpdump
Starting from Ubuntu 19.10, bpftool can be installed with:
sudo apt install linux-tools-common linux-tools-generic sudo apt install tcpdump
(Ubuntu 18.04 LTS also has it, but it is an old and quite limited bpftool version.)
Starting from Debian Bullseye, bpftool can be installed with:
sudo apt install bpftool sudo apt install tcpdump
(If you are on Debian Buster, you can get it from buster-backports.)
On a machine running the openSUSE Tumbleweed distribution, install package:
sudo zypper install bpftool sudo zypper install tcpdump
Once you have installed the dependencies you need genereate the necessary files to follow the exercises.
Start by running ./configure from the root of the repository to make sure every dependency is installed.
./configure
If there is a missing dependency it should output some error, if not we can continue.
Now run make to generate all the necessary files:
make