Routing - Mullvad VPN

Mullvad VPN manipulates the system routing table to ensure all traffic flows through the VPN tunnel and to implement split tunneling. The implementation varies by platform.

Overview

Routing management handles:

Default route replacement - Routes all traffic through tunnel
Specific routes - Allows API access and relay connectivity
Split tunneling - Excludes specific applications from tunnel
Route monitoring - Detects and handles external changes

Source: talpid-routing/src/lib.rs

Core Concepts

Route Structure

A route consists of:

pub struct Route {
    node: Node,            // Gateway/interface
    prefix: IpNetwork,     // Destination network
    metric: Option<u32>,   // Route priority
    table_id: u32,         // Routing table (Linux)
    mtu: Option<u32>,      // MTU for route
}

Source: talpid-routing/src/lib.rs:75-83

Node Types

Gateway Node:

Node::new(gateway_ip, "eth0".to_string())

Address-only Node:

Node::address(gateway_ip)

Device-only Node:

Node::device("wg0".to_string())

Source: talpid-routing/src/lib.rs:226-249

Route Destinations

Real Node:

NetNode::RealNode(node)  // Fixed route

Default Node (macOS/Windows):

NetNode::DefaultNode  // Follows current default route

Source: talpid-routing/src/lib.rs:199-210

Windows Routing

Implementation

Uses IP Helper API and routing change notifications: Source: talpid-routing/src/windows/mod.rs

Route Management

Add route:

route_manager.add_route(RequiredRoute::new(prefix, node))?;

Remove route:

route_manager.delete_route(&route)?;

Default Route Handling

Windows monitors default route changes: Detection:

Listens for NotifyRouteChange2 callbacks
Detects new default gateway
Updates symbolic default routes

Source: talpid-routing/src/windows/default_route_monitor.rs Best route selection:

get_best_default_route() -> Option<InterfaceAndGateway>

Returns:

Interface with lowest metric
Gateway IP address
Used to route non-tunnel traffic

Source: talpid-routing/src/windows/get_best_default_route.rs

Split Tunneling (Windows)

Windows implements split tunneling via driver: Architecture:

WFP callout driver intercepts packets
Checks process path against exclusion list
Redirects excluded traffic to alternative interface
Preserves in-tunnel for other traffic

Source: talpid-core/src/split_tunnel/windows/mod.rs Driver communication:

Opens device handle to driver
Sends IOCTLs to configure exclusions
Monitors driver status

Path monitoring:

Watches for excluded executable changes
Updates driver when paths modified
Handles volume mount/unmount events

Source: talpid-core/src/split_tunnel/windows/path_monitor.rs

Linux Routing

Implementation

Uses Netlink (rtnetlink) for routing operations: Source: talpid-routing/src/unix/linux.rs

Routing Tables

Linux uses multiple routing tables: Main table (254):

Default application routes
Tunnel default route

Custom table (e.g. 1984):

Split tunnel routes
Excluded process routes
Selected via fwmark

Source: talpid-core/src/firewall/linux.rs:98-100

Route Operations

Add route:

let route = Route::new(node, prefix)
    .table(table_id)
    .with_mtu(mtu);
route_manager.add_route(route)?;

Route attributes:

RTA_DST - Destination prefix
RTA_GATEWAY - Gateway IP
RTA_OIF - Output interface index
RTA_PRIORITY - Metric
RTA_TABLE - Routing table ID
RTA_METRICS - MTU and other metrics

Source: talpid-routing/src/unix/linux.rs

Default Route Replacement

Tunnel setup replaces default route:

// Remove old default
delete_route(Route::new(old_node, "0.0.0.0/0"))?;

// Add tunnel default  
add_route(Route::new(tunnel_node, "0.0.0.0/0"))?;
add_route(Route::new(tunnel_node, "::/0"))?;

Policy Routing

Linux uses policy routing for split tunneling: IP rules:

# Route marked packets to custom table
ip rule add fwmark 0x6d6f6c65 table 1984

# Default table for unmarked
ip rule add table main

Custom table routes:

# Route to physical interface
ip route add default via 192.168.1.1 dev eth0 table 1984

Split Tunneling (Linux)

cgroup2 Method (Modern)

Primary method using cgroups v2: Source: talpid-core/src/split_tunnel/linux/mod.rs:99-112 Setup:

