adblock-dns

# AdBlock DNS

Network-wide ad and tracker blocking at the DNS level. A Pi-hole alternative that runs directly on your machine as an OpenClaw skill. No separate hardware needed.

## What It Does

Runs a DNS sinkhole server that blocks ads, trackers, malware, and telemetry domains across your entire network. Any device that uses this machine as its DNS server gets ad-free browsing automatically — phones, tablets, smart TVs, laptops, IoT devices, everything.

Blocks 189,000+ ad and tracker domains using the same blocklists as Pi-hole (Steven Black, AdAway, EasyList, EasyPrivacy, Anti-Malware). Blocks both IPv4 (A) and IPv6 (AAAA) queries.

**Works great for:** Banner ads on websites, tracking pixels, third-party ad networks (Doubleclick, Amazon Ads, Criteo, Rubicon, etc.), in-app ads, telemetry/analytics trackers, malware domains.

**Won't block:** YouTube ads, Twitch ads, or any ads served from the same domain as the content itself. These platforms serve ads from their own CDN (e.g. `googlevideo.com` for YouTube), so blocking the domain would break the entire service. This is a fundamental limitation of ALL DNS-level blockers including Pi-hole. For YouTube ads, use a browser extension like uBlock Origin.

## How It Works

The skill runs a DNS server on this machine. When a device queries a domain:
- If the domain is on the blocklist, it returns 0.0.0.0 (blocked)
- If the domain is clean, it forwards the query to upstream DNS (Cloudflare 1.1.1.1 by default)

All queries are logged with stats (total queries, blocked percentage, top blocked domains).

## Setup

### Step 1: Run the setup script

```bash
cd /path/to/skills/adblock/scripts
bash setup.sh
```

This will:
1. Install dependencies if needed
2. Create a systemd service (runs as root, starts on boot, auto-restarts)
3. Download blocklists (~150K+ domains)
4. Start the DNS server on port 53
5. Start a stats API on port 8053
6. Print your DNS IP and device setup instructions

The user will need to enter their sudo password once during setup.

**Alternative (manual start without systemd):**
```bash
sudo node dns-server.js
```

### Step 2: Change DNS settings on your devices

**This is the critical step.** The DNS server does nothing until devices point to it.

Find this machine's local IP address:
```bash
hostname -I | awk '{print $1}'
```

Then configure devices to use that IP as their DNS server:

**Router (blocks entire network):**
- Log into your router admin panel (usually 192.168.1.1)
- Find DNS settings (usually under DHCP or Internet/WAN settings)
- Set primary DNS to this machine's IP
- Set secondary DNS to 1.1.1.1 (fallback if this machine is off)
- All devices on the network are now protected

**Individual devices:**

- **iPhone/iPad:** Settings > Wi-Fi > tap your network > Configure DNS > Manual > add this machine's IP
- **Android:** Settings > Network > Wi-Fi > your network > Advanced > DNS > set to this machine's IP
- **Mac:** System Settings > Network > Wi-Fi > Details > DNS > add this machine's IP
- **Windows:** Settings > Network > Wi-Fi > Hardware properties > DNS server assignment > Manual > set IPv4 DNS
- **Linux:** Edit /etc/resolv.conf or NetworkManager: `nmcli con mod "Wi-Fi" ipv4.dns "MACHINE_IP"`

### Step 3: Verify it's working

```bash
# Should return 0.0.0.0 (blocked)
nslookup ads.google.com MACHINE_IP

# Should return a real IP (allowed)
nslookup google.com MACHINE_IP
```

Or check the API: `curl http://localhost:8053/stats`

## Agent Commands

When the user asks about ad blocking, use these:

### Check stats
```bash
curl -s http://localhost:8053/stats | python3 -m json.tool
```
Report: total queries, blocked queries, block percentage, top blocked domains.

### Whitelist a domain
If something is broken because it's being blocked:
```bash
curl -s -X POST http://localhost:8053/whitelist/add -H "Content-Type: application/json" -d '{"domain":"example.com"}'
```

### Block a specific domain
```bash
curl -s -X POST http://localhost:8053/blacklist/add -H "Content-Type: application/json" -d '{"domain":"annoying-site.com"}'
```

### Check if a domain is blocked
```bash
curl -s "http://localhost:8053/check?domain=ads.google.com"
```

### Update blocklists
Blocklists auto-update every 24 hours. To force an update:
```bash
curl -s -X POST http://localhost:8053/update
```

### View whitelist
```bash
curl -s http://localhost:8053/whitelist
```

## Running as a Service

The `setup.sh` script handles this automatically. If you need to manage it manually:

```bash
sudo systemctl start adblock-dns     # Start
sudo systemctl stop adblock-dns      # Stop
sudo systemctl restart adblock-dns   # Restart
sudo systemctl status adblock-dns    # Check status
journalctl -u adblock-dns -f         # View logs

# Remove completely
sudo systemctl disable adblock-dns
sudo rm /etc/systemd/system/adblock-dns.service
sudo systemctl daemon-reload
```

## Configuration

Edit `data/config.json`:
```json
{
  "upstream": "1.1.1.1",   // Upstream DNS (Cloudflare, Google 8.8.8.8, etc.)
  "port": 53,              // DNS port (53 = standard, needs sudo)
  "apiPort": 8053           // Stats API port
}
```

## Files

- `data/blocklist.txt` - Compiled blocklist (auto-generated)
- `data/whitelist.txt` - Whitelisted domains (one per line)
- `data/custom-blacklist.txt` - Extra domains to block (one per line)
- `data/stats.json` - Query statistics
- `data/config.json` - Server configuration

## Constraints

- Port 53 requires root/sudo access
- Devices MUST be configured to use this machine's IP as DNS for blocking to work
- If this machine goes offline, devices using it as DNS will lose DNS resolution (set a secondary DNS as fallback)
- Only blocks domains, not in-page ad elements (use a browser ad blocker for that)
- HTTPS/DoH queries that bypass system DNS won't be caught