RedBPF

A Rust eBPF toolchain.

Overview

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-probes which 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

Requirements

In order to use redBPF, you need

• LLVM 12 or LLVM 11
• either the Linux kernel's headers or vmlinux, you want to target

LLVM 12 is used as a default when compiling BPF programs, but you can use LLVM 11 as follows: cargo build --no-default-features --features llvm11

Linux kernel

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.

Installing dependencies on Debian based distributions

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)

If your distribution doesn't have LLVM 12, you can add the official LLVM APT repository to your sources.list.

Installing dependencies on RPM based distributions

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

Build images

You can refer to Dockerfiles that are ready for building redBPF and foniod: build-images

Getting started

The easiest way to get started is using cargo-bpf, see the documentation for more info.

redbpf-tools is a cargo-bpf generated crate that includes simple examples you can use to understand how to structure your programs.

Finally the foniod project includes more concrete examples of redbpf programs.

Building from source

After cloning the repository run:

git submodule sync
git submodule update --init

Install the dependencies as documented above, then run cargo build as usual.

License

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.

Contribution

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.

For further advice on getting started, please consult the Contributor's Guide. Please note that all contributions MUST contain a Developer Certificate of Origin sign-off line.