Skip to content

LINUX_SETUP.md

Latest commit

 

History

History
198 lines (151 loc) · 4.59 KB

LINUX_SETUP.md

File metadata and controls

198 lines (151 loc) · 4.59 KB
Raw

IonicTrace Linux Performance Validation Setup

Overview

This guide will help you set up a Linux environment with proper privileges and dependencies for real eBPF and io_uring performance validation.

Option 1: Ubuntu/Debian VM (Recommended for Testing)

VM Requirements

  • Kernel: Linux 5.10+ (for modern eBPF and io_uring features)
  • RAM: Minimum 4GB, Recommended 8GB+
  • CPU: 2+ cores with virtualization support
  • Privileges: Full root access required

Quick VM Setup Commands

# Check kernel version (must be 5.10+)
uname -r

# Install required packages
sudo apt-get update
sudo apt-get install -y \
    clang \
    llvm \
    libbpf-dev \
    linux-headers-$(uname -r) \
    liburing-dev \
    build-essential \
    pkg-config \
    curl

# Install Rust if not already installed
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# Install BPF linker
cargo install bpf-linker

# Verify eBPF support
ls /sys/fs/bpf/
cat /proc/sys/kernel/unprivileged_bpf_disabled

# Verify io_uring support  
cat /proc/sys/kernel/io_uring_disabled

Option 2: Docker Container (For Development)

Privileged Container Setup

# Create privileged container with necessary capabilities
docker run -it --privileged \
    --cap-add=SYS_ADMIN \
    --cap-add=NET_ADMIN \
    --cap-add=BPF \
    -v /lib/modules:/lib/modules:ro \
    -v /usr/src:/usr/src:ro \
    -v /sys/fs/bpf:/sys/fs/bpf \
    ubuntu:22.04

# Inside container - install dependencies
apt-get update && apt-get install -y \
    clang llvm libbpf-dev linux-headers-generic \
    liburing-dev build-essential pkg-config curl

Option 3: Cloud Instance (For Production Testing)

AWS EC2 Setup

  • Instance: t3.medium or larger
  • AMI: Ubuntu 22.04 LTS
  • Security Group: Allow SSH (22) and custom ports for testing
  • IAM: No special permissions needed
  • Storage: 20GB+ EBS volume

Setup Commands (same as VM setup above)

Required Environment Variables

# Add to ~/.bashrc or ~/.profile
export BPF_CLANG=clang
export BPF_CFLAGS="-O2 -g -Wall -Werror"
export CARGO_TARGET_BPF_LINKER=bpf-linker

# For performance testing
export RUST_LOG=info
export RUST_BACKTRACE=1

Network Interface Setup (for XDP testing)

# List available network interfaces
ip link show

# Create test interface (optional)
sudo ip link add veth0 type veth peer name veth1
sudo ip link set veth0 up
sudo ip link set veth1 up
sudo ip addr add 192.168.100.1/24 dev veth0
sudo ip addr add 192.168.100.2/24 dev veth1

Privilege Requirements

Capabilities Needed

  • CAP_BPF - Load eBPF programs
  • CAP_NET_ADMIN - Attach XDP programs to network interfaces
  • CAP_SYS_ADMIN - Access performance counters and advanced features

Grant Capabilities (Alternative to running as root)

# Build IonicTrace first
cargo build --release

# Grant capabilities to the binary
sudo setcap cap_bpf,cap_net_admin,cap_sys_admin+ep target/release/ionic-trace

# Verify capabilities
getcap target/release/ionic-trace

Verification Checklist

Run these commands to verify your setup:

# 1. Kernel version check
uname -r  # Should be 5.10+

# 2. eBPF filesystem
ls -la /sys/fs/bpf/

# 3. BPF syscall availability
grep bpf /proc/kallsyms | head -5

# 4. io_uring support
ls /proc/sys/kernel/io_uring*

# 5. Network interfaces
ip link show

# 6. Compiler toolchain
clang --version
llvm-config --version

# 7. Rust toolchain
cargo --version
rustc --version

# 8. BPF linker
bpf-linker --version

Performance Optimization

For maximum performance testing:

# Disable CPU frequency scaling
sudo cpupower frequency-set --governor performance

# Set CPU affinity (optional)
sudo taskset -c 0-3 ionic-trace

# Increase memory limits
echo 'vm.max_map_count=262144' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

# Enable high-resolution timers
echo 'kernel.timer_migration=0' | sudo tee -a /etc/sysctl.conf

Troubleshooting

Common Issues:

  1. "Permission denied" for eBPF: Run with sudo or grant capabilities
  2. "No such file" for headers: Install linux-headers-$(uname -r)
  3. "io_uring not supported": Upgrade kernel to 5.10+
  4. XDP attach fails: Check network interface exists and is up

Debug Commands:

# Check eBPF program loading
sudo bpftool prog list

# Monitor network interfaces
sudo tcpdump -i any -c 10

# Check io_uring activity
sudo perf trace -e io_uring*

Next Steps

Once setup is complete:

  1. Transfer IonicTrace code to Linux environment
  2. Run cargo build --features="ebpf,uring"
  3. Execute performance validation tests
  4. Compare results against targets