AdGuard Home Controller
Manage AdGuard Home DNS filtering from the command line via the REST API.
Requirements
- - AdGuard Home running with web interface
- Admin username and password
- INLINECODE0 installed (usually default on macOS/Linux)
Quick Start
CODEBLOCK0
Configuration
Set environment variables for your AdGuard instance:
CODEBLOCK1
Add to ~/.bashrc or ~/.zshrc for persistence.
Config File Alternative
Create ~/.adguard/config.json (optional):
CODEBLOCK2
Then set ADGUARD_PASSWORD separately for security.
Commands
check <domain>
Check if a domain is currently blocked or allowed.
CODEBLOCK3
allow <domain> | whitelist <domain>
Add a domain to the allowlist (whitelist). Creates an exception rule that overrides blocklists.
CODEBLOCK4
block <domain> | blacklist <domain>
Add a domain to the blocklist. Creates a custom blocking rule.
CODEBLOCK5
status | stats
Display DNS filtering statistics and protection state.
CODEBLOCK6
toggle | protection
Enable or disable DNS protection. Useful for temporarily disabling filtering.
CODEBLOCK7
cache-clear
Clear the DNS cache to apply rule changes immediately.
CODEBLOCK8
Finding Your AdGuard Home Device
If you don't know your AdGuard URL:
- 1. Router admin panel — Look for a device named "AdGuard Home" or check for port 3000
- Local network scan — Use
nmap or check "Connected Devices" - If running on same machine — Default is INLINECODE11
- mDNS/Bonjour — Try
http://adguard-home.local:3000 (depends on network)
Filtering Rules Syntax
AdGuard uses a DNS filtering rule syntax:
| Rule | Effect |
|---|
| INLINECODE13 | Block example.com and subdomains |
| INLINECODE14 |
Allow example.com (exception/whitelist) |
|
example.com | Block exact domain only |
|
\|\|ad.example.com^ | Block only ad.example.com |
See API Reference for complete syntax.
Common Scenarios
Allow a site that's blocked by accident
CODEBLOCK9
Block a known malware domain
CODEBLOCK10
Check if a domain is being filtered
CODEBLOCK11
View today's statistics
CODEBLOCK12
Temporarily disable filtering (e.g., for troubleshooting)
CODEBLOCK13
Troubleshooting
Error: Failed to authenticate
→ Check ADGUARD_PASSWORD is correct and set
→ Verify ADGUARD_URL points to the right IP and port
Error: API call failed (HTTP 401)
→ Authentication failed, check credentials
Rules don't take effect
→ Run adguard.sh cache-clear to flush DNS cache
→ Wait 5+ minutes for clients to refresh their cache
→ Restart your device's network connection
Can't connect to AdGuard
→ Verify device is on the same network
→ Check firewall isn't blocking port 3000
→ Ping the device: INLINECODE20
Advanced: Batch Operations
Block multiple domains:
CODEBLOCK14
Check multiple domains:
CODEBLOCK15
API Reference
See references/api.md for complete AdGuard Home API documentation.
AdGuard Home 控制器
通过REST API从命令行管理AdGuard Home DNS过滤。
系统要求
- - 已运行并启用Web界面的AdGuard Home
- 管理员用户名和密码
- 已安装curl（macOS/Linux通常默认安装）
快速开始
bash
一次性设置密码
export ADGUARD
PASSWORD=youradmin_password
使用命令
./adguard.sh status
./adguard.sh check example.com
./adguard.sh allow broken-site.com
./adguard.sh block malware.ru
配置
为你的AdGuard实例设置环境变量：
bash
export ADGUARD_URL=http://192.168.1.100:3000 # 你的AdGuard IP和端口
export ADGUARD_USERNAME=admin # 通常为admin（默认）
export ADGUARDPASSWORD=youradmin_password # 必填
添加到~/.bashrc或~/.zshrc以持久化配置。
配置文件替代方案
创建~/.adguard/config.json（可选）：
json
{
url: http://192.168.1.100:3000,
username: admin
}
然后出于安全考虑，单独设置ADGUARD_PASSWORD。
命令
check
检查某个域名当前是否被阻止或允许。
bash
./adguard.sh check doubleclick.net
✗ doubleclick.net 已被阻止
阻止来源：Adblock Plus 过滤器
./adguard.sh check example.com
✓ example.com 未被阻止（允许访问）
allow | whitelist
将域名添加到白名单。创建一条可覆盖黑名单的例外规则。
bash
./adguard.sh allow broken-site.com
✓ 已添加规则：@@||broken-site.com^
域名：broken-site.com
操作：允许
block | blacklist
将域名添加到黑名单。创建一条自定义阻止规则。
bash
./adguard.sh block spyware-domain.ru
✓ 已添加规则：||spyware-domain.ru^
域名：spyware-domain.ru
操作：阻止
status | stats
显示DNS过滤统计信息和保护状态。
bash
./adguard.sh status
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
AdGuard Home 状态
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
保护状态：✓ 已启用
# DNS 查询数：1,234
规则阻止数：156
安全浏览阻止数：23
安全搜索替换数：5
阻止率：14%
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
toggle | protection
启用或禁用DNS保护。适用于临时关闭过滤功能。
bash
./adguard.sh toggle
正在禁用保护...
✓ 保护状态已设为 false
cache-clear
清除DNS缓存以立即应用规则更改。
bash
./adguard.sh cache-clear
正在清除DNS缓存...
✓ 缓存已清除
查找你的AdGuard Home设备
如果你不知道AdGuard的URL：
- 1. 路由器管理面板 — 查找名为AdGuard Home的设备，或检查端口3000
- 本地网络扫描 — 使用nmap或检查已连接设备
- 如果在同一台机器上运行 — 默认为http://localhost:3000
- mDNS/Bonjour — 尝试http://adguard-home.local:3000（取决于网络配置）
过滤规则语法
AdGuard使用DNS过滤规则语法：
| 规则 | 效果 |
|---|
| \ | \ | example.com^ | 阻止example.com及其子域名 |
| @@\ |
\|example.com^ | 允许example.com（例外/白名单） |
| example.com | 仅阻止精确域名 |
| \|\|ad.example.com^ | 仅阻止ad.example.com |
完整语法请参阅API参考文档。
常见场景
允许被误封的网站
bash
adguard.sh allow my-bank.com
阻止已知恶意软件域名
bash
adguard.sh block malicious-tracker.xyz
检查域名是否被过滤
bash
adguard.sh check ads.google.com
查看今日统计数据
bash
adguard.sh status
临时禁用过滤（例如用于故障排查）
bash
adguard.sh toggle
故障排查
错误：身份验证失败
→ 检查ADGUARD_PASSWORD是否正确且已设置
→ 确认ADGUARD_URL指向正确的IP和端口
错误：API调用失败（HTTP 401）
→ 身份验证失败，请检查凭据
规则未生效
→ 运行adguard.sh cache-clear刷新DNS缓存
→ 等待5分钟以上让客户端刷新缓存
→ 重启设备的网络连接
无法连接到AdGuard
→ 确认设备在同一网络
→ 检查防火墙是否阻止了端口3000
→ Ping设备：ping
高级：批量操作
批量阻止多个域名：
bash
for domain in tracker1.com tracker2.com tracker3.com; do
adguard.sh block $domain
done
批量检查多个域名：
bash
for domain in example.com test.org my-site.net; do
echo 正在检查 $domain...
adguard.sh check $domain
done
API参考
完整的AdGuard Home API文档请参阅references/api.md。
