LumenLink Relay Server

High-performance relay server using eBPF/XDP for 40Gbps+ throughput.

Website: lumenlink.org · Documentation · Roadmap · API: api.lumenlink.org

Status

Current: Foundation implementation with eBPF/XDP structure Next: Compile eBPF program and test packet forwarding

Architecture

┌─────────────┐
│   Client    │
└──────┬──────┘
       │
       ▼
┌─────────────────┐
│  XDP Program    │  ← Kernel space (eBPF)
│  (Packet Proc)  │
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│  User Space    │  ← Rust application
│  (Control)     │
└─────────────────┘

Components

1. eBPF/XDP Program (bpf/lumenlink_xdp.c)

• Kernel-space packet processing
• Token extraction and verification
• Rate limiting
• Packet forwarding
• DDoS protection

2. XDP Forwarder (src/xdp_forwarder.rs)

• Loads and attaches eBPF program
• Manages user destination mappings
• Updates BPF maps
• Metrics collection

3. Metrics (src/metrics.rs)

• Prometheus metrics
• Packet/byte counters
• Latency histograms
• Throughput monitoring

4. Main Server (src/main.rs)

• HTTP server for metrics/health
• XDP relay initialization
• Graceful shutdown

Building

Prerequisites

• Rust 1.70+
• LLVM/Clang 15+ (for eBPF compilation)
• Linux kernel 5.8+ (for XDP support)
• Root privileges (for XDP attachment)

Compile eBPF Program

Option 1: Using build script (recommended)

cd server/relay
chmod +x scripts/build-ebpf.sh
./scripts/build-ebpf.sh

Option 2: Manual compilation

# Install eBPF toolchain
cargo install bpf-linker

# Compile eBPF program
cd server/relay
mkdir -p target/bpfel-unknown-none/release
clang -O2 -target bpf \
    -I /usr/src/linux-headers-$(uname -r)/include \
    -I /usr/src/linux-headers-$(uname -r)/arch/x86/include \
    -c bpf/lumenlink_xdp.c \
    -o target/bpfel-unknown-none/release/lumenlink_xdp.o

For Windows/WSL:

cd server/relay
.\scripts\build-ebpf.ps1

Build Rust Application

cd server/relay
cargo build --release

Running

Requirements

• Root privileges (for XDP attachment)
• Network interface with XDP support
• Pre-compiled eBPF program

Start Server

# Set interface (default: eth0)
export RELAY_INTERFACE=eth0

# Run as root
sudo ./target/release/lumenlink-relay

Health Checks

# Health check
curl http://localhost:9090/health

# Readiness check
curl http://localhost:9090/ready

# Prometheus metrics
curl http://localhost:9090/metrics

Configuration

Environment Variables

• RELAY_INTERFACE: Network interface name (default: eth0)
• RUST_LOG: Log level (default: info)

BPF Maps

• user_map: User ID → Destination mapping (max 100,000 entries)
• rate_limit_map: User ID → Rate limit info (max 100,000 entries)

Performance

Target Metrics

• Throughput: 40Gbps+
• Latency: <1μs per packet (kernel space)
• Packet Rate: 10,000+ packets/second per user
• Concurrent Users: 100,000+

Optimization

• Kernel-space processing (no context switches)
• Zero-copy packet forwarding
• Efficient BPF map lookups
• Rate limiting in kernel

Security

DDoS Protection

• Rate limiting per user (10,000 packets/second)
• Invalid token dropping
• Kernel-space filtering (no user space overhead)

Token Extraction

Current (Placeholder):

• Uses IP ID + source port as token
• Note: This is insecure and should be replaced with proper token extraction

Production:

• Encrypted token in IP options
• Or token in encrypted packet header
• Token verification in kernel space

Testing

# Run unit tests
cargo test

# Test with packet generator
# (requires root and XDP-capable interface)
sudo cargo test --features integration

Deployment

Docker

FROM rust:1.70 as builder
WORKDIR /app
COPY . .
RUN cargo build --release

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y libbpf-dev
COPY --from=builder /app/target/release/lumenlink-relay /usr/local/bin/
CMD ["lumenlink-relay"]

Kubernetes

apiVersion: v1
kind: Pod
metadata:
  name: lumenlink-relay
spec:
  hostNetwork: true
  containers:
  - name: relay
    image: lumenlink/relay:latest
    securityContext:
      privileged: true  # Required for XDP
    env:
    - name: RELAY_INTERFACE
      value: "eth0"

Troubleshooting

XDP Program Fails to Load

• Check kernel version (5.8+ required)
• Verify interface supports XDP
• Ensure eBPF program is compiled correctly
• Check for kernel eBPF restrictions

No Packets Forwarded

• Verify user destinations are set in BPF map
• Check token extraction logic
• Verify interface configuration
• Check rate limiting settings

High CPU Usage

• Monitor BPF map sizes
• Check for map lookup bottlenecks
• Verify rate limiting is working
• Consider reducing map sizes

References

• eBPF/XDP Documentation
• aya-rs Documentation
• XDP Tutorial