This is an old revision of the document!


AdGuard Home

This wiki page is currently a work in progress and information is currently in the process of being transferred from the community forum. Certain defaults are assumed per default OpenWrt install. Router being at 192.168.1.1 You will need to make changes if you do not have standard defaults!

AdGuard Home (AGH) is a free and open source network-wide advertising and trackers blocking DNS server. It operates as a DNS server that re-routes tracking domains to a “black hole”, thus preventing your devices from connecting to those servers. It is based on software used with public AdGuard DNS servers.

In addition, AdGuard Home also offers DNS encryption features without any additional requirements or packages needed.

  • 50MB free RAM.
  • 30MB free disk/flash space (see flash/storage requirements).
  • Higher performance routers i.e. dual-core with higher processor clock speeds are recommended.

Routers with low RAM, flash/storage space or slower processors will potentially not be suitable to run AdGuard Home.
Routers with less than 128mb of ram or only single core will perform poorly. homehub_v5a was used for testing the 107 builds.

Since 21.02, there is a official AdGuard Home package which can be installed through opkg. Required dependencies are automatically resolved and installed when using the official package.

opkg update
opkg install adguardhome

The official package uses the following paths and directories by default:

  • AdGuard Home will be installed to /usr/bin/AdGuardHome.
  • The main adguardhome.yaml configuration file is stored at /etc/adguardhome.yaml.
  • The default working directory is /var/adguardhome (By default /var is a symlink to /tmp).
  • The working directory can be configured in /etc/config/adguardhome
  • An init.d script is provided at /etc/init.d/adguardhome.

The default configured working directory will mean query logs and statistics will be lost on a reboot. To avoid this you should configure a persistent storage path such as /opt or /mnt with external storage and update the working directory accordingly.

To have AdGuard Home automatically start on boot and to start the service:

service adguardhome enable
service adguardhome start

Thanks to elan for the setup instructions below.

After installing the opkg package, run the following commands through SSH to prepare for making AGH the primary DNS resolver, replacing dnsmasq and making it an internal DNS resolver only.

Note: If your router is not at 192.168.1.1 then replace the router IP address used in the commands below accordingly.

# Reduce dnsmasq cache size as it will only provide PTR info. 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.
uci set dhcp.@dnsmasq[0].noresolv="1"
uci set dhcp.@dnsmasq[0].cachesize="1000"
uci set dhcp.@dnsmasq[0].rebind_protection='0'
uci -q delete dhcp.@dnsmasq[0].server
uci add_list dhcp.@dnsmasq[0].server="192.168.1.1"
uci set dhcp.@dnsmasq[0].port="5353"
uci commit dhcp
/etc/init.d/dnsmasq restart

Setup AGH through the web interface

  1. Setup the Admin Web Interface to listen in 192.168.1.1 at port 8080.
  2. Set DNS server to listen in 192.168.1.1 at port 53.
  3. Create an user and choose a strong password.

Login AGH

Feel free to change upstream DNS servers to whatever you like (Adguard Home supports DoH, DoT and DoQ out of the box), add the blacklists of your preference and enjoy ad-free browsing on all of your devices.

Reverse DNS (rDNS)

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

  • Scroll to Private reverse DNS servers
  • add 192.168.1.1:5353
  • Tick both Use private reverse DNS and Enable private reverse resolving boxes.

For older builds, a custom installation or running the latest edge builds you can follow several well written guides by members of the community:

Recommendations and best configuration practices for using AGH on OpenWrt.

AGH as a NextDNS client

AGH is also recommended to be used with filtering disabled as a NextDNS client. As per here : Using AGH as a NextDNS Client

Web interface

AdGuard Home has it's own web interface and is not managed through LuCI. By default this will be on port TCP 3000. To access the web interface, use the IP of your router: http://192.168.1.1:3000. If this is the first time you have installed AdGuard Home you will go through the setup process. By default LuCI will be configured on TCP 80/443, so you will need to use an alternative port such as TCP 8080. Once AGH is active then follow the official AdGuard Home wiki instructions to configure upstreams and filters.

Debugging

If AdGuard Home won't start, you will want to run AdGuard Home from command line with the verbose flag to see the output.

AdGuardHome -v -c /path/to/adguardhome.yaml -w /path/to/adguardhome --no-check-update

Running this directly from SSH will allow you to see errors or issues preventing AdGuard Home from starting. Often this could be due to syntax errors in the adguardhome.yaml config.

Flash/storage space requirements

The compiled AdGuardHome binary has grown since the 0.107.0 release. For many routers this will be quite a significant amount of storage taken up in the overlay filesystem. In addition, features like statistics and query logging will also require further storage space when being written to the working directory. For routers with less flash space, it is highly recommended to use USB or an external storage path to avoid filling up your overlay filesystem. If you have low flash space, you may want to use the custom installation method and have all of the AdGuard Home installation stored outside of your flash storage. Alternatively you can also perform an exroot configuration.

DNS latency/performance

For the best performance and lowest latency on DNS requests, AGH should be your primary DNS resolver in your DNS chain. If you currently have dnsmasq or unbound installed, you should move these services to an alternative port and have AGH use DNS port 53 with upstream DNS resolvers of your choice configured. The reason for this is due to resolvers like dnsmasq forking each DNS request when AGH is set as an upstream, which will increase latency on DNS requests.

Changing dnsmasq DNS port

To move the DNS port used by dnsmasq, use the following uci commands.

uci set dhcp.@dnsmasq[0].port='5353'
uci commit dhcp
service dnsmasq restart

After doing this, make sure AdGuard Home is configured on standard DNS ports.

Creating ipset policies

AGH provides ipset functionality similar to dnsmasq. The configuration/syntax is slightly different and you will need to migrate any existing dnsmasq ipset policies to the AGH format. An ipset policy is defined in the adguardhome.yaml file, there is currently no web interface available to add these policies, therefore you must add these to the yaml config manually.

opkg install ipset

Example syntax:

dns:
 ipset:
 - domain.com/ipset_name
 - domain1.com,domain2.com/ipset_name,ipset_name2
...

An ipset policy in AGH can have one or more domains as well as be assigned to multiple ipset chains. Further information on ipset functionality can be found on the official AdGuard Home wiki

Note: The ipset chains must exist before being used or referenced in AGH to work.

DNS interception

Some devices will bypass DHCP provided DNS servers e.g. Chromecast, in order to make sure all DNS traffic goes through your primary DNS resolver. You can enforce this through iptables/firewall.

iptables -t nat -A PREROUTING -i br-lan -p udp --dport 53 -j DNAT --to 192.168.1.1:53
iptables -t nat -A PREROUTING -i br-lan -p tcp --dport 53 -j DNAT --to 192.168.1.1:53

You can also implement this via a fw3 rule:

config redirect 'adguardhome_dns_53'
        option src 'lan'
        option proto 'tcp udp'
        option src_dport '53'
        option target 'DNAT'
        option name 'Adguard Home'
        option dest 'lan'
        option dest_port '53'

These examples are for IPv4 DNS traffic only.

Further information on DNS Hijacking is here DNS Interception

This website uses cookies. By using the website, you agree with storing cookies on your computer. Also you acknowledge that you have read and understand our Privacy Policy. If you do not agree leave the website.More information about cookies
  • Last modified: 2021/12/29 09:17
  • by jamesmacwhite