AdGuard Home¶

AdGuard Home is a network-wide ad blocker and DNS server. dnsweaver manages DNS records via AdGuard Home's DNS Rewrite API.

Requirements¶

AdGuard Home v0.107+ (DNS Rewrite API support)
Admin credentials with API access

Configuration¶

environment:
  - DNSWEAVER_INSTANCES=adguard

  - DNSWEAVER_ADGUARD_TYPE=adguard
  - DNSWEAVER_ADGUARD_URL=http://adguard:3000
  - DNSWEAVER_ADGUARD_USERNAME=admin
  - DNSWEAVER_ADGUARD_PASSWORD_FILE=/run/secrets/adguard_password
  - DNSWEAVER_ADGUARD_ZONE=home.example.com
  - DNSWEAVER_ADGUARD_RECORD_TYPE=A
  - DNSWEAVER_ADGUARD_TARGET=192.0.2.100
  - DNSWEAVER_ADGUARD_DOMAINS=*.home.example.com

Configuration Reference¶

Variable	Required	Default	Description
`TYPE`	Yes	-	Must be `adguard`
`URL`	Yes	-	AdGuard Home web interface URL
`USERNAME`	Yes	-	Admin username
`PASSWORD`	Yes	-	Admin password
`PASSWORD_FILE`	Alt	-	Path to password file (Docker secrets)
`ZONE`	No	-	DNS zone for record filtering
`TTL`	No	`300`	Record TTL (for provider consistency; see note below)
`RECORD_TYPE`	Yes	-	`A`, `AAAA`, or `CNAME`
`TARGET`	Yes	-	Record value (IP or hostname)
`DOMAINS`	Yes	-	Glob patterns to match
`EXCLUDE_DOMAINS`	No	-	Patterns to exclude

Record Types¶

A Records¶

Points hostnames to IPv4 addresses:

- DNSWEAVER_ADGUARD_RECORD_TYPE=A
- DNSWEAVER_ADGUARD_TARGET=192.0.2.100

AAAA Records¶

Points hostnames to IPv6 addresses:

- DNSWEAVER_ADGUARD_RECORD_TYPE=AAAA
- DNSWEAVER_ADGUARD_TARGET=2001:db8::1

CNAME Records¶

Points hostnames to another hostname:

- DNSWEAVER_ADGUARD_RECORD_TYPE=CNAME
- DNSWEAVER_ADGUARD_TARGET=proxy.example.com

Capabilities and Limitations¶

No TXT Record Support — Target-Based Ownership Inference

AdGuard Home's DNS Rewrite API does not support TXT records. This means dnsweaver cannot create ownership TXT records (_dnsweaver.*) for this provider.

Instead, dnsweaver uses target-based ownership inference for orphan cleanup in managed mode. When a record's type and target value match the provider instance's configured RECORD_TYPE and TARGET, dnsweaver infers that it created the record and will delete it during orphan cleanup. Records with different targets are preserved.

How each mode works:

In managed mode (default), orphan cleanup uses target-based inference. Records matching your configured type+target are cleaned up; records with different targets (e.g., manually-created rewrites pointing elsewhere) are left untouched.
In authoritative mode, dnsweaver deletes any record in scope regardless of ownership. Orphan cleanup works fully, but any manually-created rewrites in matching domains will also be deleted.
In additive mode, dnsweaver only creates records and never deletes. No ownership needed.

Edge Case

If you manually create a rewrite in AdGuard Home with the exact same domain, record type, and target as a dnsweaver-managed record, dnsweaver will treat it as its own and may delete it during orphan cleanup. This scenario is narrow — it requires an exact match on all three fields within dnsweaver's configured domain patterns.

Other Provider Differences¶

Feature	AdGuard Home	Notes
A records	✅
AAAA records	✅	Native support (no workarounds needed)
CNAME records	✅
SRV records	❌	Not supported by rewrite API
TXT records	❌	Not supported by rewrite API
Per-record TTL	❌	Rewrites use the global DNS cache TTL; the `TTL` config is tracked for consistency but not sent to AdGuard
Native update	✅	Records are updated in-place via `PUT /control/rewrite/update`
Ownership tracking	⚡	Target-based inference (see above)

Duplicate Rewrites

AdGuard Home allows creating multiple rewrites with the same domain and answer. dnsweaver's reconciler handles deduplication, but if you're also managing rewrites manually in the AdGuard UI, be aware of potential duplicates.

Recommended Mode Configuration¶

# Default — managed mode with target-based ownership inference
- DNSWEAVER_ADGUARD_MODE=managed

# Write-only — no deletions, no ownership tracking needed
- DNSWEAVER_ADGUARD_MODE=additive

# Full control — only use for dnsweaver-exclusive subdomains
- DNSWEAVER_ADGUARD_MODE=authoritative

See Operational Modes for details on each mode.

Docker Deployment¶

Same Docker Host¶

services:
  dnsweaver:
    image: maxamill/dnsweaver:latest
    environment:
      - DNSWEAVER_INSTANCES=adguard
      - DNSWEAVER_ADGUARD_TYPE=adguard
      - DNSWEAVER_ADGUARD_URL=http://adguard:3000
      - DNSWEAVER_ADGUARD_USERNAME=admin
      - DNSWEAVER_ADGUARD_PASSWORD_FILE=/run/secrets/adguard_password
      - DNSWEAVER_ADGUARD_MODE=managed
      - DNSWEAVER_ADGUARD_RECORD_TYPE=A
      - DNSWEAVER_ADGUARD_TARGET=192.0.2.100
      - DNSWEAVER_ADGUARD_DOMAINS=*.home.example.com
    secrets:
      - adguard_password
    networks:
      - adguard_network

  adguardhome:
    image: adguard/adguardhome:latest
    networks:
      - adguard_network

secrets:
  adguard_password:
    file: ./adguard_password.txt

networks:
  adguard_network:

Remote AdGuard Home¶

services:
  dnsweaver:
    image: maxamill/dnsweaver:latest
    environment:
      - DNSWEAVER_ADGUARD_URL=http://192.168.1.100:3000
      - DNSWEAVER_ADGUARD_USERNAME=admin
      - DNSWEAVER_ADGUARD_PASSWORD=your-password

Troubleshooting¶

Authentication Failed¶

Verify your credentials work with a direct API call:

curl -u admin:password http://adguard:3000/control/status

Records Not Appearing¶

Check that the domain matches your DOMAINS pattern
Verify the rewrite was created in AdGuard Home → Filters → DNS Rewrites
If using ZONE filtering, ensure the domain ends with the zone suffix

Duplicate Records¶

If you see duplicate rewrites in AdGuard Home:

Check for manual rewrites that overlap with dnsweaver's management
Consider using authoritative mode on a dedicated subdomain
Review dnsweaver logs at debug level for reconciliation details

Records Persist After Container Stops¶

This is expected in additive mode. In managed mode, records may persist after restart because AdGuard Home doesn't support ownership TXT records — dnsweaver can't verify it created them. See Capabilities and Limitations above.