🍏 Configure macOS for Secure DNSaaS

Step-by-step guide to configure macOS to use our secure, token-gated DNS-over-HTTPS (DoH) service.

🍏 macOS • Desktop ✅ Verified • Working 🔒 DoH • Token Auth

📋 Overview

macOS does not have native GUI support for DNS-over-HTTPS (DoH) with custom providers. This guide provides two methods to configure your Mac to use our secure DNSaaS service with token-based authentication.


Service Endpoint Authentication
Primary DNS https://dns1.oss.co.za/xxxxx/dns-query Token in URL path
Protocol DNS-over-HTTPS (DoH) • Port 443 • TLS 1.3
macOS Version macOS Ventura 13+ / Sonoma 14+ / Sequoia 15+
⚠️ Important macOS does not have a built-in DoH configuration in System Settings. You must use either the Command Line (dnsdist) method or a Third-Party App.

✅ Prerequisites

💡 Token Format Your token is provided by the DNSaaS administrator. It looks like: token_xxxxxxxxxx

⭐ Method 1: dnsdist (Command Line) Recommended

This method installs a local DNS proxy using dnsdist that forwards all queries to your secure DoH service. It's persistent, secure, and includes fallback to public DNS.

✅ Why This Is Recommended
  • System-wide DNS resolution (all applications use it)
  • Persists across reboots
  • Includes fallback to 1.1.1.1 / 8.8.8.8 if your service is unreachable
  • Supports token authentication natively
  • Can be monitored via web interface

1 Install Homebrew (if not installed)

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2 Install dnsdist

brew install dnsdist

3 Configure dnsdist

Create the configuration file with your token:

sudo mkdir -p /usr/local/etc/dnsdist sudo tee /usr/local/etc/dnsdist/dnsdist.conf << 'EOF' setLocal("127.0.0.1:53") setACL({'127.0.0.0/8'}) local dohServer = newDOHServer("https://dns1.oss.co.za/testclient123/dns-query") dohServer:setPool("dohpool") addAction(AllRule(), PoolAction("dohpool")) addAction(AllRule(), FailAction({newServer("1.1.1.1"), newServer("8.8.8.8")})) webserver("127.0.0.1:8083", "admin:changeme") setWebserverConfig(true) EOF
⚠️ Important Replace token_testclient123 with your actual token in the configuration above.

4 Start dnsdist

sudo brew services start dnsdist

Or run in the foreground for testing:

sudo dnsdist --config /usr/local/etc/dnsdist/dnsdist.conf

5 Configure System DNS

Go to System Settings → Network → select your active connection → Details... → DNS.

Click the + button and add 127.0.0.1 as a DNS server.

Remove any existing DNS servers if they are not needed.

💡 Alternative: Command Line
sudo networksetup -setdnsservers Wi-Fi 127.0.0.1

(Replace Wi-Fi with your interface name if different)

6 Test Your Configuration

dig example.com A

📱 Method 2: Third-Party App (GUI)

If you prefer a graphical interface, several third-party apps support DoH with custom providers.

Option A: dnscrypt-proxy

Installation

brew install dnscrypt-proxy

Configure /usr/local/etc/dnscrypt-proxy.toml with:

server_names = ['dns1.oss.co.za'] [static] [static.'dns1.oss.co.za'] stamp = 'sdns://...'

Option B: AdGuard DNS Client

Installation

Download from the App Store or visit adguard.com.

Configure with your DoH endpoint: https://dns1.oss.co.za/testclient123/dns-query

💡 Other Options
  • Little Snitch - Advanced network monitoring with DNS filtering
  • NextDNS - CLI tool with DoH support
  • Cloudflare WARP - VPN with DoH (limited custom provider support)

🧪 Test Your Configuration

Use these test sites to verify your macOS configuration is working correctly.

Command Line Tests

Command Expected Result
dig example.com ✅ Should return A records
dig zycdjz.com ❌ Should return NXDOMAIN (blocked)
dig malware.testcategory.com ❌ Should return NXDOMAIN (blocked)

Browser Tests

Test Domain Expected Result
https://example.com ✅ Should load normally
http://zycdjz.com ❌ Should show "This site can't be reached"
http://adult.filterdns.net ❌ Should show "This site can't be reached"

DNS Leak Test

Test Domain Expected Result
https://dnsleaktest.com Should show dns1.oss.co.za or 102.220.218.218

🔧 Troubleshooting

❌ "Permission denied" or "Operation not permitted"
  • You need sudo privileges to run dnsdist
  • Check that you have admin access on your Mac
  • Try running commands with sudo prefix
❌ dnsdist not starting
  • Check the configuration syntax: dnsdist --check-config
  • View logs: sudo brew services log dnsdist
  • Port 53 may be in use: sudo lsof -i :53
❌ "The DNS server isn't responding"
  • Check that dnsdist is running: sudo brew services list | grep dnsdist
  • Verify network connectivity to dns1.oss.co.za
  • Check your token is correct in the dnsdist config
  • Try running dnsdist in the foreground to see errors
✅ Verify It's Working
  • Run dig example.com - should return A records
  • Run dig zycdjz.com - should return NXDOMAIN (blocked)
  • Visit https://dnsleaktest.com - should show your DNS server
  • Check dnsdist statistics: curl -s http://127.0.0.1:8083/metrics

↩️ How to Roll Back

To revert to your previous DNS settings:

Step 1: Stop dnsdist

sudo brew services stop dnsdist

Step 2: Reset DNS Settings

Go to System Settings → Network → select your connection → Details... → DNS.

Remove 127.0.0.1 and add your ISP's DNS servers or set to Automatic.

Or via command line:

sudo networksetup -setdnsservers Wi-Fi Empty

Step 3: Clear DNS Cache

sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

🎯 Summary


🚀 Quick Reference:
https://dns1.oss.co.za/testclient123/dns-query

🍏 macOS DNS Commands:
Install: brew install dnsdist
Start: sudo brew services start dnsdist
Stop: sudo brew services stop dnsdist
Config: /usr/local/etc/dnsdist/dnsdist.conf

DNSaaS • Secure DNS-over-HTTPS with Token Authentication
Endpoint: https://dns1.oss.co.za/xxxxx/dns-query • Port: 443

🍏 macOS • 📅 Last updated: August 2026 • 📧 Support: support@oss.co.za