Tillered Docs | Transparent Mode

Understanding how Transparent Mode preserves source IP addresses through TProxy tunnels

This article explains Arctic's Transparent Mode feature, which preserves the original source IP address when routing TCP traffic through TProxy tunnels.

What is Transparent Mode?

By default, when Arctic routes traffic between peers, the destination sees the exit node's IP address as the source. Transparent Mode changes this behavior by preserving the original client IP address throughout the entire routing path.

Why Use Transparent Mode?

Transparent Mode is essential when:

Access Control: Destination servers need to see the real client IP for allowlist/denylist enforcement
Logging and Auditing: Security logs must record actual source addresses for compliance
Rate Limiting: Per-client rate limiting requires real source IPs
Geolocation: Applications determine client location based on IP address
Protocol Requirements: Some protocols embed IP addresses in their payload (FTP, SIP)

How It Works

When Transparent Mode is enabled:

Traffic enters through the ingress node's service interface
The ingress node tunnels the traffic to the exit node with a transparency flag
The exit node makes the outbound connection using the original source IP
Response traffic returns through the same path

The client's original IP (e.g., 10.1.0.50) is preserved through the ingress node and exit node so the destination sees the real source address (10.1.0.50).

This requires special kernel configuration on exit nodes to allow binding to non-local IP addresses.

Configuration

Enabling Transparent Mode

Set the FullyTransparent field when creating a service:

arctic services create \
  --target-peer 01HXYZDEF789... \
  --transport tcp \
  --fully-transparent \
  --requires-interface

curl -X POST http://localhost:8080/v1/services \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "target_peer_id": "01HXYZDEF789...",
    "transport_type": "tcp",
    "fully_transparent": true,
    "requires_interface": true
  }'

Service Requirements

Transparent Mode requires:

transport_type: "tcp" - Only TCP traffic is supported
requires_interface: true - MACVLAN interface for traffic isolation

Prerequisites

System Configuration

Exit nodes must be configured with specific kernel settings:

1. IP Forwarding

IP forwarding must be enabled:

sysctl -w net.ipv4.ip_forward=1
echo "net.ipv4.ip_forward=1" >> /etc/sysctl.conf

2. Reverse Path Filtering

Reverse path filtering must be set to loose mode on exit nodes:

# Set to loose mode (2) instead of strict mode (1)
sysctl -w net.ipv4.conf.all.rp_filter=2
sysctl -w net.ipv4.conf.default.rp_filter=2

# Apply to the specific interface
sysctl -w net.ipv4.conf.<interface>.rp_filter=2

# Make changes persistent
echo "net.ipv4.conf.all.rp_filter=2" >> /etc/sysctl.conf
echo "net.ipv4.conf.default.rp_filter=2" >> /etc/sysctl.conf

Why? Strict reverse path filtering drops packets with source IPs that don't match the interface's network. With Transparent Mode, packets have source IPs from remote networks, so strict mode would drop them.

3. Capabilities

The TProxy service requires the CAP_NET_ADMIN capability. This is configured automatically when the agent is installed via the systemd service.

Comparison with Default Mode

Aspect	Default Mode	Transparent Mode
Source IP at destination	Exit node's IP	Original client IP
System requirements	None	RPF loose mode, IP forwarding
Protocol support	TCP	TCP only
Use case	General proxying	Source IP preservation

Use Cases

Web Application Logs

When running a web application behind Arctic:

Without Transparent Mode:

10.2.0.10 - - [10/Dec/2025:14:30:45] "GET /api/users HTTP/1.1" 200

All requests appear to come from the exit node.

With Transparent Mode:

10.1.0.50 - - [10/Dec/2025:14:30:45] "GET /api/users HTTP/1.1" 200
192.168.5.100 - - [10/Dec/2025:14:30:47] "GET /api/users HTTP/1.1" 200

Logs show actual client IP addresses.

IP-Based Access Control

Applications using IP allowlists/denylists can enforce policies based on real client IPs:

# nginx configuration
location /admin {
    allow 10.1.0.0/24;
    deny all;
}

This works correctly with Transparent Mode but would fail with default mode.

Rate Limiting

Per-client rate limiting based on IP address:

# Rate limiter sees actual client IP
@rate_limit(requests=100, per=timedelta(minutes=1), key=lambda: request.remote_addr)
def api_endpoint():
    return {"status": "ok"}

Without Transparent Mode, all requests appear to come from the exit node and share the same rate limit.

Limitations

Non-TCP Traffic

Transparent Mode only works for TCP traffic. Non-TCP traffic (UDP, ICMP) goes through the IP tunnel and undergoes NAT at the exit node. TCP traffic uses TProxy with Transparent Mode and the destination sees the original IP. UDP/ICMP traffic uses the IP tunnel with NAT applied and the destination sees the exit node IP.

arctic services get <service-id>

Verify fully_transparent: true is set.

Check kernel settings:

# Verify IP forwarding
sysctl net.ipv4.ip_forward

# Verify reverse path filtering
sysctl net.ipv4.conf.all.rp_filter

Both must be correctly configured on the exit node.

Connection Timeouts

Verify the agent service is running and has the required capabilities:

systemctl status arctic

Packets Dropped

Check reverse path filtering:

# View current settings
sysctl -a | grep rp_filter

# Check packet drops
netstat -s | grep -i reverse

If packets are being dropped due to RPF, set all interfaces to loose mode (2).

Security Considerations

Source IP Spoofing

Transparent Mode allows binding to arbitrary source IP addresses. Ensure:

Only trusted peers can connect to your Arctic cluster
License-based authentication is enforced
Firewall rules prevent unauthorized access to TProxy ports

Reverse Path Filtering

Setting RPF to loose mode (2) reduces protection against IP spoofing. Mitigate this by:

Using strict firewall rules on ingress
Deploying Arctic in trusted network segments
Monitoring for unusual traffic patterns

Transparent Mode