diegosouzapw 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