eunomia-bpf Documentation

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/eunomia-template
• example bpf programs: examples/bpftools
• tutorial: eunomia-bpf/bpf-developer-tutorial

run as a CLI tool

You can get pre-compiled eBPF programs running from GitHub Pages URLs or an OCI registry in 1 line of bash:

# download the latest release (aka.pw/bpf-ecli redirects to the current GitHub release asset)
$ wget https://aka.pw/bpf-ecli -O ecli && chmod +x ./ecli
$ sudo ./ecli https://eunomia-bpf.github.io/eunomia-bpf/sigsnoop/package.json # historical GitHub Pages workflow, kept for compatibility
$ sudo ./ecli run ghcr.io/eunomia-bpf/execve:latest # run a pre-compiled ebpf tool from OCI registry
[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

The legacy remote HTTP mode (ecli client / ecli-server) has been removed from the main branch to reduce maintenance overhead. The last implementation is preserved on the archive/ecli-remote-http branch; see the legacy mode note.

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
   
  Usage: ecli [COMMAND_LINE]... [COMMAND]
   
  Commands:
    run     run ebpf program
    push    Operations about pushing image to registry
    pull    Operations about pulling image from registry
    help    Print this message or the help of the given subcommand(s)
   
  Arguments:
    [COMMAND_LINE]...  Not preferred. Only for compatibility to older versions. Command line to run. The executable could either be a local path or URL or `-` (read from stdin). The following arguments will be passed to the program
   
  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:

  # 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