Install AdGuard Home on Edgerouter X (including local hostname resoluion using dnsmasq)

Introduction

I used to run a pihole on my home network but recently moved to Adguard Home for simplicity. My pihole ran on a seperate Raspberry Pi board but I never liked this solution, keeping the Pi running just to act as a DNS resolver and blocker. Running it this way creates another point of failure, if the Pi goes down so does access to the internet.

I have since moved to Adguard Home and offloaded this task to my Ubiquiti Edgerouter X. In doing this, I reduce the need for extra hardware and remove a point of failure. If the edgerouter goes down, the internet will be down anyway so it's a non-issue.

My setup

My setup is probably different than your's so substitute settings where needed.

Edgerouter X

• IP: 192.168.1.1
• using dnsmasq instead of the default DHCPD daemon (for local hostname resolution on my lan)

LAN clients

• IP range: 192.168.1.0/24
• local domain: lan (.lan)
• using DHCP for IP assignment (including DNS server assignment)

Instructions

Lets get into the weeds then..

Change to dnsmasq service (optional)

If you want local name resolution on your lan then change over from the default DHCPD setup to dnsmasq. Doing this will also make the Adguard Dashboard easier to read as it will display local client names in addition to IP addresses.

Change the dnsmasq service port number

we need to change the dnsmasq port number to listen on something other than the default 53. This is because we will be running the AdGuard Home service on 53 once installed.

Here I'm using port 5353 but you can use whatever you want, just remember it for the later steps. Login to your edgerouter web interface, go to the config tree tab then click service -> dns -> forwarding. Add an option with port=5353 as the value and apply changes.

Install AdGuard Home

Login to your routers command line interface, via ssh or the CLI button in the web interface. We are going to install the package in our home folder for simplicity. Grab the binary package for Edgerouter X (linux mipsle Softfloat) with the command below. NOTE: If you're using a different Ubiquiti model you might need a different build architecture than used below.

curl -sL https://static.adguard.com/adguardhome/release/AdGuardHome_linux_mipsle_softfloat.tar.gz | tar xvz

Lets test that the binary runs correctly.

cd AdGuardHome
sudo ./AdGuardHome

Open your Edgerouter IP with port 3000 on your browser, http://192.168.1.1:3000 and hopefully be greated with this.

Set your service addresses and ports on the next screen. Change your admin interface to listen to your LAN side only (the one with the internal IP of your edgerouter). We also have to change the admin interface port to something other than 80 because this is what the default EdgeOS web interface uses. I chose to use port 8080. Also change the dns listen interface the the internal interface as well with the default 53 port. You shouldn't have any red interface or port already in use messages!

Finish the steps until you get to the login screen of the dashboard. Now return the the router's command line to stop the service and install it properly. At the command line hit CTRL+C to stop the service, then install it with this command.

sudo ./AdGuardHome -s install

Documentation of the other command switches can be found here if needed.

Everything should be now be installed and running. You can return to the AdGuard web interface by going to your router ip with the port you selected. http://192.168.1.1:8080 in my case.

Reduce AdGuard logs

Edited on May 14 2021: On two occasions I managed to fill the usable space on my Edgerouter device to 100%. Obviously this can cause all kinds of issues, so I've added this section as a remedy. It is highly suggested you do the same and if you have previously installed Adguard without doing this it's best to clear the logs. With just Adguard installed on my ERX with series 1.x firmware I stand at nearly 80% usage with no logs!

Note: you can use the df command on the router CLI to check the space on your / directory.

In the AdGuard web interface on your router, go to settings -> General Settings then under Logs configuration either uncheck enable log or at the very least reduce the query logs retention to a lower value (I recommend 24 hours). You can clear the query logs here as well if needed as mentioned above.

In addition to this I recommend you reduce the statistics retention to a lower value. I have mine set to 24 hours to avoid any future space issues. I'm not sure how much affect this has on space but I rather be safe than sorry.

Set the DHCP server settings

In the router web interface go to the services tab -> DHCP server then actions button -> view details. Add 192.168.1.1 to the DNS 1 setting and lan under the Domain setting.

And you're done, AdGuard should be installed. But wait there's more...

Bonus Round: Setup local hostname resolution, DNS/rDNS/arp lookups

So we have our dnsmasq service still running on port 53 but why? We are going to point our AdGuard service to call upon it for resolving local hostnames on our private LAN only! All other requests will use the other upstream proiders we specify.

Log into our AdGuard Home interface at http://192.168.1.1:8080 and head to settings -> DNS settings. Under upstream DNS servers add the following lines along with the included address or the upstream provider address of your choice.

[/168.192.in-addr.arpa/]192.168.1.1:5353
[/lan/]192.168.1.1:5353

The first line is for reverse DNS (rDNS) lookups. It says DNS requests for names in the 192.168.1.x range should ask our dnsmasq service running at port 5353. The second line states that lookups on our own .lan domain should also use the dnsmasq service running at port 5353. Anything outside this scope should use the other upstream IPs you specified here.

