Jump to content

pfSense AdGuardHome With ( DOQ ) !

Rate this topic


Recommended Posts

Look A Here - Look A Here - Well, I am back one more again - spinning those hits that get you thumping and pumping for the tasks ( s ) ahead. You all know " The Time Honored Intro "  - https://www.youtube.com/watch?v=xg5IRsPs5E8  and https://www.youtube.com/watch?v=2u-n__lHhWU sing along -  https://genius.com/Led-zeppelin-good-times-bad-times-lyricshttps://www.youtube.com/watch?v=h1vKOchATXs - dig the vibe https://genius.com/Boogie-down-productions-my-philosophy-lyrics - and the original heart throb as a Surprise Bonus  -  https://www.youtube.com/watch?v=pc_F3PaYgl0

Now, that I have satisfied the full spectrum in time and space of  " The Beats " needed here we go with pfSense AdGuardHome.  See here for basic guide : pfSense AdGuardHome - Now this guide is designed for AdGuardHome on pfSense; however, I am going to modify it so that it is much simpler for you to master. 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 pfSense UNBOUND. However, if you prefer to use your LAN for AdGuardHome DNS as described in tutorial by all means just follow the original guide.

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 pfSense 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 pfSense by the end of this guide / tutorial.

Step 4 - After installation scripts runs, you should be seeing something like below. 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. Go to Services > DNS Resolver > General Settings > Display Custom Options > Custom options

In the Box For " Custom options " enter the following below :

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

Then Go To  System > General Setup > DNS Server Settings > DNS Servers and enter the following below for DNS Servers :

A -
B - ::1

both without any gateway  


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

D - Leave Option " DNS Resolution Behavior " at Default Setting

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 pfSense 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"

D- 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 pfSense 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
web_session_ttl: 720
  - ::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
  - 2606:4700:4700::1002
  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 pfSense 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

The target directory for ACME certificates is actually under /cf/config/acme/. Just browse to directory through Diagnostics > Edit File > Browse >
The open /cf - then open /conf - open up /acme - just open these two files below and copy and paste them into appropriate boxes in the
AdGuardHome WEB GUI. These are the files you will need to copy and paste below :


In order to log into AdGuardHome WEB GUI when it is encrypted
you must move pfSense 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 pfSsense 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.


Services DNS Resolver General Settings.png

AdGuardHome Dark.png



Link to comment
Share on other sites

  • 6 months later...

Thanks for the tutorial.  Some questions though:

1.  Why do we still need pfSense DNS Resolver when Adguard could do that?  It just adds additional latency.  Tried turning unbound off and Adguard still works flawlessly

2.  Having problem with testing upstream DNS.  Keeps getting error as if it can't go through the firewall.  Is there a firewall rule that need to be adjusted?

Link to comment
Share on other sites

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...