README.md

Awesome Aya

A curated list of awesome eBPF 🐝 projects using aya-rs and Rust 🦀

eBPF is a technology that allows running user-supplied programs inside the Linux kernel. For more info see https://ebpf.io/what-is-ebpf.

Aya is an eBPF library built with a focus on operability and developer experience. It does not rely on libbpf nor bcc - it's built from the ground up purely in Rust, using only the libc crate to execute syscalls. With BTF support and when linked with musl, it offers a true compile once, run everywhere solution, where a single self-contained binary can be deployed on many linux distributions and kernel versions.

Some of the major features provided include:

• Support for the BPF Type Format (BTF), which is transparently enabled when supported by the target kernel. This allows eBPF programs compiled against one kernel version to run on different kernel versions without the need to recompile.
• Support for function call relocation and global data maps, which allows eBPF programs to make function calls and use global variables and initializers.
• Async support with both tokio and async-std.
• Easy to deploy and fast to build: aya doesn't require a kernel build or compiled headers, and not even a C toolchain; a release build completes in a matter of seconds.

Note: The eBPF ecosystem in general is constantly evolving, including Aya itself. We'd love your help to keep this list up to date. Please feel free to file an issue or make a PR if you would like to make a correction or want to have your awesome project included.

Contributing

Contributions are welcome! Please see the contributing guide. If you would like to have your project included in this list, please file a pull request.

Contents

• Reference Documentation
• Article and Presentations
• Small Tools that Use Aya
• Major Projects that Use Aya
• Aya eBPF-Side Libraries
• Acknowledgements

Reference Documentation

• The official Aya Discord server - Community support and discussion
• The Aya Book - The official Aya book, currently a work in progress
  • Compiled mdbook version is available here
  • Some code examples are available here
• The official Aya docs on docs.rs - Up-to-date documentation on the Aya userspace library
• Aya templates for cargo-generate - An easy way to generate a new Aya project using cargo-generate

Articles and Presentations

Aya-related blog posts

• The original announcement of the Aya project
  • Covers the goals of the project and some early logistics
• Adding BPF target support to the Rust compiler
• Aya: your tRusty eBPF companion
  • Shows examples how Aya makes it easier to write eBPF programs.
  • Explains how Deepfence uses Aya, especially XDP/TC packet filtering stack.
• UDP Load-Balancer Demo using Aya
  • Provides a basic example of how to get started inspecting and modifying packets in XDP programs

Aya-related talks

• eBPF Summit 2021: Why Rust for writing eBPF programs
  • Alessandro Decina
• eCHO episode 25: eBPF, Rust, and Aya
  • Dave Tucker and Alessandro Decina discuss the Aya project and writing eBPF programs in Rust
• Linux Plumbers Conference 2021: Improving the eBPF Developer Experience with Rust
  • Dave Tucker and Alessandro Decina

Small Tools that Use Aya

• suidsnoop - Uses Aya and eBPF LSM programs to implement audit logging and policy enforcement for suid binaries
  • Includes examples of:
    • Writing LSM programs in aya-bpf
    • Getting LSM program arguments in aya-bpf
    • Enforcing custom security policy in aya-bpf
    • Using aya::AsyncPerfEventArray to pass events to userspace
• mybee - An eBPF profiler for MySQL 8.0
  • Aya is used to attach to mysqld uprobes.
  • mybee does not have to understand mysql wire protocol and utilize what mysqld already provides.
  • Uses less CPU than AF_PACKET or other eBPF-based tools that monitor TCP packets.
• cir - An tool for loading infrared remote control keymaps for Linux
  • Aya is used to load, query and remove eBPF infrared decoders
  • Compiles IRP Notation to eBPF using LLVM
    • IRP Notation is compiled to LLVM IR using inkwell crate
    • LLVM libraries compile LLVM IR to valid object file
    • Aya loads object file
    • All done in-process, no external files are read/written, or any other dependencies
• oryx - A TUI (Terminal User Interface) for sniffing network traffic.

Major Projects that Use Aya

• lockc - An eBPF LSM-based MAC security audit system for container workloads
  • Works with Docker and Kubernetes (with containerd CRI)
  • Enforcing 3 pre-defined policy levels on containers
• blixt - A Kubernetes Gateway API based Layer 4 Load-Balancer for ingress
  • Aya is used for eBPF code AND userspace (also uses Kube-RS for control-plane)
  • TC is used on the Kubernetes nodes for load-balancer functionality

Aya eBPF-Side Libraries

• aya-log - A logging library for eBPF programs written using aya-bpf
  • This is a fully-reusable logging library for eBPF programs written in aya
  • It provides a logging interface for eBPF programs that emulates Rust's standard log crate

Acknowledgements

The original idea for awesome comes from Sindre Sorhus. The format of this repository is based on zoidbergwill's Awesome eBPF list.

License

All text in this repository is governed by the Creative Commons Attribution-ShareAlike 4.0 International License.