Skip to content

FAQ

Jump to bottom
Ainar Garipov edited this page Dec 15, 2021 · 32 revisions

AdGuard Home - FAQ

Why AdGuard Home doesn't block ads?

Suppose that AdGuard Home must block somebadsite.com but for some reason it doesn't. Let's try to resolve this issue.

Most likely you didn't configure your device to use AdGuard Home as its default DNS server. To check if you're using AdGuard Home as the default DNS server:

  1. On Windows, open a Terminal window (Start → Run → cmd.exe). On other systems, open your Terminal application.

  2. Execute nslookup example.org. It will print something like this:

    Server:         192.168.0.1
Address:        192.168.0.1#53

Non-authoritative answer:
Name:   example.org
Address: <IPv4>
Name:   example.org
Address: <IPv6>

  3. Check if the Server IP address is the one on which AdGuard Home is running. If no, then you need to configure your device, see below.

  4. Ensure that your request to example.org appears in the AdGuard Home UI on the Query Log page. If not, then you need to configure AdGuard Home to listen on the specified network interface. The most straightforward way to do so is to reinstall AdGuard Home with default settings.

Now that you are sure that your device uses AdGuard Home as its default DNS server, the problem might be in AdGuard Home misconfiguration. Please check and ensure that:

  1. You have the “Block domains using filters and hosts files” setting enabled on the “Settings → General settings” page.

  2. You have the appropriate safety mechanisms, such as parental control, enabled on the “Settings → General settings”.

  3. You have the appropriate filters enabled on the “Filters → DNS blocklists” page.

  4. You don't have any filters that may interfere enabled on the “Filters → DNS allowlists” page.

  5. You don't have any DNS rewrites that may interfere on the “Filters → DNS rewrites” page.

  6. You don't have any custom filtering rules that may interfere on the “Filters → Custom filtering rules” page.

How to configure AdGuard Home to write verbose-level logs?

To troubleshoot a complicated issue, the verbose-level logging is sometimes required. Here's how to enable it:

  1. Stop AdGuard Home:

    ./AdGuardHome -s stop

  2. Configure AdGuard Home to write verbose-level logs:

    1. Open AdGuardHome.yaml in your editor.

    2. Set log_file to the desired path of the log file, for example /tmp/aghlog.txt. Note that the directory must exist.

    3. Set verbose to true.

  3. Restart AdGuard Home and reproduce the issue:

    ./AdGuardHome -s start

How to show a custom block page?

A note about HTTPS

Before doing any of this, please note that modern browsers are set up to use HTTPS, and so they validate the certificate of the web server they're trying to reach for authenticity. That means that using any of these will result in warning screens.

There are a couple of proposed extensions that, when they become reasonably well supported by clients, would allow for a better user experience, including the RFC 8914 Extended DNS Error codes and the DNS Access Denied Error Page RFC draft. We'll implement them when browsers actually start to support them.

Prerequisites

To use any of these ways to show a custom block page, you'll need an HTTP server running on some IP address and serving the page in question on all routes. Something like pixelserv-tls.

Custom block page for parental control and safe browsing filters

There is currently no way to set these parameters from the UI, so you'll need to edit the configuration file manually:

  1. Stop AdGuard Home:

    ./AdGuardHome -s stop

  2. Open AdGuardHome.yaml in your editor.

  3. Set the dns.parental_block_host or dns.safebrowsing_block_host settings to the IP address of the server (in this example, 192.168.123.45):

    # …
dns:
  # …

  # NOTE: Change to the actual IP address of your server.
  parental_block_host: 192.168.123.45
  safebrowsing_block_host: 192.168.123.45

  4. Restart AdGuard Home:

    ./AdGuardHome -s start

Custom block page for other filters

  1. Open the web UI.

  2. Open the “Settings → DNS settings” page.

  3. In the “DNS server configuration” section, select the “Custom IP” radio button in the “Blocking mode” selector and enter the IPv4 and IPv6 addresses of the server.

  4. Click “Save”.

After installing AdGuard Home, how to change dashboard interface's address?

  1. Stop AdGuard Home:

    ./AdGuardHome -s stop

  2. Open AdGuardHome.yaml in your editor.

  3. Set the bind_host setting to a new network interface. For example:

    • 0.0.0.0 to listen on all network interfaces.

    • 127.0.0.1 to listen on the local loopback interface only.

  4. Optionally, set the bind_port setting to set a new port.

  5. Restart AdGuard Home:

    ./AdGuardHome -s start

How to set up AdGuard Home as default DNS server?

Router

This setup will automatically cover all devices connected to your home router, and you won't need to configure each of them manually.

  1. Open the preferences for your router. Usually, you can access it from your browser via a URL, such as http://192.168.0.1/ or http://192.168.1.1/. You may be prompted to enter a password. If you don't remember it, you can often reset the password by pressing a button on the router itself, but be aware that if this procedure is chosen, you will probably lose the entire router configuration. If your router requires an app to set it up, please install the app on your phone or PC and use it to access the router’s settings.

  2. Find the DHCP/DNS settings. Look for the DNS letters next to a field which allows two or three sets of numbers, each broken into four groups of one to three digits.

  3. Enter your AdGuard Home server addresses there.

  4. On some router types, a custom DNS server cannot be set up. In that case, setting up AdGuard Home as a DHCP server may help. Otherwise, you should check the router manual on how to customize DNS servers on your specific router model.

