docudjeex/content/en/3.serveex/9.apps/1.adguard.md

title, description

title	description
Adguard Home	Install AdGuard Home for network-wide ad and tracker blocking with DNS-over-HTTPS, client management, and custom filtering rules.

:ellipsis{left=0px width=40rem top=10rem blur=140px zIndex=60}

Adguard Home

::note 🎯 Goals:

• Install and deploy Adguard
• Expose Adguard
• Secure DNS queries with SSL/TLS
• Configure client devices ::

AdGuard Home is a DNS server that blocks ads and tracking at the system level. Once configured, it will protect ALL your home devices without the need for any client-side software.

It works as a DNS server that redirects tracking domains to a “black hole,” preventing your devices from connecting to them.

In practice, once it's in place, all you need to do is set your devices to use Adguard as their DNS server.

Quick reminder of how DNS works:

When you visit a site or use an app, it makes requests to various domains to load content, ads in particular. Your device doesn’t know the IP addresses of these domains, so it contacts a Domain Name Server (DNS), which returns the current IP address.

By default, your device uses your ISP's DNS server, which is usually configured in your router or, for mobile devices, at the carrier’s CGNAT level. You can change this in your browser settings, your device’s system settings, or even directly in your router, depending on your ISP.

Adguard will act as a middleman between your device and the upstream DNS servers. If you configure your devices to use Adguard:

• If the domain is not in a blocklist, Adguard queries the upstream DNS servers and returns the correct IP to your device.
• If the domain is in a blocklist, Adguard will block the request and return nothing, so the associated content won’t load.

This is how ads and malicious domains are blocked: Adguard blocks only the bad domains, allowing the rest of the page to load normally.

Installation

::file-tree

tree: /: - docker: - adguard: - confdir/ - workdir/ - compose.yaml - .env

::

::note

We will also mount the /docker/swag/config/etc/letsencrypt folder to access Swag's SSL certificate. ::

Open Dockge and click compose

Name the stack adguardhome and paste the configuration below:

---
services:
  adguardhome:
    container_name: adguard
    image: adguard/adguardhome
    restart: unless-stopped
    ports:

      - 53:53/udp
      - 8080:80/tcp
      - 4443:443/tcp
      - 853:853/tcp
      - 3000:3000/tcp
    volumes:

      - /docker/adguardhome/confdir:/opt/adguardhome/conf
      - /docker/adguardhome/workdir:/opt/adguardhome/work
      - /docker/swag/config/etc/letsencrypt:/swag-ssl:ro

::tip{icon=""} ✨ Tip: Add the watchtower label to each container to automate updates

services:
  adguardhome:
    # ...
    labels:

      - com.centurylinklabs.watchtower.enable=true

::

Deploy the stack.

Go to http://yourserverip:3000 and follow the setup instructions.

That’s it! Adguard is deployed.

Exposing AdGuard with SWAG

To make AdGuard usable from outside your home network, you need to expose it.

::note

Prerequisites: We assume you've created a subdomain like adguard.mydomain.com in your DNS zone with a CNAME pointing to mydomain.com, and that you’ve already forwarded port 443 from your router to port 443 on your server in your NAT rules. Also forward port 53 and port 853 to your server. These ports are used to route DNS requests. ::

::warning

Do not use Cloudflare tunnels to expose AdGuard, and make sure any proxying is disabled. ::

In Dockge, go to the SWAG stack and edit the compose file to add the AdGuard network:

services:
  swag:
     container_name: # ...
      # ... 
     networks:             # Connect the container to the custom network 
      # ...           

      - adguard            # Name of the network declared in the stack
    
networks:                  # Define the custom network
  # ...
  adguard:                 # Name of the network declared in the stack
    name: adguard_default  # Actual name of the external network
    external: true         # Specifies that this is an external network

::note

We assume here that the AdGuard network is named adguard_default. You can verify the connection is working by visiting the SWAG dashboard at http://yourserverip:81. ::

