AdGuard Home Installation and Configuration

AdGuard Home is a self-hosted DNS server with built-in ad blocking, privacy filtering, and encrypted DNS support (DNS-over-HTTPS and DNS-over-TLS) for your entire network. This guide covers deploying AdGuard Home on Linux, configuring filtering rules, managing clients, and enabling encrypted DNS protocols.

Prerequisites

  • Ubuntu 22.04/Debian 12 or CentOS/Rocky 9
  • Static IP address
  • Root or sudo access
  • A domain name with a valid TLS certificate (for DoH/DoT)
  • Ports 53, 80, 443, 3000 (setup) available

Install AdGuard Home

# Download and install using the official script
curl -sSL https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh \
  | sudo sh -s -- -v

# The script installs AdGuard Home to /opt/AdGuardHome/
# and registers it as a systemd service

# Check installation
ls /opt/AdGuardHome/
sudo systemctl status AdGuardHome

For manual installation:

# Download the latest release
AGH_VERSION=v0.107.45
curl -L "https://github.com/AdguardTeam/AdGuardHome/releases/download/${AGH_VERSION}/AdGuardHome_linux_amd64.tar.gz" \
  -o /tmp/AdGuardHome.tar.gz

tar xvf /tmp/AdGuardHome.tar.gz -C /opt/
cd /opt/AdGuardHome

# Install as a service
sudo ./AdGuardHome -s install

# Check status
sudo systemctl status AdGuardHome

Initial Setup

Access the setup wizard before the service is fully running:

# Open port 3000 temporarily for the setup wizard
sudo ufw allow 3000/tcp

# The wizard runs at:
# http://your-server-ip:3000

Walk through the setup wizard:

  1. Set the admin username and password
  2. Choose the DNS listening port (53)
  3. Choose the web interface port (3000, change to 80 after setup)
  4. Select upstream DNS servers

After completing setup, AdGuard Home stores its configuration at /opt/AdGuardHome/AdGuardHome.yaml.

# Close the setup port and allow standard DNS/HTTP
sudo ufw deny 3000/tcp
sudo ufw allow 53/tcp
sudo ufw allow 53/udp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

DNS Upstream Configuration

Configure upstream DNS servers via the web interface or directly in the YAML config:

sudo nano /opt/AdGuardHome/AdGuardHome.yaml

dns:
  upstream_dns:
    # Cloudflare DNS-over-HTTPS
    - https://dns.cloudflare.com/dns-query
    # Quad9 DNS-over-TLS
    - tls://dns.quad9.net
    # Google DNS as fallback
    - 8.8.8.8
    - 8.8.4.4
  bootstrap_dns:
    - 1.1.1.1:53
    - 9.9.9.9:53
  fallback_dns:
    - 8.8.8.8:53
  upstream_timeout: 10s
  # Load balance across upstreams
  upstream_mode: load_balance
  # Use parallel queries for speed
  fastest_addr: true

After editing the YAML, reload AdGuard Home:

sudo systemctl restart AdGuardHome

Filtering Rules and Blocklists

AdGuard Home supports multiple blocklist formats and custom filtering rules:

Enable recommended blocklists via the web interface at Filters > DNS blocklists > Add blocklist:

Popular blocklists to add:

  • AdGuard DNS filter: https://adguardteam.github.io/HostlistsRegistry/assets/filter_1.txt
  • Steven Black Hosts: https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
  • MalwareDomainList: https://www.malwaredomainlist.com/hostslist/hosts.txt

Or configure them directly in the YAML:

filters:
  - enabled: true
    url: https://adguardteam.github.io/HostlistsRegistry/assets/filter_1.txt
    name: AdGuard DNS filter
    id: 1
  - enabled: true
    url: https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
    name: StevenBlack Unified Hosts
    id: 2
  - enabled: true
    url: https://raw.githubusercontent.com/nicehash/NiceHashAdBlock/master/adlist.txt
    name: NiceHash Ad Block
    id: 3
user_rules:
  # Block specific domains
  - "||ads.example.com^"
  - "||tracker.analytics.com^"
  # Whitelist a domain
  - "@@||legitimate-cdn.example.com^"
  # Rewrite a domain to an IP
  - "local-server.example.com A 10.0.0.50"

# Update all filter lists
curl -X POST http://localhost:3000/control/filtering/refresh \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)"

DNS-over-HTTPS and DNS-over-TLS Setup

Enable encrypted DNS to allow clients to query AdGuard Home securely:

First, obtain a TLS certificate:

# Install Certbot
sudo apt install -y certbot

# Obtain certificate (stop AdGuard Home temporarily if it uses port 80)
sudo systemctl stop AdGuardHome
sudo certbot certonly --standalone -d dns.example.com
sudo systemctl start AdGuardHome

