adguard-home

name	adguard-home
description	Manage, troubleshoot, configure, analyze, and review AdGuard Home DNS server. Use when working with AdGuard Home, DNS blocking, ad blocking, network-wide filtering, DNS queries, blocklists, client management, DHCP, or DNS rewrites. Supports REST API and SSH access. Triggers on adguard, DNS blocking, ad blocking, network filtering, DNS server, blocklist, pi-hole alternative.

AdGuard Home Management

Comprehensive management capabilities for AdGuard Home DNS server.

Prerequisites

Environment Variables

ADGUARD_URL=https://your-adguard-domain.local
ADGUARD_USER=admin
ADGUARD_PASS=your-password
ADGUARD_SSH_HOST=192.168.x.x
ADGUARD_SSH_USER=your-ssh-user

Python Packages

pip install requests paramiko

Quick Reference

API Authentication

curl -u "$ADGUARD_USER:$ADGUARD_PASS" "$ADGUARD_URL/control/status"

Common Tasks

Task	API Endpoint	Method
Get status	/control/status	GET
Get DNS info	/control/dns_info	GET
Query log	/control/querylog	GET
Get stats	/control/stats	GET
List clients	/control/clients	GET
Filter status	/control/filtering/status	GET
Clear cache	/control/cache_clear	POST

Core Management Tasks

1. Status & Health Check

curl -u "$ADGUARD_USER:$ADGUARD_PASS" "$ADGUARD_URL/control/status"

2. Query Log Analysis

python scripts/adguard_api.py querylog --limit 100 --search "blocked"

Filter by response status: all, filtered, blocked, blocked_safebrowsing, blocked_parental, whitelisted, rewritten, processed

3. Filter Management

View current filters:

python scripts/adguard_api.py filters

Add a blocklist:

python scripts/adguard_api.py add-filter --name "My List" --url "https://example.com/blocklist.txt"

Custom filtering rules:

# Block domain
||ads.example.com^

# Allow domain (whitelist)
@@||allowed.example.com^

# Block with regex
/ads[0-9]+\.example\.com/

4. Client Management

# List all clients
python scripts/adguard_api.py clients

# Add/configure client
python scripts/adguard_api.py add-client --name "Living Room TV" --ids "192.168.1.50"

5. DNS Rewrites

# List rewrites
python scripts/adguard_api.py rewrites

# Add rewrite
python scripts/adguard_api.py add-rewrite --domain "myserver.local" --answer "192.168.1.100"

6. Statistics

python scripts/adguard_api.py stats
python scripts/adguard_api.py reset-stats

SSH Server Management

Service Management

# Check service status
ssh $ADGUARD_SSH_USER@$ADGUARD_SSH_HOST "systemctl status AdGuardHome"

# Restart service
ssh $ADGUARD_SSH_USER@$ADGUARD_SSH_HOST "sudo systemctl restart AdGuardHome"

# View logs
ssh $ADGUARD_SSH_USER@$ADGUARD_SSH_HOST "sudo journalctl -u AdGuardHome -n 100"

Configuration File

Location: /opt/AdGuardHome/AdGuardHome.yaml

# Backup config
ssh $ADGUARD_SSH_USER@$ADGUARD_SSH_HOST "sudo cp /opt/AdGuardHome/AdGuardHome.yaml /opt/AdGuardHome/AdGuardHome.yaml.bak"

# View config
ssh $ADGUARD_SSH_USER@$ADGUARD_SSH_HOST "sudo cat /opt/AdGuardHome/AdGuardHome.yaml"

Update AdGuard Home

ssh $ADGUARD_SSH_USER@$ADGUARD_SSH_HOST "cd /opt/AdGuardHome && sudo ./AdGuardHome -s stop && sudo ./AdGuardHome --update && sudo ./AdGuardHome -s start"

Example Workflows

Investigate Blocked Request

1. Check query log for the blocked domain
2. Identify which filter blocked it
3. Add whitelist rule if false positive
4. Clear DNS cache
5. Test resolution

Add New Device with Custom Settings

1. Identify device IP/MAC
2. Create client configuration
3. Set custom upstream DNS if needed
4. Configure blocked services
5. Set parental controls if applicable

Security Audit

1. Review client list for unknown devices
2. Check query log for suspicious domains
3. Verify safebrowsing is enabled
4. Review TLS configuration
5. Check for software updates

Troubleshooting

DNS Resolution Failures

1. Check AdGuard Home service status
2. Verify upstream DNS servers
3. Check network connectivity
4. Review query log for errors

Clients Not Using AdGuard Home

1. Verify client DHCP settings
2. Check if client has hardcoded DNS
3. Review router DNS configuration
4. Check firewall rules

High Latency

1. Check upstream DNS performance
2. Review blocklist count
3. Enable DNS caching
4. Consider local upstream resolver

Best Practices

1. Use encrypted DNS - DoH/DoT for upstream
2. Regular blocklist updates - Keep filters current
3. Monitor query patterns - Watch for anomalies
4. Backup configuration - Before major changes
5. Enable safebrowsing - Additional protection
6. Configure rate limiting - Prevent abuse
7. Use client groups - Different policies per device
8. Regular log review - Security monitoring

When to Use This Skill

• Managing AdGuard Home installation
• Troubleshooting DNS issues
• Configuring blocklists and filters
• Setting up client-specific rules
• Analyzing DNS queries
• Managing DNS rewrites
• Performing security audits