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 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.
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
- Create a directory for wireguard configuration files
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)
- Your public key (from your clipboard)
- 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
- Copy your private key into your clipboard. Do not share this private key with anyone else.
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
3. Add configuration info to you config file
Address = [the IP address assigned by the sysadmin]
PrivateKey = [paste from your clipboard]
ListenPort = [the port assigned by the sysadmin]
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
PublicKey = [peer 2 public key]
AllowedIPs = [peer 2 IP(s)]
Endpoint = [peer 2 Endpoint]
- 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
yto save and exit. Type
nto exit without saving.
Step 5. Start WireGuard
- 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