Expand description


libbpf-rs is a safe, idiomatic, and opinionated wrapper around libbpf.

libbpf-rs, together with libbpf-cargo (libbpf cargo plugin) allow you to write Compile-Once-Run-Everywhere (CO-RE) eBPF programs. Note this document uses “eBPF” and “BPF” interchangeably.

More information about CO-RE is available here.

High level workflow

  1. Create new rust project (via cargo new or similar) at path $PROJ_PATH
  2. Create directory $PROJ_PATH/src/bpf
  3. Write CO-RE bpf code in $PROJ_PATH/src/bpf/${MYFILE}.bpf.c, where $MYFILE may be any valid filename. Note the .bpf.c extension is required.
  4. Create a build script that builds and generates a skeleton module using libbpf_cargo::SkeletonBuilder
  5. Write your userspace code by importing and using the generated module. Import the module by using the path attribute. Your userspace code goes in $PROJ_PATH/src/ as it would in a normal rust project.
  6. Continue regular rust workflow (ie cargo build, cargo run, etc)

Alternate workflow

While using the skeleton is recommended, it is also possible to directly use libbpf-rs.

  1. Follow steps 1-3 of “High level workflow”
  2. Generate a BPF object file. Options include manually invoking clang, creating a build script to invoke clang, or using libbpf-cargo cargo plugins.
  3. Write your userspace code in $PROJ_PATH/src/ as you would a normal rust project and point libbpf-rs at your BPF object file
  4. Continue regular rust workflow (ie cargo build, cargo run, etc)


libbpf-rs models various “phases”:

               from_*()        load()
                 |               |
                 v               v
   ObjectBuilder ->  OpenObject  -> Object
                         ^            ^
                         |            |
             <pre-load modifications> |
                           <post-load interactions>

The entry point into libbpf-rs is ObjectBuilder. ObjectBuilder helps open the BPF object file. After the object file is opened, you are returned an OpenObject where you can perform all your pre-load operations. Pre-load means before any BPF maps are created or BPF programs are loaded and verified by the kernel. Finally, after the BPF object is loaded, you are returned an Object instance where you can read/write to BPF maps, attach BPF programs to hooks, etc.

You must keep the Object alive the entire duration you interact with anything inside the BPF object it represents. This is further documented in Object documentation.


This is probably the best way to understand how libbpf-rs and libbpf-cargo work together.

See example here.


pub use libbpf_sys;


Query the host about BPF


Represents a bpf iterator for reading kernel data structures. This requires Linux 5.8.

Represents an attached Program.

Represents a created map.

Flags to configure Map operations.

Represents a loaded BPF object file.

Builder for creating an OpenObject. Typically the entry point into libbpf-rs.

Represents a parsed but not yet loaded BPF map.

Represents an opened (but not yet loaded) BPF object file.

Represents a parsed but not yet loaded BPF program.

Represents a special kind of Map. Typically used to transfer data between Programs and userspace.

Builds PerfBuffer instances.

Represents a loaded Program.

The canonical interface for managing a collection of ringbuf maps.

Builds RingBuffer instances.

The BPF TC subsystem has different control paths from other BPF programs As such a BPF program using a TC Hook (SEC(“classifier”) | SEC(“tc”)) must be operated more independently from other [libbpf-rs::Program]s.

A TcHookBuilder is a way to ergonomically create multiple TcHooks All with similar initial values


Canonical error type for this crate.

Type of a Map. Maps to enum bpf_map_type in kernel uapi.

Attach type of a Program. Maps to enum bpf_attach_type in kernel uapi.

Type of a Program. Maps to enum bpf_prog_type in kernel uapi.



Return the current print callback and level.

Get the number of CPUs in the system, e.g., to interact with per-cpu maps.

Set a callback to receive log messages from libbpf, instead of printing them to stderr.

Type Definitions