# High-Performance eBPF Datapath

Bauxite leverages Linux eBPF (Extended Berkeley Packet Filter) for userspace-assisted ROS 2 discovery parsing and process monitoring.

## Overview

While Bauxite primarily operates as a userspace data plane for maximum portability, it can optionally load eBPF programs into the Linux kernel to inspect ROS 2 RTPS (Real-Time Publish-Subscribe) traffic and track process execution. This offloads discovery packet parsing and endpoint authorization from the userspace agent.

**Note**: Packet classification into Bauxite's three priority lanes (Critical, Telemetry, Bulk) is performed entirely in userspace by the `DataPlaneScheduler`. The eBPF programs do not participate in priority routing.

## Key Components

### 1. RTPS Discovery Parser (`cgroup_skb`)
The `bauxite_cgroup_egress` program (attached via the `cgroup_skb` classifier) inspects outgoing UDP packets for RTPS magic bytes (`RTPS`). For discovery traffic on ports 7400/7410, it:

- Parses coalesced DDS submessages (DATA, DATA_FRAG, GAP, HEARTBEAT, ACKNACK)
- Validates endpoint entity IDs against a kernel `ENDPOINT_MAP` (keyed by `(PID, EntityID)`)
- Sends raw discovery payloads to userspace via a 1 MB `RingBuf`
- Records fragment authorization state in the `FRAG_MAP` for IP fragment reassembly

Early-exit for loopback (`127.0.0.0/8`) and link-local (`169.254.0.0/16`) traffic — these are handled by IPC bypass via shared memory.

### 2. Process Monitor (`lsm`)
The `bprm_check_security` hook (LSM, kernel ≥ 5.7) fires on every `execve()` and emits a `CitadelEvent::PROCESS` event containing the PID and executable path. This allows the userspace agent to track which processes are sending DDS traffic.

### 3. IPC Bypass (`sk_msg` / `kprobe`)
Two implementations for redirecting local IPC traffic through shared memory instead of the network stack. Both paths share the same SHM pool, BPF maps, and userspace `IpcBypassService`:

| Path | Hook | Kernel Min | Feature | Notification |
| --- | --- | --- | --- | --- |
| `sk_msg_redirect` | `sk_msg` socket filter | 5.15 | `ipc-bypass-skmsg-only` | SHM polling (10 ms interval) |
| `kprobe` (TCP/UDP send) | `kprobe`/`kretprobe` | 4.14 | `ipc-bypass-kprobe-only` | PerfEventArray (immediate) |

**sk_msg fast path**: Attempts `bpf_msg_redirect_map()` to forward messages directly to receiver sockets (~8 µs). Falls back to SHM recording + `SK_DROP` if the sockmap is empty.

**kprobe fallback**: Records metadata to SHM and emits `PerfEvent` notifications. Cannot prevent TX enqueue (fires after packet is queued), which may cause duplicate delivery on kernels < 5.15.

**Important**: `sk_msg` programs cannot emit PerfEvents (missing BPF context pointer), so they rely entirely on SHM polling for slot discovery.

### 4. CitadelEvent Ring Buffer
Bauxite uses the `CitadelEvent` structure (defined in `ebpf/mod.rs`) to transfer kernel-side events to userspace:

| Field | Purpose |
| --- | --- |
| `event_type` | `PROCESS` (1), `DISCOVERY` (2), or `VIOLATION` (3) |
| `pid` | Process ID for process-level events |
| `path` | 256-byte buffer for executable paths (process events) |
| `payload_len` / `payload` | Up to 512 bytes for discovery traffic parsing |
| `entity_id` | 4-byte DDS entity GUID (discovery events) |
| `src_port` / `dst_port` | Port pairs for policy violation events |

### 5. Feature Flags

| Flag | Description |
| --- | --- |
| `ebpf` | Enables the `CitadelManager` (eBPF program lifecycle) — **currently a stub struct** |
| `ebpf-kernel-maps` | Enables kernel BPF map synchronization |
| `ipc-bypass` | Enables the userspace `IpcBypassService` (SKMSG/UDS bypass + SHM watchdog) |
| `ipc-bypass-skmsg-only` | Restricts IPC bypass to SKMSG sockets only |
| `ipc-bypass-kprobe-only` | Restricts IPC bypass to kprobe-based monitoring only |

## SHM Watchdog (Userspace)

> **Note**: The watchdog is **not** part of the eBPF kernel datapath. It resides in the userspace `IpcBypassService` (enabled via the `ipc-bypass` feature flag).

To manage shared memory pool utilization, the `IpcBypassService` runs a watchdog loop:

- **Watchdog Interval**: Defaults to **250ms** (`watchdog_interval_ms: 250`).
- **Purpose**: Monitors SHM pool utilization. At **90%** active slot threshold, the watchdog scans and reclaims stale (deallocated) slots to prevent pool exhaustion.
- **Scope**: Shared memory lifecycle management only — no integration with robot control systems or ROS 2 Nav2.

## Requirements

To use the eBPF datapath, your system must meet the following:
- **OS**: Linux
- **Kernel**: Version 5.15+ for SKMSG IPC bypass; 4.14+ for kprobe bypass; 5.7+ for LSM process monitoring
- **Privileges**: Root or `CAP_NET_ADMIN` / `CAP_SYS_ADMIN`
- **Feature Flag**: Bauxite must be compiled with the `ebpf` feature enabled (enabled by default).

## Current Status

- **Implemented**: eBPF programs (RTPS parser, process monitor, IPC bypass), `CitadelEvent` ring buffer, SHM watchdog
- **Implemented (IPC Bypass)**: Enterprise `EbpfManager` loader (Aya `BpfLoader`), program attachment (kprobe, sk_msg, sock_ops), socket insertion into `IPC_INTERCEPT_SOCKHASH`, dynamic port sync (`DDS_PORT_SET`), PerfEvent consumer loop (kprobe), SHM polling fallback (sk_msg), slot processing, `PacketBypassed` event emission
- **Planned**: Dynamic BPF map synchronization from userspace configuration, automated program lifecycle management, IPv6 support for sk_msg path (kprobe paths complete)