How to Self-Host AdGuard Home and Block Ads Across Your Entire Network

How AdGuard Home DNS filtering works

DNS translates names such as example.com into IP addresses. In this design, your router advertises the AdGuard Home server as the DNS resolver for LAN clients. A client sends a DNS query to TCP or UDP port 53 on the server. AdGuard Home checks its filtering rules and either blocks the request or forwards it to a configured upstream resolver. Allowed answers can be cached, which avoids repeating an upstream lookup until the applicable cache entry expires.

A blocked query does not always produce an empty response. AdGuard Home supports multiple blocking response modes, and the result can vary with its configuration and the requested record type. A blocked query might receive an address such as a null address, an error response such as NXDOMAIN or REFUSED, or another configured blocking answer. The reliable way to determine whether filtering caused a result is to inspect AdGuard Home's query log and confirm that the request is marked as blocked by a specific rule or list.

What DNS filtering cannot do

DNS filtering blocks access by domain name. It cannot reliably remove individual advertisements that come from the same domain as desired content because blocking that domain would also block the content. It also cannot apply cosmetic page rules, remove empty page elements, or inspect a URL path when the DNS request contains only the hostname. A browser content blocker can complement network DNS filtering when page-level control is required.

Network-wide filtering also depends on clients actually using AdGuard Home. An application or device can bypass the server by using a hardcoded resolver, enabling its own DNS-over-HTTPS connection, using Android Private DNS with an external DNS-over-TLS provider, or learning another resolver through IPv6 router advertisements or DHCPv6. You should verify both IPv4 and IPv6 behavior rather than assuming a router's IPv4 DNS setting controls every query.

Prerequisites

Prepare the host and network before changing DHCP. DNS is an infrastructure service: if the address moves, the container stops, or a firewall blocks port 53, clients may appear connected while name resolution fails.

Confirm Docker before continuing:

docker --version
docker compose version

Save the current network configuration before making changes. Record the host's IPv4 address, any global or unique-local IPv6 address you intend to use, the default gateway, the current DNS resolvers, and the router's DHCP lease range. Keep one administrative device available with a manually configured working resolver so you can recover if the new DNS service is temporarily unavailable.

Plan the DNS address, firewall, and redundancy

Assign a stable address first

Use your router's DHCP reservation feature when available. A reservation keeps address management centralized while assigning the same LAN address to the server's network interface. If you configure a static address on the host instead, select an address outside the dynamic lease pool and preserve the correct subnet prefix, gateway, and routing settings.

On Linux, the following commands can help identify the active IPv4 route and addresses. Review the output instead of copying an address blindly:

ip -4 route
ip -4 address
ip -6 address

This guide uses SERVER_LAN_IP as a placeholder. Replace it with the real stable LAN address when testing or editing your router. Do not enter the literal placeholder into a configuration.

Restrict DNS to trusted networks

The Compose configuration publishes TCP and UDP port 53 on the host because LAN clients need to reach it. Your host firewall and upstream router should permit those ports only from trusted LAN or approved private subnets. Do not create router port-forwarding rules for port 53, and do not expose the DNS listener through an HTTP tunnel.

Do not use a public resolver as an accidental bypass

Many routers let you advertise primary and secondary DNS addresses. Clients do not necessarily treat the secondary value as a standby used only during failure. They may query either resolver. If you advertise AdGuard Home as primary and a public resolver as secondary, some requests can bypass your filters during normal operation.

Transparent DNS redundancy requires a second filtering resolver with equivalent rules, upstream settings, and availability. If you deploy only one server, decide whether the simpler design and possible DNS outage are acceptable. Keep a documented emergency procedure for restoring the router's previous resolver values if the server fails.

Plan IPv6 separately

IPv6-capable routers can advertise DNS resolvers through router advertisements or DHCPv6 independently of IPv4 DHCP. A client may prefer an advertised IPv6 resolver and bypass the IPv4 AdGuard Home address. Either configure AdGuard Home with a stable, reachable IPv6 address and advertise it correctly, or ensure the router does not advertise an unintended external IPv6 resolver. Do not disable IPv6 casually if your network depends on it.

