Author	Nejat Hakan
eMail	nejat.hakan@outlook.de
PayPal Me	https://paypal.me/nejathakan

DNS Ad Blocker AdGuard Home

Introduction Understanding the Need for Local DNS Resolution and Ad Blocking

Welcome to the world of self-hosted DNS ad blocking with AdGuard Home! In today's digital landscape, we are constantly bombarded with advertisements, trackers, and malicious websites. While browser extensions offer some relief, they often operate only within the browser, leaving other applications and devices on your network unprotected. Furthermore, relying solely on third-party DNS resolvers means entrusting your browsing habits and potentially sensitive query data to external companies.

Self-hosting a DNS resolver like AdGuard Home provides a powerful, network-wide solution to these problems. It puts you in control of your network's Domain Name System (DNS) resolution – the fundamental process that translates human-readable domain names (like www.google.com) into machine-readable IP addresses (like 172.217.160.142).

By intercepting DNS queries from all devices on your network before they reach the public internet, AdGuard Home can selectively block requests for domains known to serve ads, trackers, malware, or other undesirable content. This results in a cleaner, faster, and safer internet experience across your entire network – including computers, smartphones, tablets, smart TVs, and IoT devices.

This guide will take you from the fundamental concepts of DNS and AdGuard Home through initial setup, intermediate customization, advanced configurations like high availability and API integration, and practical troubleshooting. We aim to provide a comprehensive understanding, empowering you to effectively deploy and manage your own robust ad-blocking solution. Each section builds upon the last, with practical workshops designed to solidify your learning through hands-on experience. Let's begin by exploring the basics.

1. Understanding AdGuard Home Fundamentals

Before diving into installation and configuration, it's crucial to grasp the core concepts behind AdGuard Home and how it functions as a DNS-based ad blocker. Understanding these fundamentals will make configuration, customization, and troubleshooting significantly easier.

What is DNS Filtering?

At its heart, AdGuard Home is a filtering DNS resolver. Let's break down what that means:

