Wasm-bpf is a WebAssembly eBPF library, toolchain and runtime powered by CO-RE(Compile Once – Run Everywhere) libbpf. It can help you build almost every eBPF programs or usecases to Wasm with nearly zero modification, and run them cross platforms with Wasm sandbox.
⌨️ Introduction to wasm-bpf, and also Our talks in Kubecon
📦 Features
🚀 Running a standalone Wasm program from CLI or Docker
🔌 Embed a Wasm-eBPF function in your Rust program or C/C++ program
🔨 Examples covering the use cases from tracing, networking to security
📚 How it works
🤖 Build the runtime, or as a plugin for WasmEdge
📚 Check out our more documentations
WebAssembly (Wasm) is a portable binary format for executable code. The code is executed at a nearly-native speed in a memory-safe (for host) sandbox, with clearly defined resource constraints, and APIs for communicating with the embedding host environment (eg. proxy).The wasm-bpf project combines Wasm and eBPF technologies to enhance the performance and programmability of eBPF applications.
With wasm-bpf, users can dynamically load and securely execute user-defined or community-contributed Wasm-eBPF codes as plug-ins in their software products, such as observability platforms or service proxy. This enables efficient and scalable data collection, while also allowing for advanced processing and analysis of that data.
It also enables developers to write eBPF programs in familiar languages like C/C++, Rust, Go, and more than 30 other programming languages, and deploy them easily across different Linux distributions. Additionally, cloud providers can leverage wasm-bpf to offer a secure and high-performance environment for their customers to develop and deploy eBPF applications in their cloud environments.
Run the following command to install the wasm-bpf CLI tool:
cargo install wasm-bpf Running the runqlat example with docker:
$ wget https://eunomia-bpf.github.io/wasm-bpf/examples/runqlat/runqlat.wasm
$ docker run --rm -it --privileged -v $(pwd):/examples ghcr.io/eunomia-bpf/wasm-bpf:latest /examples/runqlat.wasm
Tracing run queue latency... Hit Ctrl-C to end.
usecs : count distribution
0 -> 1 : 72 |***************************** |
2 -> 3 : 93 |************************************* |
4 -> 7 : 98 |****************************************|
8 -> 15 : 96 |*************************************** |
16 -> 31 : 38 |*************** |
32 -> 63 : 4 |* |
64 -> 127 : 5 |** |
128 -> 255 : 6 |** |
256 -> 511 : 0 | |
512 -> 1023 : 0 | |
1024 -> 2047 : 0 | |
2048 -> 4095 : 1 | |For more tools to distribute and deploy Wasm-eBPF programs for usecases from Observability, Networking to Security, please refer to eunomia-bpf repo.
Add the following line to your Cargo.toml to use Wasm-bpf as a library:
wasm-bpf-rs = "0.2.2"See the main.rs for an example of how to use the wasm-bpf-rs library.
General purpose: provide most abilities from eBPF to Wasm,pollingfrom the ring buffer or perf buffer, bidirectional communications betweenkerneleBPF anduserspaceWasm usingmaps, dynamicallyloading,attachingordetaching, etc. Supports a large number of eBPF program types and map types.High performance: Noserializationoverhead for complex data types, usingshared memoryto avoid copy overhead between host and Wasm.Easy to use: provide a similar developing experience as the libbpf-bootstrap,auto generatethe Wasm-eBPF skeleton headers and type definitions for bindings. Write your eBPF programs inC/C++,Rust,Goand compile to Wasm.Ultralightweight: the miminal runtime has only1.5 MBin binary size. Compiled Wasm module would be only~90K. With the same toolchain, you can easily build your own Wasm-eBPF runtime in any languages and platforms!
See the examples directory for examples of eBPF programs written in C, Rust, Go and compiled to Wasm, covering the use cases from tracing, networking to security.
For tools to distribute Wasm-eBPF programs in OCI images, please refer to eunomia-bpf repo.
See the examples directory for examples of eBPF programs written in C, Rust, Go and compiled to WASM.
tracing examples
- bootstrap and rust-bootstrap: trace process exec and exit
- runqlat: summarizes scheduler run queue latency as a histogram
- execve and go-execve: trace execve syscall
security example
networking example
- sockfilter: monitoring packet and dealing with
__sk_buff. - sockops: Add the pid int tcp option in syn packet.
An eBPF application typically consists of two parts: the user space part and the kernel space part. With wasm-bpf, the user space part is executed in a WebAssembly (Wasm) sandbox while the kernel space part is executed in the eBPF runtime in the Linux kernel. This separation of concerns allows for greater flexibility and security in developing and running eBPF programs, as well as the ability to leverage the benefits of both Wasm and eBPF.
The wasm-bpf runtime require two parts: the host side(Outside the Wasm runtime) and the Wasm guest side(Inside the Wasm runtime).
- host side: A simple runtime implementation example
- see runtime/cpp, which would be a sample runtime in
C++built on the top of libbpf and WAMR. Another more complex runtime implement inRustis runtime/wasm-bpf-rs, based on Wasmtime. - You can easily build your own Wasm-eBPF runtime in
anylanguages,anyeBPF libraries andanyWasm runtimes with the same System interface.
- see runtime/cpp, which would be a sample runtime in
- wasm side: toolchains and libraries
- a
libbpf-wasmheader only library to provide libbpf APIs for Wasm guestC/C++code. - a
bpftooltool to generate the Wasm-eBPFskeletonheaders, andC struct definitionsfor passing data between the host and Wasm guest without serialization. Rust,Goand other language support is similar to theC/C++support.
- a
For details compile process, please refer to the examples/bootstrap/README.md. The figure below shows the overall interaction between the eBPF and Wasm runtimes:
A Wasm module could load and control multiple eBPF programs at the same time, and can call another Wasm module written in other languages to process the data or control with the component model.
We have proposed a new WASI issue wasi-bpf.
We have two types of runtime samples:
- A C/C++ runtime example, which is a minimal runtime based on WAMR. see runtime/cpp for more details.
- A Rust runtime example, which is a more complex runtime based on Wasmtime. see runtime/wasm-bpf-rs for more details.
The runtime can be built as a library or a standalone executable. see docs/build.md to build the runtimes.
This project has nix flake and direnv support. See:
- eunomia-bpf project: simplify and enhance eBPF with CO-RE and WebAssembly https://github.com/eunomia-bpf/eunomia-bpf
- documents and blogs: https://docs.eunomia.dev
- CO-RE (Compile Once – Run Everywhere): https://facebookmicrosites.github.io/bpf/blog/2020/02/19/bpf-portability-and-co-re.html
- WAMR (WebAssembly Micro Runtime): https://github.com/bytecodealliance/wasm-micro-runtime
- libbpf: https://github.com/libbpf/libbpf