Struct oxidebpf::Program

pub struct Program<'a> { /* private fields */ }

The description of an individual eBPF program. Note: This is not the same as the eBPF program itself, the actual binary is loaded from a ProgramBlueprint.

Implementations

impl<'a> Program<'a>

pub fn new(name: &'a str, attach_points: &[&str]) -> Program<'a>

Create a new program specification.

You must provide the program type, the name of the program section in your blueprint’s object file (see ‘ProgramBlueprint’) and a vector of attachment points.

Note

If your blueprint contains duplicate names or if you provide multiple Programs with the same specified blueprint program, the loader will attempt to pairwise load all combinations. For example, if you have two programs kprobe/program and kretprobe/program and give the ProgramVersion two Program objects, both with program program, then the loader will attempt to load and attach each probe twice. To avoid this, give the programs in your ELF binary unique names.

Example

use oxidebpf::{Program, ProgramType};

Program::new(
    "sys_ptrace_write",
    &["do_mount"],
).optional(false).syscall(true);

pub fn pid(self, pid: pid_t) -> Self

Specify a pid to attach to, if this program should trace a specific pid.

The pid is mainly used for uprobes.

pub fn optional(self, optional: bool) -> Self

Specify whether or not the program is optional to load.

If the Program is optional then any encapsulating ProgramVersion will ignore any errors when attempting to load or attach it.

pub fn syscall(self, syscall: bool) -> Self

Specify whether or not the program is tracing a syscall.

The syscall setting is used to automatically discover syscall wrappers for the system we are running on. For example, if we want to trace sys_ptrace we may want to trace __x64_sys_ptrace instead. By setting syscall(true), oxidebpf will attempt to discover and fix this for you, and you can simply pass sys_ptrace as the attachment point.

pub fn tail_call_map_index(self, map_name: &str, tail_call_index: u32) -> Self

Specify that the program should be loaded into the given tail call map at the given index.

The tail_call_index argument is used to know which indices to insert programs at in the program’s tail call map. The map that it is inserted into is the map with the given map_name. If no map exists with map_name, a runtime OxidebpfError::MapNotFound error will be thrown.

Example

If another one of your programs will tail call into this program and expects it to exist at index 5, you should call this function with 5 as the argument.

use oxidebpf::Program;

let program = Program::new(
    "my_program", &["do_mount"]
).tail_call_map_index("my_map", 5);

pub fn program_type(self, kind: ProgramType) -> Self

Optionally specify what type of program this is.

If the type specified matches what is read from the ELF file, this has no effect. If the type specified is a different, but compatible, type (e.g., kprobe and kretprobe) then the type will be “switched” and the program will be loaded as the specified type. If the types are incompatible (e.g., kprobe vs uprobe), an attempt will be made to load the program as directed, but you will likely receive an error on loading or attaching.

Example

This will tell the loader to attempt to load this program as a kretprobe, despite whatever it exists as in the ELF file.

use oxidebpf::{Program, ProgramType};

let program = Program::new(
   "my_program", &["do_mount"]
).program_type(ProgramType::Kretprobe);

Trait Implementations

impl<'a> Clone for Program<'a>

fn clone(&self) -> Program<'a>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Default for Program<'a>

fn default() -> Program<'a>

Returns the “default value” for a type.