Struct oxidebpf::ProgramGroup

source · [−]

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

Expand description

A group of eBPF ProgramVersions that a user wishes to load from a blueprint. The loader will attempt each ProgramVersion in order until one successfully loads, or none do.

Implementations

source

impl<'a> ProgramGroup<'a>

source

pub fn new() -> ProgramGroup<'a>

Create a program group that will manage multiple ProgramVersions.

Together with load(), this is the primary public interface of the oxidebpf library. You feed your ProgramGroup a collection of ProgramVersions, each with their own set of Programs. Note that you must provide your ProgramGroup with a ProgramBlueprint. The blueprint contains the parsed object file with all the eBPF programs and maps you may load.

Example

use oxidebpf::ProgramBlueprint;
use oxidebpf::{ProgramGroup, Program, ProgramVersion, ProgramType};
use std::path::PathBuf;

let program = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
            .join("test")
            .join(format!("test_program_{}", std::env::consts::ARCH));
let program_blueprint =
    ProgramBlueprint::new(&std::fs::read(program).expect("Could not open file"), None)
        .expect("Could not open test object file");

ProgramGroup::new();

source

pub fn mem_limit(self, limit: usize) -> Self

Manually set the memlock ulimit for this ProgramGroup. The limit will be applied when calling load().

source

pub fn auto_mount_debugfs(self, mount_options: DebugfsMountOpts) -> Self

Controls whether debugfs is mounted before attaching {k,u}probes. This operation only occurs if perf_event_open is not supported and debugfs is not mounted. The DebugfsMountOpts enum determines where debugfs gets mounted to.

source

pub fn polling_thread_priority(
self,
scheduling_policy: SchedulingPolicy
) -> Self

Sets the thread priority for the thread that polls perfmaps for events coming from eBPF to userspace. The priority number specified should be valid for the scheduling policy you provide (documented in the enum). This may be useful if you find you’re missing messages that you expect to be present, or are dropping more messages than seems reasonable.

source

pub fn load(
 &mut self,
 program_blueprint: ProgramBlueprint,
 program_versions: Vec<ProgramVersion<'a>>,
 perfmap_opts_fn: impl FnMut() -> (Sender<PerfChannelMessage>, usize )
) -> Result<(), OxidebpfError>

Attempt to load ProgramVersions until one successfully loads.

This function attempts to load each ProgramVersion in the order given until one successfully loads. When one loads, if that version had a perfmap channel, a PerfChannelMessage receiver crossbeam channel is available after loading by calling get_receiver() on the ProgramGroup. If none load, a NoProgramVersionLoaded error is returned, along with all the internal errors generated during attempted loading.

If the program version contain any perfmaps, perfmap_opts_fn(), will be called on each one until a version suceeds to load. perfmap_opts_fn() returns a channel from which to send perf messages, and a size (in bytes) for the per cpu perf buffer. When the perfmap is created the buffer will take at most the specified number of bytes but it will shrink to fit a page size that is a multiple of two.

NOTE: Once you call load(), it cannot be called again without re-creating the ProgramGroup.

Example

use oxidebpf::ProgramBlueprint;
use oxidebpf::{ProgramGroup, Program, ProgramVersion, ProgramType};
use std::path::PathBuf;

let program = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
            .join("test")
            .join(format!("test_program_{}", std::env::consts::ARCH));
let program_blueprint =
    ProgramBlueprint::new(&std::fs::read(program).expect("Could not open file"), None)
        .expect("Could not open test object file");
let mut program_group = ProgramGroup::new();

let (tx, rx) = crossbeam_channel::bounded(1024);

program_group.load(
    program_blueprint,
    vec![ProgramVersion::new(vec![Program::new(
        "test_program",
        &["do_mount"],
    ).syscall(true)])],
    || (tx.clone(), 1024 * 8),
).expect("Could not load programs");