🔧 Configure OpenWrt for Secure DNSaaS

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

🔧 OpenWrt • Router ✅ Verified • Working 🔒 DoH • Token Auth

📋 Overview

OpenWrt is a Linux-based router firmware that can be configured to use DNS-over-HTTPS (DoH) with custom providers. This guide will help you configure your OpenWrt router 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
OpenWrt Version 22.03+ (with dnsdist or https-dns-proxy support)
💡 OpenWrt vs Other Platforms OpenWrt can run DoH clients directly on the router, providing DNS filtering for all devices on your network without configuring each device individually.
⚠️ Important This guide assumes you have administrative access to your OpenWrt router. Modifying DNS settings incorrectly may cause network connectivity issues.

✅ Prerequisites

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

⭐ Method 1: https-dns-proxy Recommended

This method uses the https-dns-proxy package, which is designed specifically for OpenWrt to forward DNS queries over HTTPS to a DoH server.

✅ Why This Is Recommended
  • Designed specifically for OpenWrt
  • Lightweight and low memory usage
  • Persists across reboots
  • Supports token authentication via URL path
  • Works with all devices on your network

1 Update Package Lists

SSH into your OpenWrt router and update the package lists:

opkg update

2 Install https-dns-proxy

opkg install https-dns-proxy

3 Configure https-dns-proxy

Edit the configuration file:

uci set https-dns-proxy.@https-dns-proxy[0].url='https://dns1.oss.co.za/testclient123/dns-query' uci set https-dns-proxy.@https-dns-proxy[0].fallback_dns='1.1.1.1' uci set https-dns-proxy.@https-dns-proxy[0].bind_port='53' uci commit https-dns-proxy
⚠️ Important Replace token_testclient123 with your actual token in the URL above.

4 Disable dnsmasq DNS Forwarding

Disable dnsmasq from acting as a DNS server (it will still serve DHCP):

uci set dhcp.@dnsmasq[0].port='0' uci commit dhcp /etc/init.d/dnsmasq restart
💡 Why Disable dnsmasq DNS? dnsmasq normally listens on port 53 for DNS queries. https-dns-proxy needs to listen on port 53 to handle DNS queries from clients.

5 Start https-dns-proxy

/etc/init.d/https-dns-proxy enable /etc/init.d/https-dns-proxy start

Check the status:

ps | grep https-dns-proxy

6 Test Your Configuration

From the router command line:

nslookup example.com 127.0.0.1

Or from a client device on your network:

nslookup example.com

🔧 Method 2: dnsdist Alternative

If https-dns-proxy doesn't meet your needs, you can use dnsdist as an alternative.

💡 Note dnsdist requires more flash storage and memory than https-dns-proxy. Use this method if you need more advanced features like load balancing or custom Lua scripting.

1 Install dnsdist

opkg update opkg install dnsdist

2 Configure dnsdist

cat > /etc/dnsdist.conf << 'EOF' setLocal("0.0.0.0:53") setACL({'0.0.0.0/0'}) 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")})) EOF
⚠️ Important Replace token_testclient123 with your actual token in the configuration above.

3 Start dnsdist

/etc/init.d/dnsdist enable /etc/init.d/dnsdist start

🌐 Method 3: LUCI Web Interface GUI

If you prefer using the web interface, you can configure DoH through LUCI.

1 Install https-dns-proxy from LUCI

Log into your OpenWrt web interface (192.168.1.1 by default).

Go to System → Software.

Search for https-dns-proxy and install it.

2 Configure via LUCI

Go to Services → https-dns-proxy.

Enter the following settings:

  • URL: https://dns1.oss.co.za/testclient123/dns-query
  • Fallback DNS: 1.1.1.1
  • Bind port: 53
⚠️ Important Replace token_testclient123 with your actual token in the URL above.

3 Apply Changes

Click Save & Apply.

Restart the service if needed: Services → https-dns-proxy → Start.

🧪 Test Your Configuration

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

Router Command Line Tests

Command Expected Result
nslookup example.com 127.0.0.1 ✅ Should return A records
nslookup zycdjz.com 127.0.0.1 ❌ Should return NXDOMAIN (blocked)
nslookup adult.filterdns.net 127.0.0.1 ❌ Should return NXDOMAIN (blocked)

Client Device Tests

Test Expected Result
nslookup example.com (from any client) ✅ Should return A records
nslookup zycdjz.com (from any client) ❌ Should return NXDOMAIN (blocked)
Visit http://adult.filterdns.net in a browser ❌ 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

❌ "No such package: https-dns-proxy"
  • Your OpenWrt version may not have the package in the default repository
  • Update package lists: opkg update
  • Check if the package is available: opkg list | grep https-dns-proxy
  • Install from the OpenWrt package feed if available
❌ "Cannot connect to DoH server"
  • Check that your router has internet connectivity
  • Verify the URL is correct: https://dns1.oss.co.za/xxxxx/dns-query
  • Check that your token is valid and active
  • Ensure port 443 is not blocked by your ISP
❌ dnsmasq still listening on port 53
  • Verify dnsmasq DNS is disabled: uci get dhcp.@dnsmasq[0].port
  • If it shows 0, dnsmasq is not listening on port 53
  • Check with: netstat -tulpn | grep :53
  • Restart dnsmasq: /etc/init.d/dnsmasq restart
❌ Client devices not using the new DNS
  • DHCP clients may have cached DNS settings
  • Renew DHCP leases: /etc/init.d/dnsmasq reload
  • Restart the DHCP service: /etc/init.d/network restart
  • Reconnect client devices to the network
✅ Verify It's Working
  • Run nslookup example.com 127.0.0.1 - should return A records
  • Run nslookup zycdjz.com 127.0.0.1 - should return NXDOMAIN (blocked)
  • Check https-dns-proxy status: ps | grep https-dns-proxy
  • Visit https://dnsleaktest.com from a client - should show your DNS server

↩️ How to Roll Back

To revert to your previous DNS settings:

Step 1: Stop https-dns-proxy

/etc/init.d/https-dns-proxy stop /etc/init.d/https-dns-proxy disable

Step 2: Restore dnsmasq DNS

uci set dhcp.@dnsmasq[0].port='53' uci commit dhcp /etc/init.d/dnsmasq restart

Step 3: Remove https-dns-proxy (optional)

opkg remove https-dns-proxy

Step 4: Flush DNS Cache on Clients

Reconnect client devices or reboot the router to clear DNS caches.

🎯 Summary


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

🔧 OpenWrt Commands:
Install: opkg install https-dns-proxy
Config: uci set https-dns-proxy.@https-dns-proxy[0].url='...'
Start: /etc/init.d/https-dns-proxy enable && start
Status: ps | grep https-dns-proxy

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

🔧 OpenWrt • 📅 Last updated: August 2026 • 📧 Support: support@oss.co.za