Adguard Home Setup

Overview

Setup Adguard Home on Podman or Docker.

Assumptions

• Podman Setup completed.

• NPM Setup completed.

Configure System

Configure the host system based on the Adguard Home services that will be used.

Privileged Ports

To allow Adguard Home to bind to privileged ports, add unprivileged port rules to the sysctl configuration directory.

sudo vim /etc/sysctl.d/90-unprivileged-port-start.conf

If the unprivileged port starting value is less than 53, lower the value to 53. This value needs to be the lowest port that any unprivileged any container is binding to.

net.ipv4.ip_unprivileged_port_start=53

Apply sysctl changes.

sudo sysctl --system

Firewall

Open port 53 on the firewall for Adguard Home.

sudo firewall-cmd --permanent --zone=public --add-port=53/tcp

sudo firewall-cmd --permanent --zone=public --add-port=53/udp

Reload the firwall to apply changes.

sudo firewall-cmd --reload

Compose File

Create a compose file to deploy Adguard Home. When using Portainer, deploy it as a Stack. Uncomment and define container_name for explicit container names. The following example assumes the NPM local network is defined in the NPM compose file. Remove this if deploying Adguard Home standalone. After completing initial setup, uncomment the 8989:80/tcp port map and delete 8989:3000/tcp. Consider changing the restart policy to on-failure after verifying everything works.

services:
  agh:
    image: adguard/adguardhome:latest
    #container_name: agh
    restart: unless-stopped
    #restart: on-failure:5
    security_opt:
      - no-new-privileges:true
    cap_add:
      - NET_BIND_SERVICE
    ports:
      - 8989:3000/tcp
      #- 8989:80/tcp
      - 53:53/tcp
      - 53:53/udp
    volumes:
      - agh_data:/opt/adguardhome/work
      - agh_conf:/opt/adguardhome/conf
    networks:
      - npm_npm_local
    healthcheck:
      test: ['CMD', 'curl', '-f', 'http://localhost:80/']
      interval: 60s
      timeout: 10s
      retries: 5
      start_period: 30s

volumes:
  agh_data:
  agh_conf:

networks:
  npm_npm_local:
    external: true

NPM Proxy Host

Add a Nginx Proxy Manager proxy host for the Adguard service.

From the Nginx Proxy Manager dashboard, select Proxy Hosts under Hosts.

Select Add Proxy Host from the Proxy Hosts dashboard.

Proxy Host Details

Configure the new proxy host details.

Proxy Host SSL

Switch to the SSL tab for the new proxy host and configure it to use the generated certificate.

Proxy Host Connect

Save the new proxy host and view the added host in the proxy hosts list.

If a local DNS server is setup, verify there is a wildcard entry for the local server or create one specifially for Adguard.

If there is no local DNS server yet, add a custom host entry to /etc/hosts.

sudo nano /etc/hosts

Add the required domain(s) and point them to the host server IP address.

172.16.13.13 system.example.com
172.16.13.13 npm.system.example.com
172.16.13.13 adguard.system.example.com

Navigate to the Adguard service with the configured domain, no port required if Nginx Proxy Manager was assigned port 80/443.

https://adguard.system.example.com/

Initial Setup

Setup Wizard

Navigate to the configured domain to access the Adguard Home initial setup wizard. A “Welcome to AdGuard Home” prompt should be presented, select Get Started.

Verify the default configuration is suitable, in most cases it can be left unchanged. If port 80 is modified here, make note of that for later when finalising the compose file.

Define a new admin user and generate a secure password.

Review the information on the final pages of the wizard, when finished select Open Dashboard and note how it probably does not work yet. This is because port 8989 was mapped to 3000 for initial setup. Proceed to adjusting the compose file to match port 80 or whatever was configured.

Adjust Compose File

With Adguard Home setup completed, the web port needs to be adjusted in the compose file.

Under ports, replace 3000 with 80 for the 8989 port mapping (included in a comment in initial compose file). Port 3000 is only used for the initial setup wizard.

ports:
  - 8989:80/tcp
  - 53:53/tcp
  - 53:53/udp

Restart the container or stack and proceed to the Adguard Home dashboard. This time a login screen will be presented and the Adguard Home dashboard will be accessible.

https://adguard.system.example.com/

Configure Adguard Home

General Settings

Navigate to Settings - General Settings in the AdGuard Home dashboard. Review the default configuration, suitable as-is for most users. Consider disabling query logs under Logs Configuration.

DNS Settings

Define DNS servers to use for upstream, fallback, and bootstrap DNS.

Upstream DNS

• Cloudflare
  • DoT: tls://one.one.one.one
  • DoH: https://one.one.one.one/dns-query
• Mullvad
  • DoT: tls://dns.mullvad.net
  • DoH: https://dns.mullvad.net/dns-query
• Quad 9
  • DoT: tls://dns.quad9.net
  • DoH: https://dns.quad9.net/dns-query

Bootstrap DNS

• Cloudflare
  • IPv4: 1.1.1.1 / 1.0.0.1
  • IPv6: 2606:4700:4700::1111 / 2606:4700:4700::1001
• Mullvad
  • IPv4: 194.242.2.2
  • IPv6: 2a07:e340::2
• Quad9:
  • IPv4: 9.9.9.9 / 149.112.112.112
  • IPv6: 2620:fe::fe / 2620:fe::9

Encryption Settings

With Nginx Proxy Manager infront of Adguard Home, DNS over HTTPS can be configured by allowing unencrypted DoH queries in Adguard Home. Nginx Proxy Manager will handle TLS termination for the queries, as already configured, and the unencrypted queries will only happen over the local NPM network.

An alternative approach is to add the Lets Encrypt Certbot container to the Adguard Home stack. This would have the benefit of allowing DoT and DoQ to work, as only DoH will work with the reverse proxy method.

On the host system, switch to the rootless Podman user to adjust container configurations.

sudo machinectl shell --uid=podmanu

Modify the AdGuardHome.yaml file in the configuration volume for Adguard Home.

vim $HOME/.local/share/containers/storage/volumes/agh_agh_conf/_data/AdGuardHome.yaml

Update the TLS configuration section for Adguard Home, making the following notable changes.

tls:
  enabled: true
  server_name: ""
  force_https: false
  port_https: 443
  port_dns_over_tls: 853
  port_dns_over_quic: 853
  port_dnscrypt: 0
  dnscrypt_config_file: ""
  allow_unencrypted_doh: true
  certificate_chain: ""
  private_key: ""
  certificate_path: ""
  private_key_path: ""
  strict_sni_check: false

Connect

Configure client systems to use Adguard Home for DNS queries with standard DNS on port 53 or with DNS over HTTPS.

On the client, define the DNS server as the IP address of host system. Port does not need to be specified when using port 53.

172.16.13.13
172.16.13.13:53

On the client or with client applications, use the DoH endpoint for queries. This will be the domain name used to access the Adguard Home dashboard with the dns-query path.

https://adguard.system.example.com/dns-query

References

^{1 2 3 4 5 6 7 8 9 10}