Network-wide filtering with AdGuard Home#

You will end up with every client on the LAN behind a DNS filter, without touching a single client's settings, and with a query log you can search. AdGuard Home runs as a container on the router; the router's own resolver forwards to it.

This is also the best worked example of how apps and the rest of the product fit together, which is why it has a page of its own.

Before you start#

• The operator role and a licence.
• The router's resolver configured and the LAN pointed at it.
• Container support on the router, and a route to Docker Hub.

The port-53 conflict, first#

Step 1 — Install it#

Services → Apps → AdGuard Home. The three steps are the ordinary ones: directories, image, diff.

set container network apps prefix 10.99.0.0/24
set container name adguard image docker.io/adguard/adguardhome:latest
set container name adguard network apps address 10.99.0.5
set container name adguard volume work source /config/apps/adguard/work
set container name adguard volume work destination /opt/adguardhome/work
set container name adguard volume conf source /config/apps/adguard/conf
set container name adguard volume conf destination /opt/adguardhome/conf

The two volumes are the query log and statistics (work) and the configuration (conf). Both are under /config, so they survive an image upgrade and are not removed when you uninstall.

Step 2 — Run its setup wizard#

The catalogue entry's second note is the one that confuses people: the first run serves a setup wizard on port 3000; afterwards the admin UI moves to port 80.

Open http://10.99.0.5:3000 from a machine that can reach the apps network, and work through the wizard. The Open link on the app's page is built from the container's real address and the entry's declared web-UI port.

Step 3 — Point the router's resolver at it#

Once AdGuard is running, the DNS page grows a card:

Point the resolver at AdGuard Home — AdGuard is running. Forwarding the router's own resolver at it puts every client behind the filter without touching a single client's settings.

with a one-click Stage this change. That is an integration hint, and the address in it is read from the running container rather than written into the catalogue.

set service dns forwarding name-server 10.99.0.5

Remove the upstream resolvers the forwarder had, so everything goes through the filter:

delete service dns forwarding name-server 9.9.9.9
delete service dns forwarding name-server 1.1.1.1

AdGuard now does the upstream resolution, configured in its own interface.

Step 4 — Commit and test#

Check it worked#

A blocked name is blocked, and an ordinary one is not:

dig @192.0.2.1 example.com

And AdGuard sees the queries. Its query log should show them arriving from the router's address — which is the one thing worth knowing about this arrangement, below.

The container is healthy. Apps → Installed shows declared beside running, with the health probe's verdict — a TCP connection to port 3000 plus an HTTP request to /.

Every query looks like it came from the router#

Because it did. The router's forwarder is the client as far as AdGuard is concerned, so per-client rules and the per-client view in AdGuard's own interface see one client.

If you want per-client policy, point the clients at AdGuard directly instead of at the router's forwarder:

set service dhcp-server shared-network-name LAN subnet 192.0.2.0/24 option name-server 10.99.0.5

That needs the apps network reachable from the LAN, which is a firewall and routing decision rather than a DNS one, and it takes the router's own resolver out of the path — including its authoritative records. Decide which you want; you cannot have both cleanly.

Alternatives in the same category#

The catalogue has five entries under DNS and filtering: AdGuard Home, Pi-hole, Blocky, Unbound and dnsmasq. The first three do roughly this job with different interfaces; Unbound is a validating resolver rather than a filter; dnsmasq is there for a different reason.

Undoing it#

Put the upstream resolvers back in the same commit as the uninstall, or the LAN loses DNS.

set service dns forwarding name-server 9.9.9.9
delete service dns forwarding name-server 10.99.0.5
delete container name adguard

The data under /config/apps/adguard stays behind on purpose — Stop, uninstall, and what stays behind.

See also#

• Install an app
• Point the LAN at the router's resolver
• Integration offers — what a hint is and where they appear
• Apps — catalogue

Checked against agent/catalog.json · agent/apps.go · docs/apps.md · ui/src/pages/Dns.tsx