NOTE: More options and information can be found here.

Example localhost resoulution

Let's test our DNS localhost resolution.

If we set our Edgerouters hostname to "router" in the EdgeOS web interface (under system settings at the bottom). We should be able to access it via hostname as well as IP address.

So going to http://router.lan in our browser should now work, also you can try pinging it at the command line. Earlier we specified the domain "lan" under the DHCP settings passed to clients. This will set .lan to be our default DNS domain and you shouldn't need to specify .lan when accessing a device. So going to http://router or pinging router should just work without the .lan suffix. You're welcome!

You can check if you default DNS domain is set in windows clients at the command line with

ipconfig /all

should look something like this..

Because we have set up this local hostname resolution, the Adguard dashboard will show client friendly names instead of just ip addresses.

NOTE: This might not be needed in versions of AdGuard Home greater v0.106.0 as this documentation says "... you can enable and disable this feature by "Enable clients' hostname resolution" setting in the "Upstream DNS servers" section or via resolve_clients field in the configuration file."

As of this writting the current stable release is v0.105.2 so the above feature isn't an option, hence the reasoning for specifying it manually.

Additional Notes

Under settings -> general settings enabling the Use AdGuard browsing security web server checkbox may cause AdGuard to stop resolving hosts properly on the EdgeRouter. Keep it off (the
default) if you run into issues.

Sources

• https://medium.com/@casonadams/edgerouter-x-adguardhome-b9d453f5725b
• https://dev.to/jbrodriguez/running-adguard-home-on-an-edgerouter-6p-51do

Comments

[geurtsd]

Wesley,

Great post.... To add some additional info: running this on Edge-X with multiple VLAN's and all working with ADGUARD....
Had some issues in configuring the listening mode to work on all IP's of the VLAN's.
by default the setup page of ADGUARD lets you choose to listen on a single interface OR all interfaces, yet no higher granularity....

So just to share for the rest how I got this to work for me:

• Just follow you guide, upto and including the first manual run and config via port 3000
• Exit the running ADGUARD
• BEFORE you run the install: edit the AdGuardHome.yaml file and change the below section to your corresponding VLAN IP'S:

dns:
  bind_hosts:
  - 10.10.1.1
  - 10.10.10.1
  - 10.10.20.1
  - 192.168.200.1

• Save file
• TEST with a manual run
• Once verified --> continue with the INSTALL

just for reference, this only works for the DNS bind_Hosts... it does not work for the publication of the front-portal... here you can only have 1 entry (so still 0.0.0.0 if you want it available on ALL ports, !!!!!also your internet facing port!!!!!)

cheers,

Davy

[Wesley Brewer]

Thanks for the write up, I'm sure it will help others. I have yet to setup vlans on my network but this will be helpful for sure. Thanks for noting that listening on all interfaces (0.0.0.0) will include the internet facing interface. Very important and easy to overlook!

[a noob Just]

Could you please help me to do manually update Adguard on edge router? There's no auto update on mine.

[Wesley Brewer]

This should work for manual update.
1) stop the service
2) download the new package
3) start the service.

sudo ./AdGuardHome -s stop
curl -sL https://static.adguard.com/adguardhome/release/AdGuardHome_linux_mipsle_softfloat.tar.gz | tar xvz
sudo ./AdGuardHome -s start

[a noob Just]

When I do sudo ./AdGuardHome -s start, there's an error:

 ./AdGuardHome: command not found

What should I do next? Thanks

[Wesley Brewer]

are you in the AdGuardHome directory?

cd AdGuardHome

also you can check your current path

pwd

[a noob Just]

When I do a start command, an error appear:

 ./AdGuardHome: cannot execute binary file

[a noob Just]

admin@ubnt:~/AdGuardHome$ ls -la
total 35232
drwxr-xr-x    3 admin    users         4096 Jun  6 22:31 .
 drwxr-xr-x    4 admin    users         4096 Jun 26 23:24 ..
-rwxr-xr-x    1 admin    users     35913728 Jun  6 22:31 AdGuardHome
-rw-r--r--    1 admin    users          331 Jun  6 22:31 AdGuardHome.sig
-rw-r--r--    1 admin    users        43421 Jun  6 22:31 CHANGELOG.md
-rw-r--r--    1 admin    users        35149 Jun  6 22:31 LICENSE.txt
-rw-r--r--    1 admin    users        23236 Jun  6 22:31 README.md
drwxr-xr-x    3 root     root          4096 Jun 23 06:29 data

[a noob Just]

Thanks, I'll try it.

[Wesley Brewer]

Please note that I've had issues where my ERX device filled the root to 100% usage and as such I ran into issues on the device. I'm not sure what would happen if you reboot under these circumstances but I rather not tempt fate. If you do end up at 100% usage on / it's probably the fault of the Adguard logs. You can clear them on your Adguard web interface at Settings --> General Settings under log configuration. I also recommend you change some log retention settings to avoid this issue in the future!