Restart the stack by clicking "Deploy" and wait for SWAG to be fully operational.

Create and open the file adguard.subdomain.conf

::tip{icon=""} ✨ Tip for terminal haters: You can use File Browser Quantum to browse and edit files instead of using terminal commands. ::

sudo nano /docker/swag/config/nginx/proxy-confs/adguard.subdomain.conf

Paste the configuration below:

## Version 2023/05/31
# make sure that your adguard container is named adguard
# make sure that your dns has a cname set for adguard

server {
    listen 443 ssl;
    listen [::]:443 ssl;

    server_name adguard.*;

    include /config/nginx/ssl.conf;

    client_max_body_size 0;

    #if ($lan-ip = yes) { set $geo-whitelist yes; }
    #if ($geo-whitelist = no) { return 404; }
    if ($geo-blacklist = no) { return 404; }

    # enable for ldap auth (requires ldap-location.conf in the location block)
    #include /config/nginx/ldap-server.conf;

    # enable for Authelia (requires authelia-location.conf in the location block)
    #include /config/nginx/authelia-server.conf;

    # enable for Authentik (requires authentik-location.conf in the location block)
    #include /config/nginx/authentik-server.conf;

    location / {
        # enable the next two lines for http auth
        #auth_basic "Restricted";
        #auth_basic_user_file /config/nginx/.htpasswd;

        # enable for ldap auth (requires ldap-server.conf in the server block)
        #include /config/nginx/ldap-location.conf;

        # enable for Authelia (requires authelia-server.conf in the server block)
        #include /config/nginx/authelia-location.conf;

        # enable for Authentik (requires authentik-server.conf in the server block)
        #include /config/nginx/authentik-location.conf;

        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        set $upstream_app adguard;
        set $upstream_port 3000;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;

    }

    location /control {
        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        set $upstream_app adguard;
        set $upstream_port 3000;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;

    }

    location /dns-query {
        # to properly use this please set `allow_unencrypted_doh: true` and `force_https: false` in adguard
        # see https://github.com/AdguardTeam/AdGuardHome/wiki/Configuration#configuration-file
        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        set $upstream_app adguard;
        set $upstream_port 3000;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;

    }
}

Protecting AdGuard with TinyAuth

Add TinyAuth's forward-auth check directly to adguard.subdomain.conf, the same way as the TinyAuth guide. The /dns-query location is left out of the auth_request check, since DNS-over-HTTPS clients can't do an interactive login:

## Version 2023/05/31
# make sure that your adguard container is named adguard
# make sure that your dns has a cname set for adguard

server {
    listen 443 ssl;
    listen [::]:443 ssl;

    server_name adguard.*;

    include /config/nginx/ssl.conf;

    client_max_body_size 0;

    #if ($lan-ip = yes) { set $geo-whitelist yes; }
    #if ($geo-whitelist = no) { return 404; }
    if ($geo-blacklist = no) { return 404; }

    # enable for ldap auth (requires ldap-location.conf in the location block)
    #include /config/nginx/ldap-server.conf;

    # enable for Authelia (requires authelia-location.conf in the location block)
    #include /config/nginx/authelia-server.conf;

    # enable for Authentik (requires authentik-location.conf in the location block)
    #include /config/nginx/authentik-server.conf;

    location /tinyauth {
        internal;
        proxy_pass http://tinyauth:3000/api/auth/nginx;
        proxy_pass_request_body off;
        proxy_set_header Content-Length "";
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $http_host;
        proxy_set_header X-Forwarded-Uri $request_uri;
    }

    location @tinyauth_login {
        return 302 https://tinyauth.mydomain.com/login?redirect_uri=$scheme://$http_host$request_uri;
    }

    location / {
        auth_request /tinyauth;
        error_page 401 = @tinyauth_login;

        # enable the next two lines for http auth
        #auth_basic "Restricted";
        #auth_basic_user_file /config/nginx/.htpasswd;

        # enable for ldap auth (requires ldap-server.conf in the server block)
        #include /config/nginx/ldap-location.conf;

        # enable for Authelia (requires authelia-server.conf in the server block)
        #include /config/nginx/authelia-location.conf;

        # enable for Authentik (requires authentik-server.conf in the server block)
        #include /config/nginx/authentik-location.conf;

        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        set $upstream_app adguard;
        set $upstream_port 3000;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;

    }

    location /control {
        auth_request /tinyauth;
        error_page 401 = @tinyauth_login;

        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        set $upstream_app adguard;
        set $upstream_port 3000;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;

    }

    location /dns-query {
        # to properly use this please set `allow_unencrypted_doh: true` and `force_https: false` in adguard
        # see https://github.com/AdguardTeam/AdGuardHome/wiki/Configuration#configuration-file
        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        set $upstream_app adguard;
        set $upstream_port 3000;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;

    }
}

