Jump to content

OpenWrt AdGuard Home 101 ( DNSMASQ )

Rate this topic


Recommended Posts

Back here one more again - but as you well know, before we can get to the " get-go " - we must indulge ourselves with the time honored tradition of " The Intro " - check out a Soul Classic - https://www.youtube.com/watch?v=9UTqdGZt2_4 and as always lyrics - https://genius.com/Linda-jones-hypnotized-lyrics - and to keep the Groove flowing at the outset - Bounce - https://www.youtube.com/watch?v=CdvITn5cAVc - for the lyrical - https://genius.com/Martha-reeves-and-the-vandellas-dancing-in-the-street-lyrics / OK - now that the foundation has been laid - let us proceed.

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

Attention : From OG Poster ( brokenpipe )
!!!! It is possible to install AdguardHome under /opt/,
but this directory can grow. Old binaries are moved as
backup after an update. blocklists can become relatively large. It is better
to move AdGuardHome to a USB stick. So it will survive
future OpenWRT updates !!!!
That Means Setup Exroot for your AdGuardHome Install If At All Possible

Here is a great deal on 4gb USB 3.0 Drives -
Made and Shipped In The Good Ole' USA :


YO ! : I strongly suggest that you watch this video before you begin. Although lengthy - it is very informative and worthwhile. 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 OpenWRT by the end of this guide / tutorial. The setup uses DNSMASQ. I will write up a guide / tutorial incorporating Unbound with AdGuard Home in a soon to be released tutorial.

1 - First you will need to get the appropriate AdGuard Home package for your router's architecture. For example, I have WRT3200ACM, WRT32x, Wrt1900ACS V2, WRT1200AC, and NightHawk R7800. All of these have ARMv7 processors. You should find out your architecture before proceeding. Now there is a script on AdGuard Home - found here - https://github.com/AdguardTeam/AdGuardHome. However, I have never been able to get the automatic download and install script to work properly. So, I manually download and install AdGuard Home on OpenWRT, because this method is GUARANTEED ! to work.

In order to find your router's Architecture - go to Luci > Status > 
Overview then under System - on the third line down underneath 
Model ( indicating your router )

You will find your router's Architecture - for the router 
I am currently running for example these are the entries below :

Model     Netgear Nighthawk X4S R7800
Architecture   ARMv7 Processor rev 0 (v7l)
Target Platform   ipq806x/generic

You can also enter command below :

# cat /proc/cpuinfo    

or you can install hwinfo / opkg update && opkg install hwinfo
and issue command below :

# hwinfo         

### this will render all the specs for your router - 
look at the beginning of readout for CPU

2 - There are two channels to download AdGuard Home - Beta and Edge. The consensus on the thread - found here: [HowTo] Running Adguard Home on OpenWrt is to run Edge. As I mentioned earlier, make sure that you download the correct AdGuard Home package for your router's processor. In my case that is the following link - https://static.adguard.com/adguardhome/edge/AdGuardHome_linux_armv7.tar.gz - notice that edge is named in the link.
A - Just copy and paste your correct link in your browser from this section of AdGuard Home - after downloading - you will have AdGuardHome_linux_armv7.tar.gz on your desktop. Create a folder - and use WinRAR, 7Zip, PeaZip or some such file archiver to unzip AdGuardHome_linux_armv7.tar.gz ( remember to choose the proper package for your router ). You will now have a decompressed folder named " AdGuardHome " .

AdguardTeam / AdGuardHome GitHub Home Page Downloads


AdGuard Home Downloads.png

First, Install These Packages To Get Started - The Main One Needed is sudo - otherwise you will
not be able to install AdGuardHome successfully - as always # opkg update

opkg update ; opkg install ca-certificates ca-bundle sudo libustream-mbedtls libustream-openssl libwolfssl libustream-wolfssl luci-ssl px5g-wolfssl wpad-basic-wolfssl luasocket curl libevent2-7 haveged unzip ip-full curl wget libmbedtls12 tar tcpdump-mini bind-tools


3 - Now we are going to use WINSCP, but first we need to create the default proper directory for AdGuard Home installation. Go into SSH shell - enter command :

A - # mkdir -p /opt/
B - After creating directory, fire up WINSCP - open /opt/ directory 
on the right side of the application - then Drag & Drop the AdGuardHome 
decompressed folder from the directory you had it in on your desktop. 
If you know how to use SCP on OpenWRT ( Linux ) you may use 
that method here as well. After closing WINSCP  - then issue this command 
C - #  chmod 755 /opt/AdGuardHome/AdGuardHome   ## and then 
enter next command for installation of AdGuardHome
D - # /opt/AdGuardHome/AdGuardHome -s install

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 -


Major Revision To This Guide / Tutorial
Rationale For Major Revision To This Guide / Tutorial
Read Post # 24 in this thread from mercygroundabyss below :

By using AGH on Port 5353 this routing behavior is put into effect :

