1 unstable release

0.3.3 May 15, 2023

#220 in WebAssembly

MIT license

1.5K SLoC


eunomia-bpf: simplify and enhance eBPF with CO-RE[^1] and WebAssembly[^2]

Actions Status GitHub release (latest by date) codecov DeepSource CodeFactor

A compiler and runtime framework to help you build and distribute eBPF program easier.


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:
  • Build eBPF programs with Wasm[^2]: 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.

[^1]: CO-RE: Compile Once – Run Everywhere [^2]: WebAssembly or Wasm: https://webassembly.org/

Getting Started

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]
      run     run ebpf program
      client  Client operations
      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)
      [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
      -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

    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.


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.




~278K SLoC