Create cgroup2 at /sys/fs/cgroup/mullvad-exclusions

let excluded_cgroup = root_cgroup.create_or_open_child("mullvad-exclusions")?;

Add PIDs to cgroup:
```
excluded_cgroup.add_pid(pid)?;
```

nftables matches cgroup:

socket cgroupv2 level 1 {inode_of_excluded_cgroup} mark set 0x6d6f6c65

Source: talpid-core/src/firewall/linux.rs:355-375 How it works:

Processes added to cgroup2
All packets from cgroup get fwmark
Policy routing sends marked packets to custom table
Custom table routes to non-tunnel interface

cgroup2 location: Default: /sys/fs/cgroup Customize: TALPID_CGROUP2_FS=/custom/path Source: docs/README.md:207-210

net_cls Method (Legacy)

Fallback using cgroups v1 net_cls controller: Source: talpid-core/src/split_tunnel/linux/mod.rs:114-124 Setup:

Mount net_cls (if needed):
```
mount -t cgroup -o net_cls none /sys/fs/cgroup/net_cls
```
Customize: TALPID_NET_CLS_MOUNT_DIR=/custom/path

Create cgroup:

let excluded_cgroup = root_cgroup.create_or_open_child("mullvad-exclusions")?;
excluded_cgroup.set_net_cls_id(0xf41)?;

Add PIDs:
```
excluded_cgroup.add_pid(pid)?;
```
nftables matches classid:
```
meta cgroup 0xf41 mark set 0x6d6f6c65
```

Source: talpid-core/src/firewall/linux.rs:376-383 How it works:

Processes added to net_cls cgroup
Packets inherit classid (0xf41)
nftables matches classid
Applies fwmark for routing

Source: docs/README.md:212-214

Firewall Integration

Split tunnel rules in nftables: Mangle chain (mark packets):

chain mangle {
    type route hook output priority mangle; policy accept;
    
    # Mark packets from excluded cgroup
    socket cgroupv2 level 1 {inode} ct mark set 0xf41 mark set 0x6d6f6c65
}

Output chain (allow marked):

chain output {
    type filter hook output priority 0; policy drop;
    
    # Allow marked traffic
    ct mark 0xf41 accept
}

NAT chain (masquerade):

chain nat {
    type nat hook postrouting priority srcnat; policy accept;
    
    # Fix source IP for rerouted packets
    oif != "lo" ct mark 0xf41 masquerade
}

Source: talpid-core/src/firewall/linux.rs:391-495

Connection Tracking

Connection tracking ensures consistency:

# Mark new connections from cgroup
ct mark set 0xf41

# Match established connections
ct mark 0xf41

New connections marked based on cgroup
Subsequent packets match conntrack mark
Survives process exit or cgroup removal

Source: talpid-core/src/firewall/linux.rs:426-441

macOS Routing

Implementation

Uses routing socket and BSD routing APIs: Source: talpid-routing/src/unix/macos/mod.rs

Routing Socket

MacOS communicates via PF_ROUTE socket: Operations:

RTM_ADD - Add route
RTM_DELETE - Delete route
RTM_GET - Query route
RTM_CHANGE - Modify route

Source: talpid-routing/src/unix/macos/routing_socket.rs

Default Route Monitoring

Monitors default route changes: Detection:

let (tx, rx) = watch::channel(DefaultRouteEvent);
start_monitoring(tx)?;

Events:

DefaultRouteAdded - New default gateway
DefaultRouteRemoved - Default gateway removed
DefaultRouteChanged - Gateway IP changed

Source: talpid-routing/src/unix/macos/watch.rs Route parsing:

Reads routing messages from socket
Parses route attributes (dst, gateway, interface)
Identifies default routes (0.0.0.0/0, ::/0)
Resolves MAC address via ARP

Source: talpid-routing/src/unix/macos/default_routes.rs

Split Tunneling (macOS)

MacOS implements split tunneling via PF routing: Mechanism:

Process monitoring tracks excluded apps
PF rules use BPF device filters
Route-to directs traffic to physical interface
Preserves tunnel traffic for other apps

Source: talpid-core/src/split_tunnel/macos/mod.rs PF route-to rule:

pass out quick on utun3 route-to (en0 192.168.1.1) keep state

