hobokenchicken
00a95fda80
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.
92 lines
2.7 KiB
Markdown
92 lines
2.7 KiB
Markdown
# 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":"..."}}`
|