OPNsense AdGuardHome TOTAL CONTROL MODE ! ( DOQ )

[directnupe]

Go Here For The Intro and ALL ScreenShots :
https://forums.torguard.net/index.php?/topic/2545-opnsense-adguardhome-total-control-mode-doq/

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.

Code: [Select]

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.

https://github.com/AdguardTeam/AdGuardHome#test-unstable-versions

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.

Code: [Select]

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 - http://192.168.5.10:3000

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 ( 127.0.0.1 ) 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 : 

Code: [Select]

# fetch -o /usr/local/etc/pkg/repos/mimugmail.conf https://www.routerperformance.net/mimugmail.conf
# pkg update
# pkg install os-unboundcustom-maxitAfter installing plugin os-unboundcustom-maxit, go to Services > Unbound DNS > Custom Options
in the box enter the following found below :

Code: [Select]

server:
do-not-query-localhost: no
forward-zone:
 name: "."    # Allow all DNS queries
 forward-addr: 127.0.0.1@5353
 forward-addr: ::1@5353Then go to System > Settings > General > DNS Servers  and enter the following :
1 - 127.0.0.1
2 - ::1  ### both without any gateway 

and

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 :

Code: [Select]

A - # mv /usr/local/etc/rc.d/AdGuardHome /usr/local/etc/rc.d/adguardhome.sh
B - # nano /usr/local/etc/rc.d/adguardhome.shC - Delete the contents of the file and fill it with these contents below :

Code: [Select]

#!/bin/sh

. /etc/rc.subr

name="adguardhome"
rcvar="adguardhome_enable"
adguardhome_user="root"
adguardhome_command="/opt/AdGuardHome/AdGuardHome"
pidfile="/var/run/${name}.pid"
command="/usr/sbin/daemon"
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:

Code: [Select]

# 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 :

Code: [Select]

# 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:
adguardhome_enable="YES"
adguardhome_bootup_run="/usr/local/etc/rc.d/adguardhome.sh"

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

Code: [Select]

# 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

Code: [Select]

dns:
  bind_hosts:
  - 127.0.0.1
  - ::1
  port: 5353
We will edit the sections listed below
( a ) upstream_dns: ( b ) bootstrap_dns: ( c ) all_servers:

Code: [Select]

  upstream_dns:
  - 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: ""
  bootstrap_dns:
  - 1.1.1.2:853
  - 1.0.0.2:853
  - 2606:4700:4700::1112:853
  - 2606:4700:4700::1002:853
  all_servers: true
Enter the following below for filters :

Code: [Select]

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
whitelist_filters:
- 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 :

Code: [Select]

a - # /usr/local/etc/rc.d/adguardhome.sh restart
b - # /usr/local/etc/rc.d/unbound onestart
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 :

Code: [Select]

/var/etc/acme-client/home//freedom.babybaby.mywire.org/fullchain.cer
/var/etc/acme-client/home/freedom.babybaby.mywire.org/freedom.babybaby.mywire.org.key
In order to log into Encrypted AdGuardHome WEB GUI
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 ) :

Code: [Select]

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 :

Code: [Select]

https://freedom.babybaby.mywire.org:1443
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 :
https://userstyles.org/styles/browse?search_terms=adguard&type=false

I use XENORCHISM -

https://userstyles.org/styles/178841/adguard-home-dark-theme

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.

Code: [Select]

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

freedom.babybaby.mywire.org
You may then access AdGuardHome WEBGIU on port 443 - here is example from above :

Code: [Select]

https://freedom.babybaby.mywire.org:443  - with Encryption Enabled
you will see " green padlock " when logging in / your certificate pulls double duty

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.

[sclawrenc]

Thank you directnupe for your helpful guide.  I followed it and I believe I have it working as you intended.   

I noticed AdGuard Home only shows the 127.0.0.1 and ::1 in the top clients and queries.  If I wanted to see the individual clients listed instead, what would I need to do different in your guide?  I tried several things, but just wound up going in circles.   

[danniello]

Hi, as our colleague comments.

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.

 

[longtom]

Thanks for this detailed installation way!
I just used this easy install (in german)https://hoerli.net/opnsense-adguardhome-werbefrei-trackerfrei-und-hinter-einer-guten-firewall/.

[rickygm]

Thanks for this detailed installation way!
I just used this easy install (in german)https://hoerli.net/opnsense-adguardhome-werbefrei-trackerfrei-und-hinter-einer-guten-firewall/.

I am having the same problem, but I think these options are in pfsense and not opnsense.

[rickygm]

any idea how to solve?

[worie]

+1 for not resolving Hostnames when using this setup.
I've tried another guide, which allowed for the resolution of hostnames, but then DNS didn't work on my VLANs most likely due to switching the default unbound port.

I really would like to know, which clients encounter blocked ads and not just localhost.domain.name

[rickygm]

with this setup, it is not possible to resolve the hostname or ip that is accessing the navigation, it is also not possible to configure the policies in adguard home to ip groups.