1 unstable release
0.3.3 | May 15, 2023 |
---|
#220 in WebAssembly
61KB
1.5K
SLoC
eunomia-bpf: simplify and enhance eBPF with CO-RE[^1] and WebAssembly[^2]
A compiler and runtime framework to help you build and distribute eBPF program easier.
Introduction
eunomia-bpf
is a dynamic loading library/runtime and a compile toolchain framework, aim at helping you build and distribute eBPF programs easier.
With eunnomia-bpf, you can:
- A library to simplify
writing
eBPF programs:- simplify building CO-RE[^1]
libbpf
eBPF applications: write eBPF kernel code only and automatically exposing your data withperf event
orring buffer
from kernel. - Automatically sample the data from hash maps and print
hists
in userspace. - Automatically generate and config
command line arguments
for eBPF programs. - You can writing the kernel part in both
BCC
andlibbpf
styles.
- simplify building CO-RE[^1]
- Build eBPF programs with
Wasm
[^2]: seeWasm-bpf
project- Runtime, libraries and toolchains to write eBPF with Wasm in C/C++, Rust, Go...covering the use cases from
tracing
,networking
,security
.
- Runtime, libraries and toolchains to write eBPF with Wasm in C/C++, Rust, Go...covering the use cases from
- simplify
distributing
eBPF programs:- A tool for push, pull and run pre-compiled eBPF programs as
OCI
images in Wasm module - Run eBPF programs from
cloud
orURL
within1
line of bash without recompiling, kernel version and architecture independent. - Dynamically load eBPF programs with
JSON
config file orWasm
module.
- A tool for push, pull and run pre-compiled eBPF programs as
For more information, see documents/introduction.md.
[^1]: CO-RE: Compile Once – Run Everywhere [^2]: WebAssembly or Wasm: https://webassembly.org/
Getting Started
- Github Template:eunomia-bpf/ebpm-template
- example bpf programs: examples/bpftools
- tutorial: eunomia-bpf/bpf-developer-tutorial
You can get pre-compiled eBPF programs running from the cloud to the kernel in 1
line of bash:
# download the release from https://github.com/eunomia-bpf/eunomia-bpf/releases/latest/download/ecli
$ wget https://aka.pw/bpf-ecli -O ecli && chmod +x ./ecli
$ sudo ./ecli run https://eunomia-bpf.github.io/eunomia-bpf/sigsnoop/package.json # simply run a pre-compiled ebpf code from a url
$ sudo ./ecli run ghcr.io/eunomia-bpf/execve:latest # run with a name and download the latest version bpf tool from our repo
Build or install the project
-
Install the
ecli
tool for running eBPF program from the cloud:$ wget https://aka.pw/bpf-ecli -O ecli && chmod +x ./ecli $ ./ecli -h ecli subcommands, including run, push, pull, login, logout Usage: ecli-rs [PROG] [EXTRA_ARGS]... [COMMAND] Commands: run run ebpf program client Client operations push pull pull oci image from registry login login to oci registry logout logout from registry help Print this message or the help of the given subcommand(s) Arguments: [PROG] Not preferred. Only for compatibility to older versions. Ebpf program URL or local path, set it `-` to read the program from stdin [EXTRA_ARGS]... Not preferred. Only for compatibility to older versions. Extra args to the program; For wasm program, it will be passed directly to it; For JSON program, it will be passed to the generated argument parser Options: -h, --help Print help ....
-
Install the
ecc
compiler-toolchain for compiling eBPF kernel code to aconfig
file orWasm
module(clang
,llvm
, andlibclang
should be installed for compiling):$ wget https://github.com/eunomia-bpf/eunomia-bpf/releases/latest/download/ecc && chmod +x ./ecc $ ./ecc -h eunomia-bpf compiler Usage: ecc [OPTIONS] <SOURCE_PATH> [EXPORT_EVENT_HEADER] ....
or use the docker image for compile:
# for x86_64 and aarch64 docker run -it -v `pwd`/:/src/ ghcr.io/eunomia-bpf/ecc-`uname -m`:latest # compile with docker. `pwd` should contains *.bpf.c files and *.h files.
-
build the compiler, runtime library and tools:
see build for building details.
Examples
See examples for details about simple eBPF tools and eunomia-bpf library usage.
See github.com/eunomia-bpf/wasm-bpf/tree/main/examples for Wasm eBPF programs and examples.
We also have a prove of concept video: Writing eBPF programs in Wasm.
License
MIT LICENSE
Dependencies
~11–24MB
~278K SLoC