Blog Docs Roadmap GitHub
August 18, 2022

Client TUN bypass API

The Wireleap client includes support for TUN in both GNU/Linux and macOS, allowing for a “VPN like” experience of tunneling all traffic (both TCP and UDP) on the system through a multiplexed circuit.

However, at the very least, traffic destined for the first relay in the circuit needs to be excluded from the TUN device routing configuration, otherwise this would result in a blackhole. So, what is needed is for the controller to communicate a list of addresses for exclusion to the TUN daemon, as well as a way to update the list if and when the circuit is changed.

TUN bypass.json

Previously, this was accomplished through a bypass.json file. wireleap_tun would watch the file for writes. The controller would write the bypass list to bypass.json on disk. wireleap_tun would receive the write event, read the file, process the bypass list, and proceed to delete the old routes and setup new routes based on the bypass list.

This worked, but wasn’t ideal. It introduced an OS-specific file watcher library dependency, had a race condition for writes in quick succession, and did not provide a consistent interface between the controller and forwarder.


This release removes the bypass.json file method and fsnotify dependency, and introduces an API instead, having the bypass list changes written directly to wireleap_tun.sock, as well as handling setting IPv6 routes correctly.

GET/stateReturns wireleap_tun state
GET/bypassReturns the current bypass list of IPs
POST/bypassAdds one or more IPs to the bypass list
DELETE/bypassClears the bypass list
# example for debugging purposes
$ curl --unix-socket $HOME/wireleap/wireleap_tun.sock http://localhost/bypass
["", "aa:bb:cc:dd:ee:ff", "", "ff:ee:dd:cc:bb:aa"]

If you’re new to Wireleap and want to try the new client, take it for a spin on Libre, the free Wireleap relay network, powered by the community and supporters of the Wireleap project. It is free to use, provided for the purposes of casual usage, testing, and community feedback.


wireleap (0.6.1)

  • Depends on wireleap/common v0.3.6.

  • wireleap_tun bypass API:

    • wireleap no longer creates/uses bypass.json.
    • bypass list changes are written directly to wireleap_tun.sock.
    • removed dependency on fsnotify/fsnotify in wireleap_tun.
    • wireleap_tun now handles setting IPv6 routes correctly.
    • wireleap_tun IPv6 bind failure workaround applied.
    • tun will no longer start without a configured service contract.
  • API call retry interval changed to 150ms (was 100ms), total wait increased to 15s (was 10s).

  • Wireleap broker state logic improved wrt race conditions.

  • git version now includes + instead of -, marking the extra information at the end of the version number as build info instead of pre-release version suffix as per the semver spec.