Because you are double looking up (  DNS queries - with  AGH on Port 5353 ). 
By making AGH the primary DNS ( meaning AGH on Port 53 ) AGH looks upstream 
for whatever provider you set AGH up with (and uses encrypted DNS and DNSSEC), 
and ( AGH ) looks downstream to DNSMASQ for internal DHCP addresses.

By having DNSMASQ on port 53 and AGH on port 5353 you introduce another 
hop to DNS and repeat effort. Also it doubles the load on your router 
and increases memory use as DNSMASQ forks for every request.

Once again forgive the error and let's move on.

E - After installing AdGuardHome, and Prior to Configuring AdGuardHome via WEBGUI we must
FIRST set up our router properly for AdGuardHome with DNSMASQ on port 5353 .

In order to do so, enter these commands below via SSH :

Modified From Mercygroundabyss AGH Installation 
Script found here :  https://tinyurl.com/2p8n9yt8

## First Move DNSMASQ To Port 5353 - As always you must substitute your actual 
## LAN IP Address where you see the one used in this example - i.e.

1 - uci set [email protected][0].cachesize='1000'
2 - uci set [email protected][0].noresolv='1'
3 - uci add_list [email protected][-1].server=''  ## Substitute Your Actual LAN IP Address
4 - uci set [email protected][0].port='5353'
5 - uci set [email protected][0].rebind_protection='0'

6 - uci -q delete dhcp.lan.dhcp_option
7 - uci -q delete dhcp.lan.dns
8 - uci add_list dhcp.lan.dhcp_option='6,'   ## DHCP option 6: which DNS (Domain Name Server) 
##to include in the IP configuration for name resolution
9 - uci add_list dhcp.lan.dhcp_option='3,'   ##DHCP option 3: default router or last resort gateway for this interface
10 - uci add_list dhcp.lan.dns='::1'   #IPv6 Announced DNS
11 - uci set dhcp.lan.leasetime='24h' #24hr DHCP Leases
12 - uci set [email protected][0].dnsforwardmax=1024  ## Stop your network from crashing due to exceeding DNS Queries Limit

# Configure DNS provider
13 - uci -q delete network.wan.dns
14 - uci set network.wan.dns=''   ## Set WAN IPV4 DNS to Cloudflare

# Configure IPv6 DNS provider
15 - uci -q delete network.wan6.dns
16 - uci set network.wan6.dns='2606:4700:4700::1111 2606:4700:4700::1001'   ## Set WAN IPV6 DNS to Cloudflare 

# Disable peer ISP DNS
17 - uci set network.wan.peerdns="0"
18 - uci set network.wan6.peerdns="0"

##  Save Changes
19 - uci commit dhcp
20 - uci commit network

# Restart Network + DNSMASQ Service to Reflect Changes
21 - /etc/init.d/network restart
22 - /etc/init.d/dnsmasq restart


F - Now - we can configure AdGuardHome via WEBGUI. Enter LAN IP Address in your browser
in this example it is as depicted on my initial installation of AGH
as shown above. You must choose your LAN Address For Web Interface - Port 8080 - and then
Choose LAN Address For DNS - and Leave LAN on Default DNS Port 53

H - Configure AdGuardHome via AdGuardHome.yaml for DNSMASQ

