eunomia-bpf: simplify and enhance eBPF with CO-RE¹ and WebAssembly²

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¹ libbpf eBPF applications: write eBPF kernel code only and automatically exposing your data with perf event or ring 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 and libbpf styles.
Build eBPF programs with Wasm²: see Wasm-bpf project
Runtime, libraries and toolchains to write eBPF with Wasm in C/C++, Rust, Go...covering the use cases from tracing, networking, security.
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 or URL within 1 line of bash without recompiling, kernel version and architecture independent.
Dynamically load eBPF programs with JSON config file or Wasm module.

For more information, see documents/introduction.md.

Getting Started

Github Template：eunomia-bpf/ebpm-template
example bpf programs: examples/bpftools
tutorial: eunomia-bpf/bpf-developer-tutorial

run as cli tool or server

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
INFO [bpf_loader_lib::skeleton] Running ebpf program...
TIME     PID    TPID   SIG    RET    COMM   
01:54:49  77297 8042   0      0      node
01:54:50  77297 8042   0      0      node
01:54:50  78788 78787  17     0      which
01:54:50  78787 8084   17     0      sh
01:54:50  78790 78789  17     0      ps
01:54:50  78789 8084   17     0      sh
01:54:50  78793 78792  17     0      sed
01:54:50  78794 78792  17     0      cat
01:54:50  78795 78792  17     0      cat

$ sudo ./ecli run ghcr.io/eunomia-bpf/execve:latest # run with a name and download the latest version bpf tool from our repo
[79130] node -> /bin/sh -c which ps 
[79131] sh -> which ps 
[79132] node -> /bin/sh -c /usr/bin/ps -ax -o pid=,ppid=,pcpu=,pmem=,c 
[79133] sh -> /usr/bin/ps -ax -o pid=,ppid=,pcpu=,pmem=,command= 
[79134] node -> /bin/sh -c "/home/yunwei/.vscode-server/bin/2ccd690cbf 
[79135] sh -> /home/yunwei/.vscode-server/bin/2ccd690cbff 78132 79119 79120 79121 
[79136] cpuUsage.sh -> sed -n s/^cpu\s//p /proc/stat

You can also use a server to manage and dynamically install eBPF programs.

Start the server:

$ sudo ./ecli-server
[2023-08-08 02:02:03.864009 +08:00] INFO [server/src/main.rs:95] Serving at 127.0.0.1:8527

Use the ecli to control the remote server and manage multiple eBPF programs:

$ ./ecli client start sigsnoop.json # start the program
1
$ ./ecli client log 1 # get the log of the program
TIME     PID    TPID   SIG    RET    COMM   
02:05:58  79725 78132  17     0      bash
02:05:59  77325 77297  0      0      node
02:05:59  77297 8042   0      0      node
02:05:59  77297 8042   0      0      node
02:05:59  79727 79726  17     0      which
02:05:59  79726 8084   17     0      sh
02:05:59  79731 79730  17     0      which

For more information, see documents/src/ecli/server.md.

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 a config file or Wasm module(clang, llvm, and libclang 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:

```bash
# 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.
```