[Guide] How to run AdGuard Home under OPNsense

Hi! Some people ask on Discord if they can run OPNsense with AdGuard Home, so my answer is YES! In fact, it can be run in OPNsense natively!

1.0 Installation:
Firstly install the Community repo from: OPNsense Repo – Routerperformance
Then install AdGuard Home via Plugins.

Be prepared to lose connection with WAN if you start below setup!

1.1 Go to: System: Settings: General
1.2 Under “Networking” and “DNS” setup your favorite External DNS IPs (it will be used by OPNsense if you break something! I’m using Cloudflare and Quad9 here so 1.1.1.1 and 9.9.9.9)
1.3 Untick “Do not use the local DNS service as a nameserver for this system

Client > AdGuard Home > Unbound > External DNS (Cloudflare, Quad9, NextDNS etc.) Setup
2.1 Go to: Services: Unbound DNS: General
2.2 Change unbound port to other than 53 (In my setup its “53350”)
2.3 Tick “Enable DNSSEC Support”, “Register DHCP leases”, “Register DHCP static mappings”, “Register IPv6 link-local addresses”. Everything else can be unticked.
Local Zone Type: Transparent
Outgoing Network Interfaces: WAN (Your WAN interface or interface group)

2.4 Go to: Services: Unbound DNS: DNS over TLS
2.5 A. Add following (for Cloudflare):

Server IP: 1.1.1.1
Server port: 853
Verify CN: 1dot1dot1dot1.cloudflare-dns.com

2.5 B. Add following (for Cloudflare):

Server IP: 1.0.0.1
Server port: 853
Verify CN: 1dot1dot1dot1.cloudflare-dns.com

ALTERNATIVE:
Add following (for NextDNS)

Server IP: X.X.X.X (your primary dns ip from NextDNS)
Server port: 853
Verify CN: <your-id>.dns.nextdns.io
Server IP: X.X.X.X (your primary dns ip from NextDNS)
Server port: 853
Verify CN: <your-id>.dns.nextdns.io

More public DNS providers you can find here: Known DNS Providers | AdGuard DNS Knowledge Base
2.6 If you use “Dnsmasq” you need to change port to other than 53 (In my setup it’s “5335”)
2.7 Reboot your OPNsense so it will bind Dnsmasq and Unbound to different ports (not necessary, but i had bug where 53 was still “already in use”).

Now you can login back to OPNsense and continue.
3.0 Go to: Services: Adguardhome: General and tick “Enable”, then click Save. You should see green “Play” indicator on top of this page after refresh.
3.1 Now you need to configure AdGuard, navigate to opnsense_ip:3000
3.2 I set Admin interface to my main LAN (192.168.1.1) as the only listen interface and via port 81 (OPNsense uses port 80 and 443 so select something other than this for AdGuard listen port and if you configure AdGuard’s SSL settings)
3.3 DNS Server listen interface select ‘All’ on Port 53.
3.4 Now go to Settings>DNS and set “Upstream DNS servers”, “Bootstrap DNS servers” and “Private reverse DNS servers” to “0.0.0.0:53350”. Click Test (it should show you green notification “Specified DNS servers are working correctly”, then click Apply.

Now you should have working DNS. If you want to check on what IP’s AdGuard listens you can go to http://opnsense_ip:3000/#guide (“Setup Guide” on top of AdGuard WebUI).

If you want to force you OPNsense clients to use AdGuard you need to do following:

Add a new Firewall rule to forward all DNS (Port 53) traffic to AdGuard:
Firewall → NAT → Port Forward

Interface: LAN
Protocol: TCP/UDP
Destination / Invert: Ticked
Destination: LAN address
Destination port range: From: DNS - To: DNS
Redirect target IP: 127.0.0.1
Redirect target port: DNS
Description: Forward DNS to AdGuard
NAT Reflection: Disable

If you have multiple VLANs or LANs then duplicate the rule and change it to the relevant Interface and address.

I found this setup works perfectly with HAProxy (Split DNS (DNS Overrides) Tutorial 2022/08: HAProxy + Let's Encrypt Wildcard Certificates + 100% A+ Rating) and other weird setups like “Bypassing a CGNAT with Wireguard” (GitHub - mochman/Bypass_CGNAT: Wireguard setup to bypass CGNAT with a VPS)
I was trying to use it as Client > Unbound > AdGuard Home > External DNS (Cloudflare, Quad9, NextDNS etc.)

Credits: AdGuard Home setup guide @N0_Klu3

If you still problems you should visit serverbuilds discord! Link: serverbuilds.net
You can also PM me on Discord: Vrozaksen#1360

I forgot to mention something. Sometimes after updating OPNsense, AdGuard loses it’s config (happend 2 times to me). There are backups stored here: “/usr/local/AdGuardHome/” and main config file is: “/usr/local/AdGuardHome/AdGuardHome.yaml”. You can edit this file if you want to change listening port or ip’s.
You should make your own backup using command:
cp /usr/local/AdGuardHome/AdGuardHome.yaml /usr/local/AdGuardHome/AdGuardHome.yaml.bak