::note

The location /tinyauth block runs inside SWAG's own container, so SWAG needs to be on TinyAuth's Docker network to reach it by name (tinyauth here). This should already be set up from exposing TinyAuth itself. If you run into an error, double-check SWAG's compose file still has that network attached. ::

::tip{icon=""} ✨ Tip:

You can protect this app with Authentik instead of TinyAuth by opening adguard.subdomain.conf and removing the # in front of include /config/nginx/authentik-server.conf;{lang=nginx} and include /config/nginx/authentik-location.conf;{lang=nginx}. Don’t forget to create an application and a provider in Authentik. You’ll need to exclude the URL https://adguard.mydomain.com/dns-query from authentication:

• Edit the AdGuard provider
• Under Advanced Protocol Settings > Authenticated Paths, enter ^/dns-query ::

Press :kbd{value="Ctrl+O"}, then :kbd{value="Enter"} to save, and :kbd{value="Ctrl+X"} to exit.

And that's it! AdGuard is now exposed!

Configure SSL/TLS Encryption

Encryption is essential if you want to keep your queries to AdGuard private. Encrypting your queries ensures that no one, not even your ISP, can see your history. It also ensures that only your server can respond to you.

To configure encryption:

• Go to Settings then Encryption.
• Set the options as follows:

• Below, in the Certificates section, check Use file path for certificate
• In the input field, enter /swag-ssl/live/mydomain.com/fullchain.pem, replacing mydomain.com with your actual domain.
• For Private Key, check Use file path for private key
• In the input field, enter /swag-ssl/live/mydomain.com/privkey.pem, replacing mydomain.com accordingly.
• Save

Done! Your future DNS queries are now protected!

Configure Devices

You have several options (which you can combine) to configure your devices.

Secure the Local Network

You can secure your local network with AdGuard by configuring your router to direct all DNS queries by default to AdGuard instead of your ISP’s DNS. Note: your router must allow DNS changes (Orange routers do not).

This option is usually in the DHCP settings. Make sure to add a fallback DNS server such as:

• Cloudflare: 1.1.1.1
• Google: 8.8.8.8

Without this, if your server goes down, your devices will lose internet access.

::note

Some devices may have a separate DNS configured and may not use the router’s DNS. ::

Force a Browser to Use AdGuard

In your browser, you can configure a DNS to force it to use AdGuard Home. In the settings, specify the address https://adguard.mydomain.com/dns-query

Configure AdGuard at the System Level on Windows

In Windows, you need to configure AdGuard for each network adapter you want to use.

• Go to Home > Network & Internet, then select the network adapter to modify
• Click Edit DNS (sometimes under Hardware Properties)
• Choose Manual
• Enable IPv4
• Enter your server’s public IP (the one accessible from the internet)
• Enable DNS over HTTPS (manual template)
• Disable Fallback to plaintext
• Save

All programs using that network adapter will now be filtered by AdGuard.

Add Filters

• Go to the settings and change the filters.