feat: adguard-register — auto DNS registration agent for AdGuard Home

Registers {hostname}.home.dustin.coffee → host IP on boot via AdGuard Home API. Deploy to any LXC/VM with ./install.sh — supports root (system service), sudo user (system via sudo), and unprivileged user (systemd --user or crontab). Files: - adguard-register.sh — detects hostname+IP, idempotent create/update - install.sh — deployment script with auto-detection of install method - uninstall.sh — removes service and binary - README.md — full documentation Tested across 24 hosts (LXCs and VMs) on a 172.20.0.0/16 home lab network.
2026-05-02 17:41:19 -04:00
commit 00a95fda80
5 changed files with 357 additions and 0 deletions
@@ -0,0 +1,91 @@
+# 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
+
+```bash
+# 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)
+
+```bash
+sudo /usr/local/bin/adguard-register
+```
+
+### Uninstall
+
+```bash
+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
+```bash
+systemctl status adguard-register
+journalctl -u adguard-register
+```
+
+### Test manually
+```bash
+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":"..."}}`