28 releases (11 stable)
|2.3.0||Jan 9, 2022|
|2.2.0||Nov 17, 2021|
|2.1.0||Oct 29, 2021|
|1.3.0||Dec 7, 2020|
|0.9.6||Nov 9, 2019|
#21 in Unix APIs
1,301 downloads per month
Used in redbpf-macros
A Rust eBPF toolchain.
The redbpf project is a collection of tools and libraries to build eBPF programs using Rust. It includes:
redbpf - a user space library that can be used to load eBPF programs or access eBPF maps.
redbpf-probes - an idiomatic Rust API to write eBPF programs that can be loaded by the linux kernel
redbpf-macros - companion crate to
redbpf-probeswhich provides convenient procedural macros useful when writing eBPF programs. For example,
#[map]for defining a map,
#[kprobe]for defining a BPF program that can be attached to kernel functions.
cargo-bpf - a cargo subcommand for creating, building and debugging eBPF programs
In order to use redBPF, you need
- one of LLVM 13, LLVM 12 or LLVM 11 installed in the system
- either the Linux kernel headers or
vmlinux, you want to target
Currently LLVM 12 is used as a default version when compiling BPF programs, but you can specify other LLVM versions as follows:
cargo build --no-default-features --features llvm13
cargo build --no-default-features --features llvm11
rustc uses its own version of LLVM. But RedBPF also requires LLVM installed
in the system. In order to compile BPF programs, RedBPF makes use of
emit bitcode first and then parses and optimizes the bitcode by calling LLVM
API directly. Thus, two versions of LLVM are used while compiling BPF programs.
- the version of LLVM that
- the version of LLVM which is installed in system
Two versions should match.
First RedBPF executes
rustc to emit bitcode and second it calls LLVM API to
handle the resulting bitcode. Normally LLVM is likely to support backward
compatibility for intermediate representation. Thus, it is okay to use
that depends on the LLVM version that is equal to or less than system LLVM.
|Rust version||LLVM version of the Rust||Valid system LLVM version|
|1.56 ~||LLVM 13||LLVM 13|
|1.52 ~ 1.55||LLVM 12||LLVM 13, LLVM 12|
|1.48 ~ 1.51||LLVM 11||LLVM 13, LLVM 12, LLVM 11|
- The minimum rust version for compiling
redbpfis Rust 1.48
The minimum kernel version supported is 4.19. Kernel headers are discovered
automatically, or you can use the
KERNEL_SOURCE environment variable to point
to a specific location. Building against a linux source tree is supported as
long as you run
make prepare first.
NOTE for compiling BPF programs inside containers.
You need to specify
KERNEL_VERSION environment variables
that indicate kernel headers. The headers should be found inside the
container. For example, inside the Ubuntu 21.04 container that contains the
5.11.0-25-generic kernel headers, you should specify
environment variable as follows:
# KERNEL_VERSION=5.11.0-25-generic cargo build --examples
If your container has
vmlinux, you can specify it instead of the Linux kernel
# REDBPF_VMLINUX=/boot/vmlinux cargo build --examples
See, build-test.sh for more information.
On Debian, Ubuntu and derivatives you can install the dependencies running:
sudo apt-get -y install build-essential zlib1g-dev \ llvm-12-dev libclang-12-dev linux-headers-$(uname -r) \ libelf-dev
If your distribution doesn't have LLVM 12, you can add the official LLVM
APT repository to your
First ensure that your distro includes LLVM 12:
yum info llvm-devel | grep Version Version : 12.0.0
If you don't have vesion 12, you can get it from the Fedora 34 repository.
Then install the dependencies running:
yum install clang llvm-devel zlib-devel kernel-devel
You can refer to
Dockerfiles that are ready for building redBPF and foniod:
The easiest way to get started is reading a basic tutorial.
You can find several examples in this directory. All example
programs are splitted into two parts:
example-probes contains BPF programs that execute in
example-userspace includes userspace programs that load BPF
programs into kernel space and communicate with BPF programs through BPF maps.
Also see documentation of
provides a CLI tool for compiling BPF programs easily.
redbpf-tools is a
cargo-bpf generated crate that includes simple examples you can use to
understand how to structure your programs.
Finally, check the foniod project that includes more advanced, concrete production ready examples of redbpf programs.
After cloning the repository run:
git submodule sync git submodule update --init
Install the dependencies as documented above, then run
cargo build as usual.
This repository contains code from other software in the following directories, licensed under their own particular licenses:
bpf-sys/libbpf: LGPL2 + BSD-2
Where '+' means they are dual licensed.
RedBPF and its components, unless otherwise stated, are licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
This project is for everyone. We ask that our users and contributors take a few minutes to review our code of conduct.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.