# Configuring Bauxite Native Tunneling

This guide describes how to configure and deploy **Bauxite Native Dataplane Tunneling** on your edge nodes and cloud gateway proxy. 

Bauxite Native tunneling provides a high-performance, userspace, and zero-kernel-dependency secure tunnel. It integrates directly with the control plane, leveraging WebRTC-ICE/STUN/TURN NAT traversal, dynamic mTLS credentials, and eBPF-driven Quality of Service (QoS) scheduling.

---

## 1. Why Choose Bauxite Native Tunneling?

In highly restricted edge environments, Bauxite Native Tunneling provides key capabilities:
1. **Zero Kernel Dependencies**: Runs completely in userspace on standard Linux systems, avoiding kernel module compilations.
2. **Dynamic NAT Traversal (Zero Public Inbound Ports)**: Instead of exposing static inbound UDP ports on your cloud gateway security group, Bauxite coordinates connectivity via a gRPC signaling server using STUN/TURN/ICE. Connections are established entirely outbound.
3. **Control Plane Integration & Immediate Revocation**: Peer validation uses signed JSON Web Tokens (JWT) issued by the Bauxite Hub. When a node's access is revoked, the tunnel collapses in under 5ms and session keys are zeroized in memory.
4. **eBPF-driven QoS scheduling**: Telemetry, video, and critical control signals are prioritized across the single userspace tunnel. High-throughput data (like video) is throttled under cellular drops to protect critical commands (e.g. `/cmd_vel`).

---

## 2. Configuration on Edge Nodes

To enable native tunneling, modify the `[tunnel]` section of your local Bauxite configuration file (e.g., `/etc/bauxite/config.toml` or `/root/.bauxite/config.toml`):

```toml
[tunnel]
# Bauxite Native mTLS + ICE tunneling configuration (uses outbound-only NAT hole punching).
# The WebSocket address of the Hub/Control Plane signaling endpoint
signaling_server = "wss://dispatch.bauxite-fleet.internal/api/signaling"

# STUN and TURN server endpoints for P2P NAT hole punching
stun_url = "stun:stun.l.google.com:19302"
turn_url = "turn:dispatch.bauxite-fleet.internal:3478"
turn_user = "bauxite-client"
turn_pass = "secure-turn-key"

# Payload Encryption algorithm. Options: "chacha20-poly1305" (default), "aes256-gcm", "none"
cipher = "chacha20-poly1305"

# Enable kernel-level QoS packet scheduling and prioritization
ebpf_enabled = true
```

Ensure your `[security]` settings point to valid certificates for mTLS negotiation:

```toml
[security]
ca_path = "/etc/bauxite/certs/ca.crt"
cert_path = "/etc/bauxite/certs/agent.crt"
key_path = "/etc/bauxite/certs/agent.key"
```

---

## 3. Multi-Tenant Gateway Namespace Isolation

To secure multi-tenant cloud deployments, we isolate each client/tenant's Bauxite tunnel agent inside its own **Linux Network Namespace (`netns`)** on the cloud gateway. This guarantees that different tenants with overlapping virtual IP subnets cannot intercept or pollute other routing tables.

### 3.1. Provisioning the Tenant Namespace
Create and configure an isolated namespace for a specific client (e.g., `warehouse-zone-4`) using the following gateway setup script:

```bash
#!/usr/bin/env bash
set -euo pipefail

CLIENT_ID="warehouse-zone-4"
NS_NAME="ns_$CLIENT_ID"

echo "[*] Setting up network namespace: $NS_NAME"

# 1. Create the network namespace
sudo ip netns add "$NS_NAME"

# 2. Bring up the loopback interface inside the namespace
sudo ip netns exec "$NS_NAME" ip link set lo up

# 3. Create a virtual ethernet (veth) pair for Nginx-to-Namespace communication
sudo ip link add "veth_$CLIENT_ID" type veth peer name "veth_ns_$CLIENT_ID"
sudo ip link set "veth_ns_$CLIENT_ID" netns "$NS_NAME"

# 4. Assign IP addresses to the veth link
sudo ip addr add 10.42.0.1/24 dev "veth_$CLIENT_ID"
sudo ip link set "veth_$CLIENT_ID" up
sudo ip netns exec "$NS_NAME" ip addr add 10.42.0.2/24 dev "veth_ns_$CLIENT_ID"
sudo ip netns exec "$NS_NAME" ip link set "veth_ns_$CLIENT_ID" up

# 5. Add default routing inside the namespace back to the host gateway
sudo ip netns exec "$NS_NAME" ip route add default via 10.42.0.1
```

### 3.2. Running the Gateway Agent inside the Namespace
Launch the gateway Bauxite Agent inside the namespace so its virtual network interface and proxy listeners are fully sandboxed:

```bash
sudo ip netns exec "ns_warehouse-zone-4" bauxite run --config /etc/bauxite/gateway_config.toml
```

### 3.3. Reverse Proxy Configuration
Update your gateway reverse proxy (Nginx) to route incoming operator requests to the Bauxite proxy listener inside the specific client namespace:

```nginx
server {
    listen 443 ssl http2;
    server_name warehouse-zone-4.bauxite-fleet.internal;

    # SSL Certificate Configuration
    ssl_certificate /etc/letsencrypt/live/bauxite/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/bauxite/privkey.pem;

    # Operator UI and Telemetry Proxy
    location / {
        # Proxies directly to the gateway agent inside the netns (via veth pair)
        proxy_pass http://10.42.0.2:8080;
        proxy_buffering off;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

---

## 4. Verification and Troubleshooting

Once both the edge and gateway configurations are deployed, verify connectivity and security controls.

### 4.1. Reading Connection Logs
Run the following command to check the edge agent's connection handshake:

```bash
journalctl -u bauxite -f
```

You should see logs validating candidate gathering and direct peer-to-peer mapping:

```
[INFO] bauxite_conduit::network::ice: Initiating ICE candidate gathering
[INFO] bauxite_conduit::network::ice: ICE session state change: CHECKING
[INFO] bauxite_conduit::network::ice: Direct P2P tunnel established successfully (10.42.0.2 -> 10.42.0.1)
[INFO] bauxite_conduit::ebpf: Successfully attached eBPF QoS socket schedulers
```

### 4.2. Testing Revocation (CISO Kill Switch)
To verify that Bauxite's dynamic revocation works correctly:
1. Revoke the edge node credentials on the Control Plane:
   ```bash
   bauxite-dispatch admin revoke-node --id autonomous-warehouse-zone-4
   ```
2. Check the edge agent's logs. The tunnel must collapse immediately:
   ```
   [WARN] bauxite_conduit::network::signaling: Revocation token received from Hub.
   [INFO] bauxite_conduit::network::ice: Collapsing P2P tunnel in response to revocation command.
   [INFO] bauxite_conduit::network::ice: Tunnel closed. 10.42.0.2 route removed.
   [INFO] bauxite_conduit::identity: Overwrote symmetric session key memory with zeroes.
   ```