Jump to content


Rate this topic


Recommended Posts

Y'all know how I get down by now. " The Intro " is where it is always at  -  https://www.youtube.com/watch?v=YiOgPd18UmQ  - you just may want to glean the wisdom offered herein -  https://genius.com/James-brown-mind-power-lyrics  on to the next entry - https://www.youtube.com/watch?v=t7Csc6l4QLs - yes, I go eclectic and electric -  https://genius.com/Reo-speedwagon-take-it-on-the-run-lyrics -  Surprise Bonus : https://www.youtube.com/watch?v=7pOkpwgOOiI

OK - now that we are rolling - we are going to learn how to install, configure and run OPNsense 21.7 AdGuardHome.  See here for basic guide : https://broadbandforum.co/threads/installing-adguard-home-on-pfsense.205884/ - Now this guide is designed for AdGuardHome on pfSense; however, I am going to modify it for OPNsense. I know that there is a plugin for OPNsense 21.7 AdGuardHome, but I prefer this method as it gives me more control over updates / upgrades and configuration. In addition, this aforementioned guide sets up AdGuardHome on the LAN for DNS. I am going to set up AdGuardHome DNS on both the IPV4 and IPV6 local hosts - which are the default interfaces for OPNsense  UNBOUND.

AdGuardHome works flawlessly with both OpenVPN and WireGuard protocols.
No need for firewall rules or port forwarding with this set up. It works " as is "
right " OUT THE BOX ".

Step 1: Do Not Change the Port of your OPNsense DNS Resolver
To enable rDNS lookups and hostname lookups for devices on your LAN, enable
" DHCP Registration" and " Static DHCP" in DNS Resolver settings.

Step 2: Install these packages below, so that you can install AdGuardHome.

pkg install ca_root_nss
pkg install screen
pkg install nano
pkg install sudo   ## AdGuardHome will not install as service without sudo

Step 3 : Go to this page for auto installation script - the script will download proper package for your architecture.


Using AGH install script is easier and simpler for most users. Just use their Edge builds
as they are most up to date. It will also warn if there is missing dependencies.

curl -s -S -L https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh | sh -s -- -c edge

ATTENTION : I strongly suggest that you watch this video before you begin. Although lengthy - it is very informative and worthwhile. https://www.youtube.com/watch?v=yMcM40ipDlQ Van Tech Corner OpenWRT AdGuard Home. You also will be able to follow this guide much better - as a ( moving ) picture is worth a thousand words. Follow directions carefully - you will have AdGuard Home up and running on OPNsense by the end of this guide / tutorial.

Step 4 - After installation scripts runs, you should be seeing something like below. Post Install Screenshot
Naturally you may see a different IP Address depending on your network interfaces - but you must use the LAN for initial AdGuardHome Configuration
here it is -


Pick out your LAN interface so that you can perform initial configuration of AdGuardHome . Now,  I am going to show you how to use AdGuard Home with UNBOUND. Once again I implore you to look at Van Tech Corner OpenWRT AdGuard Home Video https://www.youtube.com/watch?v=yMcM40ipDlQ
A - Choose LAN Address For Web Interface - Port 8088 / Choose Localhost ( ) For DNS - Change to Port 5353

Step 5 - Now we need to configure UNBOUND for AdGuardHome.  We are going to install https://github.com/mimugmail/opn-repo  OPNsense repo by mimugmail
so that we may be able to add UNBOUND " Custom Options " to OPNsense 21.7.
Install repository following commands below : 

# fetch -o /usr/local/etc/pkg/repos/mimugmail.conf https://www.routerperformance.net/mimugmail.conf
# pkg update
# pkg install os-unboundcustom-maxit

After installing plugin os-unboundcustom-maxit, go to Services > Unbound DNS > Custom Options
in the box enter the following found below :

do-not-query-localhost: no
 name: "."    # Allow all DNS queries
 forward-addr: [email protected]
 forward-addr: ::[email protected]

Then go to System > Settings > General > DNS Servers  and enter the following :
1 -
2 - ::1
  ### both without any gateway 


3 - Remove ( Do Not ) Check
" Allow DNS server list to be overridden by DHCP/PPP on WAN " Option

