adblock-dns

name	adblock-dns
description	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 h...

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

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):

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:

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

# 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

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:

curl -s -X POST http://localhost:8053/whitelist/add -H "Content-Type: application/json" -d '{"domain":"example.com"}'

Block a specific domain

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

curl -s "http://localhost:8053/check?domain=ads.google.com"

Update blocklists

Blocklists auto-update every 24 hours. To force an update:

curl -s -X POST http://localhost:8053/update

View whitelist

curl -s http://localhost:8053/whitelist

Running as a Service

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

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:

{
  "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