Elevating Network Control: Integrating AdGuard Home with Home Assistant

In the modern smart home, controlling your network traffic is just as important as controlling your lights or thermostat. Unwanted ads, trackers, and malicious sites not only clutter your browsing experience but can also pose security and privacy risks. AdGuard Home is a powerful, network-wide software that blocks ads and tracking by acting as a DNS server.

Integrating AdGuard Home with Home Assistant brings its capabilities into your smart home ecosystem, allowing you to monitor network activity, visualize blocking statistics, and even trigger automations based on network events, all from your familiar Home Assistant interface. This guide will walk you through setting up AdGuard Home (either as a Home Assistant add-on or an external instance) and integrating it seamlessly.

Why Integrate AdGuard Home with Home Assistant?

AdGuard Home itself provides a robust web interface for configuration and monitoring. However, integrating it with Home Assistant offers several advantages:

• Unified Dashboard: See network statistics alongside your device statuses, energy consumption, and other smart home data.
• Data Visualization: Use Home Assistant's history graphs, statistics, and dashboards to visualize blocking rates, query types, and top clients over time.
• Automation Potential: Trigger actions based on AdGuard Home data, such as sending alerts if the blocking rate drops unexpectedly or logging specific domain accesses.
• Simplified Access: Access AdGuard Home's core stats without needing to open a separate web interface.
• Centralized Monitoring: Include AdGuard Home's health status in your overall Home Assistant monitoring setup.

Prerequisites

• A running Home Assistant instance (Home Assistant OS, Supervised, Container, or Core).
• Network access for both Home Assistant and the device hosting AdGuard Home.
• Basic understanding of network concepts like DNS.

Setting Up AdGuard Home

You have two primary options for running AdGuard Home:

Option 1: As a Home Assistant Add-on (Recommended for HA OS/Supervised)

This is the easiest method if you are using Home Assistant OS or Home Assistant Supervised, as AdGuard Home runs directly on your Home Assistant machine and is managed through the HA interface.

1. In Home Assistant, navigate to Settings > Add-ons.
2. Click on the Add-on Store button in the bottom right.
3. Search for "AdGuard Home" and select it.
4. Click Install.
5. Once installed, go to the Configuration tab of the AdGuard Home add-on. You can often leave the default settings, but note the default web UI port (usually 3000) and DNS port (usually 53). Make sure port 53 is not already in use on the host machine.
6. Under the Network tab, confirm or change the ports if necessary. Port 53 (DNS) is crucial.
7. Under the Info tab, start the add-on. Enable "Start on boot" and "Watchdog" for reliability.
8. Click Open Web UI to access the AdGuard Home setup wizard in a new tab. Follow the steps to set up the web admin port (e.g., 3000) and the DNS port (e.g., 53). Create an administrator username and password.
9. After the wizard, you'll reach the AdGuard Home dashboard.

Option 2: External Installation (Docker, Dedicated Machine, etc.)

If you run Home Assistant Core or Container, or prefer AdGuard Home to run on a separate machine (like a Raspberry Pi or a server), install it according to the official AdGuard Home documentation for your chosen platform. Ensure it's accessible from your Home Assistant instance over the network.

Integrating AdGuard Home with Home Assistant

Once AdGuard Home is running and accessible, integrate it with Home Assistant:

1. In Home Assistant, go to Settings > Devices & Services.
2. Click the + Add Integration button.
3. Search for "AdGuard Home" and select it.
4. Enter the details:
   • Host: The IP address or hostname of the machine running AdGuard Home (e.g., !$0$! or !$1$! if using the add-on and local host networking). If using the add-on with default networking, try the IP of your Home Assistant server. If using host networking for the add-on, use !$2$! or !$3$!.
   • Port: The web interface port you configured during the AdGuard Home setup (e.g., !$4$!).
   • Username: The administrator username you created for AdGuard Home.
   • Password: The administrator password you created for AdGuard Home.
