Getting started on macOS

Table of contents

This quickstart guide will walk you through the process of installing the Wireleap client software on macOS, importing accesskeys for the Wireleap Libre network, and getting started.

For more detailed information, please refer to the client documentation.

Installation

# download, verify and install
curl -fsSL https://get.wireleap.com/darwin -o get-wireleap.sh
sh get-wireleap.sh $HOME/wireleap

# add wireleap to your $PATH. if unsure, this should work for most users
sudo ln -s $HOME/wireleap/wireleap /usr/local/bin/wireleap

# start the controller daemon
wireleap start
wireleap status

Tip: Enable shell completion

Command line completion is available for all wireleap commands, sub-commands, option flags, as well as exec and config broker.circuit.whitelist.

Bash: Add the following line to your $HOME/.bashrc or similar location.

[ -e "$HOME/wireleap/completion.bash" ] && source "$HOME/wireleap/completion.bash"

Zsh: 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"
fi

Accesskeys

Libre accesskeys are valid for 24 hours of access. Feel free to generate fresh keys as needed:

# generate and import a new accesskey (valid for 24h)
wireleap accesskeys import https://libre.wireleap.com/accesskeys

Verification test

A simple test to verify wireleap is working is to check your IP address is different to that when using wireleap.

# your IP address
curl https://ifconfig.co

# the IP address of the last relay in the wireleap circuit
wireleap socks start
wireleap exec curl https://ifconfig.co
wireleap socks stop

Routing traffic

Traffic can be routed via wireleap either for specific applications via the SOCKSv5 forwarder, or for all traffic on the system via the TUN forwarder.

Routing specific traffic (SOCKSv5)

# start the socks daemon
wireleap socks start
wireleap socks status

Any application that supports the SOCKSv5 protocol can be configured to route its traffic via the connection broker.

# example configuring an application to use the socks forwarder
curl --proxy socks5h://$(wireleap config forwarders.socks.address) URL

As there is no standard across applications for proxy settings, some wrapper scripts are included.

# list available exec commands
wireleap exec list

# example exec usage
wireleap exec curl URL
wireleap exec git clone URL
wireleap exec firefox [URL]
wireleap exec google-chrome [URL]
wireleap exec chromium-browser [URL]

Routing all traffic (TUN)

All traffic on the system can be tunneled by using the TUN forwarder.

# configure permissions
sudo chown 0:0 $HOME/wireleap/wireleap_tun
sudo chmod u+s $HOME/wireleap/wireleap_tun

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

# all tcp/udp traffic on the system should now be tunneled...

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

Tip: Customize the circuit

The circuit defines which relays will be used to transmit traffic. A circuit is generated by randomly selecting from the available relays.

# trigger new circuit generation
wireleap reload

# display the number of relays to be used in the circuit
wireleap config broker.circuit.hops

# set the number of relays to be used (will auto-generate a new circuit)
wireleap config broker.circuit.hops 3

Additionally, a whitelist may be specified allowing the creation of an exact circuit when coupled with a specific amount of hops, or a more general only use these relays.

# set the number of circuit hops
wireleap config broker.circuit.hops 1

# set a whitelist of relays to use (tip: use <tab> for shell completion)
wireleap config broker.circuit.whitelist "wireleap://relay1.example.com:13499"