How to do DNS over HTTPS with macOS

My last post detailed how you set up DNS over HTTPS (DoH) for a client Raspberry Pi. I mentioned that I tried this out first on a Mac, and so I’ve been asked to show how running DoH on macOS works. Here goes.

DNS-over-HTTPS on a Mac via a local DNS proxy
DNS-over-HTTPS on a Mac via a local DNS proxy

Once again, I’ll be using Cloudflare’s cloudflared DNS proxy, installed locally. On a Mac, install it using Homebrew with Cloudflare’s own Tap. This assumes, of course, that you have Homebrew installed — if not, click on this link above to do so. Now open up macOS’ Terminal app and run:

brew install cloudflare/cloudflare/cloudflared
Install cloudflared on a Mac using Homebrew
Install cloud flared with Homebrew

PS. If you’re interested in maintaining your own Homebrew Tap, check out this earlier post.

Now create a cloudflared configuration file as follows:

mkdir /usr/local/etc/cloudflared
nano  /usr/local/etc/cloudflared/config.yaml

When the file is open in the editor, paste in the following config:

proxy-dns: true
Write the cloudflared config file in the nano text editor
Write the cloudflared config file

Once again, I’ve included Cloudflare’s DoH lookup URL and Google’s as the backup. Change them round or replace them entirely, as you prefer. The file itself is created at the default location for cloudflared’s configuration file.

DoH needs cloudflared to run at start up, and the macOS version of the proxy is geared up to make this happen for you. To get it to do so, just run this command:

sudo cloudflared service install
cloudflared can set itself up to run at startup
cloudflared can set itself up to run at startup

This does all the remaining setup you need. Specifically, it creates a macOS launch daemon in /Library/LaunchDaemons and starts it straight away. You can test it now with:

dig @ AA

Note dig should be already installed on you Mac.

We point dig at localhost because that’s where the cloudflared’s service setup code exposes it. So all we need do now is set macOS to issue DNS queries to that address. Go to System Preferences > Network > Advanced > DNS and set your network connection’s primary DNS server’s address to Click on the + button under the DNS Servers: box and enter the IP address in the space provided. Make sure the new address is at the top of the list: if necessary drag the entry up there. 

Specify the system-wide DNS server address in System Preferences
Specify the system-wide DNS server address in System Preferences

Click OK and then, back at the panel’s main page, Apply.

You’ll need to set the DNS server address for every network you use. For example, I happen to have a couple of wireless networks I connect to regularly, so I’ve set the DNS for each to localhost as shown above.

Once again, use dig to test it. This time you don’t need to provide the server address because that’ll be handled by your Mac’s network subsystem:

dig AA

Look for the last section of the output. You should see the query’s DNS server set to

If it doesn’t work, check your config.yaml file’s contents and that you saved your DNS preferences for the WiFi or Ethernet network you’re currently using.

Network location, location, location

The question the inevitably comes at this point is: fine, but how do I use my Pi-Hole at home and my local DNS proxy when I’m elsewhere? Easy — utilise that ‘been around for ages but is little known or used’ macOS feature, network locations.

Pop back to the System Preferences > Network, but this time click on the Location menu at the top and select Edit Locations…. The location Automatic will be selected, so select Duplicate Location from the action menu toward the bottom of the panel:

Create a new, DoH-specific network location
Create a new, DoH-specific network location

When the duplicate comes up, it’ll be selected. Double-click on it to changed its name to, say, Home. Hit Enter and then click Done. You can now edit your WiFi networks’ DNS addresses for your home network’s Pi-Hole. This leaves you with two network locations: Automatic, set up for the local DNS proxy, and Home which accesses DNS via Pi-Hole. You might want to go change Automatic to Away.

Whatever your locations are called, you can switch between them by selecting the one you want from the Location sub-menu which is now available under the main Apple menu:

With extra locations in place, you can select them from the Apple menu
With extra locations in place, you can select them from the Apple menu

Flip between the two and use dig to check DNS queries are being served correctly. Done.