AgentSkillsCN

adguard-home

管理和排查、配置、分析、审查 AdGuard Home DNS 服务器。当您使用 AdGuard Home、DNS 阻断、广告拦截、全网过滤、DNS 查询、黑名单管理、客户端管理、DHCP，或进行 DNS 重写时，请使用此功能。支持 REST API 与 SSH 访问。触发条件包括 adguard、DNS 阻断、广告拦截、网络过滤、DNS 服务器、黑名单，以及 Pi-Hole 的替代方案。

SKILL.md
--- frontmatter
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

bash
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

bash
pip install requests paramiko

Quick Reference

API Authentication

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

Common Tasks

TaskAPI EndpointMethod
Get status/control/statusGET
Get DNS info/control/dns_infoGET
Query log/control/querylogGET
Get stats/control/statsGET
List clients/control/clientsGET
Filter status/control/filtering/statusGET
Clear cache/control/cache_clearPOST

Core Management Tasks

1. Status & Health Check

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

2. Query Log Analysis

python
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
python scripts/adguard_api.py filters

Add a blocklist:

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

Custom filtering rules:

bash
# Block domain
||ads.example.com^

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

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

4. Client Management

python
# 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

python
# 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
python scripts/adguard_api.py stats
python scripts/adguard_api.py reset-stats

SSH Server Management

Service Management

bash
# 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

bash
# 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

bash
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