# How-To: Configure XDP Firewall (Rogue Node Annihilation)

This guide explains how to configure, deploy, and verify the Bauxite Express Data Path (XDP) firewall to protect robotic network interfaces from volumetric floods, localized broadcast storms, and spoofed/unauthorized ROS 2 node communications.

---

## 1. Prerequisites

To load the XDP program and interact with kernel maps, Bauxite requires:
1. **OS**: Linux Kernel version 5.8 or higher.
2. **Permissions**: Root privileges (`sudo`) or `CAP_NET_ADMIN` / `CAP_BPF` capabilities granted to the Bauxite binary.
3. **Driver Support**: Most physical drivers (e.g., `ixgbe`, `mlx5`, `e1000e`) support native XDP. For virtual environments (Docker, VMs), Bauxite automatically falls back to Generic XDP (SKB mode).

---

## 2. Configuration

To enable the XDP firewall, update the `[ebpf]` section of your Bauxite configuration file (e.g. `config.toml` or `config.yaml`):

```toml
[ebpf]
# Enable eBPF acceleration features
enabled = true

# Specify the network interface to attach the XDP filter to.
# Leave empty or omit to disable XDP ingress filtering.
xdp_interface = "eth0"
```

Once configured, restart the Bauxite agent. It will automatically load the compiled eBPF binary and hook the XDP program into the designated interface.

---

## 3. Verifying Attachment

Check the Bauxite logs to verify that the program has successfully attached to the network interface:

```bash
journalctl -u bauxite -n 50 --no-pager
```

Look for the following log outputs:
```text
INFO bauxite_agent::services::citadel_loader: Attaching XDP filter to interface: eth0
INFO bauxite_agent::services::citadel_loader: Successfully attached XDP filter to interface eth0
INFO bauxite_agent::services::citadel_loader: Citadel eBPF Data Plane successfully started.
```

Alternatively, query the network interface status using standard iproute2 tools:

```bash
ip link show dev eth0
```

If XDP is attached, the output will display `xdp` or `xdpgeneric`:
```text
2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 xdp/generic ...
```

---

## 4. Sandbox Testing & Validation

To safely verify filtering logic and performance without disrupting the local network, configure an isolated network namespace sandbox on your host.

### 4.1. Setup Isolated Virtual Interfaces

Run the following commands to create a test namespace and virtual ethernet pair:

```bash
# 1. Create a isolated namespace
sudo ip netns add bauxite-test-ns

# 2. Create a virtual ethernet pair (veth)
sudo ip link add dev veth_host type veth peer name veth_ns

# 3. Move the namespace peer into the test namespace
sudo ip link set veth_ns netns bauxite-test-ns

# 4. Configure IP addresses and bring interfaces UP
sudo ip addr add 10.200.0.1/24 dev veth_host
sudo ip link set veth_host up
sudo ip netns exec bauxite-test-ns ip addr add 10.200.0.2/24 dev veth_ns
sudo ip netns exec bauxite-test-ns ip link set veth_ns up
```

Configure Bauxite's config file to bind `xdp_interface = "veth_ns"` inside the namespace.

### 4.2. Functional Verification using Scapy

Use a Scapy script to inject test RTPS packets containing both authorized and unauthorized participant GUID prefixes:

```python
# test_xdp_functional.py
from scapy.all import IP, UDP, Raw, send

# Define GUID prefixes
AUTHORIZED_GUID = b"\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0a\x0b\x0c"
UNAUTHORIZED_GUID = b"\xde\xad\xbe\xef\xca\xfe\xba\xbe\x00\x00\x00\x01"

def build_rtps_packet(guid):
    # Construct standard RTPS header signature ("RTPS" + Protocol Version + Vendor ID + GUID)
    payload = b"RTPS" + b"\x02\x01" + b"\x01\x0f" + guid
    return IP(dst="10.200.0.2")/UDP(sport=7410, dport=7410)/Raw(load=payload)

print("[*] Sending packet with authorized GUID prefix...")
send(build_rtps_packet(AUTHORIZED_GUID), iface="veth_host")

print("[*] Sending packet with unauthorized/spoofed GUID prefix...")
send(build_rtps_packet(UNAUTHORIZED_GUID), iface="veth_host")
```

Verify that the unauthorized packet is immediately dropped by the kernel driver and never reaches userspace listeners.

### 4.3. Performance/Load Verification using `pktgen`

To test line-rate drop capability and confirm zero-allocation mitigation protects host CPU/memory, run the kernel's built-in `pktgen` module:

```bash
# 1. Load the pktgen kernel module
sudo modprobe pktgen

# 2. Configure the transmission thread for veth_host
PG_DEV=/proc/net/pktgen/veth_host
sudo echo "add_device veth_host" > /proc/net/pktgen/kpktgend_0

# 3. Configure high-speed packet flooding settings targeting the namespace interface
sudo echo "count 5000000" > $PG_DEV    # Send 5 million packets
sudo echo "delay 0" > $PG_DEV           # Line-rate speed (no delay)
sudo echo "dst 10.200.0.2" > $PG_DEV
sudo echo "udp_dst_min 7410" > $PG_DEV
sudo echo "udp_dst_max 7410" > $PG_DEV
sudo echo "pkt_size 64" > $PG_DEV

# 4. Start the flood test
sudo echo "start" > /proc/net/pktgen/pgctrl
```

Monitor drop statistics in Bauxite or using bpftool:
```bash
sudo bpftool map dump name DROP_STATS
```
Verify that dropped packets register under reason code `1` (unauthorized GUID) and CPU/RAM usage in the test namespace remains low.