Copyright © (C) 2021, moskar
Authors: moskar (moskar.drummer@gmail.com).
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
.
ebpf_maps
.
attach_point() = socket:socket() | xdp_attach_point()
load_option() = sleepable | {log_buffer_size, non_neg_integer()} | {license, string()}
abstract datatype: prog()
A loaded eBPF program as returned by load/2
.
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() = integer() | string()
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. |
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()
.
Prog
is an xdp
program, Point
is either a numeric
interface index or a string()
interface name.
close(Prog::prog()) -> ok | {error, atom()}
Closes Prog
.
detach_socket_filter(Sock::socket:socket()) -> ok | {error, atom()}
Removes the eBPF program attached to socket Sock
.
detach_xdp(Interface::xdp_attach_point()) -> ok | {error, atom()}
Removes the attached eBPF XDP program from a network interface.
fd(Prog::prog()) -> non_neg_integer()
Returns a File Descriptor for Prog
.
load(ProgType::prog_type(), BinProg::binary()) -> {ok, prog()} | {ok, prog(), string()} | {error, atom()} | {error, atom(), string()}
Same as load/3
, with default options.
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.
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(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.
Prog(Data)
, as well as DataOut
and the duration of the test as reported by the kernel.
Generated by EDoc