# AdGuard Home

AdGuard Home is not a DNS server in the traditional sense; rather, it is a DNS proxy. It does not store a database with all DNS entries itself. Instead, it asks other "upstream" servers for the response. In addition, AdGuard Home can compare the incoming DNS requests to ad-blocking filter lists and block requests that point towards advertising sources.

This means two things: firstly, the upstream DNS servers resolving your requests no longer know your personal IP address and the websites visited by this IP address. They only see the IP address of your server. Additionally, AdGuard Home can spread your requests across many different upstream servers, further improving your anonymity.

Secondly, and this is the main benefit, the filter lists allow for a network-wide ad-blocking experience on every device you have, including in the browser, in apps, and in the operating systems themselves. This feature works regardless of whether the actual devices provide you the option to configure ad-blocking. Additionally, any changes made to your filter lists are automatically applied to every connected device.

There are four differenct methods with which a device can make a DNS request to a DNS resolver:

The decision of which DNS method to use heavily depends on the devices you use daily. If you (or your users) use Android phones, you should offer DoT support. If you need to connect Windows devices, you should look into DoH support. Alternatively, if your home router supports one method or the other, you can use the DNS on the router level don't need to worry about your hardwired home devices anymore (e.g., TV, PC, consoles, and so on).

DoH is the easiest protocol to set up, and the other protocols build on top of the DoH requirements for their functionality. Therefore you only need to decide if you want the additional DoT support or not.

To use encrypted DNS methods like DoT and DoH, you need an SSL certificate. There are many ways to acquire an SSL certificate, but since Nginx can generate and manage certificates for free and is already running anyways, we'll simply use that to do the job for us.

To start, go into your Nginx interface and switch to the SSL Certificates tab. Here, click on Add SSL Certificate and choose Let's Encrypt. In the popup window, enter the domain name you want to serve DNS requests on, once directly and once with a wildcard (e.g. dns.your.domain and *.dns.your.domain). Enter an email address (it should be a real one you're reachable under), tick Use a DNS Challenge and select Cloudflare as your DNS provider.

To continue, you need a Cloudflare API key, which you can create under https://dash.cloudflare.com/?to=/profile/api-tokens. On this page, click on Create Token, followed by Edit zone DNS: Use Template. On the new screen, under Zone Resources, select your domain. You can also enter your servers IP addresses (both IPv4 and IPv6) to further ensure only that server can use the API key in case it gets leaked. I've chosen to not limit this to ensure no future issues, and instead opted for not saving the API key anywhere. When you're done setting things up, click on Continue to Summary, followed by Create Token and Copy on the token field.

Now, switch back to your Nginx tab where you should still have the "DNS Challenge" Window open. Replace the placeholder value with your generated token. Finally, agree to the ToS and save your certificate. It might load for a while, while it's working with Cloudflare to create the certificate, but it shouldn't take too long.

Once it's done, you need to confirm the certificate ID. To do so, find the certificate in your SSL Certificate list, click on the three dots to the right and note down the number from the first line. For example, if it says Certificate #10, you need to note down the number 10.

To get a basic AdGuard instance up and running, open your terminal, create a new work directory for your AdGuard config and add the compose.yml:

services:
  adguard:
    image: adguard/adguardhome
    container_name: adguard
    restart: unless-stopped
    # ports:
    #   - 853:853/tcp
    volumes:
      - work:/opt/adguardhome/work
      - conf:/opt/adguardhome/conf
      - nginx_nginx:/opt/adguardhome/cert:ro
    networks:
      - nginx_default

volumes:
  work:
  conf:
  nginx_nginx:
    external: true

networks:
  nginx_default:
    external: true

This will create two new volumes for AdGuards work and config files, and also mount the existing Nginx volume, which contains the SSL certificate you just created. Start the container with docker compose up -d and let it set up its configuration. Once it's done, open your Nginx interface and add a new host:

• Domain Name: dns.your.domain (or whichever else you generated the SSL certificate for)
• Forward Hostname: adguard
• Port: 3000
• Block Common Exploits: true

Select your Cloudflare SSL Certificate in the SSL tab, not the one you just generated. You can now access your admin panel under the domain you configured and go through the initial setup steps. On the first page, set the Admin interface port to 3000, while ignoring every other setting. Create your admin user at the end, finish the setup, and re-enter the apps' web address into your address bar. You should now be able to log into the AdGuard interface.