Inspect port 53 before changing the host resolver

Do not assume that systemd-resolved is active merely because the host runs Ubuntu, Debian, or Raspberry Pi OS. Images, releases, network managers, and local configuration differ. First identify which process, if any, is listening on port 53 and how /etc/resolv.conf is managed.

sudo ss -lntup | grep -E '(:53[[:space:]]|:53$)' || true
systemctl is-active systemd-resolved || true
readlink -f /etc/resolv.conf
cat /etc/resolv.conf
resolvectl status 2>/dev/null || true

A listener owned by another DNS server, such as dnsmasq, Unbound, BIND, or an existing container, requires a service-specific decision. Stop, reconfigure, or deliberately integrate that service before publishing AdGuard Home on the same address and port. Do not disable an unfamiliar resolver without understanding what depends on it.

Conditional systemd-resolved procedure

Use the following procedure only if your inspection confirms that the systemd-resolved stub listener is causing the port conflict and that the host has valid upstream resolver information available through /run/systemd/resolve/resolv.conf. The procedure disables the local stub listener without making the host depend on AdGuard Home at 127.0.0.1 before the container is ready.

sudo cp -a /etc/resolv.conf /etc/resolv.conf.pre-adguard
cat /run/systemd/resolve/resolv.conf

sudo mkdir -p /etc/systemd/resolved.conf.d
sudo tee /etc/systemd/resolved.conf.d/adguardhome.conf <<'EOF'
[Resolve]
DNSStubListener=no
EOF

sudo rm -f /etc/resolv.conf
sudo ln -s /run/systemd/resolve/resolv.conf /etc/resolv.conf
sudo systemctl restart systemd-resolved

getent hosts example.com
sudo ss -lntup | grep -E '(:53[[:space:]]|:53$)' || true

sudo rm -f /etc/systemd/resolved.conf.d/adguardhome.conf
sudo rm -f /etc/resolv.conf
sudo cp -a /etc/resolv.conf.pre-adguard /etc/resolv.conf
sudo systemctl restart systemd-resolved
getent hosts example.com

Install AdGuard Home with Docker Compose

The configuration below publishes DNS on host port 53. It binds the one-time setup service and ongoing administration dashboard to IPv4 loopback, so neither web interface is directly reachable from the LAN or internet. Inside the container, the wizard can still configure the web service on its normal container interface because the host mapping supplies the external boundary.

mkdir -p adguard/work adguard/conf
cd adguard

services:
  adguardhome:
    image: adguard/adguardhome:latest
    container_name: adguardhome
    restart: unless-stopped
    volumes:
      - ./work:/opt/adguardhome/work
      - ./conf:/opt/adguardhome/conf
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "127.0.0.1:3000:3000/tcp"
      - "127.0.0.1:8080:80/tcp"

docker compose up -d
docker compose ps
docker compose logs --tail=100 adguardhome

If you have a browser on the server, open http://127.0.0.1:3000. For a headless server reachable by SSH, create a temporary port forward from your workstation:

ssh -L 3000:127.0.0.1:3000 your-user@SERVER_LAN_IP

Keep that SSH session open and browse to http://127.0.0.1:3000 on your workstation. This carries the setup connection through SSH without exposing port 3000 to the LAN.

Complete the setup wizard

In the wizard, configure the DNS service to listen on port 53 inside the container. Configure the administration web service on port 80 inside the container, which the Compose mapping makes available only as 127.0.0.1:8080 on the host. Create a unique administrator username and a strong password. Record the credential in an appropriate password manager.

Interface labels can differ between AdGuard Home releases. Confirm that DNS is reachable through the container's published port and that the web interface resolves to the expected container port before distributing the service to clients.

After the dashboard works at http://127.0.0.1:8080, remove this line from the Compose file:

      - "127.0.0.1:3000:3000/tcp"

Apply the revised configuration and confirm that the setup port is no longer published:

