Adguard

# 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 - `curl` installed (usually default on macOS/Linux)

## Quick Start

```bash # Set password once export ADGUARD_PASSWORD=your_admin_password

# Use commands ./adguard.sh status ./adguard.sh check example.com ./adguard.sh allow broken-site.com ./adguard.sh block malware.ru ```

## Configuration

Set environment variables for your AdGuard instance:

```bash export ADGUARD_URL="http://192.168.1.100:3000" # Your AdGuard IP and port export ADGUARD_USERNAME="admin" # Usually 'admin' (default) export ADGUARD_PASSWORD="your_admin_password" # REQUIRED ```

Add to `~/.bashrc` or `~/.zshrc` for persistence.

### Config File Alternative

Create `~/.adguard/config.json` (optional):

```json { "url": "http://192.168.1.100:3000", "username": "admin" } ```

Then set `ADGUARD_PASSWORD` separately for security.

## Commands

### check `<domain>`

Check if a domain is currently blocked or allowed.

```bash ./adguard.sh check doubleclick.net # ✗ doubleclick.net IS BLOCKED # Blocked by: Adblock Plus filter

./adguard.sh check example.com # ✓ example.com is NOT blocked (allowed) ```

### allow `<domain>` | whitelist `<domain>`

Add a domain to the allowlist (whitelist). Creates an exception rule that overrides blocklists.

```bash ./adguard.sh allow broken-site.com # ✓ Added rule: @@||broken-site.com^ # Domain: broken-site.com # Action: allow ```

### block `<domain>` | blacklist `<domain>`

Add a domain to the blocklist. Creates a custom blocking rule.

```bash ./adguard.sh block spyware-domain.ru # ✓ Added rule: ||spyware-domain.ru^ # Domain: spyware-domain.ru # Action: block ```

### status | stats

Display DNS filtering statistics and protection state.

```bash ./adguard.sh status # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ # AdGuard Home Status # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ # Protection: ✓ ENABLED # # DNS Queries: 1,234 # Blocked by rules: 156 # Blocked by safe browsing: 23 # Safe search replacements: 5 # Block rate: 14% # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ```

### toggle | protection

Enable or disable DNS protection. Useful for temporarily disabling filtering.

```bash ./adguard.sh toggle # Disabling protection... # ✓ Protection is now false ```

### cache-clear

Clear the DNS cache to apply rule changes immediately.

```bash ./adguard.sh cache-clear # Clearing DNS cache... # ✓ Cache cleared ```

## 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 2. **Local network scan** — Use `nmap` or check "Connected Devices" 3. **If running on same machine** — Default is `http://localhost:3000` 4. **mDNS/Bonjour** — Try `http://adguard-home.local:3000` (depends on network)

## Filtering Rules Syntax

AdGuard uses a DNS filtering rule syntax:

| Rule | Effect | |------|--------| | `\|\|example.com^` | Block example.com and subdomains | | `@@\|\|example.com^` | Allow example.com (exception/whitelist) | | `example.com` | Block exact domain only | | `\|\|ad.example.com^` | Block only ad.example.com |

See [API Reference](references/api.md) for complete syntax.

## Common Scenarios

### Allow a site that's blocked by accident

```bash adguard.sh allow my-bank.com ```

### Block a known malware domain

```bash adguard.sh block malicious-tracker.xyz ```

### Check if a domain is being filtered

```bash adguard.sh check ads.google.com ```

### View today's statistics

```bash adguard.sh status ```

### Temporarily disable filtering (e.g., for troubleshooting)

```bash adguard.sh toggle ```

## 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: `ping <ip>`

## Advanced: Batch Operations

Block multiple domains:

```bash for domain in tracker1.com tracker2.com tracker3.com; do adguard.sh block "$domain" done ```

Check multiple domains:

```bash for domain in example.com test.org my-site.net; do echo "Checking $domain..." adguard.sh check "$domain" done ```

## API Reference

See [references/api.md](references/api.md) for complete AdGuard Home API documentation.