mirror of https://github.com/aya-rs/aya
feat: initialize eBPF traffic monitor project structure
- Add Cargo.toml with aya dependencies and project configuration - Add build.rs with aya-build integration for eBPF compilation - Configure workspace and example targets 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>reviewable/pr1291/r1
Krish Sharma
3 weeks ago
parent
44b26b3b50
commit
c590290bdf
@ -0,0 +1,144 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Project Overview
|
||||
|
||||
Aya is a pure-Rust eBPF library built without dependencies on libbpf or bcc. It provides a complete eBPF development stack with both userspace and kernel-space components, supporting BTF (BPF Type Format) for portable "compile once, run everywhere" eBPF programs.
|
||||
|
||||
## Key Components
|
||||
|
||||
### Crate Structure
|
||||
- **aya**: Main userspace library for loading and managing eBPF programs
|
||||
- **aya-obj**: BPF object file parsing and manipulation
|
||||
- **aya-build**: Build-time utilities for eBPF program compilation
|
||||
- **aya-log**: Logging infrastructure for eBPF programs
|
||||
- **aya-tool**: Command-line tools for eBPF development
|
||||
- **aya-ebpf**: Kernel-space eBPF program development library (no_std)
|
||||
- **aya-ebpf-bindings**: Low-level kernel bindings for eBPF programs
|
||||
- **test-distro**: Testing infrastructure for different kernel versions
|
||||
|
||||
### Program Types
|
||||
The library supports all major eBPF program types:
|
||||
- **Probes**: KProbe, UProbe, TracePoint, RawTracePoint, BtfTracePoint
|
||||
- **Network**: XDP, TC (traffic control), SocketFilter, SkMsg, SkSkb, SockOps
|
||||
- **Cgroup**: CgroupSkb, CgroupSock, CgroupSockAddr, CgroupSockopt, CgroupSysctl, CgroupDevice
|
||||
- **Security**: LSM (Linux Security Module), FEntry, FExit
|
||||
- **Specialized**: PerfEvent, LircMode2, FlowDissector, SkLookup, Extension, Iter
|
||||
|
||||
### Map Types
|
||||
Comprehensive map support including:
|
||||
- Basic: Array, HashMap, LruHashMap, PerCpuArray, PerCpuHashMap
|
||||
- Advanced: RingBuf, PerfEventArray, BloomFilter, LpmTrie, Stack, Queue
|
||||
- Specialized: SockMap, SockHash, CpuMap, DevMap, XskMap, ProgramArray
|
||||
|
||||
## Common Development Commands
|
||||
|
||||
### Building
|
||||
```bash
|
||||
# Build all workspace members
|
||||
cargo build
|
||||
|
||||
# Build specific crate
|
||||
cargo build -p aya
|
||||
```
|
||||
|
||||
### Testing
|
||||
```bash
|
||||
# Run unit tests
|
||||
cargo test
|
||||
|
||||
# Run integration tests (requires special setup)
|
||||
cargo xtask integration-test local
|
||||
|
||||
# Run virtualized integration tests
|
||||
cargo xtask integration-test vm
|
||||
```
|
||||
|
||||
### Linting and Formatting
|
||||
```bash
|
||||
# Format code
|
||||
cargo +nightly fmt --all
|
||||
|
||||
# Run clippy with project-specific configuration
|
||||
./clippy.sh
|
||||
|
||||
# Run clippy with arguments
|
||||
./clippy.sh --fix
|
||||
```
|
||||
|
||||
### eBPF-specific Commands
|
||||
```bash
|
||||
# Generate code from kernel headers
|
||||
cargo xtask codegen
|
||||
|
||||
# Check public API compatibility
|
||||
cargo xtask public-api
|
||||
|
||||
# Build documentation
|
||||
cargo xtask docs
|
||||
```
|
||||
|
||||
### Architecture-specific Building
|
||||
```bash
|
||||
# Build eBPF programs for specific target
|
||||
cargo +nightly build --target bpfel-unknown-none -Z build-std=core
|
||||
|
||||
# Build for specific BPF architecture
|
||||
CARGO_CFG_BPF_TARGET_ARCH=x86_64 cargo +nightly build --target bpfel-unknown-none
|
||||
```
|
||||
|
||||
## Key Architecture Patterns
|
||||
|
||||
### EbpfLoader Pattern
|
||||
The main loading mechanism uses a builder pattern:
|
||||
```rust
|
||||
let mut bpf = EbpfLoader::new()
|
||||
.btf(Btf::from_sys_fs().ok().as_ref())
|
||||
.map_pin_path("/sys/fs/bpf/my-program")
|
||||
.set_global("CONFIG_VALUE", &42u32, true)
|
||||
.load_file("program.o")?;
|
||||
```
|
||||
|
||||
### Program Lifecycle
|
||||
1. Parse object file with `Object::parse()`
|
||||
2. Apply relocations (BTF, maps, calls)
|
||||
3. Load into kernel with appropriate program type
|
||||
4. Attach to hook points
|
||||
|
||||
### Map Management
|
||||
- Maps are created during object loading
|
||||
- Support for pinning in `/sys/fs/bpf/`
|
||||
- Automatic BTF integration when available
|
||||
- Per-CPU variants for performance
|
||||
|
||||
## Development Notes
|
||||
|
||||
### Feature Detection
|
||||
The library automatically detects kernel BPF features at runtime through `detect_features()` and stores them in a global `FEATURES` static.
|
||||
|
||||
### Cross-compilation
|
||||
- Uses `bpf-linker` for linking eBPF programs
|
||||
- Requires nightly Rust for eBPF target compilation
|
||||
- Supports multiple architectures: x86_64, aarch64, arm, riscv64, powerpc64, s390x, mips
|
||||
|
||||
### Testing Infrastructure
|
||||
- `test-distro` provides a minimal Linux distribution for testing
|
||||
- Integration tests run against multiple kernel versions
|
||||
- Virtualized testing with QEMU for different architectures
|
||||
|
||||
### Workspace Configuration
|
||||
- Uses Rust 2024 edition
|
||||
- Minimum supported Rust version: 1.85.0
|
||||
- Shared dependencies managed through `workspace.dependencies`
|
||||
- Default members exclude integration tests (built separately)
|
||||
|
||||
## Important File Locations
|
||||
|
||||
- **Build configuration**: `Cargo.toml` (workspace root)
|
||||
- **CI configuration**: `.github/workflows/ci.yml`
|
||||
- **Rust toolchain**: `ebpf/rust-toolchain.toml`
|
||||
- **Format configuration**: `rustfmt.toml`
|
||||
- **eBPF programs**: `ebpf/` directory
|
||||
- **Integration tests**: `test/integration-test/` and `test/integration-ebpf/`
|
||||
- **Test kernels**: `test/.tmp/` (downloaded during CI)
|
||||
@ -0,0 +1,96 @@
|
||||
{
|
||||
"nodes": {
|
||||
"flake-utils": {
|
||||
"inputs": {
|
||||
"systems": "systems"
|
||||
},
|
||||
"locked": {
|
||||
"lastModified": 1731533236,
|
||||
"narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=",
|
||||
"owner": "numtide",
|
||||
"repo": "flake-utils",
|
||||
"rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"owner": "numtide",
|
||||
"repo": "flake-utils",
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"nixpkgs": {
|
||||
"locked": {
|
||||
"lastModified": 1751792365,
|
||||
"narHash": "sha256-J1kI6oAj25IG4EdVlg2hQz8NZTBNYvIS0l4wpr9KcUo=",
|
||||
"owner": "NixOS",
|
||||
"repo": "nixpkgs",
|
||||
"rev": "1fd8bada0b6117e6c7eb54aad5813023eed37ccb",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"owner": "NixOS",
|
||||
"ref": "nixos-unstable",
|
||||
"repo": "nixpkgs",
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"nixpkgs_2": {
|
||||
"locked": {
|
||||
"lastModified": 1744536153,
|
||||
"narHash": "sha256-awS2zRgF4uTwrOKwwiJcByDzDOdo3Q1rPZbiHQg/N38=",
|
||||
"owner": "NixOS",
|
||||
"repo": "nixpkgs",
|
||||
"rev": "18dd725c29603f582cf1900e0d25f9f1063dbf11",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"owner": "NixOS",
|
||||
"ref": "nixpkgs-unstable",
|
||||
"repo": "nixpkgs",
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"root": {
|
||||
"inputs": {
|
||||
"flake-utils": "flake-utils",
|
||||
"nixpkgs": "nixpkgs",
|
||||
"rust-overlay": "rust-overlay"
|
||||
}
|
||||
},
|
||||
"rust-overlay": {
|
||||
"inputs": {
|
||||
"nixpkgs": "nixpkgs_2"
|
||||
},
|
||||
"locked": {
|
||||
"lastModified": 1751942411,
|
||||
"narHash": "sha256-01uMHCt2U9tP4f24DGch145tT8YQppLY5TC9mWK7O0A=",
|
||||
"owner": "oxalica",
|
||||
"repo": "rust-overlay",
|
||||
"rev": "c587235f892930a61c9e415f0d9792a1b27a41a2",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"owner": "oxalica",
|
||||
"repo": "rust-overlay",
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"systems": {
|
||||
"locked": {
|
||||
"lastModified": 1681028828,
|
||||
"narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
|
||||
"owner": "nix-systems",
|
||||
"repo": "default",
|
||||
"rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"owner": "nix-systems",
|
||||
"repo": "default",
|
||||
"type": "github"
|
||||
}
|
||||
}
|
||||
},
|
||||
"root": "root",
|
||||
"version": 7
|
||||
}
|
||||
@ -0,0 +1,144 @@
|
||||
{
|
||||
description = "Aya eBPF development environment";
|
||||
|
||||
inputs = {
|
||||
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
|
||||
rust-overlay.url = "github:oxalica/rust-overlay";
|
||||
flake-utils.url = "github:numtide/flake-utils";
|
||||
};
|
||||
|
||||
outputs = { self, nixpkgs, rust-overlay, flake-utils }:
|
||||
flake-utils.lib.eachDefaultSystem (system:
|
||||
let
|
||||
overlays = [ (import rust-overlay) ];
|
||||
pkgs = import nixpkgs {
|
||||
inherit system overlays;
|
||||
};
|
||||
|
||||
# Rust toolchain with stable for general development
|
||||
rustToolchain = pkgs.rust-bin.stable.latest.default.override {
|
||||
extensions = [ "rust-src" "clippy" "rustfmt" ];
|
||||
};
|
||||
|
||||
# Nightly Rust for eBPF compilation (when on Linux)
|
||||
rustNightly = pkgs.rust-bin.nightly.latest.default.override {
|
||||
extensions = [ "rust-src" ];
|
||||
};
|
||||
|
||||
in
|
||||
{
|
||||
devShells.default = pkgs.mkShell {
|
||||
buildInputs = with pkgs; [
|
||||
# Rust toolchains
|
||||
rustToolchain
|
||||
rustNightly
|
||||
|
||||
# Development tools
|
||||
cargo-watch
|
||||
cargo-edit
|
||||
cargo-audit
|
||||
cargo-deny
|
||||
cargo-expand
|
||||
|
||||
# System tools
|
||||
git
|
||||
curl
|
||||
wget
|
||||
|
||||
# JSON processing
|
||||
jq
|
||||
|
||||
# Documentation
|
||||
mdbook
|
||||
|
||||
# Testing and CI tools
|
||||
taplo-cli # TOML formatter
|
||||
|
||||
# Additional useful tools
|
||||
fd
|
||||
ripgrep
|
||||
bat
|
||||
eza
|
||||
|
||||
# Optional eBPF tools (available on some platforms)
|
||||
pkg-config
|
||||
|
||||
] ++ lib.optionals stdenv.isLinux [
|
||||
# Linux-specific eBPF tools
|
||||
llvm_15
|
||||
clang_15
|
||||
libbpf
|
||||
bpftools
|
||||
iproute2
|
||||
nettools
|
||||
tcpdump
|
||||
strace
|
||||
ltrace
|
||||
gdb
|
||||
] ++ lib.optionals stdenv.isDarwin [
|
||||
# macOS-specific tools
|
||||
darwin.apple_sdk.frameworks.Security
|
||||
darwin.apple_sdk.frameworks.CoreFoundation
|
||||
];
|
||||
|
||||
shellHook = ''
|
||||
echo "🦀 Aya eBPF Development Environment"
|
||||
echo "=================================="
|
||||
echo
|
||||
echo "Available Rust toolchains:"
|
||||
echo " - Stable: $(rustc --version)"
|
||||
echo " - Nightly: $(rustc +nightly --version 2>/dev/null || echo 'Available for eBPF targets')"
|
||||
echo
|
||||
echo "Traffic Monitor:"
|
||||
echo " cd traffic-monitor"
|
||||
echo " cargo build --release"
|
||||
echo " cargo run --example macos-demo # Demo on macOS"
|
||||
echo " cargo test # Run tests"
|
||||
echo
|
||||
echo "System info:"
|
||||
echo " OS: $(uname -s)"
|
||||
echo " Arch: $(uname -m)"
|
||||
echo
|
||||
|
||||
# Set up environment variables for development
|
||||
export RUST_BACKTRACE="1"
|
||||
export RUST_LOG="debug"
|
||||
|
||||
# Add cargo tools to PATH if not already there
|
||||
export PATH="$HOME/.cargo/bin:$PATH"
|
||||
|
||||
# Platform-specific setup
|
||||
if [[ "$(uname -s)" == "Linux" ]]; then
|
||||
echo "🐧 Running on Linux - eBPF programs can be loaded!"
|
||||
if command -v ip >/dev/null 2>&1; then
|
||||
echo " Available interfaces: $(ip link show | grep -E '^[0-9]+:' | cut -d: -f2 | tr -d ' ' | head -5 | tr '\n' ' ')"
|
||||
fi
|
||||
# Set up for eBPF compilation
|
||||
export CARGO_TARGET_BPFEL_UNKNOWN_NONE_LINKER="bpf-linker"
|
||||
export CARGO_TARGET_BPFEB_UNKNOWN_NONE_LINKER="bpf-linker"
|
||||
export CARGO_CFG_BPF_TARGET_ARCH="x86_64"
|
||||
else
|
||||
echo "🍎 Running on $(uname -s) - eBPF demo mode available"
|
||||
echo " For full eBPF testing, use a Linux container or VM"
|
||||
fi
|
||||
echo
|
||||
echo "Ready to start developing! 🚀"
|
||||
echo
|
||||
'';
|
||||
};
|
||||
|
||||
# Minimal shell for quick access
|
||||
devShells.minimal = pkgs.mkShell {
|
||||
buildInputs = with pkgs; [
|
||||
rustToolchain
|
||||
pkg-config
|
||||
git
|
||||
jq
|
||||
];
|
||||
shellHook = ''
|
||||
echo "🦀 Minimal Rust environment for Aya"
|
||||
'';
|
||||
};
|
||||
}
|
||||
);
|
||||
}
|
||||
@ -0,0 +1,33 @@
|
||||
[package]
|
||||
name = "traffic-monitor"
|
||||
version = "0.1.0"
|
||||
edition = "2021"
|
||||
|
||||
[[bin]]
|
||||
name = "traffic-monitor"
|
||||
path = "src/main.rs"
|
||||
|
||||
[dependencies]
|
||||
aya = { path = "../aya", features = ["async_tokio"] }
|
||||
aya-log = { path = "../aya-log" }
|
||||
clap = { version = "4.0", features = ["derive"] }
|
||||
env_logger = "0.11"
|
||||
log = "0.4"
|
||||
tokio = { version = "1.0", features = ["macros", "rt", "rt-multi-thread", "signal"] }
|
||||
anyhow = "1.0"
|
||||
serde = { version = "1.0", features = ["derive"] }
|
||||
serde_json = "1.0"
|
||||
cidr = "0.2"
|
||||
ipnet = "2.9"
|
||||
chrono = { version = "0.4", features = ["serde"] }
|
||||
tempfile = "3.0"
|
||||
|
||||
[build-dependencies]
|
||||
aya-build = { path = "../aya-build" }
|
||||
|
||||
[workspace]
|
||||
members = []
|
||||
|
||||
[[example]]
|
||||
name = "test-traffic"
|
||||
path = "examples/test-traffic.rs"
|
||||
@ -0,0 +1,8 @@
|
||||
use aya_build::EbpfBuilder;
|
||||
|
||||
fn main() {
|
||||
EbpfBuilder::new()
|
||||
.file("src/traffic_monitor.bpf.rs")
|
||||
.build()
|
||||
.unwrap();
|
||||
}
|
||||
Loading…
Reference in New Issue