docker compose up -d
docker compose ps
sudo ss -lntup | grep -E '(:53[[:space:]]|:8080[[:space:]]|:3000[[:space:]])' || true

Configure upstream DNS carefully

In AdGuard Home, open the DNS settings and select upstream resolvers that meet your operational and privacy requirements. You can use conventional DNS or a supported encrypted upstream format. Resolver availability, filtering policy, logging policy, jurisdiction, and validation behavior are choices separate from AdGuard Home itself.

After saving an upstream change, use the dashboard's available test function if present, then issue a direct query and inspect the logs. Avoid configuring AdGuard Home to forward to itself, to the router when the router forwards back to AdGuard Home, or to another resolver that ultimately returns the query to this server. Such configurations create resolver loops.

Configure router DHCP and client DNS

Change DHCP only after direct tests against the server succeed. Router interfaces vary, so look for LAN, DHCP server, DNS server, IPv6 DNS, DHCPv6, or router advertisement settings. Do not confuse WAN DNS, which controls the router's own upstream behavior, with LAN DNS values distributed to clients.

Useful client inspection commands include:

# Linux with systemd-resolved
resolvectl status

# Linux with NetworkManager
nmcli device show | grep -E 'IP4.DNS|IP6.DNS'

# macOS
scutil --dns

# Windows Command Prompt
ipconfig /all

Choose current DNS filter lists and manage exceptions

Start with AdGuard Home's default DNS filter and the curated list catalog available in your installed dashboard. Catalog contents can change, so review each list's current description, maintainer, update status, syntax, and scope before enabling it. A longer list is not automatically more accurate.

AdGuard Home accepts DNS-oriented filtering rules, including supported Adblock-style domain rules and hosts-style entries. Browser filter lists can also contain cosmetic selectors, scriptlet rules, URL-path logic, and other browser-specific syntax that a DNS resolver cannot meaningfully apply. For that reason, do not assume every browser list is suitable as a DNS blocklist.

Enable a small baseline first, then observe it. When a site or application breaks, reproduce the problem while watching the query log. Identify the exact blocked hostname and matching rule. Allow only what is required rather than disabling all filtering or broadly allowing a parent domain without investigation.

Verify the deployment end to end

Verification should prove each layer independently: container health, direct DNS reachability, filtering behavior, DHCP propagation, query logging, IPv4 and IPv6 resolver selection, and dashboard isolation.

1. Check the container and listeners

cd adguard
docker compose ps
docker compose logs --tail=100 adguardhome
sudo ss -lntup | grep -E '(:53[[:space:]]|:8080[[:space:]])' || true

Confirm that Docker reports the container running, no repeated startup errors appear, TCP and UDP port 53 are published as intended, and port 8080 is bound only to 127.0.0.1. If IPv6 exposure matters on your host, inspect the IPv6 listener output and Docker daemon behavior separately.

2. Send direct allowed queries

From a LAN client with dig installed, query the server explicitly. This bypasses DHCP selection and tests the DNS service itself:

dig @SERVER_LAN_IP example.com A
dig +tcp @SERVER_LAN_IP example.com A

The first command normally tests UDP, while +tcp tests TCP. Both protocols matter because DNS can use TCP for responses and operations that do not fit or complete over UDP. Confirm both requests appear in AdGuard Home's query log.

3. Perform a controlled blocking test

Instead of relying on an undocumented domain that may later disappear from a list, add a temporary custom block rule for a harmless test target such as example.org. Query that domain directly, then confirm the query log marks it as blocked and identifies your temporary rule. The DNS answer depends on the configured blocking response mode.

dig @SERVER_LAN_IP example.org A

Remove the temporary rule immediately after the test and query the domain again. Confirm that the subsequent request is allowed. This tests rule application, logging, and removal without relying on a third-party advertising domain.

4. Inspect the DHCP lease and active client resolver

Renew a test client's lease and use the platform-specific commands from the router section. Confirm that the active resolver is the AdGuard Home address, not merely that the router settings page contains it. Review the router's lease table where available to confirm the client obtained a new lease after the change.