To enable encryption for DoH, as well as the other protocols, look at the top bar and click on Settings > Encryption Settings, and set the following values:

1. Enable Encryption
2. Server Name: the server name you want to resolve DNS requests under, e.g. dns.your.domain
3. Set HTTPS port to 443 and emptry the other two fields
4. Under certificates, click Set a file path for both options, and enter the following in the respective fields:
   • Earlier, you noted down the SSL certificate ID. Replace the questionmarks in npm-?? with that number.
   • Field 1: /opt/adguardhome/cert/live/npm-??/fullchain.pem
   • Field 2: /opt/adguardhome/cert/live/npm-??/privkey.pem

$ docker exec adguard ls /opt/adguardhome/cert/live/
README
npm-10

Once both fields get a green label, click on "Save configuration". Immediately after this, the website will no longer be reachable, which is normal. To fix it, switch back to Nginx, edit your AdGuard host configuration, and change the application port from 3000 to 443. After saving, the AdGuard website will be reachable again, and you can continue setting the app up.

If you want to add DoT support to your DNS, you need to go through some additional steps to get it all working. Read more about that here.

Once you've finished setting up AdGuard with the method you desire, you can continue here to finish setting up AdGuard.

The settings here are quite opinionated and depend on how you want to use the instance. Should you be uncertain, feel free to fall back to these exemplatory values:

• Check "Block domains using filters" and "Use AdGuard browsing security"
• Check "Enable Log" and set a Query log retention of 24 hours
• Check "Enable Statistics" and set a Statistics retention of 24 hours

As mentioned in the method guides, you're able and encouraged to use Client IDs to tell apart the different devices accessing your service. This makes the logs clearer, provides better statistics, and allows to tell which devices might be accessing infected sources.

While you don't need to need to add these clients here, doing so allows you to join multiple clients into one entry (my-phone and my-laptop as one client, and dads-phone as another client). It also allows to use different filtering settings per client, which can be useful in certain situations.

To add a persistent client, click on Add Client and enter the Client name which will show up in the interface, the client tags with which you can categorize the device, and the identifier that you're using on the device in the configured DNS address (e.g. phone from phone.dns.your.domain).

As explained in the introduction, AdGuard is dependant on other "upstream" DNS servers to get its responses. On this page, you enter these servers you want AdGuard to use. It is recommended to chose servers that are close to both you and your VPS for fast responses, as well as servers that have good privacy policies and support encrypted DNS channels. You should do research on the available providers in your country. As a general starting point, refer to this article.

Once you've entered your desired DNS servers, change the request mode setting to Parallel requests for maximum speed.

Under Bootstrap DNS servers, supply the unencrypted addresses of some of the major DNS providers, e.g. Cloudflare (1.1.1.1 & 1.0.0.1), Quad9 (9.9.9.9 & 149.112.112.112) or Google (8.8.8.8 & 8.8.4.4). These servers will only be used to resolve the names of your main DNS servers, nothing else.

Finally, check Enable reverse resolving of clients' IP addresses for some extra information in your query logs and save.

• Set Rate limit to 6
• Check Enable EDNS and Enable DNSSEC

• Cache Size to 10000000
• Minimum TTL to 7200 (equals 2 hours)
• Maximum TTL to 172800 (equals 48 hours)

If you want to limit the devices that are able to use your service, you can enter a list of Client IDs in this field. As soon as you enter a single entry here and save, access from anything not on the list will be denied, so be careful to enter every device identifier you are using.

The DNS blocklists page under Filters contains the list of adblock-lists that the DNS server should deny access to, and is where you configure the adblocking behaviour of the server. To get started, click on Add blocklist and Choose from the list to get a handy list of sources to quickly add.

Which lists to add is very opinionated. Be aware however that higher amounts of total rules also increase the RAM consumption of the app, and negatively affect the response time of every request. Don't simply add every list there is, but pick the most efficient ones carefully. You can always check the query logs and see which lists are blocking requests and disable ones that don't do any work.

You've finished all the steps and now have a fully functioning and ad-blocking DNS server at your hands. You can check in every once in a while and feel happiness over all the ads and trackers you've successfully blocked.