5. Click Submit. If the connection is successful, it will ask you to assign it to an area.
6. Click Finish.

The integration will now create various entities representing the state and statistics of your AdGuard Home instance.

Exploring the Data in Home Assistant

The AdGuard Home integration exposes several useful entities:

• Switch Entity: An entity (e.g., !$5$!) to enable or disable DNS filtering directly from Home Assistant.
• Sensor Entities: Entities providing key statistics (e.g., !$6$!, !$7$!, !$8$!, !$9$!, !$10$!).
• Attributes: Many entities, particularly the sensors, contain valuable attributes. The blocked sensors, for instance, might have attributes listing the top blocked domains or clients.

You can find these entities by going to Settings > Devices & Services, selecting the AdGuard Home integration, and clicking on the listed device.

Leveraging the Data in Home Assistant

Visualizing Statistics

Add the AdGuard Home sensor entities to your Lovelace dashboard using cards like:

• Entities Card: Display the current values of sensors like total queries or blocked queries.
• History Graph Card: Visualize the blocking rate or query count over time.
• Statistics Card: Show daily, weekly, or monthly sums for blocked queries using the long-term statistics available for some sensors.
• Custom Cards: More advanced users might find custom cards (via HACS) that are specifically designed to display AdGuard Home stats in a more visually appealing way.

For example, a simple Entities card showing key stats:

!$11$!

You can also use Template sensors to calculate percentages, like the blocking rate:

!$12$!

Add this template sensor to your !$13$! (or a split file) and then use it in Lovelace.

Simple Automations

While extensive automation based on DNS queries can be complex, simple automations are straightforward:

• Low Blocking Rate Alert: Notify you if the blocking rate drops below a certain threshold (using the template sensor above), which might indicate an issue with AdGuard Home or your blocklists.
• High Processing Speed Alert: Get a notification if the average processing speed increases significantly, suggesting performance degradation.
• Disable Filtering Button: Create an automation that temporarily disables filtering via the !$14$! entity, useful for troubleshooting network issues (though the AdGuard Home UI is often better for this).

Example automation trigger (using the template sensor):

!$15$!

Best Practices for a Reliable AdGuard Home Integration

• Ensure AdGuard Home Reliability: If using the add-on, enable "Start on boot" and "Watchdog." If external, ensure it runs as a service that starts automatically and is monitored (e.g., using systemd or Docker restart policies). Home Assistant's AdGuard integration will show 'unavailable' if AdGuard Home stops running.
• DNS Configuration: Point your router's DNS settings to the IP address of your AdGuard Home instance. This ensures *all* devices on your network benefit. Alternatively, manually configure DNS on individual devices. Using the router is generally more effective for full network coverage.
• Choose Blocklists Wisely: AdGuard Home comes with default blocklists. Explore others (like StevenBlack's host file or various privacy-focused lists), but be mindful that overly aggressive lists can break websites or services. Start with defaults and add more cautiously.
• Handle Updates: Keep both Home Assistant and AdGuard Home updated. If using the add-on, updates are managed via the Add-on store. For external installations, follow AdGuard Home's update procedures.
• Monitor Performance: Use the average processing speed sensor in Home Assistant to keep an eye on AdGuard Home's performance. High latency might indicate resource issues or network problems.
• Consider Backups: While not directly managed by the Home Assistant integration, back up your AdGuard Home configuration (blocklists, custom rules, etc.) periodically. The add-on might be included in full Home Assistant backups, but verify this.

Conclusion

Integrating AdGuard Home with Home Assistant provides a powerful combination for enhancing network privacy, blocking intrusive content, and gaining valuable insights into your network's activity, all presented within your familiar smart home dashboard. By following these steps, you can set up a robust ad-blocking solution that contributes to a faster, more secure, and more reliable smart home environment, leveraging Home Assistant's capabilities for monitoring and basic automation.