5. Test normal client traffic

Open several ordinary sites or applications on the test client, then identify those queries in the AdGuard Home log. If no entries appear, the client may be using cached answers, an external encrypted resolver, a manually configured DNS address, a VPN-provided resolver, or an IPv6 resolver.

6. Check IPv4 and IPv6 separately

Compare the client's IPv4 DNS and IPv6 DNS values. If an unintended IPv6 resolver is present, inspect the router's IPv6 DNS, router advertisement, and DHCPv6 settings. Do not declare the deployment complete until the observed behavior matches the design for both protocol families enabled on your LAN.

7. Verify dashboard isolation

On the host, http://127.0.0.1:8080 should reach the dashboard. From another LAN device, http://SERVER_LAN_IP:8080 should not work with the loopback-only Compose mapping. If it does, inspect the actual container mappings, other reverse proxies, and firewall rules.

Expose only the dashboard with Localtonet

Localtonet can provide a public HTTPS address for the loopback-bound administration service without inbound router port forwarding, firewall changes, VPN setup, or a public IP address. Our client on the selected device establishes an outbound connection to a Localtonet relay server. In this design, the tunnel targets 127.0.0.1:8080. DNS on port 53 remains a LAN service and must not be exposed through the HTTP tunnel.

For the current dashboard sequence and available options, consult the Localtonet HTTP tunnel documentation. Tunnel availability depends on both conditions remaining true: the selected client device must be connected, and the tunnel must be running. A reboot does not by itself prove that either condition has been restored, and the public address after a restart can depend on the selected process type and configuration.

Back up, update, reboot, and monitor the service

Create recoverable backups

The Compose project stores persistent data in ./conf and ./work. Back up both directories together with compose.yaml. Protect backups because configuration and query data can reveal internal hostnames, client activity, credentials, and network structure.

For a consistent maintenance backup, stop the container briefly, create the archive, and restart it:

cd adguard
docker compose stop
tar -czf "../adguard-backup-$(date +%Y%m%d-%H%M%S).tar.gz" compose.yaml conf work
docker compose start
docker compose ps

Test restoration in a safe environment or during a planned maintenance window. A backup is not proven until its files can be read and the service can start from them.

Update with a rollback plan

Before updating, read the AdGuard Home release notes, create a fresh backup, record the currently running image identifier, and preserve the exact image reference or digest needed for rollback. The example Compose file follows the latest tag, which is convenient but does not itself preserve a prior version. Administrators who require deterministic updates should replace it with a deliberately selected image version or digest after checking current project releases.

cd adguard
docker compose images
docker image inspect adguard/adguardhome:latest --format '{{.Id}}'
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 adguardhome

After every update, repeat a direct UDP query, a direct TCP query, a controlled blocked-domain test, a client query-log check, and dashboard access verification. If the update fails, restore the previous explicit image reference and the pre-update data backup according to the rollback plan you recorded before pulling the new image.

Verify behavior after reboot

restart: unless-stopped asks Docker to restart the container when the Docker daemon starts, unless the container was intentionally stopped. It does not help if Docker itself fails to start, storage is unavailable, port 53 is occupied, the configuration is invalid, or the host has no network connectivity.

After a planned reboot, verify each dependency:

docker compose ps
docker compose logs --tail=100 adguardhome
getent hosts example.com
sudo ss -lntup | grep -E '(:53[[:space:]]|:8080[[:space:]])' || true

Then query AdGuard Home directly from a separate client and inspect the query log. If you use Localtonet, also verify that its client is connected and that the HTTP tunnel is running. Do not assume a previously assigned public URL is available until the live tunnel status and an external browser test confirm it.

Routine monitoring

• Review container state and recent logs after host or network changes.
• Watch query-log trends for unexpected clients, repeated failures, and excessive blocks.
• Review custom allow rules and remove obsolete exceptions.
• Confirm filter lists still update and remain maintained by their stated owners.
• Check available disk space for persistent data and backups.
• Test DNS from a representative IPv4 and IPv6 client after router firmware changes.
• Review whether continuous public dashboard access is still necessary.