We will edit the sections listed below
( a ) upstream_dns: ( b ) bootstrap_dns: ( c ) all_servers: and ( d ) filters:
( e ) dns: ( bind_hosts:
From mercygroundabyss : Only other gotcha is to manually edit the interfaces (because they will bind to the WAN side for DNS as well - I really should PR that) so manually editing the yaml file once it is up is needed.
Enter the command below and edit file as detailed here :

# nano /opt/AdGuardHome/AdGuardHome.yaml

1 - Enter the following below ( these entries cover dns: ( bind_hosts: ), upstream_dns, 
bootstrap_dns and sets AdGuardHome DNS in parallel mode )

web_session_ttl: 720
  -  # enter your LAN IP ADDRESS HERE
  - ::1
  port: 53

  - 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
  - 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://fdns1.dismail.de
  - tls://dns.neutopia.org
  - tls://dns.digitale-gesellschaft.ch
  upstream_dns_file: ""
  - 2606:4700:4700::1112
  - 2606:4700:4700::1002
  all_servers: true

If you use Encryption - where you enter your own valid SSL certificates chain for your domain
then for bootstrap_dns: entry you may enter something like this below for DOT Bootstrap DNS :

  - 2606:4700:4700::1112:853
  - 2606:4700:4700::1002:853
  all_servers: true

Cloudflare Alternative DNS SERVERS
Two Flavors: (No Malware) & (No Malware or Adult Content

See Here Below : for Families

Above Malware Blocking DNS - if you prefer
Cloudflare Plain DNS then it is :

  - 2606:4700:4700::1111
  - 2606:4700:4700::1001
  all_servers: true

and for Cloudflare Plain DOT Servers using Encryption -
where you enter your own valid SSL certificates chain for your domain

  - 2606:4700:4700::1111:853
  - 2606:4700:4700::1001:853
  all_servers: true
2  - 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: []


3 - From Original Post [HowTo] Running Adguard Home on OpenWrt

Adguard Home Regex:
Those are really good regex rules which already block 50% of all ads/trackers/bots etc.

You have to add the to  
( as per this example - use your actual LAN IP )


Configure Via /opt/AdGuardHome/AdGuardHome.yaml :

nano /opt/AdGuardHome/AdGuardHome.yaml

- https://github.com/mmotti/adguard-home-filters/blob/master/regex.txt

Special thanks to Mercygroundabyss once again for this information below :

The following settings allows AGH to pull 
client info from OpenWRT's DNSMASQ .

Configure Reverse DNS on AGH


/opt/AdGuardHome/AdGuardHome.yaml settings for this feature :

resolve_clients: true
  use_private_ptr_resolvers: true

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

a - # /etc/init.d/AdGuardHome restart
b - # /etc/init.d/dnsmasq restart

I - If encryption is enabled, 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
( 1 ) - enable Encryption - check the Box
( 2 ) - Fill in full server name such as this example -  
freedom.babybaby.mywire.org  from my tutorial below :

( 3 ) 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 my tutorial above you can issue yourself a LetsEncrypt Certificate cost free.Cross referencing my tutorial above your certificate and key would be the following below :


a - /root/.acme.sh/freedom.babybaby.mywire.org/fullchain.cer
b - /root/.acme.sh/freedom.babybaby.mywire.org/freedom.babybaby.mywire.org.key

You have the option to " set the path " ( use a & b above ) or copy and paste them into the appropriate boxes found at the bottom of Encryption settings page.

You must move Luci to different port than 443 see commands below :

c - # nano /etc/config/uhttpd

        list listen_https ''
        list listen_https '[::]:1443'

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.

Since you moved OpenWRT Admin Port to Port 1443 you may still log into your Luci Encrypted WEBGUI at :



In order to get DNSSEC working with AdGuardHome do the following below :
Go into AdGuardHome WEBGUI - then Settings > scroll down to DNS server configuration
Enable EDNS client subnet and Enable DNSSEC. This is all that is required.

Make sure that Upstream DNS Servers in your 
/opt/AdGuardHome/AdGuardHome.yaml file -
( and /or AdGuardHome WEBGUI )
support DNSSSEC. This is because AdGuardHome 
piggybacks on configured DNS Servers 
for DNSSEC Validation.


You can test DNSSEC on AdGuardHome by issuing command:

## you need bind-tools installed to run this command 

dig dnssectest.sidn.nl +dnssec +multi @

So long as you see in the ;; flags: section the ad; entry = ( meaning Authenticated Data )
you are all set and good to go. See example of AdGuardHome ( proxy-dnssec ) DNSSEC in action below :







If you see next to flags: section the ad; entry then you are good to go
see below :

I was going to tackle Unbound on AdGuardHome here but
I think that is best covered in a separate guide.

How To Upgrade Your AdGuardHome Install :

Some claim that you can upgrade from AdGuardHome WEBGUI - it has never worked
for me while running OpenWRT. No need to fear - here is how to upgrade when new EDGE
Version pops up. Hopefully, if you initially Setup Exroot for your AdGuardHome Install
( that means on a USB Stick ) then all you have to do is grab the new
installation by doing exactly what you did when
you first installed AdGuardHome. With Exroot - you do not have to worry about
any space issues - this is why we recommend Exroot to begin with.

1 - Download the correct AdGuard Home package for your router's processor.
2 - Create a folder to extract the archive into - and use WinRAR, 7Zip, PeaZip or 
some such file archiver to unzip AdGuardHome_linux_your_router.tar.gz
3 - You will now have a decompressed folder named " AdGuardHome " .
4 - Then issue this command below :

# /etc/init.d/AdGuardHome stop

5 - Fire up WINSCP - open /opt/ directory on the right side of 
the application - then Drag & Drop the AdGuardHome 
decompressed folder from the directory you had it in on your desktop. 
If you know how to use SCP on OpenWRT ( Linux ) you may use 
that method here as well.

6 - After you drag and drop new AdGuardHome into the /opt/ directory
( overwriting the old installation ) - then enter these commands :

a - # /etc/init.d/AdGuardHome restart
b - # /etc/init.d/dnsmasq restart


You have now upgraded your AdGuardHome Install on OpenWRT.

I was going to tackle Unbound on AdGuardHome here but
I think that is best covered in a separate guide.

Peace Stay Safe and God Bless All Always

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. Special thanks to mercygroundabyss
for his devotion to this project, his time and patience for all with inquiries, and most of all his
kindness and thoroughness in demeanor and practice.
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 :

Themes & Skins for "adguard"


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






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