Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision Next revisionBoth sides next revision | ||
| docs:guide-user:services:dns:adguard-home [2021/12/29 09:29] – jamesmacwhite | docs:guide-user:services:dns:adguard-home [2022/06/25 22:41] – [Bypassing encrypted DNS for NTP] enhanced warning for NTP bypass for lookups. mercygroundabyss | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| ====== AdGuard Home ====== | ====== AdGuard Home ====== | ||
| - | <WRAP center important 100%> | + | [[https:// |
| - | Certain defaults are assumed per default OpenWrt install. Router being at '' | + | |
| - | AdGuard Home (AGH) is a free and open source network-wide advertising and trackers blocking | + | In addition, |
| - | In addition, AdGuard Home also offers DNS encryption features without any additional requirements or packages needed. | + | {{: |
| ===== Prerequisites ===== | ===== Prerequisites ===== | ||
| - | | + | <WRAP important 100%> |
| - | * 30MB free disk/flash space ([[# | + | Routers with low RAM, flash/ |
| + | </ | ||
| + | |||
| + | | ||
| + | * Minimum of 100MB free disk/flash space ([[# | ||
| * Higher performance routers i.e. dual-core with higher processor clock speeds are recommended. | * Higher performance routers i.e. dual-core with higher processor clock speeds are recommended. | ||
| - | Routers with low RAM, flash/ | + | The amount of RAM required |
| - | Routers with less than 128MB of RAM or only having a single core processor will perform poorly. The [[: | + | Routers with less than 128MB of RAM or only having a single core processor will tend to perform poorly. The [[: |
| + | |||
| + | An alternative option could be to use a Raspberry Pi Zero plugged into your routers USB port to run AGH. [[https:// | ||
| + | |||
| + | ==== DNS latency/ | ||
| + | |||
| + | 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. This wiki recommends keeping dnsmasq/ | ||
| + | |||
| + | The rationale for this is due to resolvers like dnsmasq forking each DNS request when AGH is set as an upstream, this will have an impact on DNS latency which is can be viewed in the AGH dashboard. You will also not benefit from being able to see the DNS requests made by each client if AGH is not your primary DNS resolver as all traffic will appear from your router. | ||
| + | |||
| + | The install script in the setup section will move dnsmasq to port 5353 and set it for AGH to use as local PTR / reverse DNS lookups. | ||
| + | |||
| + | ==== Flash/ | ||
| + | |||
| + | The compiled '' | ||
| + | |||
| + | Currently (May 2022 edge build 108) a full install to the /opt folder you really require about 100mb of space. | ||
| + | * (70mb) 35mb x2 for the AGH binary and again for when it backups and upgrades. (that' | ||
| + | * 20mb for my filters. (Again you can raise or lower this depending on what lists you use) | ||
| + | * 2mb - 90 days of statistics. | ||
| + | * 53mb - 7 days of query logs. | ||
| + | |||
| + | You can tweak your logging to keep things smaller if required. | ||
| + | |||
| + | ==== Query/ | ||
| + | |||
| + | One of the main benefits of AGH is the detailed query and statistics data provided, however for many routers having long retention periods for this data can cause issues (see flash/ | ||
| ===== Installation ===== | ===== Installation ===== | ||
| - | Since 21.02, there is a official [[: | + | Since 21.02, there is a official [[: |
| + | |||
| + | The opkg package for 21.02 has also been confirmed to work on 19.07, but will require transferring the correct ipk through SSH or SCP and installing with opkg manually due to not being present in the 19.07 packages repository. | ||
| + | |||
| + | Required dependencies | ||
| <code bash> | <code bash> | ||
| Line 27: | Line 60: | ||
| </ | </ | ||
| - | The official package uses the following paths and directories by default: | + | The official |
| - | * AdGuard Home will be installed to ''/ | + | * The '' |
| * The main '' | * The main '' | ||
| * The default working directory is ''/ | * The default working directory is ''/ | ||
| Line 46: | Line 79: | ||
| ==== Setup ==== | ==== Setup ==== | ||
| - | // | + | After installing the opkg package, run the following commands through SSH to prepare |
| - | After installing the opkg package, run the following | + | <code bash> |
| + | # Get the first IPv4 and IPv6 Address of router and store them in following | ||
| + | NET_ADDR=$(/ | ||
| + | NET_ADDR6=$(/ | ||
| - | **Note:** If your router is not at '' | + | echo " |
| + | echo " | ||
| - | <code bash> | + | # 1. Disable dnsmasq from needlessly looking at the / |
| - | # Reduce dnsmasq cache size as it will only provide PTR info. Disable rebind protection. | + | # 2. Reduce dnsmasq cache size as it will only provide PTR/rDNS info. |
| - | # 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. | + | # 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 5353. | ||
| + | # 5. Set Ipv4 DNS advertised by option 6 DHCP | ||
| + | # 6. Set Ipv6 DNS advertised by DHCP | ||
| uci set dhcp.@dnsmasq[0].noresolv=" | uci set dhcp.@dnsmasq[0].noresolv=" | ||
| uci set dhcp.@dnsmasq[0].cachesize=" | uci set dhcp.@dnsmasq[0].cachesize=" | ||
| uci set dhcp.@dnsmasq[0].rebind_protection=' | uci set dhcp.@dnsmasq[0].rebind_protection=' | ||
| - | uci -q delete dhcp.@dnsmasq[0].server | ||
| - | uci add_list dhcp.@dnsmasq[0].server=" | ||
| uci set dhcp.@dnsmasq[0].port=" | uci set dhcp.@dnsmasq[0].port=" | ||
| + | uci -q delete dhcp.@dnsmasq[0].server | ||
| + | uci add_list dhcp.@dnsmasq[0].server=" | ||
| + | |||
| + | #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=' | ||
| + | |||
| + | #DHCP option 3: default router or last resort gateway for this interface | ||
| + | uci add_list dhcp.lan.dhcp_option=' | ||
| + | |||
| + | #Set IPv6 Announced DNS | ||
| + | for OUTPUT in $(ip -o -6 addr list br-lan scope global | awk '{ split($4, ip_addr, "/" | ||
| + | do | ||
| + | echo " | ||
| + | uci add_list dhcp.lan.dns=$OUTPUT | ||
| + | done | ||
| uci commit dhcp | uci commit dhcp | ||
| / | / | ||
| Line 69: | Line 126: | ||
| On first time setup the default web interface port is TCP 3000. | On first time setup the default web interface port is TCP 3000. | ||
| - | - Go to http:// | + | - Go to http:// |
| - | - Setup the Admin Web Interface to listen | + | - Setup the Admin Web Interface to listen |
| - | - Set DNS server to listen | + | - Set DNS server to listen |
| - Create an user and choose a strong password. | - Create an user and choose a strong password. | ||
| === Login AGH === | === Login AGH === | ||
| - | * http:// | + | * http:// |
| 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. | 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. | ||
| - | |||
| - | * Open http:// | ||
| - | * Scroll to " | ||
| - | * Add '' | ||
| - | * Tick both "Use private reverse DNS resolvers" | ||
| - | |||
| - | {{: | ||
| ==== Manual installation ==== | ==== Manual installation ==== | ||
| Line 103: | Line 152: | ||
| Recommendations and best configuration practices for using AGH on OpenWrt. | Recommendations and best configuration practices for using AGH on OpenWrt. | ||
| - | === AGH as a NextDNS client | + | ==== Web interface ==== |
| - | AGH is also recommended to be used with filtering disabled as a NextDNS client. As per here : [[https://forum.openwrt.org/ | + | AdGuard Home has it's own web interface for configuration and management and is not managed through LuCI. There is no official LuCI application for managing AdGuard Home. By default the web setup interface will be on port TCP 3000. To access the web interface, use the IP of your router: http://192.168.1.1: |
| - | === Web interface | + | By default LuCI will be configured to use standard ports TCP 80/443, so AdGuard Home will need to use an alternative port for the web interface. You can use the default setup port TCP 3000 or change it to an alternative (8080 is the usual port 80 replacememt). |
| - | AdGuard Home has it's own web interface for configuration and management 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:// | + | Once AGH is active then [[https:// |
| - | Note: Some settings may not be editable via the web interface and instead will need to be changed by editing the '' | + | Note: Some settings may not be editable via the web interface and instead will need to be changed by editing the '' |
| - | === Debugging | + | ==== Nginx Reverse proxy through LuCI ==== |
| - | If AdGuard Home won' | + | If you already use [[: |
| - | < | + | The following example will allow accessing the AdGuard Home interface as a sub directory path / |
| - | AdGuardHome | + | |
| + | < | ||
| + | location /adguard-home/ { | ||
| + | proxy_pass http://192.168.1.1: | ||
| + | proxy_redirect / /adguard-home/; | ||
| + | proxy_cookie_path | ||
| + | } | ||
| </ | </ | ||
| - | 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 | + | Accessing |
| - | === Flash/storage space requirements === | + | You can read more [[https:// |
| - | The compiled '' | + | **Disable DoH encryption on AdGuard Home** |
| - | === DNS latency/ | + | If you have configured TLS on LuCI, there' |
| - | 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. | + | ==== Reverse |
| - | === Changing dnsmasq DNS port === | + | To enable rDNS so AGH picks up your DHCP assignments from OpenWrt. |
| - | To move the DNS port used by dnsmasq, use the following uci commands. | + | - From the AdGuard Home web interface **Settings** -> **DNS settings** |
| + | - Scroll to " | ||
| + | - Add '' | ||
| + | - Tick both "//Use private reverse DNS resolvers//" | ||
| - | < | + | {{: |
| - | uci set dhcp.@dnsmasq[0].port='5353' | + | |
| - | uci commit dhcp | + | ==== LAN domain interception ==== |
| - | service dnsmasq restart | + | |
| + | Adding the following to the Upstream DNS Server configuration will intercept any LAN domain request or requests without a FQDN and pass those requests to the appropriate resolver, which is mostly like your OpenWrt router but it doesn' | ||
| + | |||
| + | The default LAN domain configured by OpenWrt is " | ||
| + | |||
| + | (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. | ||
| + | |||
| + | **Settings** -> **DNS Settings** > **Upstream Servers** | ||
| + | |||
| + | < | ||
| + | [/lan/]127.0.0.1:5353 | ||
| + | [// | ||
| </ | </ | ||
| - | After doing this, make sure AdGuard Home is configured on standard DNS ports. | ||
| - | === Creating ipset policies === | + | ==== Creating ipset policies |
| - | AGH provides ipset functionality similar to dnsmasq. The configuration/ | + | For users using ipset policies for purposes such as VPN split tunnelling, |
| + | |||
| + | An ipset policy is defined in the '' | ||
| + | |||
| + | If ipset is not already installed, install it: | ||
| <code bash> | <code bash> | ||
| + | opkg update | ||
| opkg install ipset | opkg install ipset | ||
| </ | </ | ||
| - | Example syntax: | + | **Example |
| + | |||
| + | Using the following example ipset rules in dnsmasq as a reference, the AGH equivalent is demonstrated. | ||
| + | |||
| + | < | ||
| + | ipset=/ | ||
| + | ipset=/ | ||
| + | </ | ||
| + | |||
| + | **Example AGH syntax** | ||
| <code yaml> | <code yaml> | ||
| Line 161: | Line 243: | ||
| </ | </ | ||
| - | An ipset policy | + | The main syntax differences is each domain is separated using a comma ('','' |
| - | **Note:** The ipset chains must exist before being used or referenced | + | Like dnsmasq, an ipset policy |
| - | === DNS interception === | + | **Note:** The ipset chains must exist before being used or referenced as AGH does not initialise them. It is possible to potentially encounter a race condition on startup if the ipset chains are not created in time when AGH attempts to start. An alternative is creating a [[: |
| - | 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/ | + | ==== AGH as a NextDNS client ==== |
| + | |||
| + | AGH is recommended to be used with filtering disabled as a NextDNS client. [[https:// | ||
| + | |||
| + | ===== DNS Interception ===== | ||
| + | |||
| + | Some devices will bypass DHCP provided DNS servers e.g. Google | ||
| + | |||
| + | In order to make sure all DNS traffic goes through your primary DNS resolver, you can enforce this through | ||
| + | |||
| + | ==== IPTables (firewall3) ==== | ||
| + | |||
| + | Copy and paste these iptables | ||
| <code bash> | <code bash> | ||
| - | iptables -t nat -A PREROUTING -i br-lan -p udp --dport 53 -j DNAT --to 192.168.1.1: | ||
| iptables -t nat -A PREROUTING -i br-lan -p tcp --dport 53 -j DNAT --to 192.168.1.1: | iptables -t nat -A PREROUTING -i br-lan -p tcp --dport 53 -j DNAT --to 192.168.1.1: | ||
| + | iptables -t nat -A PREROUTING -i br-lan -p udp --dport 53 -j DNAT --to 192.168.1.1: | ||
| </ | </ | ||
| - | You can also implement this via a fw3 rule: | + | You can also implement this via a fw3 rule within ''/ |
| <code bash> | <code bash> | ||
| Line 187: | Line 281: | ||
| </ | </ | ||
| - | These examples are for IPv4 DNS traffic only. | + | These examples are for IPv4 DNS traffic only as they use DNAT. |
| + | |||
| + | [[: | ||
| + | |||
| + | ==== NFT Tables (firewall4) ==== | ||
| + | |||
| + | <code bash> | ||
| + | nft add rule nat pre udp dport 53 ip saddr 192.168.1.0/ | ||
| + | </ | ||
| + | This will redirect all DNS traffic from 192.168.1.0/ | ||
| + | |||
| + | ===== Bypassing encrypted DNS for NTP ===== | ||
| + | |||
| + | <WRAP important 100%> | ||
| + | In order for SSL to work the correct date/time MUST be set on the device. Not all routers have a Real Time Clock and thus must use NTP to update to the correct date/time on boot. As SSL will NOT work without the correct date/time you MUST bypass encrypted DNS to enable NTP updates to work. | ||
| + | </ | ||
| + | <WRAP important 100%> | ||
| + | Your router does NOT need encrypted DNS. Only your clients behind the router require filtering and encryption. Setting your router to use AGH as its DNS **WILL** result in failed NTP lookups unless you bypass encrypted lookups for NTP. This is **NOT** a recommended setup. Your router should have its own unencrypted upstream for NTP lookups. | ||
| + | </ | ||
| + | When using a upstream DNS setup that utilises DNS encryption e.g. DoT or DoH, you may come across a race condition on startup where communication to such DNS resolvers is not possible because of the NTP service not being able to establish a connection to a network time source and the set the correct time on your router. Given encrypted DNS relies on TLS/ | ||
| + | |||
| + | From the AdGuard Home web interface: **Settings** -> **DNS Settings** -> **Upstream DNS Servers** | ||
| + | |||
| + | Add the following to ensure any DNS request for NTP uses plain DNS. In this example, Cloudflare resolvers have been used. You can use any resolvers you like however. | ||
| + | |||
| + | < | ||
| + | [/ | ||
| + | [/ | ||
| + | [/ | ||
| + | [/ | ||
| + | </ | ||
| + | |||
| + | Click apply to enable these specific DNS rules. | ||
| + | |||
| + | ===== Debugging ===== | ||
| + | |||
| + | If AdGuard Home won't start, you will want to view error logs to understand why. | ||
| + | |||
| + | If using the opkg package you can view syslog for errors using '' | ||
| + | |||
| + | <code bash> | ||
| + | logread -e AdGuardHome | ||
| + | </ | ||
| + | |||
| + | You can also run AdGuardHome from command line and see the output directly. | ||
| + | |||
| + | <code bash> | ||
| + | AdGuardHome -v -c / | ||
| + | </ | ||
| + | |||
| + | This example uses the defaults set in the init script with the extra addition of the verbose flag. | ||
| + | |||
| + | * '' | ||
| + | * '' | ||
| + | * '' | ||
| + | * '' | ||
| + | |||
| + | The most common reason for AdGuard Home not starting is due to syntax errors in the '' | ||
| + | |||
| + | ===== Uninstalling ===== | ||
| + | This script uninstalls AGH and resets your router DNS to Google DNS. This is a known good default and should always work. | ||
| + | |||
| + | **Note:** If your router is not at '' | ||
| + | |||
| + | '' | ||
| + | <code bash> | ||
| + | #!/bin/sh | ||
| + | opkg update | ||
| + | service adguardhome stop | ||
| + | service adguardhome disable | ||
| + | opkg remove adguardhome | ||
| + | |||
| + | # 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=' | ||
| + | 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=" | ||
| + | uci set network.wan6.peerdns=" | ||
| + | |||
| + | # Configure DNS provider to Google DNS | ||
| + | uci -q delete network.wan.dns | ||
| + | uci add_list network.wan.dns=" | ||
| + | uci add_list network.wan.dns=" | ||
| + | |||
| + | # Configure IPv6 DNS provider to Google DNS | ||
| + | uci -q delete network.wan6.dns | ||
| + | uci add_list network.wan6.dns=" | ||
| + | uci add_list network.wan6.dns=" | ||
| + | |||
| + | # Save and apply | ||
| + | uci commit dhcp | ||
| + | uci commit network | ||
| + | / | ||
| + | / | ||
| + | / | ||
| + | </ | ||
| + | |||
| + | Reconnect your clients to apply the changes. | ||
| + | |||
| + | ===== Data Files ===== | ||
| + | |||
| + | The '' | ||
| + | < | ||
| + | root@OpenWrt:/ | ||
| + | drwxr-xr-x | ||
| + | drwxrwxrwx | ||
| + | drwxr-xr-x | ||
| + | -rw-r--r-- | ||
| + | -rw-r--r-- | ||
| + | -rw-r--r-- | ||
| + | -rw-r--r-- | ||
| + | </ | ||
| + | |||
| + | * '' | ||
| + | * '' | ||
| + | * '' | ||
| + | |||
| + | The filters folder contains all your filter downloads. Purge if it is full but AGH 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. | ||
| + | |||
| + | The '' | ||
| - | Further information on DNS Hijacking is here [[: | ||
| ===== References ===== | ===== References ===== | ||
| * [[https:// | * [[https:// | ||
| - | * [[https:// | ||
| * [[https:// | * [[https:// | ||
| + | * [[https:// | ||
| + | * [[https:// | ||