Module ebpf_user

Interactions with the eBPF system.

Copyright © (C) 2021, moskar

Authors: moskar (moskar.drummer@gmail.com).

Description

Interactions with the eBPF system

ebpf_user contains functions that expose the Linux eBPF userspace API, including loading, debugging and applying eBPF programs.

For generating binary eBPF programs see ebpf_asm and ebpf_kern. Note that the functions in this module can work with any binary eBPF program, not only those created via ebpf.

For creating and using eBPF maps see ebpf_maps.

Data Types

attach_point()

attach_point() = socket:socket() | xdp_attach_point()

load_option()

load_option() = sleepable | {log_buffer_size, non_neg_integer()} | {license, string()}

prog()

abstract datatype: prog()

A loaded eBPF program as returned by load/2.

prog_type()

prog_type() = unspec | socket_filter | kprobe | sched_cls | sched_act | tracepoint | xdp | perf_event | cgroup_skb | cgroup_sock | lwt_in | lwt_out | lwt_xmit | sock_ops | sk_skb | cgroup_device | sk_msg | raw_tracepoint | cgroup_sock_addr | lwt_seg6local | lirc_mode2 | sk_reuseport | flow_dissector | cgroup_sysctl | raw_tracepoint_writable | cgroup_sockopt | tracing | struct_ops | ext | lsm | sk_lookup

An atom used to specify the type of an eBPF program, see load/2

xdp_attach_point()

xdp_attach_point() = integer() | string()

Function Index

attach/2 Attaches Prog as a callback program to be called by the kernel at Point.
close/1 Closes Prog.
detach_socket_filter/1 Removes the eBPF program attached to socket Sock.
detach_xdp/1 Removes the attached eBPF XDP program from a network interface.
fd/1 Returns a File Descriptor for Prog.
load/2 Same as load/3, with default options.
load/3 Loads an eBPF program in binary form to the kernel.
test/4 Performs a test run of Prog with Data as input.

Function Details

attach/2

attach(Point::attach_point(), Prog::prog()) -> ok | {error, atom()}

Attaches Prog as a callback program to be called by the kernel at Point.

The possible values of Point depend on the eBPF program type of Prog, which is determined at load time. The following attach points are currently supported:

If Prog is a socket_filter program, Point is a socket:socket().

If Prog is an xdp program, Point is either a numeric interface index or a string() interface name.

close/1

close(Prog::prog()) -> ok | {error, atom()}

Closes Prog.

detach_socket_filter/1

detach_socket_filter(Sock::socket:socket()) -> ok | {error, atom()}

Removes the eBPF program attached to socket Sock.

detach_xdp/1

detach_xdp(Interface::xdp_attach_point()) -> ok | {error, atom()}

Removes the attached eBPF XDP program from a network interface.

fd/1

fd(Prog::prog()) -> non_neg_integer()

Returns a File Descriptor for Prog.

load/2

load(ProgType::prog_type(), BinProg::binary()) -> {ok, prog()} | {ok, prog(), string()} | {error, atom()} | {error, atom(), string()}

Same as load/3, with default options.

load/3

load(ProgType::prog_type(), BinProg::binary(), Options::[load_option()]) -> {ok, prog()} | {ok, prog(), string()} | {error, atom()} | {error, atom(), string()}

Loads an eBPF program in binary form to the kernel.

The program is verified by the kernel's verifier before returning a handle to the loaded program to the caller.

The following Options are currently supported:

sleepable - Loads the eBPF program as sleepable, meaning it can use eBPF helpers that might sleep, e.g. copy_from_user, but it can only be attached to certain sleepable kernel contexts. Defaults to non-sleepable.

{log_buffer_size, non_neg_integer()} - Specifies the size of the log buffer used by the kernel's verifier. If set to 0, verifier logs are disabled, otherwise this call returns also the verifier's log as a string(). Defaults to 0, i.e. logging is disabled.

Note: if log_buffer_size is specified to a positive value, but the specified size is found to be insufficient during verification, the kernel may return an error even if the program would otherwise be valid. In that case either specify a bigger log_buffer_size or disable the verifier's log completely with {log_buffer_size, 0}. {license, string()} - Specifies the license for BinProg. Some eBPF helpers may only be used by GPL-comliant eBPF programs. Defaults to "".

test/4

test(Prog::prog(), Repeat::integer(), Data::binary(), DataOutSize::non_neg_integer()) -> {ok, Ret::non_neg_integer(), DataOut::binary(), Duration::non_neg_integer()} | {error, atom()}

Performs a test run of Prog with Data as input.

WARNING: only use with trusted eBPF programs. This function uses the BPF_PROG_TEST_RUN Linux feature, which is unfortunately inherently unsafe if not used correctly. The way BPF_PROG_TEST_RUN works is that the kernel will write DataOut, created by applying Prog to Data, into a userspace buffer of some predetermined size, exposed in this function as DataOutSize. In most cases this is fine because Prog shouldn't create extensively large DataOut in normal use case, but in case where Prog might create an output that is larger DataOutSize, this can lead to buffer overflow. Hence the warning.

If DataOut is not needed, DataOutSize should be set to 0 in which case no DataOut will be created.

On success, returns the return value of Prog(Data), as well as DataOut and the duration of the test as reported by the kernel.


Generated by EDoc