Cheatsheet for setting up a WireGuard client on a Mac

WireGuard is a virtual private network (VPN) that works well for mobile users. It takes care of keeping users connected while they are roaming and makes sure that the network connection between peers stays secure even as IP addresses change.

This walkthrough assumes you are adding a new Mac to an existing WireGuard network. Because of this, there are a few steps that require you to ask and send information to the person who setup the initial network. We will call this person the sysadmin.

Hopefully this will extend the official documentation, so that you won’t hit the same issues I did when getting set up on a Mac. This article from Stavros was also helpful with setup / troubleshooting.

Don’t want to manage WireGuard yourself? Check out our hosted solution: http://hq.network/wireguard

Step 1: Install WireGuard tools

From the Terminal app, install tools using homebrew.

brew install wireguard-tools

This installs both “wg” (main WireGuard utility) and “wq-quick” (used in this tutorial to start/stop WireGuard).

Step 2. Configure your device

1. Create a directory for wireguard configuration files

cd ~/.config/
mkdir wireguard
cd wireguard/

2. Using the wg utility, create your public and private keys

wg genkey | tee privatekey | wg pubkey > publickey

3. Secure the keys

sudo chmod -R og-rwx ~/.config/wireguard/*

4. Copy your public key to your clipboard (you will send this to your sysadmin). Careful, do not share your private key!!!

cat publickey | pbcopy

Step 3: Communicate with your sysadmin

Next, send your public key to the sysadmin and ask for your connection info and peers.

WireGuard assumes that you have a secure channel to exchange keys on. Make sure to exchange these values in person or using an end-to-end encrypted channel. (Matrix, Signal, etc)

Send

• Your public key (from your clipboard)

Ask For

• an internal IP address and port
• the public key, allowed IPs, and endpoint for all the other peers that you want to connect to

Once you exchange that information with your sysadmin, and the sysadmin has added you as a peer for the other clients, it is time for the next step.

Step 4. Setup your configuration file

1. Copy your private key into your clipboard. Do not share this private key with anyone else.

cd ~/.config/wireguard/
cat privatekey | pbcopy

2. Create and open your configuration file. We will use nano in this example, but feel free to use whatever text editor you prefer

nano wg0.conf

3. Add configuration info to you config file

[Interface]
Address = [the IP address assigned by the sysadmin]
PrivateKey = [paste from your clipboard]
ListenPort = [the port assigned by the sysadmin]

[Peer]
PublicKey = [peer 1 public key]
AllowedIPs = [peer 1 IP(s)]
Endpoint = [peer 1 Endpoint]
# This is for if you’re behind a NAT and want the connection to be kept alive.
PersistentKeepalive = 25

[Peer]
PublicKey = [peer 2 public key]
AllowedIPs = [peer 2 IP(s)]
Endpoint = [peer 2 Endpoint]
...

Notes

• You can add as many peers as you need, just keep adding them to the bottom.
• Also, you only need the “PersistentKeepalive” line once. This will intermittently ping that peer, so that you don’t time out when you are behind a NAT (e.g. a firewall that is clearing out IPs when they aren’t actively connected). Without this, you might not receive incoming peer requests.
• If you aren’t familiar with nano, type ctrl-x then y to save and exit. Type ctrl-x then n to exit without saving.

Step 5. Start WireGuard

1. You should now be configured and ready to start up WireGuard.

wg-quick up ~/.config/wireguard/wg0.conf

2. Test that you are connected by pinging a peer by their IP address that you got from the sysadmin.

ping [peer IP]

If you see pings, you are all done, woohoo! Welcome to your new WireGuard connection.

3. To turn WireGuard off

wg-quick down ~/.config/wireguard/wg0.conf

Don’t want to manage WireGuard yourself? Check out our hosted solution: http://hq.network/wireguard