uwcl_rbpf

Rust (user-space) virtual machine for eBPF

Description

This is a fork of RBPF by Quentin Monnet.

This crate contains a virtual machine for eBPF program execution. BPF, as in Berkeley Packet Filter, is an assembly-like language initially developed for BSD systems, in order to filter packets in the kernel with tools such as tcpdump so as to avoid useless copies to user-space. It was ported to Linux, where it evolved into eBPF (extended BPF), a faster version with more features. While BPF programs are originally intended to run in the kernel, the virtual machine of this crate enables running it in user-space applications; it contains an interpreter, an x86_64 JIT-compiler for eBPF programs, as well as an assembler, disassembler and verifier.

The crate is supposed to compile and run on Linux, MacOS X, and Windows, although the JIT-compiler does not work with Windows at this time.

Link to the crate

This crate is available from crates.io, so it should work out of the box by adding it as a dependency in your Cargo.toml file:

[dependencies]
uwcl_rbpf = "0.0.1"

You can also use the development version from this GitHub repository. This should be as simple as putting this inside your Cargo.toml:

[dependencies]
uwcl_rbpf = { git = "https://github.com/trancesnail/uwcl_rbpf", branch = "master" }

Of course, if you prefer, you can clone it locally, possibly hack the crate, and then indicate the path of your local version in Cargo.toml:

[dependencies]
uwcl_rbpf = { path = "path/to/uwcl_rbpf" }

Then indicate in your source code that you want to use the crate:

extern crate uwcl_rbpf;

API

The API is pretty well documented inside the source code. You should also be able to access an online version of the documentation from here, automatically generated from the crates.io version (may not be up-to-date with master branch). Examples, unit tests and performance benchmarks should also prove helpful.

Here are the steps to follow to run an eBPF program with rbpf:

1. Create an executable, either from the bytecode or an ELF.
2. Create a syscall-registry, add some syscalls and put it in the executable.
3. If you want a JIT-compiled program, compile it.
4. Create a memory mapping, consisting of multiple memory regions.
5. Create the config and a virtual machine using all of the previous steps. You can also pass a readonly memory here which will be mapped as packet data in the eBPF programs register at index one.
6. If you registered syscall functions then bind their context objects.
7. Create an instruction meter.
8. Execute your program: Either run the interpreter or call the JIT-compiled function.

License

Following the effort of the Rust language project itself in order to ease integration with other projects, the rbpf crate is distributed under the terms of both the MIT license and the Apache License (Version 2.0).

See LICENSE-APACHE and LICENSE-MIT for details.