November 12, 2021

MacOS TUN device and Zsh completion support

The Wireleap client on MacOS reaches feature parity (except for intercept) of the Linux client with TUN device support, allowing for a “VPN like” experience of tunneling all traffic (both TCP and UDP) on the system through a multiplexed circuit.

Additionally, shell completion on Zsh (MacOS and Linux) is now supported in addition to bash completion.

TUN on MacOS

Multiplexing, UDP and TUN device support landed in wireleap 0.2.0 for Linux, and is now available for MacOS as well. To forward all traffic on a system (both TCP and UDP) through the wireleap connection broker, it is possible to use wireleap tun.

The wireleap tun subcommand will use the bundled wireleap_tun binary (unpacked on wireleap init) to set up a tun device and configure default routes through it so that all traffic from the local system goes through the tun device, effectively meaning that it is routed through the currently used wireleap broker circuit.

Note: wireleap_tun needs sufficient privileges to create a tun device and manage routes during the lifetime of the daemon, hence the suid bit. Alternatively, wireleap tun commands can be run with sudo or su (as root).

# set suid bit
sudo chown 0:0 $HOME/wireleap/wireleap_tun
sudo chmod u+s $HOME/wireleap/wireleap_tun
# start the wireleap broker (required for tun)
wireleap start

# setup tun device, configure routes, and verify its running
wireleap tun start
wireleap tun status

# show the log (eg. $HOME/wireleap/wireleap_tun.log)
wireleap tun log

# (at some later time) stop the wireleap tun daemon
wireleap tun stop

Note: Potential MacOS firewall issues

If the MacOS built-in application firewall is enabled, it can interfere with wireleap tun, making it fail silently instead of tunneling through the configured circuit.

For more details and how to address the issue, please refer to the documentation.

Note: Developer cannot be verified warning

When first running wireleap on MacOS you might encounter a warning saying “wireleap cannot be opened because the developer cannot be verified” or similar. This is due to Wireleap not yet enrolling in the Apple Developer Program and receiving a certificate to sign the binary.

Please note, that all Wireleap builds have an associated hashfile generated by our build pipeline, used to cryptographically verify its integrity via GPG signature and the corresponding binary via checksum hash.

The verification process is performed automatically when using, and during inline upgrades. Alternatively, you can download the latest release and perform manual verification and installation, or build from source.

Zsh completion

The bash completion support added in the 0.4.0 release has been updated to be compatible with Zsh (on MacOS and Linux) by using the bashcompinit compatibility layer.

To enable completion for all wireleap commands, sub-commands, option flags, as well as exec and config circuit.whitelist, add the following to your $HOME/.zshrc or similar location.

if [ -e "$HOME/wireleap/completion.bash" ]; then
    autoload compinit && compinit
    autoload bashcompinit && bashcompinit
    source "$HOME/wireleap/completion.bash"

Opening a new shell will automatically source the script. Once sourced, hitting TAB will auto-complete…

$ wireleap <TAB>
config      import      intercept   restart     start       tun
exec        info        log         rollback    status      upgrade
help        init        reload      servicekey  stop        version

$ wireleap st<TAB>
start   status   stop

$ wireleap tun <TAB>
log     restart  start    status   stop

$ wireleap exec <TAB>
chromium-browser  firefox           google-chrome
curl              git               surf

$ wireleap config <TAB>
accesskey.use_on_demand  address.tun              contract
address.h2c              circuit.hops             timeout
address.socks            circuit.whitelist

$ wireleap config circuit.whitelist <TAB>
...list of relays


wireleap (0.5.1)

  • Ported wireleap tun functionality to macOS.
  • Updated completion.bash script to be compatible with zsh via bashcompinit on both Linux and macOS.