Transparent Mode

This article explains Arctic's Transparent Mode feature, which preserves the original source IP address when routing TCP traffic through Pegasus 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:

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

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

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

Pegasus requires the CAP_NET_ADMIN capability:

# If running as systemd service
AmbientCapabilities=CAP_NET_ADMIN

# Or using setcap
setcap 'cap_net_admin+ep' /opt/tillered/bin/pegasus

Comparison with Default Mode

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 (Tempest) and undergoes NAT at the exit node.

Asymmetric Routing

If the destination server routes responses through a different path (not back through Arctic), connections will fail. Transparent Mode requires symmetric routing.

Network Configuration Complexity

Exit nodes require specific kernel settings (loose RPF, IP forwarding) that may conflict with other security policies or network configurations.

Troubleshooting

Source IP Not Preserved

Check service configuration:

arctic services get <service-id>

Verify fully_transparent: true is set.

Check Pegasus configuration:

cat /opt/tillered/pegasus/config.json | jq '.links[] | select(.transparent == true)'

If no links have transparent: true, the service configuration was not applied correctly.

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

Check Pegasus capabilities:

getcap /opt/tillered/bin/pegasus

Should show: cap_net_admin+ep

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 Pegasus 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

Compliance and Logging

When using Transparent Mode for compliance:

• Verify logs capture original source IPs correctly
• Test logging under failure scenarios
• Document the transparent proxying in your architecture diagrams

Performance Impact

Transparent Mode has minimal performance overhead compared to standard TProxy mode:

The primary overhead is the additional socket setup and routing lookup.

See Also

• Transparent Services Tutorial - Step-by-step setup guide
• Routing - General routing concepts
• Architecture - System components
• Create Service - Service configuration guide