Skip to content

splittunnel.md

Latest commit

 

History

History
90 lines (61 loc) · 2.63 KB

splittunnel.md

File metadata and controls

90 lines (61 loc) · 2.63 KB

Application Split Tunneling

This tree contains an application split-tunneling implementation for Windows that routes configured applications through WireGuard while leaving other processes on the host path.

Current Model

  • Matching is by absolute executable path.
  • The configuration surface is IncludedApplications in [Interface].
  • Selected applications are redirected to a local split-tunnel proxy.
  • The proxy reconstructs the original destination and opens the outbound connection bound to the WireGuard interface.
  • Unselected applications continue to use ordinary Windows routing.

Configuration Requirements

Split mode is only accepted when all of the following are true:

  • IncludedApplications contains one or more absolute .exe paths.
  • DNS is present in [Interface].
  • the tunnel is full-tunnel for the enabled family, for example AllowedIPs = 0.0.0.0/0
  • Table = off is not used

Example:

[Interface]
PrivateKey = ...
Address = 10.6.0.3/32
DNS = 10.6.0.1
IncludedApplications = C:\Program Files\VideoLAN\VLC\vlc.exe

[Peer]
PublicKey = ...
AllowedIPs = 0.0.0.0/0
Endpoint = example.com:51820
PersistentKeepalive = 25

Components

Split tunneling uses three Windows components:

  • WireGuardTunnel$NAME
  • WireGuardSplitTunnel
  • WireGuardSplitTunnelDriver

The control service speaks to the driver over an internal device interface and to the tunnel service over a named pipe.

Developer Commands

Build and install the driver:

powershell -ExecutionPolicy Bypass -File .\scripts\install-wgsplitdrv.ps1

Install the split-tunnel service:

.\wireguard.exe /installsplittunnelservice

Health and status:

.\wireguard.exe /splittunnelhealth
.\wireguard.exe /splittunnelquery <tunnel-name>
.\wireguard.exe /splittunnelstats <tunnel-name>

Validation Helpers

The repository contains bounded test helpers under scripts\:

  • scripts\test-vlc-split.ps1
  • scripts\inspect-vlc-path.ps1
  • scripts\compare-selected-vs-unselected.ps1

These were used to validate:

  • selected VLC traffic redirected through the proxy and out via the WireGuard address
  • unselected curl.exe traffic remained on the host address
  • nonpaged pool stayed stable during bounded runs

Driver Signing Notes

The local development path uses a test certificate created by the install script. On development machines, Windows may require test-signing mode before a test-signed kernel driver can be loaded.

Safety

If split tunneling is configured and the control service or driver is unavailable, tunnel activation fails closed instead of silently degrading to ordinary full-tunnel behavior.