[][src]Crate libbpf_rs

libbpf-rs

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. Install libbpf-cargo (cargo install libbpf-cargo)
  2. Create new rust project (via cargo new or similar) at path $PROJ_PATH
  3. Create directory $PROJ_PATH/src/bpf
  4. 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.
  5. Build your bpf code by running cargo libbpf build
  6. Generate skeleton code by running cargo libbpf gen
  7. Write your userspace code by importing and using the module generated in $PROJ_PATH/src/bpf/mod.rs. Your userspace code goes in $PROJ_PATH/src/ as it would in a normal rust project.
  8. 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-5 of "High level workflow"
  2. Write your userspace code in $PROJ_PATH/src/ as you would a normal rust project and point libbpf-rs at the object file generated at $PROJ_PATH/target/bpf/${MYFILE}.bpf.o
  3. Continue regular rust workflow (ie cargo build, cargo run, etc)

Design

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.

Example

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

See example here.

Re-exports

pub use libbpf_sys;

Modules

query

Query the host about BPF

Structs

Link

Represents an attached Program.

Map

Represents a created map.

MapFlags

Flags to configure Map operations.

Object

Represents a loaded BPF object file.

ObjectBuilder

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

OpenMap

Represents a parsed but not yet loaded BPF map.

OpenObject

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

OpenProgram

Represents a parsed but not yet loaded BPF program.

PerfBuffer

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

PerfBufferBuilder

Builds PerfBuffer instances.

Program

Represents a loaded Program.

RingBuffer

The canonical interface for managing a collection of ringbuf maps.

RingBufferBuilder

Builds RingBuffer instances.

Enums

Error

Canonical error type for this crate.

MapType

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

ProgramAttachType

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

ProgramType

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

Type Definitions

Result