Struct SocketFilter 

pub struct SocketFilter { /* private fields */ }

A program used to inspect and filter incoming packets on a socket.

SocketFilter programs are attached on sockets and can be used to inspect and filter incoming packets.

Each socket has one filter slot. Attaching a new SocketFilter replaces the socket’s current filter, and detaching clears that current filter regardless of which program installed it. Aya therefore does not expose a link-style attachment handle for SocketFilter or automatically track socket filter attachments for cleanup. Dropping SocketFilter or crate::Ebpf does not detach the filter; call SocketFilter::detach explicitly when you want to remove it, or close the socket.

Minimum kernel version

The minimum kernel version required to use this feature is 3.19. BPF_PROG_TYPE_SOCKET_FILTER and SO_ATTACH_BPF are present in Linux v3.19: https://github.com/torvalds/linux/blob/v3.19/include/uapi/linux/bpf.h#L118-L120 https://github.com/torvalds/linux/blob/v3.19/include/uapi/asm-generic/socket.h#L87-L88

Examples

use std::net::TcpStream;
use aya::programs::SocketFilter;

let mut client = TcpStream::connect("127.0.0.1:1234")?;
let prog: &mut SocketFilter = bpf.program_mut("filter_packets").unwrap().try_into()?;
prog.load()?;
prog.attach(&client)?;

Implementations

impl SocketFilter

pub const PROGRAM_TYPE: ProgramType = ProgramType::SocketFilter

The type of the program according to the kernel.

pub fn load(&mut self) -> Result<(), ProgramError>

Loads the program inside the kernel.

pub fn attach<T: AsFd>(&self, socket: T) -> Result<(), ProgramError>

Attaches the filter on the given socket.

If the socket already has a filter attached, attaching again replaces the current filter instead of returning an already-attached error. This follows the kernel model: each socket has one filter slot and cannot run multiple socket filters together. The kernel detach API also clears the socket’s current filter slot; it cannot detach a specific program attachment. For that reason, Aya does not provide link-level RAII semantics for socket filters. Dropping SocketFilter or crate::Ebpf does not detach the filter. Call SocketFilter::detach explicitly when you want to remove it, or close the socket.

pub fn detach<T: AsFd>(socket: T) -> Result<(), ProgramError>

Detaches the current filter from the given socket.

Detaching clears the socket’s current filter slot, regardless of which program was used to attach that filter. Unlike SocketFilter::attach, this operation does not require the program to remain loaded in this process. If another filter replaced this program on the same socket, detaching will remove that replacement filter.

pub fn from_pin<P: AsRef<Path>>(path: P) -> Result<Self, ProgramError>

Creates a program from a pinned entry on a bpffs.

SocketFilter does not use link-style attachments, so this only restores access to the pinned program itself.

Dropping the returned value unloads the local program FD, but does not detach the filter from any socket. This will also not unload the program from the kernel while it remains pinned.

impl SocketFilter

pub fn unload(&mut self) -> Result<(), ProgramError>

Unloads the program from the kernel.

Tracked links will be detached before unloading the program. Attachment mechanisms that do not create tracked links are not affected. Note that owned links obtained using take_link() will not be detached.

impl SocketFilter

pub fn fd(&self) -> Result<&ProgramFd, ProgramError>

Returns the file descriptor of this Program.

impl SocketFilter

pub fn pin<P: AsRef<Path>>(&mut self, path: P) -> Result<(), PinError>

Pins the program to a BPF filesystem.

When a BPF object is pinned to a BPF filesystem it will remain loaded after Aya has unloaded the program. To remove the program, the file on the BPF filesystem must be removed. Any directories in the the path provided should have been created by the caller.

pub fn unpin(&mut self) -> Result<(), Error>

Removes the pinned link from the filesystem.

impl SocketFilter

pub fn info(&self) -> Result<ProgramInfo, ProgramError>

Returns metadata information of this program.

Uses kernel v4.13 features.

Trait Implementations

impl Debug for SocketFilter

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for SocketFilter

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl TestRun for SocketFilter

type Opts<'a> = TestRunOptions<'a>

The options type used to configure a single test invocation.

type Result = TestRunResult

The Result type for a single test invocation.

fn test_run(&self, opts: Self::Opts<'_>) -> Result<Self::Result, ProgramError>

Runs the program with test input data and returns the result.

impl<'a> TryFrom<&'a Program> for &'a SocketFilter

type Error = ProgramError

The type returned in the event of a conversion error.

fn try_from(program: &'a Program) -> Result<&'a SocketFilter, ProgramError>

Performs the conversion.

impl<'a> TryFrom<&'a mut Program> for &'a mut SocketFilter

type Error = ProgramError

The type returned in the event of a conversion error.

fn try_from( program: &'a mut Program, ) -> Result<&'a mut SocketFilter, ProgramError>

Performs the conversion.