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.1as 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.)
opkg results
root@OpenWrt:~# opkg list-upgradable
luci-app-opkg - git-21.079.58598-6639e31 - git-21.312.69848-4745991
iw - 5.9-8fab0c9e-1 - 5.9-8fab0c9e-3
busybox - 1.33.1-6 - 1.33.2-1
luci-mod-system - git-21.295.66903-8acd0d7 - git-21.305.74567-388dae9
luci-theme-bootstrap - git-21.298.68362-d24760e - git-21.320.44446-0cee46b
wpad-basic-wolfssl - 2020-06-08-5a8b3662-35 - 2020-06-08-5a8b3662-37
netifd - 2021-07-26-440eb064-1 - 2021-10-30-8f82742c-1
luci-app-firewall - git-21.295.66767-8eceb63 - git-21.312.70727-3eac573
luci-base - git-21.295.67054-13df80d - git-21.327.65561-7f37a58
luci-mod-network - git-21.295.67048-4d3de0e - git-21.335.80427-5091496
hostapd-common - 2020-06-08-5a8b3662-35 - 2020-06-08-5a8b3662-37
wireless-regdb - 2021.04.21-1 - 2021.08.28-1
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
#!/bin/sh
# Reconfigure router DNS provider to cloudflare upstream
# Disable peer ISP DNS
uci set network.wan.peerdns="0"
uci set network.wan6.peerdns="0"
# Reconfigure router IPv4 DNS provider to cloudflare upstream
uci -q delete network.wan.dns
uci add_list network.wan.dns="1.1.1.1"
uci add_list network.wan.dns="1.0.0.1"
# Reconfigure router IPv6 DNS provider to cloudflare upstream
uci -q delete network.wan6.dns
uci add_list network.wan6.dns="2606:4700:4700::1111"
uci add_list network.wan6.dns="2606:4700:4700::1001"
# Save changes
uci commit network
# Restart network service to reflect changes
/etc/init.d/network restart
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.
#!/bin/sh
# Switch to Adguard setup
# Grab packages for AGH and updates.
opkg update
opkg install sudo ca-certificates ca-bundle curl wget wget-ssl tar unzip bind-tools
#grab and install AGH
curl -s -S -L https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh | sh -s -- -c edge
# 1. Enable dnsmasq to do PTR requests.
# 2. Reduce dnsmasq cache size as it will only provide PTR/rDNS info.
# 3. Disable rebind protection. Filtered DNS service responses from blocked domains are 0.0.0.0 which causes dnsmasq to fill the system log with possible DNS-rebind attack detected messages.
# 4. Move dnsmasq to port 54.
# 5. Set Ipv4 DNS advertised by option 6 DHCP
# 6. Set Ipv6 DNS advertised by DHCP
# 7. Set 24hr DHCP Leases
# Get the first IPv4 and IPv6 Address of router and store them in following variables for use during the script.
NET_ADDR=$(/sbin/ip -o -4 addr list br-lan | awk 'NR==1{ split($4, ip_addr, "/"); print ip_addr[1] }')
NET_ADDR6=$(/sbin/ip -o -6 addr list br-lan scope global | awk 'NR==1{ split($4, ip_addr, "/"); print ip_addr[1] }')
echo "Router IPv4 : ""${NET_ADDR}"
echo "Router IPv6 : ""${NET_ADDR6}"
uci set dhcp.@dnsmasq[0].noresolv='0'
uci set dhcp.@dnsmasq[0].cachesize='1000'
uci set dhcp.@dnsmasq[0].rebind_protection='0'
uci set dhcp.@dnsmasq[0].port='54'
uci -q delete dhcp.@dnsmasq[0].server
uci add_list dhcp.@dnsmasq[0].server="${NET_ADDR}"
uci set dhcp.lan.leasetime='24h'
#Delete existing config ready to install new options.
uci -q delete dhcp.lan.dhcp_option
uci -q delete dhcp.lan.dns
# DHCP option 6: which DNS (Domain Name Server) to include in the IP configuration for name resolution
uci add_list dhcp.lan.dhcp_option='6,'"${NET_ADDR}"
#DHCP option 3: default router or last resort gateway for this interface
uci add_list dhcp.lan.dhcp_option='3,'"${NET_ADDR}"
#Set IPv6 Announced DNS
for OUTPUT in $(ip -o -6 addr list br-lan scope global | awk '{ split($4, ip_addr, "/"); print ip_addr[1] }')
do
echo "Adding $OUTPUT to IPV6 DNS"
uci add_list dhcp.lan.dns=$OUTPUT
done
# Save changes
uci commit dhcp
# Restart dnsmasq service to reflect changes
/etc/init.d/dnsmasq restart
echo 'Goto http://'"${NET_ADDR}"':3000 and configure AdGuardHome.'
Output from the install.
Router IPv4 : 192.168.1.1
Router IPv6 : fd1a:c860:7174::1
Adding fd1a:c860:7174::1 to IPV6 DNS
starting AdGuard Home installation script
2021/12/06 11:29:10 [info] service: control action: install
2021/12/06 11:29:11 [info] service: started
2021/12/06 11:29:11 [info] Almost ready!
AdGuard Home is successfully installed and will automatically start on boot.
There are a few more things that must be configured before you can use it.
Click on the link below and follow the Installation Wizard steps to finish setup.
AdGuard Home is now available at the following addresses:
2021/12/06 11:29:11 [info] Go to http://127.0.0.1:3000
2021/12/06 11:29:11 [info] Go to http://[::1]:3000
2021/12/06 11:29:11 [info] Go to http://192.168.1.1:3000
2021/12/06 11:29:11 [info] Go to http://[fd1a:c860:7174::1]:3000
2021/12/06 11:29:11 [info] Go to http://192.168.1.1:3000
2021/12/06 11:29:11 [info] service: action install has been done successfully on unix-systemv
AdGuard Home is now installed and running
you can control the service status with the following commands:
sudo /opt/AdGuardHome/AdGuardHome -s start|stop|restart|status|install|uninstall
udhcpc: started, v1.33.2
udhcpc: sending discover
udhcpc: no lease, failing
Goto http://192.168.1.1:3000 and configure AdGuardHome.
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.
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:
dns:
bind_hosts:
- 127.0.0.1
- ::1
- 192.168.1.1
- fd1a:c860:7174::1
port: 53
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:
resolve_clients: true
use_private_ptr_resolvers: true
local_ptr_upstreams:
- 192.168.1.1:54
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 :
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.
root@OpenWrt:/opt/AdGuardHome/data# ll -h
drwxr-xr-x 3 root root 512 Oct 29 09:42 ./
drwxrwxrwx 4 root root 736 Oct 30 09:06 ../
drwxr-xr-x 2 root root 800 Nov 2 09:52 filters/
-rw-r--r-- 1 root root 45.4M Nov 2 20:42 querylog.json
-rw-r--r-- 1 root root 8.9M Oct 29 09:00 querylog.json.1
-rw-r--r-- 1 root root 32.0K Oct 30 05:28 sessions.db
-rw-r--r-- 1 root root 4.0M Nov 2 21:00 stats.db
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
#!/bin/sh
curl -s -S -L https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh | sh -s -- -v -u
# 1. Reverts AdGuard Home configuration and resets settings to default.
# 2. Enable rebind protection.
# 3. Remove DHCP options for IPv4 and IPv6
uci -q delete dhcp.@dnsmasq[0].noresolv
uci -q delete dhcp.@dnsmasq[0].cachesize
uci set dhcp.@dnsmasq[0].rebind_protection='1'
uci -q delete dhcp.@dnsmasq[0].server
uci -q delete dhcp.@dnsmasq[0].port
uci -q delete dhcp.lan.dhcp_option
uci -q delete dhcp.lan.dns
# Network Configuration
# Disable peer/ISP DNS
uci set network.wan.peerdns="0"
uci set network.wan6.peerdns="0"
# Configure DNS provider to Google DNS
uci -q delete network.wan.dns
uci add_list network.wan.dns="8.8.8.8"
uci add_list network.wan.dns="8.8.4.4"
# Configure IPv6 DNS provider to Google DNS
uci -q delete network.wan6.dns
uci add_list network.wan6.dns="2001:4860:4860::8888"
uci add_list network.wan6.dns="2001:4860:4860::8844"
# Save and apply
uci commit dhcp
uci commit network
/etc/init.d/network restart
/etc/init.d/dnsmasq restart
/etc/init.d/odhcpd restart
Changelog:
- Tidied up a few sentances and improved layout.
- Added more info about encrypted DNS and no need for external modules/programs.
- Added screen shots for configuring upstreams.
- Added post about using NextDNS. (see here) December 7, 2021
- Tweaked script to do IPv6 DNS December 9, 2021
- Removed my filter list. AGH has updated theirs. December 15, 2021
- Added local domain interception. Thanks to @Cheddoleum - December 16, 2021
- opkg version update. December 25, 2021
- Uninstall instructions. January 14, 2022
- Minor editing and readability tweaks. January 19, 2022
- IPV6 DNS Fix and Script updates January 29, 2022
- apparently jq for json parsing isnt default installed. January 31, 2022
- Added AGH Manual Update FAQ February 1, 2022
- IPV6 - removed json/jq replaced with awk February 4, 2022
- Added introduction, changed title, linked to opkg version, warning on unix/windows file issues, nginx proxy info added. April 3, 2022
- NTP Warning enhanced. Replaced PTR picture. NFT tables added/DNS Interception. June 24, 2022
- dnsmasq port replaced from 5353 to 54 due to clash with mDNS service. June 25, 2022
- Fixed router PTR lookups to dnsmasq. June 28, 2022
- Removed manual update and left link to AGH wiki. October 6, 2022
- Revisiting filter lists. November 19, 2022
Really kind of you!