Matches tunnel interface
Routes to physical interface instead
Bypasses tunnel for excluded processes

Source: talpid-core/src/firewall/macos.rs:755-775 Process identification:

Uses Endpoint Security framework
Monitors process launch/exit
Tracks process tree (parent-child)
Updates exclusions dynamically

Source: talpid-core/src/split_tunnel/macos/process.rs BPF integration:

Attaches BPF program to interface
Filters packets by process
Works with PF rules for routing

Source: talpid-core/src/split_tunnel/macos/bpf.rs

Interface and Gateway Resolution

Gateway includes MAC address:

pub struct Gateway {
    pub ip_address: IpAddr,
    pub mac_address: MacAddress,
}

Required for proper route-to operation. Source: talpid-routing/src/lib.rs:63-70

Android Routing

Implementation

Uses VPN Service API - no direct routing control: Source: talpid-routing/src/unix/android.rs

VPN Service Routing

Configuration:

VpnService.Builder()
    .addRoute("0.0.0.0", 0)    // Route all IPv4
    .addRoute("::", 0)          // Route all IPv6
    .addDisallowedApplication(pkg) // Split tunneling

Behavior:

System handles all routing automatically
Cannot add specific routes
Split tunneling via allowed/disallowed apps

Split Tunneling (Android)

Per-app exclusion:

builder.addDisallowedApplication("com.example.app")

Excluded apps bypass VPN entirely
Use system default routes
Get system DNS

Source: docs/split-tunneling.md:63-73

Route Manager Interface

Initialization

let (route_manager, handle) = RouteManager::new().await?;
tokio::spawn(route_manager.run());

Adding Routes

Simple route:

let route = RequiredRoute::new(
    "10.0.0.0/8".parse()?,
    Node::address(gateway_ip)
);
handle.add_route(route).await?;

With options:

let route = RequiredRoute::new(prefix, node)
    .use_main_table(false)  // Linux: custom table
    .with_mtu(1380);        // Set MTU
handle.add_route(route).await?;

Source: talpid-routing/src/lib.rs:170-196

Removing Routes

handle.delete_route(&route).await?;

Default Route Handling

Routes using DefaultNode update automatically:

let route = RequiredRoute::new(
    api_ip_prefix,
    NetNode::DefaultNode  // Tracks default gateway
);

When system default route changes:

Route manager detects change
Updates all DefaultNode routes
Uses new default gateway

Source: talpid-routing/src/lib.rs:199-210

Common Routing Patterns

Tunnel All Traffic

// Add default routes through tunnel
add_route(RequiredRoute::new("0.0.0.0/0".parse()?, tunnel_node));
add_route(RequiredRoute::new("::/0".parse()?, tunnel_node));

Relay Endpoint Access

// Route relay traffic via default gateway
add_route(RequiredRoute::new(
    relay_ip_prefix,
    NetNode::DefaultNode
));

API Access

// Route API via default gateway  
add_route(RequiredRoute::new(
    api_ip_prefix,
    NetNode::DefaultNode
));

LAN Access

// Private networks via default gateway
for net in ALLOWED_LAN_NETS {
    add_route(RequiredRoute::new(net, NetNode::DefaultNode));
}

MTU Considerations

Routes can specify MTU:

let route = RequiredRoute::new(prefix, node)
    .with_mtu(1380);  // Lower MTU for encapsulation

Why lower MTU:

WireGuard adds ~60 bytes overhead
Prevents fragmentation
Typical: 1420 for tunnel, 1380 for multihop

Source: talpid-routing/src/lib.rs:192-196

Monitoring and Resilience

Route Change Detection

All platforms monitor routing changes: Windows:

NotifyRouteChange2 callbacks
Detects route additions/deletions
Updates symbolic routes

Source: talpid-routing/src/windows/default_route_monitor.rs Linux:

Netlink route notifications
Monitors RTM_NEWROUTE/RTM_DELROUTE
Validates expected routes

Source: talpid-routing/src/unix/linux.rs macOS:

Routing socket messages
Parses RTM_* events
Updates gateway information

Source: talpid-routing/src/unix/macos/watch.rs

Route Restoration

On disconnect:

Remove tunnel default routes
Restore original default gateway
Delete custom routes
Reset routing tables (Linux)

