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. 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)

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 crate::btf::Btf;
• pub use crate::btf::HasSize;
• pub use crate::btf::ReferencesType;
• pub use libbpf_sys;

Modules

• btf
  Parse and introspect btf information, from files or loaded objects.
• query
  Query the host about BPF
• skel
  Skeleton related definitions.

Macros

• btf_type_match
  A macro that allows matching on the type of a BtfType as if it was an enum.

Structs

• Error
  The error type used by the library.
• Iter
  Represents a bpf iterator for reading kernel data structures. This requires Linux 5.8.
• Link
  Represents an attached Program.
• Linker
  A type used for linking multiple BPF object files into a single one.
• MapFlags
  Flags to configure Map operations.
• MapHandle
  A handle to a map. Handles can be duplicated and dropped.
• MapInfo
  A convenience wrapper for bpf_map_info. It provides the ability to retrieve the details of a certain map.
• MapIter
  An iterator over the maps in a BPF object.
• MapKeyIter
  An iterator over the keys of a BPF map.
• Object
  Represents a loaded BPF object file.
• ObjectBuilder
  Builder for creating an OpenObject. Typically the entry point into libbpf-rs.
• OpenObject
  Represents an opened (but not yet loaded) BPF object file.
• PerfBuffer
  Represents a special kind of Map. Typically used to transfer data between Programs and userspace.
• PerfBufferBuilder
  Builds PerfBuffer instances.
• ProgIter
  An iterator over the programs in a BPF object.
• ProgramInput
  The input a program accepts.
• ProgramOutput
  The output a program produces.
• RingBuffer
  The canonical interface for managing a collection of ringbuf maps.
• RingBufferBuilder
  Builds RingBuffer instances.
• TcHook
  Represents a location where a TC-BPF filter can be attached.
• TcHookBuilder
  Builds TcHook instances.
• TracepointOpts
  Options to optionally be provided when attaching to a tracepoint.
• UprobeOpts
  Options to optionally be provided when attaching to a uprobe.
• UsdtOpts
  Options to optionally be provided when attaching to a USDT.
• UserRingBuffer
  Represents a user ring buffer. This is a special kind of map that is used to transfer data between user space and kernel space.
• UserRingBufferSample
  A mutable reference to sample from a UserRingBuffer.
• Xdp
  Represents a XDP program.
• XdpFlags
  Flags to configure the XDP operations

Enums

• ErrorKind
  An enum providing a rough classification of errors.
• MapType
  Type of a Map. Maps to enum bpf_map_type in kernel uapi.
• PrintLevel
  An enum representing the different supported print levels.
• 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.

Constants

• TC_CUSTOM
  See libbpf_sys::BPF_TC_CUSTOM.
• TC_EGRESS
  See libbpf_sys::BPF_TC_EGRESS.
• TC_H_CLSACT
• TC_H_INGRESS
• TC_H_MIN_EGRESS
• TC_H_MIN_INGRESS
• TC_INGRESS
  See libbpf_sys::BPF_TC_INGRESS.

Traits

• AsRawLibbpf
  A trait implemented for types that are thin wrappers around libbpf types.
• ErrorExt
  A trait providing ergonomic chaining capabilities to Error.
• MapCore
  A trait representing core functionality common to fully initialized maps.

Functions

• get_print
  Return the current print callback and level.
• num_possible_cpus
  Get the number of CPUs in the system, e.g., to interact with per-cpu maps.
• set_print
  Set a callback to receive log messages from libbpf, instead of printing them to stderr.

Type Aliases

• Map
  An immutable loaded BPF map.
• MapMut
  A mutable loaded BPF map.
• OpenMap
  An immutable parsed but not yet loaded BPF map.
• OpenMapMut
  A mutable parsed but not yet loaded BPF map.
• OpenProgram
  An immutable parsed but not yet loaded BPF program.
• OpenProgramMut
  A mutable parsed but not yet loaded BPF program.
• PrintCallback
  The type of callback functions suitable for being provided to set_print.
• Program
  An immutable loaded BPF program.
• ProgramMut
  A mutable loaded BPF program.
• Result
  A result type using our Error by default.
• TcAttachPoint
  See libbpf_sys::bpf_tc_attach_point.