Skip to content

AdGuard Home

AdGuard Home is a network-wide DNS filtering service that blocks ads, trackers, and malicious domains at the DNS level, providing protection for all devices on the network without requiring client-side software.

Quick Reference

  • Local URL: https://dns.rbnk.uk
  • Container Name: adguard
  • Default Port: 53 (DNS), 3000 (Admin UI)
  • Data Directory: /srv/dockerdata/adguard/
  • Logs: docker compose -f /srv/dockerdata/adguard/docker-compose.yml logs -f

Service Overview

AdGuard Home provides: - DNS-level ad blocking - Blocks ads before they reach your device - Privacy protection - Prevents tracking and telemetry - Malware & phishing protection - Blocks malicious domains - Parental controls - Content filtering and safe search - Custom filtering rules - Fine-grained control over DNS resolution - DNS-over-HTTPS/TLS - Encrypted DNS queries - Statistics & monitoring - Detailed query analytics

Architecture

graph LR
    A[Client Device] -->|DNS Query| B[AdGuard Home]
    B -->|Check| C{Filter Lists}
    C -->|Blocked| D[0.0.0.0]
    C -->|Allowed| E[Upstream DNS]
    E -->|Response| B
    B -->|Response| A

    F[Admin UI] -->|Configure| B
    G[Prometheus] -->|Metrics| B

Key Features in Use

  1. Multiple Blocklists: 8 active filters blocking ads, trackers, malware, and scams
  2. Load-Balanced Upstreams: Uses Cloudflare, Google, and Quad9 DNS
  3. Tailscale Integration: Allows Tailscale network (100.64.0.0/10) queries
  4. Query Logging: 90-day retention for analysis
  5. DNS-over-HTTPS: Available at https://dns.rbnk.uk/dns-query

Common Operations

View Current Statistics

# Access the dashboard
open https://dns.rbnk.uk

# View query logs from CLI
docker exec adguard cat /opt/adguardhome/work/data/querylog.json | jq | less

Update Blocklists

# Via UI: Settings -> Filters -> Update
# Or restart to force update
docker compose -f /srv/dockerdata/adguard/docker-compose.yml restart

Add Custom DNS Records

# Via UI: Filters -> DNS rewrites
# Example: Point test.local to 192.168.1.100

Clear DNS Cache

# Via UI: Tools -> Clear DNS cache
# Or restart the container
docker restart adguard

Whitelist a Domain

# Via UI: Query log -> Find blocked domain -> Unblock
# Or add to Filters -> Custom rules:
# @@||example.com^

Configuration Details

Network Access

  • DNS Service: Available on port 53 (TCP/UDP)
  • Admin Interface: https://dns.rbnk.uk (proxied via Traefik)
  • DNS-over-TLS: Port 853
  • Allowed Networks:
  • Tailscale: 100.64.0.0/10
  • Docker: 172.18.0.1
  • External: 62.197.47.166

Active Filters

  1. AdGuard DNS filter (default)
  2. HaGeZi's Xiaomi Tracker Blocklist
  3. Dandelion Sprout's Game Console Adblock
  4. Scam Blocklist by DurableNapkin
  5. Dandelion Sprout's Anti-Malware List
  6. ShadowWhisperer's Dating List
  7. HaGeZi's Badware Hoster Blocklist
  8. Phishing URL Blocklist

Performance Settings

  • Cache Size: 4MB
  • Cache TTL: 10-60 minutes
  • Query Log Buffer: 1000 entries
  • Upstream Timeout: 10 seconds

Integration Points

With Traefik

  • HTTPS access to admin interface
  • DNS-over-HTTPS endpoint
  • Automatic SSL certificates

With Docker Services

All containers can use AdGuard for DNS: 

services:
  myapp:
    dns:
      - adguard

With Monitoring Stack

  • Prometheus metrics export
  • Grafana dashboard for DNS analytics
  • AlertManager integration for anomalies

Troubleshooting

DNS Not Resolving

# Check service status
docker ps | grep adguard

# Test DNS resolution
dig @localhost google.com

# Check logs
docker logs adguard --tail 50

High Memory Usage

# Check current usage
docker stats adguard

# Reduce query log retention
# UI: Settings -> General -> Query log retention -> 24h

Blocked Legitimate Site

# Find in query log
# UI: Query log -> Search for domain

# Whitelist
# UI: Filters -> Custom rules
# Add: @@||legitimate-site.com^

Maintenance

Daily

  • Monitor blocked percentage (normal: 10-30%)
  • Check for failed queries

Weekly

  • Review top blocked domains
  • Update blocklists
  • Check disk usage

Monthly

  • Clean old statistics
  • Review whitelist/blacklist rules
  • Update AdGuard version

Advanced Usage

Configure Conditional Forwarding

For local domain resolution: 

# UI: Settings -> DNS settings -> Upstream DNS servers
[/local.domain/]192.168.1.1
[/company.internal/]10.0.0.1

Enable DNSSEC

# UI: Settings -> DNS settings -> DNSSEC
# Enable DNSSEC validation

Custom Filtering Rules

# Block entire domain and subdomains
||example.com^

# Block specific subdomain
||ads.example.com^

# Whitelist (exception)
@@||good.example.com^

# Block by regex
/banner[0-9]*.js$/

# Block CNAME cloaking
||tracker.com^$important

Files and Directories

/srv/dockerdata/adguard/
├── conf/
│   └── AdGuardHome.yaml    # Main configuration
├── work/
│   ├── data/
│   │   ├── filters/        # Downloaded blocklists
│   │   ├── querylog.json   # DNS query logs
│   │   └── stats.db        # Statistics database
│   └── logs/               # Application logs
├── docker-compose.yml      # Service definition
├── .env                    # Environment variables
└── README.md              # Detailed documentation

Security Considerations

  1. Access Control: Admin interface requires authentication
  2. Network Restrictions: Only allowed IPs can query DNS
  3. Encrypted DNS: DoH/DoT support for privacy
  4. Regular Updates: Automated blocklist updates
  5. Query Privacy: Option to anonymize client IPs

See Also