Troubleshooting common failures

Docker reports that port 53 is already in use

Run sudo ss -lntup and identify the owning process. Check existing containers with docker ps. If systemd-resolved owns only a local stub binding and causes the collision, use the conditional procedure above. If another DNS service owns the port, decide whether to remove it, move it, or integrate it. Do not repeatedly restart Docker without resolving the ownership conflict.

The host loses DNS before AdGuard Home starts

This commonly indicates that the host was pointed at 127.0.0.1 before a working resolver was available or that /etc/resolv.conf was replaced incorrectly. Restore the saved resolver configuration, restart its managing service, and verify getent hosts example.com. Keep the host on a known working resolver until AdGuard Home has started and passed direct tests.

Queries time out from LAN clients

Confirm the server still owns its stable address, then test locally and remotely in sequence. Check the container, logs, TCP and UDP listeners, host firewall, Docker firewall integration, VLAN policy, wireless client isolation, and router access-control rules. A successful query from the server itself does not prove that another LAN segment can reach it.

Clients still show the old DNS server

The DHCP lease may not have renewed, or you may have edited the router's WAN DNS rather than LAN DHCP settings. Renew the client lease, reconnect the interface, and inspect the active resolver. Some clients cache network settings until a reboot. If the router advertises itself as DNS and forwards queries internally, the query log may identify the router rather than individual devices.

Queries work directly but normal applications bypass filtering

Inspect the client's active IPv4 and IPv6 resolvers. Check browser secure-DNS settings, Android Private DNS, VPN profiles, endpoint security software, and applications with hardcoded DNS. Some managed devices enforce an organizational resolver. Change only settings you are authorized to manage, and do not attempt to bypass administrative policy.

A website or application breaks

Reproduce the failure while watching the query log. Look for blocked requests at the same timestamp and identify the matching rule. Temporarily allow the narrowest necessary hostname, retest, and document the reason. If no relevant DNS query is blocked, the problem may be unrelated to AdGuard Home or may involve cached application data. Avoid allowing an entire parent domain unless the service genuinely requires it.

IPv6 clients bypass AdGuard Home

Inspect the client's IPv6 DNS entries and the router's router advertisement or DHCPv6 configuration. An ISP or router-provided IPv6 resolver may be preferred over the advertised IPv4 address. Configure a stable AdGuard Home IPv6 service and suitable firewall policy, or correct the router's resolver advertisements. Reconnect the client and verify the new information rather than relying on the router UI alone.

DNS fails intermittently

Check whether a public secondary resolver is being advertised, whether the AdGuard host is changing address, and whether Wi-Fi power saving or host suspension takes the server offline. Review logs for upstream timeouts. If two filtering resolvers are advertised, confirm both contain equivalent rules and both are healthy. Intermittent behavior can result from clients choosing between inconsistent resolvers.

Allowed domains fail because of a resolver loop

Review every upstream entry. AdGuard Home must not forward to an address that returns the same request to AdGuard Home. A common loop occurs when AdGuard forwards to the router while the router forwards to AdGuard. Replace the circular upstream path with a deliberately selected resolver, restart only if required by the configuration, and repeat direct tests.

The local dashboard works but the Localtonet URL does not

First verify http://127.0.0.1:8080 on the Localtonet client device. Then confirm that the correct device token was selected, that the client is connected, that an available relay server was chosen, that the local target is 127.0.0.1:8080, and that the tunnel was explicitly started. Creating the tunnel is not enough. Test the assigned URL from a network outside the LAN.

The server is unavailable and the network cannot resolve names

Use the recovery device or documented router procedure to restore the previous LAN DNS values. Renew affected client leases. Repair the host, restore a known-good backup if needed, and test AdGuard Home directly before advertising it again. If DNS availability is critical, deploy a second equivalent filtering resolver rather than using an unfiltered public secondary.

Frequently asked questions