Routing

Arctic accelerates TCP by carrying it through a transparent proxy. Traffic is classified by protocol: TCP takes the accelerated proxy path, and everything else takes the non-TCP tunnel. Within a path, routing rules decide which service and target peer the traffic belongs to.

Traffic Flow Overview

When traffic matches an Arctic route, it is directed based on the target peer and protocol. TCP, the traffic Arctic accelerates, goes to the in-process TProxy engine, which terminates the connection and carries it to the target peer over a tuned, encrypted TCP tunnel. Everything else (UDP, ICMP, and other IP protocols) goes to the in-process IP-tunnel engine, which forwards it to the target over an encrypted per-peer tunnel without acceleration, so non-TCP traffic can follow the same path for convenience.

Both data planes run inside the agent process; there is no separate proxy binary or data-plane config file to manage. Traffic destined for different peers is routed through separate tunnels, keeping peers isolated.

TCP Traffic (TProxy)

TCP traffic uses transparent proxying. The TProxy engine on the entry peer captures the client's TCP connection and opens its own connection to the target peer, relaying data between the two. Running its own connection to the target is what lets Arctic accelerate the flow: instead of one end-to-end TCP connection, the proxy carries the traffic over an optimised connection between the peers, so a long-distance or lossy TCP flow moves more data than it would end to end.

TProxy Benefits

• Acceleration: the proxied connection between peers is optimised to raise throughput on long-distance and lossy links
• Transparency: the original source IP can be preserved (with Transparent Mode)
• Application agnostic: no client modifications needed
• Connection awareness: full TCP state tracking

TProxy Limitations

• TCP only (UDP, ICMP, and other protocols use the tunnel)
• Requires kernel TProxy support
• Adds per-connection proxy state on the entry peer, so the gain shows on sustained flows rather than a single small packet

Transparent Mode

By default, TProxy preserves the source IP only to the exit node. The destination sees the exit node's IP address. When Transparent Mode is enabled on a service, the original source IP is preserved all the way to the destination.

See Transparent Mode for detailed information about how it works, when to use it, and how to configure it.

Non-TCP Traffic (IP Tunnel)

Non-TCP traffic (UDP, ICMP, and other IP protocols) uses encrypted IP tunnels. Packets are captured, encrypted, and sent through the tunnel to the target peer. This path is not accelerated; it exists so you can send non-TCP traffic down the same route as your TCP traffic instead of handling it separately. If you only care about accelerating TCP, you do not need to route non-TCP at all.

IP Tunnel Characteristics

• All protocols: UDP, ICMP, and any IP traffic
• Encryption: all tunneled traffic is encrypted
• Convenience: non-TCP follows the same peer-to-peer path as TCP, so a flow's traffic stays together

IP Tunnel Limitations

• Not accelerated (the proxy and traffic shaping apply to TCP only)
• Does not preserve source IP (masquerade)
• Per-peer routing (not per-connection)

Route Evaluation

Specificity is checked first. Priority only breaks ties between routes that are equally specific.

Specificity Rules

1. MACVLAN interface matches first (most specific)
2. Source + Destination CIDR matches next
3. Source-only CIDR matches
4. Destination-only CIDR matches last

Priority Within a Specificity Level

When two routes are equally specific, the one with the LOWER priority value wins. Lower value means higher priority.

Priority 100: 10.0.0.0/16 -> 192.168.100.0/24  (wins)
Priority 200: 10.0.0.0/16 -> 192.168.100.0/24

Example Evaluation

Given routes:

Traffic from 10.1.2.3 to 192.168.100.50:

1. Matches both route 1 and route 2 by source
2. Route 2 is more specific (10.1.0.0/16 vs 10.0.0.0/8)
3. Route 2 wins -> SVC-B

Traffic from 10.2.3.4 to 192.168.200.50:

1. Matches route 1 by source
2. No better match exists
3. Route 1 wins -> SVC-A

Transport Selection

Traffic is routed based on protocol:

Bandwidth Limiting

Services can have bandwidth limits (QoS):

arctic services create --target-peer PEER_ID --bandwidth-limit 1000

On a TCP service, shaping is part of the acceleration story, not just a cap. Arctic shapes the service's egress to hold the rate at the limit while keeping latency low under load and sharing capacity fairly between connections:

• On a TCP service, the full shaper runs on the TProxy path: it keeps latency low when the link is busy and shares capacity fairly across connections
• On a KCP service, the limit is a bandwidth ceiling in both directions, without fair queueing or latency control
• Measured in Mbps (megabits per second)

MACVLAN Interfaces

When --requires-interface is set, Arctic creates a dedicated MACVLAN interface for the service. Traffic arriving on that interface is captured and routed by the service, which gives each service its own network isolation and dedicated IPs on the host network.

Use Cases

• Bind applications to specific service interfaces
• Isolate traffic by service
• Assign dedicated IPs per service

Troubleshooting Routing

Wrong Destination

1. Check that the matching route is the most specific one for the traffic.
2. When two routes are equally specific, confirm the intended one has the lower priority value.
3. Verify the route exists with arctic routes list --service SERVICE_ID.

Performance Issues

1. Check bandwidth limits with arctic services get SERVICE_ID.
2. Consider the KCP transport for lossy links, or for short, interactive flows over a high-latency link. A clean, high-latency link carrying a bulk transfer still favours TCP.
3. Monitor agent resource usage.

See Also

• Transparent Mode - Source IP preservation details
• Service Management - How-to guide for configuring routes and bandwidth limits