[How

Introduction:

This thread mostly covers the manual installation of AdGuard Home's edge/beta version. OpenWrt's opkg version is the stable release. The edge version installs to /opt/AdGuardHome , the opkg version to /etc/adguardhome for the config files and /tmp for filters, logs etc thus you WILL loose them when your router reboots.

AGH - https://github.com/AdguardTeam/AdGuardHome

A few points first of all.

The ports chosen are either well known alternate ports or reasonable compromises. You are free to edit the scripts to use your own ports but you should check with https://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers for reserved ports.

OpenWrt has a AGH package in opkg. Instructions are here https://openwrt.org/docs/guide-user/services/dns/adguard-home

NextDNS - It is recommended to use AGH as a better client for NextDNS : [How-To-Updated 2021] Installing AdGuardHome on OpenWrt [Manual and opkg method] - #6 by mercygroundabyss

For limited space routers you can mount a USB drive and use that to host AGH. Mounting it as /opt/AdGuardHome will ensure you do not run out space on smaller routers. Currently AGH is 35mb. Add in filters, DNS queries, Stats, (and a 2nd copy of AGH binary when it updates and backs up) and your space rapidly vanishes. With careful setting of options you can keep the requirements low but having an entire USB drive to use will avoid issues.

Another interesting option is what @Cheddoleum uses. He kindly wrote up about using a pi zero off the USB port router piggy backing on OpenWrt. Raspberry Pi Zero as a router-attached ethernet gadget This gives AGH a separate cpu to run on if your router is older and lacks space and power.

My installation uses 192.168.1.1 as default IP. Please ensure you edit any scripts to match your config or this will break things in bad ways.

https://github.com/AdguardTeam/AdGuardHome/wiki/Encryption - AGH supports encrypted DNS internally and it is just a matter of choice as to which method you use and what servers you put in.

I do NOT use SSL for AGH's web frontend. Luci (OpenWrt's web interface) runs on port 80 and port 443 for SSL. I run AGH on port 8080. If you wish to use SSL for AGH you will need to move Luci or run AGH on non standard ports. AGH does use SSL for encrypted DNS but that is separate to the web interface. You can also use nginx to proxy AGH. See https://openwrt.org/docs/guide-user/services/dns/adguard-home#nginx_reverse_proxy_through_luci for more details.

Installation:

I use Putty for SSH shell access and WinSCP for remote file access to my router. This means I can edit files directly and also create the scripts required for install. It also avoids windows to unix file issues that can occur with editing of files. (unix uses Line Feed for new line, windows uses Carriage Return / Line Feed. This will cause unexpected errors in unix.)

Ok. Having had some free time today I have updated my backup router to OpenWrt 21.02.1.

Completely clean install and reset to defaults. OpenWrt uses 192.168.1.1 thus all my scripts assume and follow that convention.

I updated opkg and pulled new updates. (listed below if you are curious.)

With that done I now use the following script to install packages required for AGH install and a few test tools.

The most important is sudo. This is required for setting up AGH service.

ca-certificates ca-bundle - These are the certificates required for SSL.

curl wget tar unzip - System tools for downloading AGH and unzipping updates etc.

Bind-tools is all the DNS tools. This package is for testing DNS queries and ensuring DNSSec is on and proper resolution of DNS queries.

The script then pulls the AGH installer script and installs the Edge version. This is the most up to date and is generally best version to use.

Now the fun bit. With AGH installed, we now switch OpenWrts DNSMasq to the background so we can pull client info from it and resolve the OpenWrt clients. Rebind protection is removed. DHCP options are added so AGH will take over from DNSMasq. Unless DNSMasq is moved from port 53 to port 54 then AGH cannot take over and be primary DNS. Luci's web interface lives on port 80 so we just tell AGH when we set it up to use port 8080 for its web interface instead.

(The reason you setup OpenWrt to use a different unencrypted upstream is so when it brings up your connection it can do NTP and updates as AGH will still be loading. Without NTP setting your router time / date correctly, SSL will fail and thus no encrypted DNS.) See https://openwrt.org/docs/guide-user/services/dns/adguard-home#bypassing_encrypted_dns_for_ntp for more details.

I have split my install script into two. The first swaps the routers upstream DNS for Cloudflare DNS. As some may want to keep their existing DNS settings I've moved this to a separate script that you can run or ignore and continue to the installation script instead.

routerDNS.sh

installAGH.sh The install script looks up the first ipv4 and v6 addresses to use for installing. It uses the br-lan interface for this. If you have a different interface you will need to change the script.

With that complete now we login http://192.168.1.1:3000 and configure AGH. AGH should see port 53 for DNS is clear so that option is fine. However Luci runs on port 80 so AGH detects this and will not let you proceed. Change the web interface port to 8080 and continue the install.

Setup your user and password and then you should be at the main web interface.

At this point you can just follow AGH's wiki to guide you into setting up AGH. But for completeness I have documented the process below.

Network-wide ads & trackers blocking DNS server. Contribute to AdguardTeam/AdGuardHome development by creating an account on GitHub.

There are a few needed tweaks depending on if you selected listen on all interfaces during setup. To fix this some manual editing is required of the yaml file. By default AGH in its setup asks you what interfaces to bind to. It either lets you select a single interface or ALL interfaces. (That means if your WAN interface is up you will have DNS listening there. There is an issue in for that to be selectable so you can deselect WAN interfaces. Its currently filed as an improvement for the 108 version I believe)

