Before you can start completing the steps in this XDP-tutorial, go though this document and install the needed software packages.
This XDP-tutorial leverages libbpf to ease development and loading of BPF-programs. The library libbpf 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 libbpf as a git-submodule. After cloning this repository you need to run the command:
git submodule update --init
If you want submodules to be part of the clone, you can use this command:
git clone --recurse-submodules https://github.com/xdp-project/xdp-tutorial
If you need to add this to your own project, you can use the command:
git submodule add https://github.com/libbpf/libbpf/ libbpf
The main dependencies are 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. 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
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 gcc-multilib build-essential
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
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.
On a machine running the Fedora Linux distribution, install package:
$ sudo dnf install bpftool
Starting from Ubuntu 19.10, bpftool can be installed with:
$ sudo apt install linux-tools-common linux-tools-generic
(Ubuntu 18.04 LTS also has it, but it is an old and quite limited bpftool version.)
Unfortunately, bpftool is not officially packaged for Debian yet.
However, note that an unofficial .deb package is provided by Netronome on their support website. The binary is statically linked, and should work on any x86-64 Linux machine.
On a machine running the openSUSE Tumbleweed distribution, install package:
$ sudo zypper install bpftool