# Or use a certificate from an existing ACME setup
ls /etc/letsencrypt/live/dns.example.com/

Configure TLS in AdGuard Home:

# In AdGuardHome.yaml
tls:
  enabled: true
  server_name: dns.example.com
  force_https: true
  port_https: 443
  port_dns_over_tls: 853
  port_dns_over_quic: 853
  certificate_path: /etc/letsencrypt/live/dns.example.com/fullchain.pem
  private_key_path: /etc/letsencrypt/live/dns.example.com/privkey.pem

sudo systemctl restart AdGuardHome

# Test DoH
curl -H "accept: application/dns-json" \
  "https://dns.example.com/dns-query?name=google.com&type=A"

# Test DoT
kdig -d @dns.example.com +tls-ca +tls-host=dns.example.com google.com

Configure clients to use encrypted DNS:

  • DNS-over-HTTPS URL: https://dns.example.com/dns-query
  • DNS-over-TLS: tls://dns.example.com

Client Management and Parental Controls

Manage per-device settings and apply different filtering policies:

In the web interface, go to Settings > Client Settings > Add Client:

# Directly in AdGuardHome.yaml
clients:
  persistent:
    - name: kids-tablet
      ids:
        - "192.168.1.50"
        - "aa:bb:cc:dd:ee:ff"   # MAC address
      use_global_settings: false
      filtering_enabled: true
      parental_enabled: true      # Block adult content
      safesearch_enabled: true    # Force safe search on Google/Bing/YouTube
      use_global_blocked_services: false
      blocked_services:
        - youtube    # Block YouTube for kids
        - tiktok
    - name: work-laptop
      ids:
        - "192.168.1.60"
      use_global_settings: false
      filtering_enabled: true
      parental_enabled: false
      safesearch_enabled: false
      upstreams:
        # Work laptop uses different DNS
        - https://dns.cloudflare.com/dns-query

Block specific services (social media, gaming, etc.):

# Via API
curl -X POST http://localhost:3000/control/clients/update \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -d '{
    "name": "kids-tablet",
    "blocked_services": ["youtube", "tiktok", "instagram"]
  }'

Performance Optimization

# In AdGuardHome.yaml
dns:
  cache_size: 4194304         # 4 MB cache
  cache_ttl_min: 0
  cache_ttl_max: 0
  cache_optimistic: true      # Serve stale cache while refreshing
  edns_cs_enabled: false      # Disable EDNS Client Subnet for privacy
  use_private_ptr_resolvers: true
  max_goroutines: 300         # Max concurrent DNS queries

Configure rate limiting to protect against DNS floods:

dns:
  ratelimit: 20               # Queries per second per client
  ratelimit_whitelist:
    - 192.168.1.0/24          # No rate limit for local network
  refuse_any: true            # Refuse ANY queries (reduces amplification risk)

# Check cache hit rate in logs
grep "cache hit" /opt/AdGuardHome/AdGuardHome.log | wc -l

Troubleshooting

AdGuard Home not blocking ads:

# Test that DNS is routing through AdGuard Home
dig @192.168.1.100 ads.doubleclick.net
# Expected: returns 0.0.0.0

# Check if domain is in a blocklist
# Web interface: Query Log > search for the domain

# Update all filter lists
sudo systemctl restart AdGuardHome

Service fails to start:

sudo journalctl -u AdGuardHome -n 100 --no-pager

# Check configuration syntax
sudo /opt/AdGuardHome/AdGuardHome --check-config -c /opt/AdGuardHome/AdGuardHome.yaml

# Check port conflicts
sudo ss -tlnup | grep -E ":53|:80|:443|:853"

DoH/DoT certificate errors:

# Verify certificate
openssl s_client -connect dns.example.com:853 -servername dns.example.com

# Check certificate expiry
openssl x509 -in /etc/letsencrypt/live/dns.example.com/fullchain.pem -noout -dates

# Renew certificate
sudo certbot renew && sudo systemctl restart AdGuardHome

Clients not using AdGuard Home DNS:

# Verify client DNS settings
cat /etc/resolv.conf   # on Linux clients
# Should show nameserver 192.168.1.100

# Check DHCP is sending the correct DNS server
grep dhcp /var/log/syslog | tail -20

Conclusion

AdGuard Home combines network-wide ad blocking with privacy-focused encrypted DNS (DoH/DoT) in a single, easy-to-manage package. Its per-client configuration allows applying different filtering policies for different users or devices, while the built-in parental controls provide safe browsing enforcement without additional software. The encrypted DNS support means clients can reach your AdGuard Home instance over HTTPS or TLS, protecting DNS queries even on untrusted networks.