AdGuard Home Management
adguard-home
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 blocki...
SKILL.md
Full skill instructions
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
- Check query log for the blocked domain
- Identify which filter blocked it
- Add whitelist rule if false positive
- Clear DNS cache
- Test resolution
Add New Device with Custom Settings
- Identify device IP/MAC
- Create client configuration
- Set custom upstream DNS if needed
- Configure blocked services
- Set parental controls if applicable
Security Audit
- Review client list for unknown devices
- Check query log for suspicious domains
- Verify safebrowsing is enabled
- Review TLS configuration
- Check for software updates
Troubleshooting
DNS Resolution Failures
- Check AdGuard Home service status
- Verify upstream DNS servers
- Check network connectivity
- Review query log for errors
Clients Not Using AdGuard Home
- Verify client DHCP settings
- Check if client has hardcoded DNS
- Review router DNS configuration
- Check firewall rules
High Latency
- Check upstream DNS performance
- Review blocklist count
- Enable DNS caching
- Consider local upstream resolver
Best Practices
- Use encrypted DNS - DoH/DoT for upstream
- Regular blocklist updates - Keep filters current
- Monitor query patterns - Watch for anomalies
- Backup configuration - Before major changes
- Enable safebrowsing - Additional protection
- Configure rate limiting - Prevent abuse
- Use client groups - Different policies per device
- 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