aya-rs/aya
Aya
Aya is a Rust-native framework for writing, compiling, and loading eBPF programs into the Linux kernel. It provides a complete development environment that eliminates the need for a C toolchain or libbpf, allowing developers to work entirely within the Rust ecosystem. The framework manages the full lifecycle of eBPF programs, including async runtime integration, CO-RE BTF resolution for kernel version portability, ELF-based program loading, and safe kernel memory access.
The framework distinguishes itself through its pure Rust compilation pipeline, which compiles Rust source code directly into eBPF bytecode without requiring external compilers. It supports kernel hook attachment across multiple attachment points including tracepoints, kprobes, cgroups, and network interfaces. Aya also provides safe packet parsing with bound checks for Ethernet, IPv4, TCP, and UDP headers, along with userspace-kernel map communication for synchronizing data between kernel-space eBPF programs and userspace applications.
The project covers the full eBPF development lifecycle, including program writing with support for function calls and global variables, program loading and attachment, kernel observability through structured log emission and consumption, and network packet processing with XDP and socket filters. It includes project scaffolding for generating new Rust eBPF project skeletons with the correct toolchain and program type, as well as toolchain installation commands to prepare the development environment.
Features
- eBPF Frameworks for Rust - Provides a complete Rust-native framework for writing, compiling, and loading eBPF programs into the Linux kernel.
- eBPF Function Call Relocations - Support function call relocation and global data maps so eBPF programs can call functions and use initialized globals.
- eBPF Log Consumers - Provides a userspace API to read and process structured log messages emitted by eBPF programs.
- Kernel Event Hooks - Loads compiled eBPF objects into the kernel and attaches them to hook points like system calls or network events.
- Kernel-Space Packet Processing - Filters, redirects, and inspects network packets at the kernel level using XDP and socket filters.
- Kernel Bytecode Execution - Loads compiled eBPF bytecode into the Linux kernel for execution.
- CO-RE Relocation - Resolves kernel data structure offsets at load time using BTF for portable eBPF binaries across kernel versions.
- eBPF Lifecycle Management - Manages the full lifecycle of eBPF programs including loading, attachment, logging, and event handling from userspace.
- eBPF Object Loading - Loads compiled eBPF programs from ELF object files, resolving program references and maps for kernel execution.
- Network Interface Attachments - Loads compiled eBPF objects and attaches them to network interfaces for packet processing.
- Kernel Map Management - Creates and interacts with kernel-side data structures that share state between user-space and eBPF programs.
- eBPF Program Deployment - Loads compiled eBPF programs into the kernel and manipulates them from user-space.
- CO-RE Portable eBPF Deployments - Builds single compiled eBPF binaries that run across different Linux kernel versions using CO-RE and BTF.
- Event-Triggered Programs - Writes kernel-space programs in Rust that run inside the Linux kernel in response to events.
- XDP Program Writers - Provides a Rust-native API for writing XDP programs that process incoming network packets.
- eBPF Kprobe Attachments - Attaches eBPF programs to kernel function entry points via kprobes for custom logic execution.
- Kernel-Userspace Shared Maps - Synchronizes data between kernel-space eBPF programs and userspace applications using shared memory maps.
- Userspace Map Populators - Insert entries into an eBPF map from a userspace program to dynamically update the packet filtering policy at runtime.
- BTF and CO-RE Resolvers - Resolves kernel data structure offsets at load time using BTF for portable eBPF binaries.
- eBPF Async Lifecycle Managers - Provides async runtime integration for managing non-blocking eBPF program lifecycle and event handling.
- eBPF Bytecode Compilers - Compiles Rust source code directly into eBPF bytecode without requiring a C toolchain or external compiler.
- Pure Rust Compilation Pipelines - Compiles Rust source code directly into eBPF bytecode without requiring a C toolchain or external compiler.
- Kernel Execution Hooks - Binds eBPF programs to kernel attachment points such as tracepoints, kprobes, cgroups, and network interfaces.
- Kernel Event Observability - Monitors system events by attaching eBPF programs to tracepoints and kprobes for debugging and performance analysis.
- Protocol Header Parsers - Provides safe parsing of Ethernet, IPv4, TCP, and UDP headers with bound checks.
- Safe Packet Header Parsers - Ships safe packet parsing with bound checks for Ethernet, IPv4, TCP, and UDP headers.
- IP Blocklist Droppers - Drops packets by looking up destination IP addresses in a blocklist map.
- Source IP Blocklist Droppers - Filters packets by looking up source IP addresses in a hash map and dropping matches.
- eBPF Socket Filters - Attaches eBPF programs to network sockets for per-packet inspection and modification.
- Bidirectional Traffic Inspectors - Attaches classifier programs to qdiscs for bidirectional packet inspection and decision-making.
- Async Runtime Integrations - Integrates eBPF program lifecycle and event handling with async runtimes for non-blocking operation.
- eBPF Context Memory Copiers - Provides safe kernel memory access by copying data structures into eBPF context without page faults.
- eBPF Context Readers - Copies kernel data structures into eBPF context safely to prevent page faults.
- Userspace Memory Readers - Read a string from userspace memory inside an eBPF program using a per-CPU buffer to work around stack limits.
- eBPF Cgroup Hooks - Attaches eBPF programs to cgroup hooks to execute custom logic on process operations.
- eBPF Log Emissions - Emits structured log messages from kernel-space eBPF code that are received and printed by the userspace loader.
- Tracepoint Monitoring - Attaches eBPF programs to static kernel tracepoints to monitor events like system calls or scheduler activity.
- Packet Arrival Logging - Logs a message from inside an eBPF program each time a packet arrives, visible in user-space output.
- Packet Metadata Extraction Logging - Outputs extracted packet information such as source IP and port to the kernel log for debugging or monitoring.
- Packet Field Extractors - Ships safe packet parsing with bound checks to extract IP addresses and ports from headers.
- Structured Logging - Emits structured log messages from kernel-space eBPF programs using the info macro for debugging or monitoring.
- Development Frameworks - Rust library for writing and managing eBPF objects.