Windows

  1. Open Control Panel through Start menu or Windows search.

  2. Go to Network and Internet category and then to Network and Sharing Center.

  3. On the left side of the screen find “Change adapter settings” and click on it.

  4. Select your active connection, right-click on it and choose Properties.

  5. Find “Internet Protocol Version 4 (TCP/IPv4)” (or, for IPv6, “Internet Protocol Version 6 (TCP/IPv6)”) in the list, select it and then click on Properties again.

  6. Choose “Use the following DNS server addresses” and enter your AdGuard Home server addresses.

macOS

  1. Click on Apple icon and go to System Preferences.

  2. Click on Network.

  3. Select the first connection in your list and click Advanced.

  4. Select the DNS tab and enter your AdGuard Home server addresses.

Android

  1. From the Android Menu home screen, tap Settings.

  2. Tap Wi-Fi on the menu. The screen listing all of the available networks will be shown (it is impossible to set custom DNS for mobile connection).

  3. Long press the network you're connected to and tap Modify Network.

  4. On some devices, you may need to check the box for Advanced to see further settings. To adjust your Android DNS settings, you will need to switch the IP settings from DHCP to Static.

  5. Change set DNS 1 and DNS 2 values to your AdGuard Home server addresses.

iOS

  1. From the home screen, tap Settings.

  2. Choose Wi-Fi in the left menu (it is impossible to configure DNS for mobile networks).

  3. Tap on the name of the currently active network.

  4. In the DNS field enter your AdGuard Home server addresses.

Are there any known limitations?

Here are some examples of what cannot be blocked by a DNS-level blocker:

  • YouTube, Twitch ads.

  • Facebook, Twitter, Instagram sponsored posts.

Essentially, any advertising that shares a domain with content cannot be blocked by a DNS-level blocker.

Is there a chance to handle this in the future?

DNS will never be enough to do this. Your only option is to use a content blocking proxy like what we do in the standalone AdGuard applications. We're going to bring this feature support to AdGuard Home in the future. Unfortunately, even in this case, there still will be cases when this won't be enough or would require quite complicated configuration.

Why am I getting bind: address already in use error when trying to install on Ubuntu?

Because 127.0.0.1:53, which is used for DNS, is already occupied by another program.

The easiest solution would be simply to choose a different network interface and bind it to your external IP (for instance, your Wi-Fi IP).

If for some reason you really want to bind to 127.0.0.1, read the explanation below.

Ubuntu comes with a local DNS server by default called systemd-resolved, which uses port 53 and thus prevents AdGuard Home from binding to it. To fix this, disable the systemd-resolved daemon. Luckily, AdGuard Home can detect such configurations and disable systemd-resolved for you if you press "Fix" button which is shown near the address already in use message.

Note that if you're using AdGuard Home with docker or snap, you'll have to do it yourself by following these steps:

  1. Deactivate DNSStubListener and update DNS server address. Create a new file: /etc/systemd/resolved.conf.d/adguardhome.conf (create a /etc/systemd/resolved.conf.d directory if necessary) with the following content:

    [Resolve]
DNS=127.0.0.1
DNSStubListener=no

  2. Specifying 127.0.0.1 as DNS server address is necessary because otherwise the nameserver will be 127.0.0.53 which doesn't work without DNSStubListener.

  3. Activate another resolv.conf file:

    sudo mv /etc/resolv.conf /etc/resolv.conf.backup
sudo ln -s /run/systemd/resolve/resolv.conf /etc/resolv.conf

  4. Restart DNSStubListener:

    systemctl reload-or-restart systemd-resolved

How to configure a reverse proxy server for AdGuard Home?

If you're running a web server already and you want to access AdGuard Home dashboard UI from an URL like http://YOUR_SERVER/aghome/ you can use this configuration for your web server:

nginx

location /aghome/ {
    proxy_pass http://AGH_IP:AGH_PORT/;
    proxy_redirect / /aghome/;
    proxy_cookie_path / /aghome/;
}

caddy

:80/aghome/* {
    route {
        uri strip_prefix /aghome
        reverse_proxy AGH_IP:AGH_PORT
    }
}

Or, if you just want to serve AdGuard Home with automatic TLS, something similar to:

DOMAIN {
    encode gzip zstd
    tls YOUR_EMAIL@DOMAIN
    reverse_proxy AGH_IP:AGH_PORT
}

Disable DoH encryption on AdGuard Home

When you use TLS on your reverse proxy server, there's no need to use TLS on AdGuard Home. Set allow_unencrypted_doh: false in AdGuardHome.yaml to allow AdGuard Home respond to DoH requests without TLS encryption.

How to fix permission denied errors on Fedora?

  1. Move the AdGuardHome binary to /usr/local/bin.

  2. As root, execute the following command to change the security context of the file:

    chcon -t bin_t /usr/local/bin/AdGuardHome

  3. Add the required firewall rules in order to make it reachable through the network. For example:

    firewall-cmd --new-zone=adguard --permanent
firewall-cmd --zone=adguard --add-source=192.168.0.14/24 --permanent
firewall-cmd --zone=adguard --add-port=3000/tcp --permanent
firewall-cmd --zone=adguard --add-port=53/udp --permanent
firewall-cmd --zone=adguard --add-port=80/tcp --permanent
firewall-cmd --reload

See issue 765.

How to uninstall AdGuard Home?

The way to uninstall AdGuard Home depends on how you installed it.

IMPORTANT: After uninstalling AdGuard Home, don't forget to change your devices configuration and point them to a different DNS server.

Regular installation

In this case you need to do the following:

  • Unregister AdGuard Home service: ./AdGuardHome -s uninstall.

  • Remove the AdGuard Home directory.

Docker

Simply stop and remove the image.

Snap Store

snap remove adguard-home

Guides

Clone this wiki locally