adguard-register/README.md

AdGuard Home DNS Auto-Registration

Automatically registers {hostname}.home.dustin.coffee → its own IP with AdGuard Home DNS rewrites on boot. Designed for the home.dustin.coffee home lab domain.

How It Works

1. On boot (via systemd oneshot service), the script determines the host's short hostname and primary IPv4 address
2. It authenticates with the AdGuard Home API at 172.20.1.1
3. It checks if a DNS rewrite for {hostname}.home.dustin.coffee already exists:
   • No entry: creates a new rewrite pointing to the current IP
   • Entry exists with same IP: skips (idempotent)
   • Entry exists with different IP: updates the rewrite (handles renumbering)
4. Verifies the rewrite was applied successfully

The IP detection skips Docker bridges, Tailscale interfaces, and loopback to find the host's real primary address.

Deployment

On a new LXC/VM

# Copy the agent directory to the target host
scp -r adguard-register/ user@target-host:/tmp/

# SSH in and install
ssh user@target-host
cd /tmp/adguard-register
sudo ./install.sh

Manual registration (one-off, no install)

sudo /usr/local/bin/adguard-register

Uninstall

sudo /path/to/adguard-register/uninstall.sh

Requirements

• curl — for API calls
• python3 — for JSON parsing
• systemd — for boot-time execution (or use @reboot cron as fallback)
• Network access to 172.20.1.1:80

Files

File	Purpose
adguard-register.sh	Main registration script
install.sh	Copies script to /usr/local/bin/ and sets up systemd service
uninstall.sh	Removes the service and script
README.md	This file

Troubleshooting

Check service status

systemctl status adguard-register
journalctl -u adguard-register

Test manually

sudo /usr/local/bin/adguard-register

Common issues

• "Failed to authenticate": Verify AdGuard Home is running at 172.20.1.1 and credentials are correct
• "Could not determine primary IPv4 address": Ensure the host has a non-loopback, non-Docker, non-Tailscale IPv4 address
• "Verification failed": The API accepted the change but the read-back didn't match; check AdGuard Home logs
• Python3 not found: Install with apt install python3 or equivalent

AdGuard Home API Reference

• Base URL: http://172.20.1.1/control/
• Auth: POST /control/login with {"name":"...","password":"..."}
• List rewrites: GET /control/rewrite/list
• Add rewrite: POST /control/rewrite/add with {"domain":"...","answer":"..."}
• Update rewrite: POST /control/rewrite/update with {"target":{"domain":"..."},"update":{"domain":"...","answer":"..."}}