DNS (Domain Name System): As mentioned, DNS is like the phonebook of the internet. When you type www.example.com into your browser, your device needs to find the corresponding IP address to connect to the server hosting that website. It sends a DNS query to a DNS resolver (like your ISP's default resolver, Google Public DNS 8.8.8.8, or Cloudflare 1.1.1.1).
Resolver: The DNS resolver receives the query (e.g., "What is the IP address for www.example.com?"). It then looks up this information, potentially querying other DNS servers across the internet in a hierarchical fashion, and sends the IP address back to your device.
Filtering: AdGuard Home inserts itself into this process. You configure your devices (or your router) to send their DNS queries to AdGuard Home instead of directly to a public resolver. AdGuard Home maintains lists of domain names associated with ads, tracking, malware, etc. (these are called "blocklists"). When it receives a query, it checks if the requested domain is on any of its active blocklists.
- If the domain is blocked: AdGuard Home typically responds with a non-routable IP address (like 0.0.0.0) or simply refuses to resolve the domain (NXDOMAIN response). This prevents your device from ever connecting to the ad server.
- If the domain is NOT blocked: AdGuard Home forwards the query to an "upstream" DNS resolver (which you configure – this could be Google, Cloudflare, Quad9, or others) to get the real IP address. It then passes this legitimate IP address back to your device, allowing the connection.

The beauty of this approach is that it happens at the network level. Any device configured to use AdGuard Home as its DNS server benefits from the filtering, regardless of the application or browser being used.

Core Components Explained

DNS Server: The primary function. Listens for incoming DNS queries (usually on UDP and TCP port 53) from clients on your network.
Filtering Engine: The brain of the operation. Compares incoming queries against enabled blocklists and custom filtering rules.
Blocklists: Curated lists of domain names to be blocked. These are typically maintained by the community or specific organizations (e.g., EasyList, AdAway list). AdGuard Home allows you to add multiple lists.
Custom Filtering Rules: Allows you to define your own blocking or unblocking rules using a specific syntax. This provides fine-grained control beyond pre-defined blocklists, letting you block specific subdomains or whitelist domains that are mistakenly blocked.
Upstream DNS Servers: The external DNS resolvers AdGuard Home forwards legitimate (non-blocked) queries to. You can configure multiple upstream servers and choose how AdGuard Home uses them (e.g., load balancing, parallel requests). AdGuard Home supports various secure DNS protocols for upstream communication, such as DNS-over-TLS (DoT), DNS-over-HTTPS (DoH), and DNS-over-QUIC (DoQ).
Query Log: Records all DNS queries processed by AdGuard Home, showing which client made the request, the requested domain, whether it was blocked or allowed, and which filter list or rule caused the block (if any). This is invaluable for troubleshooting.
Client Management: Allows you to identify and manage individual devices (clients) making DNS requests. You can apply different filtering rules or blocklists to different clients, offering granular control (e.g., stricter filtering for kids' devices).
Web Interface: A user-friendly graphical interface, usually accessible via a web browser, for configuring all aspects of AdGuard Home, viewing statistics, and examining the query log.

Understanding these components is key to effectively managing your AdGuard Home instance.

Workshop Installing AdGuard Home (Docker)

This workshop guides you through installing AdGuard Home using Docker, a popular containerization platform. Docker simplifies deployment by packaging the application and its dependencies together. We assume you have Docker and Docker Compose installed on your host system (e.g., a Linux server, Raspberry Pi, NAS).

Goal:

Install and run a basic AdGuard Home container.

Prerequisites:

A host machine (Linux recommended, but macOS/Windows with Docker Desktop works).
Docker installed (sudo apt update && sudo apt install docker.io or platform equivalent).
Docker Compose installed (sudo apt install docker-compose or platform equivalent).
Basic command-line familiarity.
An available static IP address for your host machine on your local network (important for client configuration later). Let's assume your host's static IP is 192.168.1.100.

Steps:

Create a Directory:
- Choose a location on your host system to store AdGuard Home's configuration and data. This ensures your settings persist even if the container is removed and recreated.
- Open your terminal and run:
```
mkdir ~/adguardhome
cd ~/adguardhome
mkdir workdir confdir
```
- workdir will store operational data (like query logs, statistics), and confdir will store the main configuration file.

Create a docker-compose.yml File:

Inside the ~/adguardhome directory, create a file named docker-compose.yml using a text editor (like nano or vim).
```
nano docker-compose.yml
```

Paste the following content into the file. Read the comments carefully to understand each part:

version: "3.7"
services:
  adguardhome:
    image: adguard/adguardhome:latest # Use the official AdGuard Home image
    container_name: adguardhome      # Assign a predictable name
    # Volumes map directories on your host to directories inside the container.
    # This persists your configuration and data.
    volumes:
      - ./workdir:/opt/adguardhome/work # Map host 'workdir' to container's work directory
      - ./confdir:/opt/adguardhome/conf # Map host 'confdir' to container's config directory
    ports:
      # Port mappings: <Host Port>:<Container Port>
      # AdGuard Home web interface (Initial setup on 3000, then moves to 80)
      - "3000:3000/tcp" # For the initial setup wizard
      - "8080:80/tcp"   # Map host port 8080 to container port 80 for the web UI (avoiding conflicts if host port 80 is used)
      - "443:443/tcp"   # If you plan to enable HTTPS later (optional for now)
      - "443:443/udp"   # If you plan to enable HTTPS later (optional for now)
      # Standard DNS port
      - "53:53/udp"
      - "53:53/tcp"
      # DNS-over-TLS (DoT) - Optional, if you enable it later
      - "853:853/tcp"
      # DNS-over-HTTPS (DoH) - Optional, if you enable it later
      - "8443:8443/tcp" # Example port for DoH, mapped from container's default (often 443, but conflicts with web UI HTTPS)
      # DNS-over-QUIC (DoQ) - Optional, needs UDP
      # - "784:784/udp" # AdGuard default DoQ port (uncomment if needed)
    restart: unless-stopped # Automatically restart the container unless manually stopped
    # Optional: Set the container's timezone (replace with your timezone)
    environment:
      - TZ=Europe/Berlin
    # Optional: Network mode (host mode simplifies port mapping but has security implications)
    # For simplicity now, we use bridge mode (default) with explicit port mapping.
    # network_mode: host # Alternative: removes need for port mapping but less isolated. Avoid unless needed.

Important Notes on Ports:
- We map the container's standard web UI port 80 to the host's port 8080. This is common practice to avoid conflicts if another service (like a web server) is already using port 80 on your host machine. You will access the AdGuard Home web UI via http://<your_host_ip>:8080.
- Port 3000 is only needed for the very first time you run AdGuard Home to complete the initial setup wizard. After setup, AdGuard Home will use the port mapped to its internal port 80 (which we set as 8080 on the host).
- DNS queries always use port 53 (both UDP and TCP). We map host port 53 directly to container port 53. Crucially, no other service on your host machine should be using port 53. If a local DNS service (like systemd-resolved's stub listener) is using port 53, you'll need to disable it or configure AdGuard Home to use a different host port (which makes client configuration more complex). Check with sudo ss -tulnp | grep :53.
- Ports 443, 853, 8443, 784 are for advanced features (HTTPS UI, DoT, DoH, DoQ) and can be commented out or removed if you don't plan to use them immediately. Mapping 443:443 is common if you intend to secure the web UI with HTTPS. Mapping 8443 to the container's DoH port avoids conflict if 443 is used for the web UI.

Start the Container:
- Make sure you are in the ~/adguardhome directory (where your docker-compose.yml file is).
- Run the following command:
```
sudo docker-compose up -d
```
- up tells Docker Compose to create and start the services defined in the file.
- -d runs the containers in detached mode (in the background).
- Docker will download the adguard/adguardhome image if you don't have it locally and then start the container.
Verify the Container is Running:
- Check the status of your containers:
```
sudo docker ps
```
- You should see the adguardhome container listed with status Up.
- Check the container logs for any immediate errors:
```
sudo docker logs adguardhome
```
Access the Initial Setup Wizard:
- Open a web browser on a computer on the same network as your host machine.
- Navigate to http://<your_host_ip>:3000 (replace <your_host_ip> with the static IP address of the machine running Docker, e.g., http://192.168.1.100:3000).
- You should see the AdGuard Home "Get Started" screen.

Troubleshooting:

Port Conflict: If the container fails to start, check the logs (sudo docker logs adguardhome). A common issue is another service using port 53. You might need to stop/disable the conflicting service (e.g., sudo systemctl stop systemd-resolved, sudo systemctl disable systemd-resolved) or reconfigure it to not listen on 0.0.0.0:53.
Firewall: Ensure your host machine's firewall allows incoming connections on the ports you mapped in docker-compose.yml (especially UDP/TCP 53, TCP 8080, and TCP 3000 for setup). For ufw on Ubuntu: sudo ufw allow 53/udp, sudo ufw allow 53/tcp, sudo ufw allow 8080/tcp, sudo ufw allow 3000/tcp.
Incorrect IP: Double-check you are using the correct IP address of the host machine running Docker.

You have now successfully installed AdGuard Home using Docker! The next step is to proceed with the initial configuration via the web interface.

2. Initial Configuration and Basic Usage

With AdGuard Home installed and running, the next step is to perform the initial setup and familiarize yourself with the basic administrative tasks. This involves configuring essential settings through the web wizard, understanding the dashboard, adding your first client device, and managing basic blocklists.

The Initial Setup Wizard

When you first access AdGuard Home via http://<your_host_ip>:3000, you'll be greeted by a step-by-step setup wizard. Let's walk through it:

Get Started: A welcome screen. Click "Get Started".
Web Interface Configuration:
- Listen Interfaces: Specifies which network interfaces AdGuard Home's web UI will be accessible from. Choosing "All interfaces" (0.0.0.0) is usually fine for a home network, making it accessible via any IP address assigned to your host machine.
- Port: Sets the port for the web UI. Crucially, inside the container, AdGuard Home defaults to port 80. Because we mapped host port 8080 to container port 80 in our docker-compose.yml, you should leave the port inside the wizard as 80. You will continue to access the UI via http://<your_host_ip>:8080 after setup. Click "Next".
DNS Server Configuration:
- Listen Interfaces: Specifies which network interfaces the AdGuard Home DNS server will listen on for queries. Again, "All interfaces" (0.0.0.0) is typically appropriate for a home setup, allowing any device on your network to potentially send queries to it.
- Port: Sets the port for the DNS server. The standard DNS port is 53. Leave this as 53. Our docker-compose.yml correctly maps host port 53 to container port 53. Click "Next".
- Note: If you encounter errors here, it likely means port 53 is already in use on your host machine (see Workshop 1 troubleshooting).
Authentication:
- Set up a username and a strong password for accessing the AdGuard Home web interface. This is critical for security. Store these credentials safely. Click "Next".
Configure Devices:
- This screen provides instructions on how to configure various operating systems (Windows, macOS, Android, iOS, Routers) to use your new AdGuard Home instance as their DNS server. It will display the IP address of your AdGuard Home server (e.g., 192.168.1.100). We will cover this in the workshop below. Click "Next".
Done: Setup is complete! Click "Open Dashboard". You will be redirected to the login page, likely now at http://<your_host_ip>:8080. Log in with the username and password you just created.

Exploring the Dashboard

The AdGuard Home dashboard provides a quick overview of its activity:

General Statistics: Shows total queries, blocked queries (and percentage), blocked malware/phishing attempts, and average processing time.
Top Queried Domains: Lists the domains your clients are requesting most frequently.
Top Blocked Domains: Shows the domains being blocked most often. Useful for identifying noisy trackers or potentially misbehaving applications.
Top Clients: Lists the devices (by IP address initially) sending the most queries.
Query Log Snippet: Shows the most recent DNS queries.

Spend some time navigating the top menu bar:

Dashboard: The main overview page.
Query Log: Detailed view of all processed queries. Essential for troubleshooting.
Settings: Contains various configuration sections:
- General Settings: Basic options like blocking mode, query log retention, etc.
- DNS Settings: Configure upstream DNS servers, bootstrap DNS, caching.
- Encryption Settings: Configure HTTPS for the web UI, DNS-over-HTTPS/TLS.
- Client Settings: Manage identified clients and apply per-client settings.
- DHCP Settings: (Advanced) Configure AdGuard Home to act as a DHCP server.
Filters: Manage blocklists and custom filtering rules.
- DNS blocklists: Add, enable/disable, and update community-maintained lists of domains to block.
- DNS allowlists: Add lists of domains that should never be blocked.
- DNS rewrites: Define custom DNS records (e.g., point mylocalservice.lan to a local IP).
- Blocked services: Easily block common web services (Facebook, Twitter, etc.) with a single click.
- Custom filtering rules: Manually add your own block/allow rules.

Basic Blocklist Management

AdGuard Home comes with a default blocklist enabled ("AdGuard DNS filter"). You can manage blocklists under Filters -> DNS blocklists:

Adding Lists: Click "Add blocklist". You can choose from a list of well-known blocklists or add your own by providing a name and the URL of the list (usually a text file with one domain per line). Popular choices include OISD (oisd.nl), AdAway, StevenBlack's hosts.
Enabling/Disabling: Use the toggle switch next to each list name.
Updating: AdGuard Home automatically updates lists periodically (configurable under Settings -> General Settings -> Filters update interval). You can force an update by clicking the "Check for updates" button in the blocklist section.

Start with the default list, and perhaps add one or two reputable general-purpose lists like OISD. Adding too many lists can increase memory usage and potentially cause conflicts or block legitimate domains (false positives).

Workshop Configuring Your First Client and Adding a Blocklist

This workshop will guide you through configuring one of your devices to use AdGuard Home for DNS resolution and adding an additional popular blocklist.

Goal:

Make your computer or smartphone use AdGuard Home and enhance blocking with a new list.

Prerequisites:

AdGuard Home installed and running (from Workshop 1).
Access to the AdGuard Home web UI (http://<your_host_ip>:8080).
The IP address of your AdGuard Home server (e.g., 192.168.1.100).
Access to the network settings of a client device (e.g., your Windows/macOS computer or Android/iOS phone).

Steps:

Configure a Client Device (Example: Windows 10/11):
- Right-click the Network icon in your system tray (usually near the clock).
- Click "Network & Internet settings".
- Click "Change adapter options" (or "Advanced network settings" -> "More network adapter options").
- Right-click the network adapter you are currently using (e.g., "Wi-Fi" or "Ethernet").
- Select "Properties".
- Select "Internet Protocol Version 4 (TCP/IPv4)" and click "Properties".
- Select the radio button "Use the following DNS server addresses:".
- In the "Preferred DNS server" field, enter the IP address of your AdGuard Home server (e.g., 192.168.1.100).
- Optional but recommended: In the "Alternate DNS server" field, you could enter the IP address of a reliable public DNS server (like 1.1.1.1 or 8.8.8.8) or a second AdGuard Home instance if you set one up for redundancy. However, be aware: Some operating systems might use the alternate server unpredictably, potentially bypassing AdGuard Home. For maximum filtering, you might leave the alternate blank or point it to the same AdGuard Home IP. For this basic setup, let's leave it blank or use the AdGuard Home IP again.
- Click "OK" on the TCP/IPv4 Properties window.
- Click "Close" on the adapter Properties window.
- Note for other OS: The process is similar: find the network settings for your active connection (Wi-Fi or Ethernet) and look for the DNS settings. Change them from "Automatic (DHCP)" to "Manual" and enter the AdGuard Home IP address. On Android/iOS, this is usually under the specific Wi-Fi connection's advanced settings.
Verify Client Configuration:
- Open a command prompt (Windows: cmd or PowerShell) or terminal (macOS/Linux).
- Flush your local DNS cache:
  - Windows: ipconfig /flushdns
  - macOS: sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder
  - Linux: sudo systemd-resolve --flush-caches (or sudo resolvectl flush-caches)
- Try to ping a common domain: ping google.com. It should resolve successfully.
- Browse a few websites, including some known to have ads (e.g., news sites).
Check AdGuard Home Dashboard:
- Go back to your AdGuard Home web UI (http://<your_host_ip>:8080).
- You should start seeing statistics populate on the Dashboard. The IP address of the client device you just configured should appear under "Top Clients".
- Go to the "Query Log". You should see DNS queries coming from your client's IP address. Some might be blocked (often highlighted in red or orange, depending on the theme).
Add a New Blocklist:
- In the AdGuard Home UI, navigate to Filters -> DNS blocklists.
- Click the "Add blocklist" button.
- Select "Choose from the list".
- Scroll down and find a reputable list, for example, "OISD Blocklist Big". Check its box.
- Click "Save".
- AdGuard Home will download and enable the list. You can monitor the progress at the top of the page. Once added, ensure the toggle switch next to it is enabled (usually blue).
Observe the Effect:
- Continue browsing the web on your configured client device.
- You may notice fewer ads appearing on websites.
- Check the "Query Log" again. You should see more queries being blocked, and the "Response" column might indicate which list caused the block (e.g., "Blocked by OISD Blocklist Big").
- The statistics on the Dashboard (especially "Ads blocked") should increase over time.

Troubleshooting:

No Internet Access: If the client device loses internet connectivity after changing DNS, double-check you entered the correct AdGuard Home IP address. Ensure the AdGuard Home container is running and port 53 is correctly mapped and not blocked by a firewall. Try pinging the AdGuard Home IP address from the client device.
Ads Still Appearing: Some ads use complex methods or are served from the same domain as content, making them hard to block via DNS alone. Ensure the blocklists are enabled and updated. Check the Query Log to see if the ad domains are being queried and whether they are being blocked or allowed. You might need more specific blocklists or custom rules (covered later). Remember to clear your browser cache after changing DNS settings.

You have now successfully configured a client to use AdGuard Home and expanded its blocking capabilities by adding a new list. This forms the foundation for network-wide ad blocking. The next step is often configuring your router to use AdGuard Home, automatically covering all devices on your network. However, per-device configuration is useful for testing or applying different rules to specific machines.

3. Advanced Filtering and Customization

While default blocklists catch a significant amount of unwanted content, you'll inevitably encounter situations requiring more granular control. This section delves into AdGuard Home's advanced filtering capabilities, allowing you to tailor its behavior precisely to your needs, troubleshoot blocking issues, and refine your setup.

Understanding Custom Filtering Rule Syntax

AdGuard Home utilizes a powerful filtering syntax, largely compatible with Adblock-style rules, but with specific nuances for DNS-level blocking. These rules are added under Filters -> Custom filtering rules.

Basic Syntax:

Blocking a domain:
```
||example.com^
```
- ||: Matches domains at the beginning (anchors to the domain name).
- example.com: The domain to block.
- ^: Separator character. This rule blocks example.com and all its subdomains (e.g., www.example.com, ads.example.com).
Blocking a specific subdomain:
```
|subdomain.example.com^
```
- This blocks only subdomain.example.com. www.example.com or example.com would not be blocked by this rule.
Unblocking (Allowlisting/Whitelisting) a domain:
```
@@||example.com^
```
- @@: Marks the rule as an exception (allowlist).
- This rule prevents example.com and all its subdomains from being blocked, even if they appear on a blocklist. This is crucial for fixing "false positives" where a blocklist incorrectly blocks a needed domain.
Unblocking a specific subdomain:
```
@@|subdomain.example.com^
```
- This specifically unblocks subdomain.example.com.

Important Modifiers (DNS-Specific):

$client: Apply rule only to specific clients (identified by IP address, MAC address, or ClientID set in Client Settings).

||ads.example.net^$client=192.168.1.50  # Block ads.example.net only for client 192.168.1.50
@@||analytics.google.com^$client='My_Phone' # Unblock Google Analytics only for client named 'My_Phone'

$dnstype: Apply rule only to specific DNS query types (e.g., A, AAAA, MX, TXT). Useful for very specific blocking scenarios.
```
||evil-tracker.com^$dnstype=AAAA # Block only IPv6 requests for evil-tracker.com
```
$important: Increases the rule's priority. An $important allowlist rule (@@) will override even $important block rules. Useful for ensuring critical services are never blocked.
```
@@||critical.service.local^$important # Make sure this local service is always accessible
```
$badfilter: Used in blocklist definitions to disable specific overly aggressive rules from those lists without disabling the entire list. You generally won't use this directly in custom rules but might see it if you inspect default list rules.

Comments: Lines starting with ! or # are treated as comments and ignored.

! This is a comment explaining the next rule
# Block the entire bad-domain.org
||bad-domain.org^

Managing Multiple Blocklists Effectively

Using multiple blocklists increases coverage but also the potential for conflicts and false positives.

Start Conservatively: Begin with one or two well-regarded, general-purpose lists (e.g., AdGuard DNS filter, OISD).
Add Specialized Lists Cautiously: If you need to block specific types of content (e.g., social media trackers, specific malware families), add specialized lists one at a time and monitor the Query Log for issues.
Prioritize Quality over Quantity: A single, large, well-maintained list (like OISD) can often be more effective and less problematic than dozens of smaller, potentially outdated lists.
Use Allowlisting Generously: Don't hesitate to use @@ rules in your Custom Filtering Rules to unblock domains essential for website functionality or specific services if a blocklist catches them. It's better to allow a few non-critical trackers than to break important websites.
Regularly Check Updates: Ensure your lists are updating correctly (Settings -> General Settings -> Filters update interval). Manually check for updates via Filters -> DNS blocklists -> Check for updates if you suspect an issue.

Whitelisting and Blacklisting Specific Domains

Beyond using @@ rules, AdGuard Home provides dedicated sections for clarity:

Filters -> DNS allowlists: Primarily designed for adding entire lists of domains to allow (similar to blocklists, but for unblocking). You can add URLs pointing to allowlist files. Use cases include corporate environments needing to ensure access to specific partner domains or unblocking domains commonly flagged by overly aggressive lists.
Filters -> DNS blocklists: For adding lists of domains to block.
Filters -> Custom filtering rules: The most flexible place for individual domain blocking (||domain.com^) and unblocking (@@||domain.com^). This is typically where you'll add your specific overrides.

When to use which:

Need to block a single domain not on your lists? Add ||domain.com^ to Custom Rules.
Need to unblock a single domain blocked by a list? Add @@||domain.com^ to Custom Rules.
Have a file/URL containing many domains to always allow? Add it to DNS Allowlists.
Have a file/URL containing many domains to always block? Add it to DNS Blocklists.

Understanding and Using Query Logs for Troubleshooting

The Query Log is your most powerful diagnostic tool. When a website isn't loading correctly, an app fails to connect, or ads are still showing up, the Query Log holds the answers.

Filtering: You can filter the log by client IP, domain name, status (Blocked, Allowed, etc.), and time range.
Information: Each entry shows:
- Time of the query.
- Client IP address (or name, if configured).
- Domain requested.
- Type of query (A, AAAA, etc.).
- Status (Processed, Blocked, Whitelisted, etc.).
- Response (IP address returned, or blocking reason).
- Upstream server used (if forwarded).
- Time taken.
- Crucially for blocking: If blocked, it often indicates which list or custom rule caused the block.

Troubleshooting Workflow:

Identify the Problem: Note the approximate time the issue occurred and the service/website involved.
Access Query Log: Go to the AdGuard Home Query Log.
Filter: Filter by the client IP address experiencing the issue and potentially the domain name if known (e.g., problematic-service.com). Set the time range to cover when the issue occurred.
Analyze: Look for queries related to the problematic service.
- Blocked Query: If you see a query for a domain related to the service being Blocked, check the "Response" column. It should indicate which filter list or custom rule blocked it.
  - Solution: If the block is incorrect (false positive), click the "Unblock" button directly in the log entry (this adds an @@ rule to your Custom filtering rules) or manually add a more specific @@ rule.
- Allowed Query but Service Fails: If the query is processed and an IP address is returned, the issue might not be DNS blocking. It could be an upstream DNS problem, a network connectivity issue, a server-side problem with the service itself, or browser-level blocking (extensions).
- No Query Found: If you expect a query for a specific domain but don't see it, ensure the client device is actually using AdGuard Home for DNS. Check the client's DNS settings and flush its DNS cache. The application might also have hardcoded DNS servers, bypassing AdGuard Home (common in some smart TVs or IoT devices).
- Unexpected Domain Blocking: Sometimes, blocking one domain (e.g., a tracker) can break functionality on a seemingly unrelated domain that relies on it. Look for blocked domains around the time the main site was accessed. Try unblocking related domains temporarily to see if it resolves the issue.

Workshop Creating Custom Filtering Rules

In this workshop, we'll simulate common scenarios requiring custom rules: blocking a specific unwanted domain not caught by lists and unblocking a legitimate domain mistakenly blocked.

Goal:

Create custom block and allow rules and observe their effect.

Prerequisites:

AdGuard Home running and accessible.
A client device configured to use AdGuard Home.
Access to the AdGuard Home Query Log.

Scenario 1: Blocking a Specific Annoyance

Let's imagine there's a specific tracking subdomain, tracker.annoyingsite.com, that isn't included in your current blocklists, but you see it frequently in your Query Log and want it gone.

Steps:

Identify the Domain:
Go to your AdGuard Home Query Log. Filter or scroll to find queries for tracker.annoyingsite.com (you can use a real example you find, or just pretend this one exists for the exercise). Note that it's currently being "Processed" or "Forwarded".
Navigate to Custom Rules:
Go to Filters -> Custom filtering rules.

Add Blocking Rule:
In the text area, add the following line:

! Block the specific tracking subdomain for annoyingsite.com
||tracker.annoyingsite.com^

Apply Changes:
Click the "Apply" or "Save" button.
Verify Blocking:
- On your client device, clear the DNS cache (see Workshop 2, Step 2).
- Try to trigger an action that would cause a query to tracker.annoyingsite.com (e.g., visiting annoyingsite.com if that's where it loads from, or just using a DNS lookup tool).
- Use a command-line tool like nslookup or dig on your client device:
```
nslookup tracker.annoyingsite.com
```
  or
```
dig tracker.annoyingsite.com
```
- You should see a response indicating the domain is blocked (e.g., 0.0.0.0, NXDOMAIN, or a server failure depending on AdGuard Home's blocking mode).
- Check the Query Log in AdGuard Home. You should now see queries for tracker.annoyingsite.com being marked as "Blocked by Custom filtering rules".

Scenario 2: Unblocking a False Positive

Now, imagine a blocklist (e.g., "Problematic List") is blocking api.essentialservice.com, which is required for an application you use.

Steps:

Identify the Block: Go to the Query Log. Find a query for api.essentialservice.com that is marked as "Blocked". The "Response" column should indicate it was "Blocked by Problematic List" (or whichever list caused it).
Use the Quick Unblock (Option 1):
- In the Query Log entry for the blocked domain, simply click the "Unblock" button.
- AdGuard Home will automatically add a rule like @@||api.essentialservice.com^ to your Filters -> Custom filtering rules.
- Click "Apply" or "Save" in the Custom filtering rules section if prompted.
Manually Add Unblock Rule (Option 2):
- Go to Filters -> Custom filtering rules.
- Add the following line:
```
! Unblock the essential API endpoint mistakenly blocked by a list
@@||api.essentialservice.com^
```
- Click "Apply" or "Save".
Verify Unblocking:
- On your client device, clear the DNS cache.
- Try using the application or website that depends on api.essentialservice.com. It should now function correctly.
- Use nslookup or dig again:
```
nslookup api.essentialservice.com
```
- You should now receive the correct IP address(es) for the domain.
- Check the Query Log. Queries for api.essentialservice.com should now be marked as "Processed" or potentially "Whitelisted by Custom filtering rules", and they should not be blocked by "Problematic List" anymore.

Troubleshooting:

Rule Not Working: Ensure the syntax is correct (especially ||, ^, @@). Check for typos in the domain name. Remember that ||domain.com^ blocks subdomains, while |sub.domain.com^ only blocks the specific subdomain. Ensure you clicked "Apply" or "Save". Clear client DNS cache after applying rules.
Overly Broad Unblocking: If you unblock @@||example.com^, you also unblock ads.example.com. If you only needed www.example.com, use a more specific rule like @@|www.example.com^.

Mastering custom filtering rules gives you ultimate control over your network's DNS resolution, allowing you to strike the perfect balance between blocking unwanted content and ensuring seamless access to legitimate services.

4. Optimizing DNS Performance and Security

Once you have basic filtering set up, you can focus on enhancing the performance and security of your AdGuard Home instance. This involves choosing the right upstream DNS providers, leveraging secure protocols, optimizing caching, and securing access to AdGuard Home itself.

Choosing and Configuring Upstream DNS Servers

AdGuard Home forwards non-blocked queries to upstream DNS servers. Your choice of upstream provider impacts privacy, security, speed, and potentially filtering effectiveness (some providers offer their own filtering).

Popular Public DNS Providers:

Cloudflare: 1.1.1.1, 1.0.0.1 (Focus on speed and privacy, supports DoH/DoT/DoQ)
Google Public DNS: 8.8.8.8, 8.8.4.4 (Widely used, reliable, supports DoH/DoT)
Quad9: 9.9.9.9, 149.112.112.112 (Focus on security, blocks known malicious domains, supports DoH/DoT)
OpenDNS Home: 208.67.222.222, 208.67.220.220 (Offers optional family filtering, supports DoH)

Factors to Consider:

Privacy Policy: Review how the provider handles your query data. Providers like Cloudflare and Quad9 generally have strong privacy stances.
Security Features: Does the provider block malicious domains (like Quad9)?
Performance (Latency): Servers geographically closer to you usually offer lower latency. You can use tools like ping or specialized DNS benchmark tools to test latency to different providers from your location.
Supported Protocols: Ensure the provider supports the secure protocols you want to use (DoH, DoT, DoQ).

Configuration in AdGuard Home:

Go to Settings -> DNS Settings -> Upstream DNS servers.

Adding Servers: Enter the server address in the text box. AdGuard Home recognizes various formats:
- Standard IP: 8.8.8.8
- DNS-over-TLS (DoT): tls://1.1.1.1 (Uses TCP port 853 by default)
- DNS-over-HTTPS (DoH): https://dns.google/dns-query (Uses TCP port 443 by default)
- DNS-over-QUIC (DoQ): quic://dns-unfiltered.adguard.com (Uses UDP port 784 or 8853 typically)
- DNSCrypt: sdns://... (Less common now compared to DoH/DoT)
Load Balancing vs Parallel Requests:
- Load Balance: Distributes queries among the configured upstream servers (round-robin). Good for distributing load but might be slightly slower as it waits for one server's response.
- Parallel Requests: Sends the query to all configured upstream servers simultaneously and uses the fastest response. This often results in lower perceived latency but increases overall query load. Generally recommended if you have multiple fast upstreams.
Bootstrap DNS Servers: These servers are used only to resolve the IP addresses of your DoH/DoT/DoQ upstream server hostnames (e.g., to find the IP for dns.google when you use https://dns.google/dns-query). Use reliable IP-based DNS servers here (e.g., 8.8.8.8, 1.1.1.1). Avoid using the same DoH/DoT hostnames here, as it creates a circular dependency.

Secure DNS Protocols (DoT, DoH, DoQ):

Why Use Them?
Standard DNS queries (port 53) are sent in plain text. Anyone between your AdGuard Home instance and the upstream server (like your ISP) can see the domains you are querying. Secure DNS protocols encrypt these queries.
- DoT (DNS-over-TLS):
  Encrypts DNS queries using TLS, typically over TCP port 853. Well-established standard.
- DoH (DNS-over-HTTPS):
  Encrypts DNS queries within HTTPS traffic, typically over TCP port 443. Can be harder to block by firewalls as it looks like regular web traffic.
- DoQ (DNS-over-QUIC):
  Encrypts DNS using the QUIC transport protocol, typically over UDP (ports vary, often 784 or 8853). A newer standard aiming for lower latency than TCP-based DoT/DoH, especially on lossy networks. Support is less widespread than DoT/DoH but growing.
Recommendation:
Use DoT, DoH, or DoQ for your upstream queries whenever possible to enhance privacy and security. Parallel requests with multiple secure upstreams often provide the best balance of speed and reliability.

DNS Caching Explanation and Configuration

Caching is critical for DNS performance. When AdGuard Home resolves a domain (either by forwarding or blocking), it stores the result in its cache for a specific period (defined by the domain's TTL - Time To Live). If another query for the same domain arrives before the TTL expires, AdGuard Home can serve the result directly from its cache, which is significantly faster than querying an upstream server again.

Configuration in AdGuard Home:

Go to Settings -> DNS Settings -> DNS cache configuration.

Cache Size: The number of entries AdGuard Home will keep in its cache. A larger cache might improve performance slightly for frequently visited sites but consumes more memory. The default is often sufficient (4194304 bytes = 4MB).
Override Minimum TTL: Sets a minimum time (in seconds) AdGuard Home will cache a record, even if the domain's authoritative server specified a shorter TTL. Default is 0. Increasing this can improve cache hit rates but might delay updates if a domain's IP changes rapidly.
Override Maximum TTL: Sets a maximum time (in seconds) AdGuard Home will cache a record, even if the domain's authoritative server specified a longer TTL. Default is 0. Decreasing this ensures you get fresher records more quickly but reduces cache effectiveness.
Optimistic Caching: (Experimental Feature) If enabled, AdGuard Home can serve a slightly stale cache entry while simultaneously refreshing it in the background. This can improve perceived performance but might briefly serve outdated information.

Recommendation:
Start with the default cache settings. Only adjust TTL overrides if you have specific reasons (e.g., troubleshooting propagation delays or trying to maximize cache hits). Monitor the "Average processing time" on the dashboard; low times (under 50ms, often much lower) indicate caching is working well.

Setting Up DNS Rewrites for Local Services

If you host services on your local network (e.g., a NAS dashboard, a home automation server, another web service), you might access them via IP address (e.g., 192.168.1.150). DNS Rewrites allow you to assign easy-to-remember domain names to these local IP addresses.

Configuration in AdGuard Home:

Go to Filters -> DNS rewrites. Click "Add DNS rewrite".

Domain: Enter the custom domain name you want to use (e.g., nas.lan, homeassistant.local). Choose a domain suffix that doesn't conflict with real internet domains (.lan, .local, .home are common choices, though .local is officially used by mDNS/Bonjour).
IP address or domain: Enter the local IP address of the service (e.g., 192.168.1.150). You can also CNAME rewrite to another domain.
Example:
- Domain: my-nas.home
- IP address: 192.168.1.150
- Now, any client using AdGuard Home can access your NAS by typing http://my-nas.home in their browser, instead of needing the IP address.

This makes accessing local resources much more user-friendly.

Enabling Basic Security Features

Securing access to AdGuard Home itself is important.

Strong Admin Password: Ensure you set a strong, unique password during initial setup or change it later under Settings -> General Settings -> Authentication.
HTTPS for Web Interface: Encrypts the connection between your browser and the AdGuard Home web UI, protecting your admin password and configuration settings from being intercepted on your local network.
- Go to Settings -> Encryption Settings.
- Check "Enable encryption (HTTPS, DNS-over-HTTPS, DNS-over-TLS)".
- Server name: Enter the domain name or IP address you use to access AdGuard Home (e.g., adguard.local if you set up a rewrite, or 192.168.1.100). This needs to match what the browser uses, for the certificate to be valid.
- Certificates: You can either generate a self-signed certificate (browsers will show a warning you need to bypass) or provide paths to a valid certificate and private key file (e.g., obtained via Let's Encrypt if you have a public domain pointing to AdGuard Home, or using tools like mkcert for local domains). For Docker, you'd typically map these certificate files into the container using volumes.
- Ports: Ensure the HTTPS port (usually 443) is correctly mapped in your docker-compose.yml if you enable this. You'll then access the UI via https://<your_server_name_or_ip>.
Access Settings: (Under Settings -> General Settings -> Access Settings)
- Allowed clients: You can restrict which IP addresses are allowed to send DNS queries to AdGuard Home. By default, it allows all. You could restrict this to your local subnet (e.g., 192.168.1.0/24).
- Disallowed clients: Block specific IPs from querying.
- Blocked domain for disallowed clients: Define what response disallowed clients get (e.g., refuse query).

Recommendation:
At minimum, use a strong password. Enabling HTTPS is highly recommended, even with a self-signed certificate (just accept the browser warning), especially on networks you don't fully trust (like shared Wi-Fi, though AdGuard Home is typically on a private LAN). Restricting allowed clients adds another layer of security.

Workshop Configuring Secure DNS (DoH/DoT) and DNS Rewrites

This workshop guides you through switching your upstream DNS configuration to use secure protocols (DoH or DoT) and setting up a DNS rewrite for a hypothetical local service.

Goal:

Enhance upstream privacy using DoH/DoT and create a convenient local domain name.

Prerequisites:

AdGuard Home running and accessible.
Knowledge of your AdGuard Home server's IP (e.g., 192.168.1.100).
Knowledge of the IP address of another device/service on your local network (e.g., your router at 192.168.1.1, or just use the AdGuard Home IP itself for testing).

Steps:

Configure Secure Upstream DNS (DoH Example):
- Navigate to Settings -> DNS Settings.
- Under Upstream DNS servers, remove any existing standard IP addresses (like 8.8.8.8).
- Add at least two secure DNS servers. We'll use Cloudflare and Quad9 DoH endpoints as examples:
  - Enter https://1.1.1.1/dns-query and click Add or press Enter.
  - Enter https://dns.quad9.net/dns-query and click Add or press Enter.
- Select the Parallel requests mode for potentially faster resolution.
- Under Bootstrap DNS servers, ensure you have reliable IP-based resolvers listed (the defaults like 1.1.1.1, 8.8.8.8, 9.9.9.9 are usually fine). Do not put https://... addresses here.
- Click Apply at the bottom of the page. AdGuard Home will test the upstream servers. You should see green checkmarks or successful test results next to them after a moment.
Verify Secure Upstream Usage:
- Go to the Query Log.
- Browse some new websites on a client device configured to use AdGuard Home.
- Look at the log entries for queries that were "Processed". The "Upstream" column should now show the DoH addresses you configured (e.g., https://1.1.1.1/dns-query). This confirms AdGuard Home is encrypting its upstream queries.
Configure DNS Rewrite:
- Let's create a rewrite so that accessing myguard.lan points to your AdGuard Home server itself.
- Navigate to Filters -> DNS rewrites.
- Click Add DNS rewrite.
- In the "Domain" field, enter myguard.lan.
- In the "IP address or domain" field, enter the IP address of your AdGuard Home server (e.g., 192.168.1.100).
- Click Save.
Verify DNS Rewrite:
- On your client device (that uses AdGuard Home), open a command prompt or terminal.
- Flush the DNS cache (see Workshop 2, Step 2).
- Use nslookup or ping to test the new rewrite:
```
nslookup myguard.lan
```
  or
```
ping myguard.lan
```
- The command should show that myguard.lan resolves to the IP address you entered (192.168.1.100).
- Try accessing your AdGuard Home web UI using the new name: http://myguard.lan:8080 (use the port you mapped). It should load the AdGuard Home interface.
- Check the Query Log. You should see queries for myguard.lan being resolved according to your rewrite rule.

Troubleshooting:

Upstream Errors: If AdGuard Home fails to test the DoH/DoT servers, check for typos in the addresses. Ensure your host machine (where Docker runs) has internet connectivity and its firewall isn't blocking outgoing connections on ports 443 (for DoH) or 853 (for DoT). Check the AdGuard Home log (sudo docker logs adguardhome) for more detailed errors. Ensure Bootstrap DNS servers are configured correctly.
Rewrite Not Working: Double-check the domain and IP address in the rewrite rule. Ensure the client device is definitely using AdGuard Home and that you flushed the client's DNS cache. Some browsers have their own internal DNS cache or might be using Secure DNS (DoH) internally, potentially bypassing AdGuard Home – this often needs to be disabled in browser settings (like Chrome's "Use secure DNS" or Firefox's "Enable DNS over HTTPS") for local rewrites to work reliably.

You have now improved the privacy of your DNS lookups by encrypting upstream queries and made accessing a local service (in this case, AdGuard Home itself) more convenient using a custom domain name. These optimizations provide a more robust and user-friendly DNS experience.

5. High Availability and Scalability

For many home users, a single AdGuard Home instance is sufficient. However, if DNS resolution becomes critical (e.g., for home automation, work-from-home setups, or simply avoiding family complaints when the server is down for maintenance), implementing high availability (HA) becomes important. Scalability refers to handling a larger number of clients or queries, which often goes hand-in-hand with HA.

Why High Availability for DNS?

DNS is a fundamental network service. If your only DNS server (your AdGuard Home instance) goes offline (due to hardware failure, OS updates, container issues, power outage), devices configured to use it will likely lose internet connectivity entirely, as they cannot resolve domain names.

An HA setup typically involves running two or more synchronized AdGuard Home instances. Clients are then configured to use both instances, ensuring that if one fails, the other can seamlessly take over DNS resolution.

Strategies for Running Multiple AdGuard Home Instances

Two Independent Instances:
- Setup: Install AdGuard Home on two separate machines (e.g., two Raspberry Pis, a Pi and a NAS, a server and a VM). Each instance has its own IP address (e.g., 192.168.1.100 and 192.168.1.101).
- Client Configuration: Configure clients (or your router's DHCP settings) to use both IP addresses as DNS servers (Primary: 192.168.1.100, Secondary: 192.168.1.101).
- Pros: Simple to set up initially. Provides redundancy if one host fails completely.
- Cons:
  - Configuration Drift: You need to manually keep the settings (blocklists, custom rules, client settings, etc.) synchronized between the two instances. If you add a rule to one, you must remember to add it to the other.
  - Failover Behavior: Client operating systems handle secondary DNS servers differently. Some might only switch after a noticeable timeout, while others might randomly query the secondary even when the primary is up, potentially leading to inconsistent blocking if configurations differ.
  - Split Query Logs: Statistics and logs are split between the two instances, making overall analysis harder.
Shared Virtual IP Address (using Keepalived):
- Concept: Use a tool like keepalived on two AdGuard Home hosts. keepalived manages a "virtual" IP address (VIP) (e.g., 192.168.1.99). One host is designated as the MASTER and holds the VIP. The other is the BACKUP. They monitor each other using the VRRP protocol. If the MASTER fails, the BACKUP takes over the VIP address.
- Setup: Install AdGuard Home on two hosts. Install and configure keepalived on both hosts to manage the VIP. Both AdGuard Home instances should be configured to listen on all interfaces (or specifically on the interface expected to hold the VIP).
- Client Configuration: Configure clients to use only the Virtual IP address (192.168.1.99) as their DNS server.
- Pros: Seamless failover from the client's perspective (they always talk to the same VIP). Centralizes the client-facing IP.
- Cons:
  - More complex to set up (keepalived configuration).
  - Still requires manual or automated synchronization of AdGuard Home configurations between the two instances.
  - Logs are still split (though all queries hit the active server holding the VIP at any given time).
Load Balancer (Advanced):
- Concept: Place a dedicated load balancer (hardware or software like HAProxy, Nginx) in front of two or more AdGuard Home instances. The load balancer distributes incoming DNS queries (port 53) across the active AdGuard Home backends and performs health checks.
- Setup: Requires configuring a load balancer and pointing clients to the load balancer's IP address.
- Pros: Provides both HA and load balancing for performance. Can handle more sophisticated health checks.
- Cons: Significant setup complexity. Introduces another potential point of failure (though load balancers can also be made highly available). Usually overkill for home networks unless dealing with very high query volumes.

Recommendation for Most Users: Start with the "Two Independent Instances" approach, accepting the need for manual synchronization initially. If configuration synchronization becomes tedious, explore automated solutions (see below). If seamless failover is critical, investigate the keepalived approach.

Syncing Configurations Between Instances

Manually keeping settings identical across multiple instances is error-prone. Here are ways to approach synchronization:

Manual Sync: Log in to both web interfaces and make identical changes. Tedious and unreliable.
Configuration File Sync (Basic):
- AdGuard Home stores its primary configuration in AdGuardHome.yaml (located in the confdir volume we mapped in Docker). Blocklists and rules are also stored within the work/data directory structure.
- You could periodically use tools like rsync or scp to copy the AdGuardHome.yaml file and potentially relevant parts of the data directory from a primary instance to a secondary instance.
- Caution: Simply copying the entire data directory might cause issues with statistics or query logs. Copying just AdGuardHome.yaml synchronizes most settings (upstreams, blocklist URLs, custom rules, client settings, rewrites). You'd still need to trigger a filter update on the secondary instance after syncing. Requires stopping/restarting the secondary AdGuard Home service for AdGuardHome.yaml changes to take effect.
Automated Sync Tools (Community Solutions):
- adguardhome-sync: A popular open-source tool designed specifically for synchronizing AdGuard Home instances. It runs as a separate service (often a Docker container) and uses the AdGuard Home API to compare and replicate configurations (filters, rules, clients, settings) between a primary and one or more replicas.
- Setup: Requires deploying the adguardhome-sync tool and configuring it with the API credentials for your AdGuard Home instances.
- Pros: Automates the synchronization process reliably. Designed specifically for AdGuard Home.
- Cons: Adds another component to manage. Relies on the AdGuard Home API.

Recommendation:
For a two-instance setup, using adguardhome-sync is generally the most robust and convenient method for keeping configurations aligned automatically.

Workshop Setting Up AdGuard Home Sync (Conceptual/Manual)

This workshop focuses on the concept of synchronization. We'll demonstrate manual sync of the configuration file and discuss the principles behind using a tool like adguardhome-sync. Setting up adguardhome-sync itself involves deploying another container and specific configuration, which is slightly beyond a basic AdGuard Home setup but crucial for HA.

Goal:

Understand how configuration is stored and manually synchronize key settings between two conceptual instances.

Prerequisites:

One AdGuard Home instance running (Instance A, IP 192.168.1.100, config in ~/adguardhome/).
Conceptually, imagine a second instance (Instance B, IP 192.168.1.101). For this workshop, we'll simulate Instance B by creating a copy of the configuration directory. In a real scenario, these would be on separate machines.
Access to the host machine's terminal for Instance A.

Steps (Manual Sync Simulation):

Identify Key Configuration File:
- On the host machine for Instance A, navigate to the AdGuard Home configuration directory:
```
cd ~/adguardhome/confdir
ls -l
```
- You should see the AdGuardHome.yaml file. This file contains most of your settings: upstream servers, blocklist URLs, enabled filters, custom rules, client configurations, DHCP settings (if enabled), encryption settings, etc.
Make a Change on Instance A:
- Log in to the web UI of Instance A (http://192.168.1.100:8080).
- Go to Filters -> Custom filtering rules.
- Add a new, unique comment or rule, for example:
```
! Synced Rule Test - Instance A - 2023-10-27
||test-sync-block.com^
```
- Click Apply.
Observe the Change in the File:
- Go back to the terminal on the host machine for Instance A.
- View the contents of the configuration file. You can use cat or less:
```
cat ~/adguardhome/confdir/AdGuardHome.yaml
```
- Search within the file (e.g., using / in less) for test-sync-block.com. You should find the rule you just added, confirming that UI changes are saved to this file.

Simulate Syncing to Instance B:

In a real HA setup with two machines, you would now copy this file from Instance A to Instance B. Using scp (secure copy) is common:

# Syntax: scp <local_file> <user@remote_host>:<remote_path>
# Example (don't run this unless you have a real second host setup):
# scp ~/adguardhome/confdir/AdGuardHome.yaml user@192.168.1.101:/path/to/instanceB/adguardhome/confdir/

For this simulation: We'll just make a backup copy to represent the state before sync and then copy our modified file into a simulated "Instance B" location.

# Create a simulated directory for Instance B config
mkdir ~/adguardhome_instanceB_simulated
mkdir ~/adguardhome_instanceB_simulated/confdir

# Copy the *modified* AdGuardHome.yaml to the simulated Instance B
cp ~/adguardhome/confdir/AdGuardHome.yaml ~/adguardhome_instanceB_simulated/confdir/

Restart Instance B (Conceptual):
- For AdGuard Home to load changes made directly to AdGuardHome.yaml, the service needs to be restarted. In our Docker setup, this would be:
```
# On the host machine for Instance B (if it were real):
# cd /path/to/instanceB/adguardhome/
# sudo docker-compose restart adguardhome
```
- After restarting, Instance B would load the configuration from the copied AdGuardHome.yaml and would now include the ! Synced Rule Test and the block rule for test-sync-block.com.
Understanding adguardhome-sync:
- Instead of manual file copying and restarting, adguardhome-sync works differently:
  - It runs periodically (or triggered via webhook).
  - It connects to the API of the primary instance and reads its configuration (filters, rules, clients, etc.).
  - It connects to the API of the replica instance(s) and reads their configurations.
  - It compares the configurations and identifies differences.
  - It uses API calls to push the necessary changes (additions, deletions) from the primary to the replicas.
- This avoids manual file handling and service restarts, making synchronization seamless and automated. Configuration typically involves providing the URLs and API credentials (username/password) for each AdGuard Home instance to the adguardhome-sync tool.

Conclusion of Workshop: You've seen that AdGuard Home's configuration is primarily stored in AdGuardHome.yaml. While manual synchronization via file copying is possible, it's cumbersome and requires service restarts. Tools like adguardhome-sync leverage the AdGuard Home API to provide a much more elegant and automated solution for maintaining configuration consistency across multiple instances in a High Availability setup. For any serious HA deployment, exploring adguardhome-sync is highly recommended.

6. Integration with Other Services

AdGuard Home can be even more powerful when integrated with other network services and tools. This section explores common integrations, including leveraging its capabilities within your DHCP infrastructure, automating tasks via its API, and exporting metrics for monitoring systems.

Integrating AdGuard Home with DHCP Servers

Dynamic Host Configuration Protocol (DHCP) is the service on your network (usually running on your router) that automatically assigns IP addresses, subnet masks, default gateways, and DNS server information to devices when they join the network.

By controlling the DNS server information provided by your DHCP server, you can automatically direct all DHCP clients on your network to use AdGuard Home without manually configuring each device.

Methods:

Configure Router's DHCP Server:
- Most Common Method: Access your main router's web administration interface.
- Find the DHCP Server settings (often under LAN, Network Settings, or DHCP).
- Look for options labeled "DNS Server 1", "DNS Server 2", "Static DNS", or similar.
- Change these settings from "Automatic" or your ISP's defaults to the static IP address(es) of your AdGuard Home instance(s).
  - If you have one instance (e.g., 192.168.1.100), enter it as DNS Server1. You could leave DNS Server 2 blank or point it to the same AdGuard Home IP. Avoid pointing it to a non-AdGuard Home DNS server if you want to ensure all queries go through AdGuard Home.
  - If you have two HA instances (e.g., 192.168.1.100 and 192.168.1.101), enter them as DNS Server 1 and DNS Server 2.
  - If using a Virtual IP (192.168.1.99 with keepalived), enter the VIP as DNS Server 1 and potentially leave DNS Server 2 blank or use the VIP again.
- Save the changes on your router.
- Effect: Devices joining the network (or renewing their DHCP lease) will now automatically receive the AdGuard Home IP(s) as their DNS server. Devices might need to disconnect/reconnect or have their DHCP lease renewed (ipconfig /renew on Windows) to pick up the new settings immediately.
Use AdGuard Home's Built-in DHCP Server:
- Alternative Method: AdGuard Home includes an optional DHCP server. You can disable the DHCP server on your main router and enable the one in AdGuard Home.
- Configuration: Go to Settings -> DHCP Settings in AdGuard Home.
  - Check "Enable DHCP server".
  - Configure the IP address range to lease out (e.g., 192.168.1.101 to 192.168.1.200).
  - Set the Router IP address (Default Gateway).
  - Lease duration.
  - Crucially, AdGuard Home will automatically configure clients connecting via its DHCP server to use itself for DNS.
- Pros:
  - Automatic Client Identification: AdGuard Home's DHCP server can automatically register client hostnames, making the Query Log and Client Settings much more informative (showing device names instead of just IP addresses).
  - Ensures clients always get AdGuard Home as the DNS server.
- Cons:
  - Requires disabling your router's DHCP server, which might disable other integrated features on some consumer routers.
  - If your AdGuard Home instance goes down, devices might not be able to obtain or renew IP addresses (unless you have an HA DHCP setup, which is more complex). Running DHCP on your primary AdGuard Home instance in an HA pair is common, but failover needs consideration.
  - May require configuring static leases within AdGuard Home for servers or devices needing fixed IP addresses.

Recommendation:
For most users, configuring your existing router's DHCP server to point DNS to AdGuard Home (Method 1) is the simplest and safest approach. Using AdGuard Home's DHCP server (Method 2) offers benefits like better client identification but requires more careful planning, especially regarding redundancy.

Using AdGuard Home's API for Automation

AdGuard Home provides a comprehensive HTTP API that allows you to programmatically interact with and control nearly all of its features. This opens up possibilities for automation, custom scripting, and integration with other systems.

API Basics:

Endpoint: The API is typically accessible via the same hostname/IP and port as the web UI.
Authentication: API requests require authentication using the same username and password you use for the web UI (Basic Authentication).
Format: The API generally accepts and returns data in JSON format.
Documentation: While official, comprehensive Swagger/OpenAPI documentation has been requested by the community, you can often discover endpoints by:
- Using your browser's developer tools (Network tab) while navigating the AdGuard Home web UI. Actions you perform in the UI trigger API calls you can inspect.
- Consulting the source code or community-maintained documentation snippets.
- Examining how tools like adguardhome-sync interact with the API.

Common Use Cases & Example Endpoints (Illustrative - Check your version):

Getting Stats:
- Endpoint: /control/stats
- Method: GET
- Returns: JSON object with statistics (total queries, blocked, etc.).
Getting Query Log:
- Endpoint: /control/querylog (often accepts parameters like limit, offset, search)
- Method: GET
- Returns: JSON array of query log entries.
Enabling/Disabling Blocking:
- Endpoint: /control/safebrowsing/disable or /control/safebrowsing/enable (similar endpoints exist for parental control, adblocking)
- Method: POST
Adding Custom Filter Rule:
- Endpoint: /control/filtering/set_rules
- Method: POST
- Body: JSON containing an array of rules (e.g., {"rules": ["||example.com^", "@@||google.com^"]})
Adding DNS Rewrite:
- Endpoint: /control/rewrite/add
- Method: POST
- Body: JSON defining the rewrite (e.g., {"domain": "nas.local", "answer": "192.168.1.50"})

Example using curl (Command-line tool):

# Replace with your AdGuard Home details
AGH_USER="your_admin_user"
AGH_PASS="your_admin_password"
AGH_HOST="http://192.168.1.100:8080" # Use HTTPS if enabled

# Get Stats
curl -u "$AGH_USER:$AGH_PASS" "$AGH_HOST/control/stats"

# Disable Blocking (Example Endpoint - Verify Correct Endpoint for your version)
# Assuming /control/filtering/disable exists or similar for global blocking
# curl -u "$AGH_USER:$AGH_PASS" -X POST "$AGH_HOST/control/filtering/disable" -d '{}' --header "Content-Type: application/json"

# Add a custom blocking rule
curl -u "$AGH_USER:$AGH_PASS" -X POST "$AGH_HOST/control/filtering/set_rules" \
--header "Content-Type: application/json" \
--data '{"rules": ["||api-block-via-script.com^"]}'

The API allows for powerful automation scripts, such as temporarily disabling blocking for specific tasks, dynamically adding devices to client groups, or integrating blocking status into dashboards.

Integrating with Monitoring Systems (e.g., Prometheus/Grafana)

For advanced users who run monitoring stacks like Prometheus (for data collection) and Grafana (for visualization), AdGuard Home provides an endpoint to expose metrics in Prometheus format.

Metrics Endpoint: /control/stats_info (Check your version, sometimes /metrics or /control/metrics)
Configuration:
1. Configure Prometheus to "scrape" (collect data from) this endpoint on your AdGuard Home instance(s). This involves adding a target to your prometheus.yml configuration file, specifying the AdGuard Home host/port and the metrics path. Authentication might be needed depending on your setup.
2. Import or create a Grafana dashboard designed for AdGuard Home metrics. Several community-provided dashboards are available online (search for "Grafana AdGuard Home dashboard").
Benefits:
- Visualize trends over time (queries per second, blocked percentage, top clients/domains).
- Set up alerts in Prometheus/Alertmanager based on AdGuard Home metrics (e.g., alert if blocking percentage drops significantly, or if query processing time spikes).
- Correlate AdGuard Home activity with other network or system metrics in a centralized dashboard.

This integration provides deep insights into AdGuard Home's performance and behavior over time, essential for large or critical deployments.

Workshop Querying the AdGuard Home API

This workshop provides a hands-on introduction to interacting with the AdGuard Home API using the curl command-line tool to fetch statistics and add a custom blocking rule.

Goal:

Learn how to authenticate and make basic API calls to AdGuard Home.

Prerequisites:

AdGuard Home running and accessible.
Admin username and password for AdGuard Home.
The IP address and port of your AdGuard Home web UI (e.g., 192.168.1.100:8080).
curl installed on your client machine (usually installed by default on Linux/macOS; downloadable for Windows).
jq installed (optional, but helpful for formatting JSON output). Install using sudo apt install jq or brew install jq.

Steps:

Set Environment Variables (Optional but Recommended):
- Open your terminal. Setting variables makes the commands cleaner and avoids repeatedly typing credentials.
- Replace placeholders with your actual AdGuard Home details:
```
export AGH_USER="your_admin_user"
export AGH_PASS="your_admin_password"
export AGH_HOST="http://192.168.1.100:8080" # Use https:// if you enabled it
```
- Verify the variables are set: echo $AGH_HOST
Fetch Statistics:
- Use curl with the -u flag for basic authentication (username:password) to query the /control/stats endpoint.
- If you have jq installed, pipe the output (|) to jq for pretty-printed JSON.
```
curl -s -u "$AGH_USER:$AGH_PASS" "$AGH_HOST/control/stats" | jq
```
- If you don't have jq:
```
curl -s -u "$AGH_USER:$AGH_PASS" "$AGH_HOST/control/stats"
echo "" # Adds a newline for better readability
```
- Expected Output: A JSON object containing various statistics like num_dns_queries, num_blocked_filtering, avg_processing_time, etc. The -s flag in curl silences progress meters.
Fetch Query Log (Last 10 Entries):
- Query the /control/querylog endpoint. We can add parameters like limit.
```
curl -s -u "$AGH_USER:$AGH_PASS" "$AGH_HOST/control/querylog?limit=10" | jq '.data' # jq filters to show just the data array
```
- Without jq:
```
curl -s -u "$AGH_USER:$AGH_PASS" "$AGH_HOST/control/querylog?limit=10"
echo ""
```
- Expected Output: A JSON object containing a data array, where each element represents a query log entry with details like client, question, status, rule, etc.
Add a Custom Blocking Rule via API:
- First, check your current custom rules in the Web UI (Filters -> Custom filtering rules) to see the "before" state.
- We need to send a POST request to /control/filtering/set_rules. The body must be JSON containing all the rules you want to have (it overwrites existing custom rules).
- Important: It's safer to get the current rules first, append your new rule, and then set the combined list. However, for simplicity in this workshop, we'll just set a single new rule (overwriting any existing ones you might have added manually in this section). Be careful doing this on a production system!
- Define the rule to add: ||api-blocked-domain.com^
- Construct the JSON payload. Note the escaping needed for quotes if defining directly in the shell:
```
{"rules": ["! Rule added via API", "||api-blocked-domain.com^"]}
```
- Execute the curl command:
```
curl -s -u "$AGH_USER:$AGH_PASS" \
     -X POST "$AGH_HOST/control/filtering/set_rules" \
     --header "Content-Type: application/json" \
     --data '{"rules": ["! Rule added via API", "||api-blocked-domain.com^"]}'
```
- Expected Output: Usually, a successful POST request returns an empty response or a simple {"message": "OK"}. No output (with -s) generally indicates success.
- Verify: Go back to the AdGuard Home web UI -> Filters -> Custom filtering rules. You should see only the comment and the ||api-blocked-domain.com^ rule you just added via the API. Any previous custom rules will have been overwritten.
Cleanup (Optional):
- To restore your previous custom rules, you'll need to re-add them manually via the UI or use the API again with the correct full list.
- You can remove the test rule via the UI or by sending an empty rule list via API:
```
curl -s -u "$AGH_USER:$AGH_PASS" \
     -X POST "$AGH_HOST/control/filtering/set_rules" \
     --header "Content-Type: application/json" \
     --data '{"rules": []}'
```

Troubleshooting:

Authentication Errors (401 Unauthorized): Double-check your AGH_USER and AGH_PASS. Ensure you are using the correct username and password created for AdGuard Home.
Connection Refused: Verify the AGH_HOST (IP address and port) is correct and reachable from the machine where you are running curl. Check firewalls. Ensure the AdGuard Home container/service is running.
Incorrect Endpoint/Method (404 Not Found / 405 Method Not Allowed): Verify the API endpoint path (/control/stats, /control/filtering/set_rules) is correct for your AdGuard Home version. Ensure you are using the correct HTTP method (GET vs POST).
Bad Request (400): Check the JSON payload syntax in POST requests. Ensure it's valid JSON and matches what the API expects.

This workshop demonstrated the basics of interacting with the AdGuard Home API. By exploring other endpoints (using browser developer tools or documentation), you can build powerful scripts to automate management, monitoring, and integration tasks.

7. Troubleshooting Advanced Scenarios

Even with a well-configured setup, you might encounter more complex issues. This section covers strategies for diagnosing problems related to intricate filtering interactions, upstream DNS resolution failures, performance bottlenecks, and challenges with identifying specific clients.

Diagnosing Complex Filtering Issues

Sometimes, blocking one domain unintentionally breaks functionality on another site, or a specific element remains unblocked despite your efforts.

Symptom: A website is partially broken (missing images, non-functional buttons), or a specific ad/tracker persists.
Diagnosis:
1. Aggressive Query Logging: Temporarily disable blocking (General Settings -> Block domains using filters and hosts files toggle off, or use the "Disable Protection" button on the dashboard) and clear your browser/client DNS cache. Access the problematic site/service. Observe the Query Log to see all domains being requested. Note down domains related to the site, CDNs (Content Delivery Networks like cdn.jsdelivr.net, ajax.googleapis.com), analytics, and ad servers.
2. Re-enable Blocking & Filter Log: Re-enable blocking, clear caches again, and access the site. Now, filter the Query Log specifically for Blocked queries from your client IP around the time you accessed the site.
3. Identify Overblocking: Look for blocked domains that seem legitimate or related to core site functionality (e.g., CDNs, API endpoints, authentication domains). Blocking cdn.some-framework.com might break many sites using that framework.
4. Targeted Whitelisting: Add temporary @@ rules in Custom filtering rules for suspicious blocked domains, one by one. Clear cache and test the site after each addition. This helps pinpoint the exact domain causing the breakage. Once identified, decide if you want to permanently whitelist it.
5. Persistent Ads/Trackers: If an element isn't blocked, find the domain serving it (browser developer tools -> Network tab can help identify the source URL). Check the Query Log to see if this domain is being queried.
  - Query Allowed: Add a specific block rule (||ad-domain.com^) to Custom Rules.
  - Query Not Found: The ad might be served from the same domain as the content (hard to block via DNS), the client might be bypassing AdGuard Home (hardcoded DNS, browser DoH), or the ad content might be cached.
Tools: Browser developer tools (Network tab) are invaluable for seeing exactly what resources a page is trying to load, even if DNS blocking prevents the connection.

Resolving Upstream DNS Problems

Symptom: Slow website loading across all clients, timeouts, intermittent "Server not found" errors, NXDOMAIN errors for valid sites. AdGuard Home dashboard might show high average processing times or errors in the log related to upstream servers.
Diagnosis:
1. Check AdGuard Home Log: Look for errors like "upstream request failed", "server misbehaving", "connection refused" related to your configured upstream servers (sudo docker logs adguardhome).
2. Test Upstreams Directly: From the host machine running AdGuard Home, use dig or nslookup to query your configured upstream servers directly.
  - Standard DNS: dig @8.8.8.8 google.com
  - DoT: kdig @1.1.1.1 +tls google.com (kdig from knot-dnsutils package often needed) or dig @1.1.1.1 -p 853 +tls google.com (requires specific dig version).
  - DoH: curl -H 'accept: application/dns-json' 'https://dns.google/resolve?name=google.com&type=A'
  - If these direct tests fail or are slow, the issue lies between your AdGuard Home host and the upstream provider (network connectivity, firewall blocking outgoing DoT/DoH ports, ISP issues, upstream provider outage).
3. Test AdGuard Home Upstream Configuration: In AdGuard Home UI -> Settings -> DNS Settings, click the "Test upstreams" button. Check for errors.
4. Simplify Configuration: Temporarily remove all but one known-good, standard DNS upstream (like 8.8.8.8). If resolution improves, the issue was with your specific selection or combination of secure upstreams (e.g., a DoH provider being down). Re-add them one by one.
5. Check Bootstrap DNS: Ensure your Bootstrap DNS servers (under DNS Settings) are reachable and working correctly. If AdGuard Home can't resolve the hostname of your DoH/DoT server (e.g., cloudflare-dns.com), it can't use it.
6. System Resources: Check CPU/Memory usage on the AdGuard Home host. If the system is overloaded, DNS processing can suffer.

Performance Bottleneck Analysis

Symptom:
High average processing time in AdGuard Home dashboard, generally sluggish DNS resolution.
Diagnosis:
1. Cache Hit Rate:
  While AdGuard Home doesn't directly display a cache hit rate, consistently high processing times (e.g., > 100ms average) suggest caching might not be effective or upstreams are slow. Consider adjusting cache size or TTLs cautiously (see Section 4).
2. Number of Blocklists/Rules:
  Too many active blocklists (> 1-2 million rules combined) can consume significant memory and slightly increase processing time per query, especially on low-resource devices like older Raspberry Pis. Disable less critical lists and observe performance. Check memory usage of the AdGuard Home process/container.
3. Upstream Latency:
  Use ping or DNS benchmark tools from the host to measure latency to your configured upstreams. Switch to faster/closer providers if necessary. Using "Parallel requests" mode can mitigate the impact of a single slow upstream.
4. Host System Performance:
  Check CPU, memory, and disk I/O on the host machine running AdGuard Home. Other processes consuming resources can impact AdGuard Home's responsiveness.
5. Client Query Volume:
  A single misbehaving client sending thousands of queries per second (e.g., a faulty IoT device in a query loop) can overload AdGuard Home. Check the "Top Clients" on the dashboard. Investigate any client with an abnormally high query count. Consider rate-limiting clients if necessary (configurable in Settings -> General Settings -> Access Settings).

Dealing with Client Identification Challenges

By default, AdGuard Home identifies clients by their IP address. This can be problematic if:

Your DHCP server assigns IPs dynamically, meaning a device's IP might change.
Multiple devices are behind a NAT gateway or router that forwards DNS (less common in home setups, more in complex networks), making all queries appear to come from the router's IP.
Strategies:
1. Static DHCP Leases:
  Configure your DHCP server to always assign the same IP address to specific devices based on their MAC address. This makes IP-based identification in AdGuard Home reliable.
2. Use AdGuard Home's DHCP Server:
  As mentioned in Section 6, enabling DHCP in AdGuard Home allows it to automatically learn and display client hostnames, providing much better identification.
3. Configure Clients Manually in AdGuard Home:
  Go to Settings -> Client Settings. You can manually add clients and assign them names. You can identify them by:
  - IP Address: Suitable if using static leases.
  - MAC Address: More reliable than dynamic IPs, but requires AdGuard Home to be on the same network segment as the clients to see MAC addresses (won't work if AdGuard Home is on a different VLAN/subnet than the clients).
  - Client ID (CIDR or Tag): You can assign custom tags (Client IDs) to clients. This requires configuring the clients themselves to send this identifier with their DNS queries. This is often difficult or impossible on many consumer devices but might be feasible in controlled environments or using specialized client software.
4. Per-Client Filtering: Once clients are identified (by IP, MAC, Name, or Tag), you can apply specific settings: block different services, use different blocklists, or disable filtering entirely for that client.

Recommendation:
Combining static DHCP leases on your router with manually adding and naming clients in AdGuard Home (Settings -> Client Settings) using their static IPs provides good identification without replacing your router's DHCP. Using AdGuard Home's DHCP is the most seamless for hostname identification if feasible in your network.

Workshop Diagnosing a Filtering Problem Using Query Logs

This workshop simulates a common scenario: a user reports that www.important-partner-site.com is not loading, suspecting the new AdGuard Home setup is the cause. We'll use the Query Log to diagnose and fix the issue.

Goal:

Use the Query Log to identify an incorrect block and apply a fix using custom rules.

Prerequisites:

AdGuard Home running, with at least one blocklist enabled.
A client device configured to use AdGuard Home.
Access to the AdGuard Home web UI, particularly the Query Log.

Scenario: A blocklist ("Overly Aggressive List") incorrectly contains api.important-partner-site.com, which is required for www.important-partner-site.com to function fully. The user only reports the main site failing.

Steps:

Reproduce the Issue:
- On the client device, clear the browser cache and DNS cache (ipconfig /flushdns, etc.).
- Try to access http://www.important-partner-site.com (or imagine doing so). Note the time. Assume the site fails to load essential content or throws an error.
Investigate the Query Log:
- Go to the AdGuard Home Query Log.
- Filter the log:
  - Client: Enter the IP address of the client device that experienced the issue.
  - Time Range: Select a range covering the time you attempted to access the site.
  - Status: Initially, leave as "All" to see the full picture.
- Look for queries related to important-partner-site.com. You might see:
  - www.important-partner-site.com - Status: Processed (or maybe blocked if the main domain was also listed)
  - static.important-partner-site.com - Status: Processed
  - api.important-partner-site.com - Status: Blocked (Response might say "Blocked by Overly Aggressive List")
  - Other related domains (CDNs, etc.).
Identify the Likely Culprit:
- The blocked query for api.important-partner-site.com is highly suspicious. API endpoints are often crucial for website functionality. The block coincides with the reported failure of the main website.
Confirm the Block Reason:
- Click on the log entry for api.important-partner-site.com.
- The details view should explicitly state which filter list or rule caused the block (e.g., "Blocked by: Overly Aggressive List - https://list.example.com/overly_aggressive.txt").
Apply a Fix (Whitelist):
- You have two primary options:
  - Quick Unblock: In the Query Log details for the blocked entry, click the "Unblock" button. This automatically adds @@||api.important-partner-site.com^ to your Custom filtering rules.
  - Manual Rule: Go to Filters -> Custom filtering rules. Add the following lines:
```
! Unblock essential partner API mistakenly blocked by Overly Aggressive List
! Required for www.important-partner-site.com functionality
@@||api.important-partner-site.com^
```
    Then click "Apply".
Verify the Fix:
- On the client device, clear browser cache and DNS cache again.
- Try accessing http://www.important-partner-site.com again. It should now load correctly.
- Go back to the AdGuard Home Query Log.
- Find the new query for api.important-partner-site.com. Its status should now be "Processed" (or potentially "Whitelisted by Custom filtering rules"), and it should not show as blocked by the "Overly Aggressive List". The website should function as expected.

Troubleshooting during Diagnosis:

Can't Find Related Queries: Ensure the client is definitely using AdGuard Home. Try searching for a broader domain part (e.g., just partner-site.com). Check if the "Disable Protection" toggle was accidentally left on.
Unblocking Doesn't Fix It: The issue might be unrelated to DNS blocking (server down, network issue), or another necessary domain might also be blocked. Repeat the Query Log analysis, looking for other blocked domains accessed around the same time. Browser developer tools (Network tab) can also show which specific resource requests are failing.

This workshop demonstrates a typical troubleshooting workflow using the Query Log: observe the failure, filter logs, identify the incorrect block by checking blocked queries related to the failing service, apply a specific fix (usually whitelisting), and verify the resolution. The Query Log is indispensable for resolving these kinds of filtering side effects.

Conclusion

Throughout this guide, we've journeyed from the fundamental principles of DNS and ad blocking to the practical implementation, customization, and advanced management of AdGuard Home. You've learned how to install it using Docker, perform initial configuration, manage blocklists, and tailor filtering with custom rules. We explored enhancing performance and security through upstream DNS choices, caching, secure protocols, and DNS rewrites. Furthermore, we delved into advanced topics like high availability using multiple instances, synchronization strategies, API automation, integration with DHCP and monitoring systems, and systematic troubleshooting techniques.

Self-hosting AdGuard Home empowers you to reclaim control over your network's DNS resolution. It offers tangible benefits:

Network-Wide Ad Blocking: Cleaner browsing experience on all connected devices.
Enhanced Privacy: Reduced tracking and encrypted upstream queries (using DoH/DoT/DoQ).
Improved Security: Protection against malware, phishing, and other malicious domains.
Customization: Fine-grained control over what is blocked or allowed via lists and custom rules.
Local DNS Management: Easy naming for local services using DNS rewrites.
Learning Opportunity: Deeper understanding of DNS, networking, and filtering technologies.

While the initial setup is relatively straightforward, mastering AdGuard Home involves continuous learning and occasional troubleshooting, particularly as websites and blocking techniques evolve. The Query Log remains your most valuable tool for understanding precisely how AdGuard Home interacts with your network traffic.

The workshops provided practical, step-by-step experience, reinforcing the theoretical concepts. By successfully installing AdGuard Home, configuring clients, managing filters, optimizing settings, exploring HA concepts, using the API, and diagnosing issues, you've built a solid foundation.

The journey doesn't end here. The AdGuard Home community is active, new features are regularly added, and blocklists are constantly updated. Continue exploring the settings, experiment with different configurations (perhaps setting up a second instance for HA using adguardhome-sync), delve deeper into the API, or contribute to community blocklists.

By taking control of your DNS, you've taken a significant step towards a faster, safer, and more private online experience for your entire network. Enjoy the cleaner internet!