28
Jun, 2021
Using WireGuard on macOS via the CLI
CloudI’ve written a few different posts on WireGuard, the “simple yet fast and modern VPN” (as described by the WireGuard web site) that aims to supplant tools like IPSec and OpenVPN. My first post on WireGuard showed how to configure WireGuard on Linux, both on the client side as well as on the server side. After that, I followed it up with posts on using the GUI WireGuard app to configure WireGuard on macOS and—most recently—making WireGuard from Homebrew work on an M1-based Mac. In this post, I’m going to take a look at using WireGuard on macOS again, but this time via the CLI.
Some of this information is also found in this WireGuard quick start. Here I’ll focus only on using macOS as a WireGuard client, not as a server; refer to the WireGuard docs (or to my earlier post) for information on setting up a WireGuard server. I’ll also assume that you’ve installed WireGuard via Homebrew.
Generating Keys
The first step is to generate the public/private keys you’ll need. If the /usr/local/etc/wireguard (or the /opt/homebrew/etc/wireguard for users on an M1-based Mac) directory doesn’t exist, you’ll need to first create that directory. (It didn’t exist on my system.) Then, from that directory, run these commands:
umask 077
wg genkey | tee privatekey | wg pubkey > publickey
This generates files named privatekey and publickey, the contents of which you’ll use in the configuration of WireGuard. Some tutorials indicate the need to become root or use sudo, but my configuration seems to work fine without either of those.
Setting up a WireGuard Interface
Once you have public/private keys, you’re ready to set up the interface configuration. Note that you’ll also need the public key of the server (peer) system to which you’re connecting.
Create a file named wg0.conf in /usr/local/etc/wireguard (that would be in /opt/homebrew/etc/wireguard for M1-based Macs). The contents of the file should look like this:
[Interface]
PrivateKey = <private-key-generated-earlier>
Address = <vpn-ip-address-for-this-interface> [Peer]
PublicKey = <public-key-for-peer-system>
Endpoint = <public-ip-address>:51280
AllowedIPs = <vpn-ip-address-for-peer-interface>, <additional-cidrs>
PersistentKeepalive = 25
Most of this configuration file is pretty straightforward:
- You’ll need to specify the private key for the local system plus the public key of the peer system.
- Each system will need “VPN IP addresses” that are routable/reachable from each other (I use a /29 CIDR from which I assign peer VPN IP addresses). The VPN IP addresses do not have to be publicly routable (they can be RFC 1918 ranges), but they should not overlap other IP address ranges—otherwise you’ll run into routing table issues.
- For the
AllowedIPssetting, you need to specify the VPN IP address of the peer plus any additional networks that are reachable via the peer. In my case, I use WireGuard to access private EC2 instances in an AWS VPC, so I specify the VPC CIDR here.
The peer system will have/need a similar configuration. As described here, my primary use case is enabling connectivity to EC2 instances with private IP addresses inside a VPC, so the peer system for me is a Linux instance with WireGuard installed and configured.
Activating the VPN
Once you have the WireGuard interface configuration finished, you can activate the VPN connection using wg-quick up wg0 (if you called your configuration file from the previous section something other than wg0.conf, then change the command accordingly). If the peer system is already configured and its interface is up, then the VPN connection should establish automatically and you should be able to start routing traffic through the peer (assuming you specified some additional networks to be routed through the peer).
Use wg-quick down wg0 to take the VPN connection down.
I did see some references to being able to use launchd on macOS to automatically start the WireGuard interface, but I haven’t explored that configuration yet.
Troubleshooting the Connection
If you run into problems getting the connection up and working, here are a few things you can check:
- When specifying
AllowedIPs, make sure to include the VPN interface IP address as well as any additional networks. Failing to include the VPN interface IP address can cause the connection to fail. - Double-check that you’ve specified public and private keys correctly. It’s easy to get these mixed up. Each system’s configuration should reference its own private key and the peer’s public key.
- Make sure you’ve specified the peer’s endpoint correctly.
- Make sure that the traffic is being allowed to reach each system. Double-check firewalls, network access control lists, host-based firewalls, and security groups.
- Make sure the WireGuard interface is up and active on both systems. When troubleshooting connections, it can be easy to forget whether the interface is active or not.
Aside from the location of the configuration files, configuring WireGuard via the CLI using configuration files is very, very similar across systems. The interface configuration shown above is—as far as I’ve been able to tell so far—identical across both macOS and Linux.
I hope this article is helpful. If you have any questions, comments, or corrections, please feel free to contact me. You can reach me on Twitter (DMs are open), or hit me up on one of a variety of Slack communities. I’d be happy to chat with you.
…
25
Jun, 2021
Installing Older Versions of Kumactl on an M1 Mac
CloudThe Kuma community recently released version 1.2.0 of the open source Kuma service mesh, and along with it a corresponding version of kumactl, the command-line utility for interacting with Kuma. To make it easy for macOS users to get kumactl, the Kuma community maintains a Homebrew formula for the CLI utility. That includes providing M1-native (ARM64) macOS binaries for kumactl. Unfortunately, installing an earlier version of kumactl on an M1-based Mac using Homebrew is somewhat less than ideal. Here’s one way—probably not the only way—to work around some of the challenges.
Note that this post really only applies to users of M1-based Macs; users of Intel-based Macs can extract the kumactl binary from the release archive available linked from the Kuma install docs. (The same goes for users of Linux distributions running on Intel-based hardware.) On the Kuma website, simply select the desired version of Kuma from the drop-down in the upper left, check the page for the direct download link, and off you go. This doesn’t work for M1-based Macs because at the time this post was written, the Kuma community was not providing ARM64 binaries. This leaves Homebrew as the only way (aside from building it yourself from source) to get a native ARM64 binary of kumactl for an M1-based Mac.
There are a couple of things to point out—caveats, if you will—about this workaround before I get into the details.
- It seems (based what I’ve observed regarding Homebrew’s behavior) that the ability to have multiple versions installed via Homebrew relies on what I’m calling “versioned formulas,” like
[email protected](where the version number is embedded in the name of the formula). - Although you can have multiple versions of a formula present on the disk in the correct locations, that doesn’t necessarily mean that Homebrew will recognize them as “installed.”
- Without Homebrew recognizing the packages as “installed,” then using commands like
brew unlinkorbrew linkwill be severely limited. This is particularly impactful in this situation.
With these limitations in mind, let’s look at the workaround I’ve found. It’s based on information from a variety of sources; this one and this one are good examples. It was this GitHub gist, however, that finally got me to success. The approaches that describe using a remote URL failed with a Homebrew error for me (this is using Homebrew 3.2.0).
Here’s the steps that worked for me, based very largely on the referenced GitHub gist:
- Navigate to the directory where the Homebrew formulas are stored. On my M1-based system, that location was
/opt/homebrew/Library/Taps/homebrew/homebrew-core/Formula. You can usebrew --prefixto determine the base location where Homebrew is installed; the rest of the path should be the same. - As it turns out, the directory where Homebrew is installed is a giant Git repository. Thus, we can “roll back” to the state of the repository when the previous version of the formula you want is available. To figure that out for
kumactl, usegit log --follow kumactl.rb. Examine the output to determine the correct Git commit that will get you the desired version. I needed version 1.1.6 ofkumactl, so the Git commit I needed was89b6866. - Run
git checkout -b kumactl-1.1.6 89b6866to create a new branch at that commit hash. - Reinstall the older version with
brew reinstall ./kumactl.rb. - If you have a newer version installed, this command will remove the newer version.
If you only needed to roll back to a previous kumactl version, then you’re good to go. If you need multiple versions, read on. The following steps will help you get multiple copies installed (with some limitations):
- Copy the
/opt/homebrew/Cellar/kumactl/<version>directory to a backup location on disk somewhere. You can replace/opt/homebrewwith$(brew --prefix)if you’re not sure where Homebrew is installed. - Assuming you’re still inside the
/opt/homebrew/Library/Taps/homebrew/homebrew-core/Formuladirectory, rungit checkout masterto switch out of the branch you created earlier in order to install the older version. - Run
brew install kumactlto install the latest version. This will remove the earlier version. - Copy the
<version>directory from step 1 from the backup location to/opt/homebrew/Cellar/kumactl. In my example, this meant I had both a1.1.6and a1.2.0directory in/opt/homebrew/Cellar/kumactl.
You now have multiple versions installed. However, due to the caveats/limitations listed earlier, Homebrew doesn’t recognize both versions as “installed.” This is in spite of the fact that brew info kumactl shows that it recognizes both versions are present on the disk. Since both versions aren’t recognized as “installed,” this means you cannot use brew unlink or brew link to switch between versions. (Some of the articles I found also referenced a brew switch command, which apparently does the same function but appears to have been removed from the latest versions of Homebrew.)
So what to do? Probably the easiest thing to do is this:
ln -s $HOME/bin/kumactl-1.1.6 /opt/homebrew/Cellar/kumactl/1.1.6/bin/kumactl
Replace $HOME/bin with the path of your choice, preferably something already in $PATH. This allows you to run the older version by specifying the binary (via symbolic link) with the version in the name, and running the latest version by just using the binary’s name. It’s not a great solution, but it works.
I hope this (somewhat limited) workaround is useful. There are discussions happening in the Kuma community about what, if anything, the community can do to help solve this problem. Join the Kuma community Slack and have your opinions heard—or, even better, offer to help! In the meantime, feel free to hit me on Twitter if you have any questions, or if you have a better solution to this problem.
…