Open the /opt/AdGuardhome.yaml file and find the following:

That config serves DNS on localhost ipv4, ::1 localhost ipv6, 192.168.1.1 and ipv6 fd1a:c860:7174

DNS Settings:

On your AGH web interface open the DNS settings page http://192.168.1.1:8080/#dns and then configure your provider as you want.

I use Cloudflare but other providers are listed here.

https://github.com/AdguardTeam/AdGuardHome/wiki/Configuration#upstreams - Configure upstreams

(edit - Added example DNS picture as guide. You do not need to use any other programs like Unbound or DNS-Over-Https. AGH does it internally. All you have to do is pick your provider and method of encrypted DNS.)

Domain interception :

If you have the default OpenWrt DHCP then adding :

[/lan/]127.0.0.1:54 [//]127.0.0.1:54

to the upstream list that will intercept lan and domainless requests and pass those requests back to openwrt. "lan" is OpenWrt's default domain. (127.0.0.1) local loopback is used here to enable statistics tracking but you may also use your router ip (192.168.1.1) here too. Domain Interception is necessary for multi ip networks. For simple IP networks rDNS should cover this.

Bootstrap Servers

Then I setup the bootstrap servers. These are known ip addresses to allow AGH to find DNS resolvers.

https://kb.adguard.com/en/general/dns-providers#cloudflare-dns - Cloudflare DNS info.

(edit - List of providers here - https://kb.adguard.com/en/general/dns-providers)

Reverse DNS (rDNS)

To enable rDNS so AGH picks up your DHCP assignments from OpenWrt.

From the AdGuard Home web interface Settings → DNS settings

Scroll to “Private reverse DNS servers”

Add 192.168.1.1:54

Tick both “Use private reverse DNS resolvers” and “Enable reverse resolving of clients' IP addresses” boxes and click apply.

https://github.com/AdguardTeam/AdGuardHome/wiki/Configuration#rdns-clients - Configuring rdns.

yaml settings for this:

Filters:

AGH comes with built in filters. Add as you see fit. There are more filter lists available on the internet but be aware as you add more filters, you use more memory and space. Limited space/mem routers will need to be monitored to ensure you do not run out of memory with huge lists.

Filter Sites:

https://firebog.net/ https://oisd.nl/ For AdGuardHome you must use abp.oisd.nl

I have updated info about filter lists here : [How-To-Updated 2021] Installing AdGuardHome on OpenWrt [Manual and opkg method] - #401 by mercygroundabyss

Interface:

You will notice that the interface shows "0 malware/phishing sites blocked". You will only see Blocked lists showing for your results from your filter lists. It is their DNS which gives those definitions so you will have to use AGH DNS as upstream if you wish to use those counters.

It is explained in their blog here :

As many of you probably know, AdGuard provides a lot of ways to block ads in form of various apps and browser extensions. Some even heard about AdGuard DNS, a way to block ads without installing anything on your device. And today we are announcing...

Limited space routers:

Due to space limitations and AGH silently failing to update from the web interface I created a manual script to update AGH from SSH. It will not backup AGH like the web interface does. It just downloads and then overwrites the binary. (Issue filed - https://github.com/AdguardTeam/AdGuardHome/issues/3801) (more explanation here - [HowTo] Running Adguard Home on OpenWrt - #442 by mercygroundabyss) Please refer to the AGH wiki for manual updating.

https://github.com/AdguardTeam/AdGuardHome/wiki/FAQ#manual-update - Manual Update documented here.

Data Files:

The /opt/AdGuardHome/data folder contains the following.

querylog files : These are your DNS queries. Can be removed. sessions.db : active logins to AGH currently. This can be deleted but you will need to relog back in. stats.db : Your statistics database. can purge but you will lose your statistics data.

filters folder contains all your filter downloads. Purge if it is full but it will re-download your filters. If your filters are too large for your diskspace you will have to disable large filters and restrict their usage.

Future Updates:

For those wondering what's coming next in AGH - https://github.com/AdguardTeam/AdGuardHome/milestone/37 )

https://github.com/AdguardTeam/AdGuardHome/issues/2830 is potentially the bit we have been waiting for to have AGH take over DHCP from OpenWrt.

Space:

One of the reasons I use the lists I do is down to memory. While big lists have their place, we have to bear in mind that what we are doing here is adding AGH to OpenWrt routers. This usually means limitations on disk space and memory, especially for older routers. OpenWrt already has depreciated 4 and 8mb routers. I tested with a 128mb BT Hub 5. I can get about 140k of filter rules before I run into memory issues. The bigger problem is the disk space and AGH binary being 35mb alone. Its why I created my script to do updates and filed an issue on AGH's hub. https://github.com/AdguardTeam/AdGuardHome/issues/3801

DNS Lockdown:

If you want to lock things down? https://openwrt.org/docs/guide-user/services/dns/adguard-home#dns_interception

Firewall rules to enforce your Adguard DNS to be the only DNS and to block other outgoing attempts.

Just make sure you have an exclusion for your router and Adguard or you will find yourself DNSless.

Uninstalling:

This script uninstalls AGH and resets your router to Google DNS as your upstream. This is a known good default and should always work.

uninstallAGH.sh

Changelog: