# AdGuard Home

## Overview

AdGuard Home serves as the **primary** LAN-wide DNS resolver for the entire homelab
network. All devices on the `192.168.1.0/24` subnet use it as their primary DNS
server (`192.168.1.85:53`). It provides:

- DNS-based ad and tracker blocking
- Wildcard DNS entry `*.home.local → 192.168.1.85` enabling all Traefik internal routes
- DNS rewrites for custom local hostnames
- Query logging and per-client statistics
- Upstream DNS forwarding (via DoH to external resolvers)

A **secondary AdGuard Home** instance runs on the CorSec server (Home Assistant
machine at `192.168.1.64`). DNS rewrites are also maintained there so that name
resolution continues during Centerpoint maintenance or restarts. Client devices
should have both IPs configured as DNS resolvers.

## Access

| Type      | URL                              | Notes                                |
|-----------|----------------------------------|--------------------------------------|
| Internal  | `https://adguard.home.local`     | LAN access via Step-CA TLS           |
| Direct    | `http://192.168.1.85:80`         | Plain HTTP UI (AdGuard internal port) |

DNS service itself runs on port `53` (TCP + UDP), bound to the host IP.

## Configuration

**Image:** `adguard/adguardhome:v0.107.71`
**Compose project:** `adguardhome` (managed via Portainer)

### Ports

| Port  | Protocol | Purpose                         |
|-------|----------|---------------------------------|
| `53`  | TCP+UDP  | DNS resolver (host-bound)       |
| `80`  | TCP      | AdGuard web UI (HTTP, internal) |
| `443` | TCP      | DNS-over-HTTPS                  |
| `853` | TCP      | DNS-over-TLS                    |
| `3000`| TCP      | Initial setup port              |

Only port `53` is bound to the host. Other ports are exposed only within `traefik-net`.

### Traefik Labels

```yaml
traefik.enable: "true"
traefik.http.routers.adguard.rule: Host(`adguard.home.local`)
traefik.http.routers.adguard.entrypoints: websecure
traefik.http.routers.adguard.tls.certresolver: step-ca
traefik.http.services.adguard.loadbalancer.server.port: 80
```

Internal-only route — no external Traefik router.

### Critical Wildcard DNS Entry

AdGuard Home (both primary and secondary) must have a DNS Rewrite configured as:

```
*.home.local → 192.168.1.85
```

This single wildcard record means Traefik receives all `*.home.local` HTTP requests
and routes them by hostname. Without it, no internal service domain resolves.

All custom DNS rewrites (for individual hostnames outside the wildcard) must be
kept in sync between the Centerpoint and CorSec instances.

### Upstream DNS Resolvers

Upstream DNS (for forwarding public queries) is configured in AdGuard's settings
UI. Common configuration:

- Primary: `https://dns.cloudflare.com/dns-query` (DoH)
- Secondary: `https://dns.google/dns-query` (DoH)

## Volumes / Bind Mounts

| Host Path                            | Container Path              | Purpose                       |
|--------------------------------------|-----------------------------|-------------------------------|
| `/home/jeeves/docker/adguard/conf`   | `/opt/adguardhome/conf`     | Configuration (`AdGuardHome.yaml`) |
| `/home/jeeves/docker/adguard/work`   | `/opt/adguardhome/work`     | Query logs and statistics database |

## Networks

AdGuard Home is on `traefik-net` for its web UI route and has port `53` bound
directly to the host for DNS service.

## Dependencies

- None (AdGuard must start first; it has no upstream service dependencies)
- AdGuard's own DNS resolution bootstraps via the upstream DoH resolvers using
  hardcoded IPs if DNS is not yet available

## High Availability

| Instance    | Host       | IP              | Role      |
|-------------|------------|-----------------|-----------|
| Primary     | Centerpoint | `192.168.1.85`  | Primary — full config, rewrites, logging |
| Secondary   | CorSec (Home Assistant) | `192.168.1.64` | Backup — same rewrites, ad-block lists |

Client devices should configure both DNS servers in priority order. The secondary
takes over automatically if the primary becomes unreachable.

DNS rewrites must be manually kept in sync between the two instances — there is no
automated synchronisation.

## Notes / Gotchas

- The `work/data` directory requires root-level permissions — the container runs as
  root. This is expected behaviour.
- If port `53` is already in use on the host (e.g. `systemd-resolved`), AdGuard will
  fail to start. On Ubuntu 24.04, disable the stub listener:
  ```bash
  sudo systemctl disable --now systemd-resolved
  ```
- Client-specific rules (blocking, bypass, custom upstream) are stored in
  `AdGuardHome.yaml` and are preserved across container upgrades as long as the
  `conf/` bind mount is intact.
- AdGuard Home should be pinned to a specific version tag rather than `latest` to
  avoid schema migrations breaking the config on unexpected upgrades.
- When adding a new `*.home.local` service, no DNS change is needed (the wildcard
  covers it). New custom hostnames outside the wildcard pattern must be added to
  both the primary and secondary AdGuard instances.

## FUTURE WORK

- Update the DNS blocklist to include more sites
- Provide a summary of sites blocked via AI for review and/or include in Grafana for trend analysis to know if the numbers go up or down over time- find rogue machines

---
*Last Updated: 2026-06-16*