Step 6 - Making AdGuard Home start on boot :
Special thanks to eoghan2t9 for a start up script for AdGuardHome which works flawlessly.
The script is found here :  https://github.com/AdguardTeam/AdGuardHome/issues/1352   
Some modifications are required for OPNsense 21.7 AdGuardHome. Follow these steps below :

A - # mv /usr/local/etc/rc.d/AdGuardHome /usr/local/etc/rc.d/adguardhome.sh
B - # nano /usr/local/etc/rc.d/adguardhome.sh

C - Delete the contents of the file and fill it with these contents below :


. /etc/rc.subr

command_args="-P ${pidfile} -r -f ${adguardhome_command}"

load_rc_config $name
: ${adguardhome_enable:=yes}

run_rc_command "$1"

Make it executable - I run this command - it works for me:

# chmod 755 /usr/local/etc/rc.d/adguardhome.sh

E - In order to have OPNsense use default start up script ( /usr/local/etc/rc.d/adguardhome.sh )
at boot time you will have to create a boot time start up script for it
in /etc/rc.conf.d/. Not to prolong this - do the following :

# touch /etc/rc.conf.d/adguardhome  - create the needed new file
# nano /etc/rc.conf.d/adguardhome   - in the new file enter the following two lines:


Save and exit / then make the file executable - once again - works for me :

# chmod 755 /etc/rc.conf.d/adguardhome

Step 7 - Configure AdGuardHome via AdGuardHome.yaml for UNBOUND
We will edit the sections listed below :
( a ) dns: ( bind_hosts: )
( b ) upstream_dns:
( c ) bootstrap_dns:
( d ) all_servers:
( e ) filters:

# nano /opt/AdGuardHome/AdGuardHome.yaml

  - ::1
  port: 5353

We will edit the sections listed below
( a ) upstream_dns: ( b ) bootstrap_dns: ( c ) all_servers:

  - quic://dns.adguard.com:784
  - quic://dot-jp.blahdns.com:784
  - quic://dot-fi.blahdns.com:784
  - quic://dot-sg.blahdns.com:784
  - quic://dot-de.blahdns.com:784
  - quic://doh.tiar.app:784
  - quic://dns.emeraldonion.org:8853
  - quic://uk.adhole.org:784
  - quic://de.adhole.org:784
  - quic://sg.adhole.org:784
  - quic://dandelionsprout.asuscomm.com:48582
  - quic://dns.arapurayil.com:784
  - quic://dns.comss.one:784
  - quic://dns.east.comss.one:784
  - tls://getdnsapi.net
  - tls://dns-nyc.aaflalo.me
  - tls://dns.cmrg.net
  - tls://dot.ny.ahadns.net
  - tls://dot.la.ahadns.net
  - tls://dot.chi.ahadns.net
  - tls://ordns.he.net
  - tls://us-east.adhole.org
  - tls://dns.neutopia.org
  - tls://dns.digitale-gesellschaft.ch
  - tls://dot.sb
  - tls://draco.plan9-ns2.com
  upstream_dns_file: ""
  - 2606:4700:4700::1112:853
  - 2606:4700:4700::1002:853
  all_servers: true

Enter the following below for filters :

- enabled: true
  url: https://adguardteam.github.io/AdGuardSDNSFilter/Filters/filter.txt
  name: AdGuard DNS filter
  id: 1
- enabled: true
  url: https://badmojr.github.io/1Hosts/Lite/adblock.txt
  name: 1Hosts (Lite)
  id: 1635566025
- enabled: true
  url: https://raw.githubusercontent.com/durablenapkin/scamblocklist/master/adguard.txt
  name: Scam Blocklist by DurableNapkin
  id: 1625359388
- enabled: true
  url: https://block.energized.pro/basic/formats/hosts.txt
  name: Energized Basic Protection
  id: 1625359389
- enabled: true
  url: https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
  name: https://github.com/StevenBlack/hosts
  id: 1625359390
- enabled: true
  url: https://osint.digitalside.it/Threat-Intel/lists/latestdomains.txt
  name: https://firebog.net/  - OSINT.digitalside.it
  id: 1625359391