Split Tunneling Summary

Windows

Method: WFP callout driver Granularity: Per executable path How: Driver intercepts and redirects packets

Linux

Method: cgroup2 + nftables (or net_cls fallback) Granularity: Per process (PID) How: Mark packets, policy routing to alternate table

macOS

Method: PF route-to + process monitoring Granularity: Per process tree How: BPF + PF rules route to physical interface

Android

Method: VPN Service disallowed apps Granularity: Per app package How: System bypasses VPN for excluded apps Source: docs/split-tunneling.md

Environment Variables

# Linux: cgroup2 filesystem path
TALPID_CGROUP2_FS=/custom/path

# Linux: net_cls mount directory
TALPID_NET_CLS_MOUNT_DIR=/custom/path

Source: docs/README.md:207-214

Troubleshooting

Routes Not Applied

Check route manager status:

# Linux
ip route show
ip route show table 1984

# macOS  
netstat -rn

# Windows
route print

Split Tunneling Not Working

Linux - Verify cgroup:

# Check cgroup2
ls -la /sys/fs/cgroup/mullvad-exclusions/
cat /sys/fs/cgroup/mullvad-exclusions/cgroup.procs

# Check nftables rules
sudo nft list table inet mullvad

# Check policy routing
ip rule show
ip route show table 1984

macOS - Check PF:

# View PF rules
sudo pfctl -a mullvad -sr

# Check route-to rules
sudo pfctl -a mullvad -sr | grep route-to

Windows - Check driver:

# Verify driver loaded
sc query mullvad-split-tunnel

# Check exclusions
mullvad split-tunnel list

Default Route Issues

Symptoms: No connectivity after tunnel up Diagnosis:

Verify tunnel interface exists
Check default routes point to tunnel
Verify relay route via physical interface
Check firewall allows relay endpoint

Fix: Route manager should auto-correct, or restart daemon

Overview

Components

Connection

System Integration

Documentation Index

​Overview

​Core Concepts

​Route Structure

​Node Types

​Route Destinations

​Windows Routing

​Implementation

​Route Management

​Default Route Handling

​Split Tunneling (Windows)

​Linux Routing

​Implementation

​Routing Tables

​Route Operations

​Default Route Replacement

​Policy Routing

​Split Tunneling (Linux)

​cgroup2 Method (Modern)

​net_cls Method (Legacy)

​Firewall Integration

​Connection Tracking

​macOS Routing

​Implementation

​Routing Socket

​Default Route Monitoring

​Split Tunneling (macOS)

​Interface and Gateway Resolution

​Android Routing

​Implementation

​VPN Service Routing

​Split Tunneling (Android)

​Route Manager Interface

​Initialization

​Adding Routes

​Removing Routes

​Default Route Handling

​Common Routing Patterns

​Tunnel All Traffic

​Relay Endpoint Access

​API Access

​LAN Access

​MTU Considerations

​Monitoring and Resilience

​Route Change Detection

​Route Restoration

​Split Tunneling Summary

​Windows

​Linux

​macOS

​Android

​Environment Variables

​Troubleshooting

​Routes Not Applied

​Split Tunneling Not Working

​Default Route Issues

Build docs developers (and LLMs) love

Overview

Core Concepts

Route Structure

Node Types

Route Destinations

Windows Routing

Implementation

Route Management

Default Route Handling

Split Tunneling (Windows)

Linux Routing

Implementation

Routing Tables

Route Operations

Default Route Replacement

Policy Routing

Split Tunneling (Linux)

cgroup2 Method (Modern)

net_cls Method (Legacy)

Firewall Integration

Connection Tracking

macOS Routing

Implementation

Routing Socket

Default Route Monitoring

Split Tunneling (macOS)

Interface and Gateway Resolution

Android Routing

Implementation

VPN Service Routing

Split Tunneling (Android)

Route Manager Interface

Initialization

Adding Routes

Removing Routes

Default Route Handling

Common Routing Patterns

Tunnel All Traffic

Relay Endpoint Access

API Access

LAN Access

MTU Considerations

Monitoring and Resilience

Route Change Detection

Route Restoration

Split Tunneling Summary

Windows

Linux

macOS

Android

Environment Variables

Troubleshooting

Routes Not Applied

Split Tunneling Not Working

Default Route Issues