I noticed the issues when I tried to change settings on my EdgeRouter web interface. I tried to enable some firewall rules I had in place and ended up with a red x icon instead of a green saved icon, ouch!

You can check for space issues on your Edgerouter at the command line with the "df" command. If your root / is at 100% you're going to have issues. Clear the logs and check again!

I've updated this guide to include the fix, under the heading "Reduce AdGuard logs". These steps include the remedy and prevention steps for this issue.

Sorry for the oversite lady and gents, lets keep those packets flowin'

[geurtsd]

Wesley,

small additional element to gain some room.....
most of the time the Edge-x has 2 system images on file (current and previous)

just run:

show system image

if there are multiple images you can:

delete system image

this will delete ONLY your previous system image (not your current)

it brought my df % down from 81% to 44%.

cheers,

Davy

[Wesley Brewer]

Nice, thank you for the heads up on this. I was not aware that it kept a firmware backup by default. Looking further into this, Ubiquiti documentation recommends doing it if you need more space.

It also mentions a similar command that shows the used space of each image.

show system image storage

further reading: help.ui.com/hc/en-us/articles/2051...

[Enrico Deleo]

This post addressed exactly what I was looking for. Thank you!

[Wesley Brewer]

You're welcome! I wrote it initially so I had a reference for myself to remember, then I thought why not share it. Also, check out my revision on the document as I ran into an issue with logging and space usage hitting 100%. It's an easy fix but better to fix it before you run into problems.

[Enrico Deleo]

Update: no issues so far with storage after I changed to 24h retention! Profit!

Anyways I am facing issues trying to reach devices with .local domains (I used local instead of lan because I use home assistant that advertises as .local - and it works! - and I wanted to keep consistent). No luck trying to visit edgerouter.local even if edgerouter is the system name and I have

[/168.192.in-addr.arpa/]192.168.1.1:5353
[/local/lan/]192.168.1.1:5353

among upstream servers. I tried load-balancing and parallel resolution algorithms but cannot reach the router by name, only by IP :(

Any ideas?

[Wesley Brewer]

• remove local from [/lan/]192.168.1.1:5353 just make it [/local/]192.168.1.1:5353
• also there is now a new option to checkmark "enable reverse resolving of clients IP addresses". Keep that enabled.
• maybe reboot the router after you changed the system name
• do other clients resolve at [hostname].local ?

[Enrico Deleo]

Tried everything. I think maybe because .local has a special meaning on macOS (avahi/bonjour discovery services) but still cannot figure out why it does work for home assistant and not for other hots (I guess it is because home assistant advertises this hostnames and other nodes not, but I'm not sure).

** update **

It's worthwhile mentioning that yes, .local domains do cause troubles on Apple OS (iOS, iPad, Mac). The solution I found is to enable an mdns repeater. Edgerouter luckily has avahi built-in so you just need to

configure
set service mdns reflector 
commit; save

these commands will run dbus and avahi-daemon automatically and magically all hosts will be available under .local domain instead of 127.0.1.1 (which was the previous reply to all the ping commands I tried on my mac).

I dunno if there are any consequence/cons enabling this service (I have some security concern, I hope I didn't open any hole) but it works so far.

[chyron8472]

I'm at the step to run curl -sL https://static.adguard.com/adguardhome/release/AdGuardHome_linux_mipsle_softfloat.tar.gz | tar xvz but it responds with "tar: short read" and I can not continue further.

[Scotty]

Was having the same problem and updating the firmware fixed it.
Download: ui.com/download/software/er-x
Install: help.ui.com/hc/en-us/articles/2051...

[kingtron]

thanks for this useful and detailed guide, I have a problem in updating adguard, it does not update when there is a new version. I remember before we were be able to click "update" and get it updated, now you can only see the message "AdGuard Home v0.107.4 is now available! Click here for more info." and that is it. any idea ?
btw I'm using v0.107.3 thanks

dev-to-uploads.s3.amazonaws.com/up...

[Svetoslav Popov]

Thank you, works great. I'm using 0.106.2 and I still need
[/lan/]192.168.1.1:5353

[Wesley Brewer]

Good to know! Check out my revision on the document as I ran into an issue with logging and space usage hitting 100%. It's an easy fix but better to fix it before you run into problems.

[Duong Nguyen hoang]

hi. Can you help me uninstall this from my Edgerouter X. I want to uninstall and install into Raspberry Pi 4

[Wesley Brewer]

cd AdGuardHome
sudo ./AdGuardHome -s uninstall

should work, then you can remove the AdGuardHome folder if it's left over with

cd
rm -rf AdGuardHome

[benek984]

Hello,

Should I see hostnames instead of just IP addresses on the top clients list?

dev-to-uploads.s3.amazonaws.com/up...

[Wesley Brewer]

I find it works with some of my clients not all for some reason. Typically my phones and smart devices don't show their hostnames in AdGuard despite showing hostnames in the Edgerouter OS client list.