- enabled: true
  url: https://v.firebog.net/hosts/Easyprivacy.txt
  name: https://firebog.net/  - EasyPrivacy
  id: 1625359393
- enabled: true
  url: https://raw.githubusercontent.com/anudeepND/whitelist/master/domains/whitelist.txt
  name: https://github.com/anudeepND/whitelist
  id: 1625359392
user_rules: []

After configuring AdGuardHome via AdGuardHome.yaml both of the commands below :

a - # /usr/local/etc/rc.d/adguardhome.sh restart
b - # /usr/local/etc/rc.d/unbound onestart

 Note : The best practice is to reboot your OPNense after configuring AdGuardHome via AdGuardHome.yaml .

Step 8 - I strongly recommend enabled Encryption. With Encryption AdGuard Home admin interface will work over HTTPS, and the DNS server will listen for requests over DNS-over-HTTPS and DNS-over-TLS. For Encryption = Go To Top of AdGuardHome WEB GUI - Settings > Encryption settings the follow instructions
( a ) - enable Encryption - check the Box
( b ) - Fill in full server name such as this example - freedom.babybaby.mywire.org  : https://www.wolffhaven45.com/2017/11/07/intranet-ssl-certificate-for-pfsense-using-lets-encrypt--cloudflare/ - I recommend Dynu ACME LET’S ENCRYPT

( c ) Certificates :
In order to use encryption, you need to provide a valid SSL certificates chain for your domain.
You can get a free certificate on LetsEncrypt.org or you can buy it from one of the trusted Certificate Authorities.
If you follow the tutorial above you can issue yourself a LetsEncrypt Certificate cost free. This is fictional domain.
See here for how to get Dynu Account and Credentials : https://forum.openwrt.org/t/dynu-openwrt-acme-lets-encrypt/110758

Your certificate and key would be in the following format below :


In order to log into AdGuardHome WEB GUI when it is encrypted
you must move OPNsense WEBGUI to a different port than 443 -
You may now log into Encrypted AdGuardHome WEB GUI -
this option is available by entering the following ( from example above ) :

https://freedom.babybaby.mywire.org:443  - with Encryption Enabled

you will see " green padlock " when logging in / your certificate pulls double duty.

say moved FireWall Admin to Port 1443 - you may still log into your OPNsense Encrypted WEBGUI at :


PS - I started this journey in order to learn how to use DNS-over-QUIC, or DoQ.
In full disclosure I exclusively use DNS-over-QUIC upstream servers with AdGuardHome.
Also, I used Encryption for DNS OVER TLS bootstrap servers.
So - the whole damn thing ( my DNS ) is encrypted.
BTW, I certainly will not at all miss having to update the SPKI PIN Keys
for DOT SERVERS in the Stubby yaml configuration file.

Bonus Feature:
For Those Who Care To PIMP Their AdGuardHome WEBGUI
You must install Stylish Addon To Use AdGuardHome Dark Theme
Firefox addon : https://addons.mozilla.org/en-US/firefox/addon/stylish/
Chrome extension : https://tinyurl.com/yntw4wyw

Go here - For Stylish Dark Themes :



You must enter your LAN IP ADDRESS IN " Customize Settings " Box prior to installation
If you enabled Encryption with a valid SSL certificates chain for your domain - then enter
your Full Domain Name in " Customize Settings " Box prior to installation instead of LAN IP.

As per this example, Full Domain Name in 
" Customize Settings " Box  see below :


You may then access AdGuardHome WEBGIU on port 443 - here is example from above :

https://freedom.babybaby.mywire.org:443  - with Encryption Enabled

you will see " green padlock " when logging in / your certificate pulls double duty

Here Is What You Get After Install :
See AdGuardHome Dark Screenshot

When a new AdGuardHome version becomes available on The Edge Channel it will show up
in the WEBGUI. All you need to do in order to stay up to date is press the " update to the latest version "
button on the AdGuardHome WEBGUI page. Easy Peasy.



Unbound DNS General Settings.png

AdGuardHome Dark.png


Link to comment
Share on other sites

  • directnupe changed the title to OPNsense AdGuardHome TOTAL CONTROL MODE ! ( DOQ )

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.

Reply to this topic...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.


  • Create New...