From fd6a816b0cbb1126020c5c988bc957b6b1a2eeb5 Mon Sep 17 00:00:00 2001 From: Franck Nijhof Date: Mon, 30 Jun 2025 10:54:00 +0200 Subject: [PATCH] AdGuard integration documentation improvements (#39749) Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com> --- source/_integrations/adguard.markdown | 241 ++++++++++++++++++++------ 1 file changed, 190 insertions(+), 51 deletions(-) diff --git a/source/_integrations/adguard.markdown b/source/_integrations/adguard.markdown index dbb2537c60b..b02b55667b6 100644 --- a/source/_integrations/adguard.markdown +++ b/source/_integrations/adguard.markdown @@ -9,7 +9,7 @@ ha_release: 0.95 ha_iot_class: Local Polling ha_config_flow: true ha_codeowners: - - '@frenck' + - "@frenck" ha_domain: adguard ha_platforms: - sensor @@ -17,15 +17,38 @@ ha_platforms: ha_integration_type: service --- -AdGuard Home is a network-wide DNS server that supports ad, tracker, -and adult content blocking. The **AdGuard** integration allows you to control and -monitor your AdGuard Home instance in Home Assistant. +The **AdGuard Home** {% term integration %} allows you to control and monitor your [AdGuard Home](https://adguard.com/adguard-home/overview.html) instance in Home Assistant. + +AdGuard Home is a network-wide software for blocking advertisements and tracking. It provides DNS-level protection, automatically covering all home devices without requiring client-side software. When you use AdGuard Home as your DNS server, it blocks advertisements, trackers, and malicious domains for all devices on your network. + +## Prerequisites + +Before setting up the AdGuard Home integration, ensure you have: + +1. AdGuard Home installed and running on your network +2. The IP address or hostname of your AdGuard Home instance +3. Admin access to AdGuard Home {% include integrations/config_flow.md %} -## Sensors +{% configuration_basic %} +Host: + description: "The IP address or hostname of your AdGuard Home instance. For example: `192.168.1.100` or `adguard.local`." +Port: + description: "The port AdGuard Home is running on. Default is `3000` for the web interface." +Username: + description: "Your AdGuard Home admin username." +Password: + description: "Your AdGuard Home admin password." +Verify SSL certificate: + description: "Enable SSL certificate verification when connecting via HTTPS." +{% endconfiguration_basic %} -This integration provides {% term sensors %} for the following information from AdGuard Home: +## Supported functionality + +### Sensors + +This integration provides sensors for the following information from AdGuard Home: - Number of DNS queries. - Number of blocked DNS queries. @@ -36,77 +59,193 @@ This integration provides {% term sensors %} for the following information from - Total number of active filter rules loaded. - Average response time of AdGuard's DNS server in milliseconds. -## Switches +### Switches -The integration will create a number of switches: +The integration provides switches to control AdGuard Home features: -- AdGuard Protection (master switch). -- Filtering. -- Safe Browsing. -- Parental Control. -- Safe Search. -- Query Log. +- **AdGuard protection**: Master switch that controls all AdGuard features +- **Filtering**: Enables DNS filtering using blocklists +- **Safe browsing**: Blocks known phishing and malware sites +- **Parental control**: Blocks adult content +- **Safe search**: Enforces safe search on search engines +- **Query log**: Records DNS queries for statistics -These switches allow you to automate things easily. For example, one could -write an automation to turn off Safe Search after the kids' bedtime. +These switches enable powerful automations. For example, you could automatically enable parental controls during school hours or disable ad blocking for specific time periods. -The "AdGuard Protection" switch is a master switch. It will turn off and -bypass all AdGuard features, regardless of whether they are switched on or not. +The **AdGuard protection** switch acts as a master control. When turned off, it bypasses all AdGuard features regardless of individual switch states. {% important %} -Turning off Query Log will result in all sensors not receiving updates anymore. -AdGuard relies on Query Log to provide stats. +Turning off **Query log** stops all sensor updates. AdGuard requires query logging to provide statistics. {% endimportant %} ## Actions -These {% term actions %} allow one to manage filter subscriptions in AdGuard Home. -Using these actions in automations could be helpful to block certain -sites/domains at certain times. +The integration provides {% term actions %} to manage filter subscriptions in AdGuard Home. Use these actions in automations to dynamically control content filtering based on time, presence, or other conditions. -For example, you could create a custom filter list that blocks social media sites -during the day and releases them during the evening. +For example, you could create automations that: -### Action `add_url` +- Block social media during work hours +- Enable strict filtering when guests connect to your network +- Temporarily disable filtering for specific downloads -Add a new filter subscription to AdGuard Home. +### Action `adguard.add_url` -| Data attribute | Optional | Description | -| ---------------------- | -------- | ------------------------------------------------------------ | -| `name` | No | The name of the filter subscription. | -| `url` | No | The filter URL to subscribe to, containing the filter rules. | +Adds a new filter subscription to AdGuard Home. -### Action `remove_url` +| Data attribute | Optional | Description | +| -------------- | -------- | --------------------------------------------- | +| `name` | No | The name of the filter subscription | +| `url` | No | The filter list URL containing blocking rules | + +### Action `adguard.remove_url` Removes a filter subscription from AdGuard Home. -| Data attribute | Optional | Description | -| ---------------------- | -------- | -------------------------------------- | -| `url` | No | The filter subscription URL to remove. | +| Data attribute | Optional | Description | +| -------------- | -------- | ------------------------------------- | +| `url` | No | The filter subscription URL to remove | -### Action `enable_url` +### Action `adguard.enable_url` -Enables a filter subscription in AdGuard Home. +Enables a previously disabled filter subscription. + +| Data attribute | Optional | Description | +| -------------- | -------- | ------------------------------------- | +| `url` | No | The filter subscription URL to enable | + +### Action `adguard.disable_url` + +Temporarily disables a filter subscription without removing it. | Data attribute | Optional | Description | -| ---------------------- | -------- | -------------------------------------- | -| `url` | No | The filter subscription URL to enable. | +| -------------- | -------- | -------------------------------------- | +| `url` | No | The filter subscription URL to disable | -### Action `disable_url` +### Action `adguard.refresh` -Disables a filter subscription in AdGuard Home. +Refreshes all filter subscriptions to get the latest blocking rules. -| Data attribute | Optional | Description | -| ---------------------- | -------- | --------------------------------------- | -| `url` | No | The filter subscription URL to disable. | +| Data attribute | Optional | Description | +| -------------- | -------- | ----------------------------------------------- | +| `force` | Yes | Force update (bypasses AdGuard Home throttling) | -### Action `refresh` +By default, `force` is `false`. AdGuard Home normally throttles filter updates to reduce server load. Use forced updates sparingly. -Refresh all filter subscriptions in AdGuard Home. +## Examples -| Data attribute | Optional | Description | -| ---------------------- | -------- | ------------------------------------------------- | -| `force` | Yes | Force update (bypasses AdGuard Home throttling). | +### Block social media during work hours -By default, `force` is set to `false`. Forcing an update bypasses AdGuard Home's -throttling logic, so use with care. +This automation blocks social media sites during business hours: + +```yaml +automation: + - alias: "Block social media during work" + triggers: + - trigger: time + at: "09:00:00" + actions: + - action: adguard.add_url + data: + name: "Social media blocklist" + url: "https://raw.githubusercontent.com/example/social-media-blocklist/main/list.txt" + - action: adguard.refresh + + - alias: "Unblock social media after work" + triggers: + - trigger: time + at: "17:00:00" + actions: + - action: adguard.remove_url + data: + url: "https://raw.githubusercontent.com/example/social-media-blocklist/main/list.txt" +``` + +### Enable strict filtering when guests arrive + +Automatically enable all protection features when guests connect to your network: + +```yaml +automation: + - alias: "Enable strict filtering for guests" + triggers: + - trigger: state + entity_id: group.guest_devices + from: "not_home" + to: "home" + actions: + - action: switch.turn_on + target: + entity_id: + - switch.adguard_parental_control + - switch.adguard_safe_browsing + - switch.adguard_safe_search +``` + +### Monitor DNS performance + +Send a notification if DNS response time exceeds threshold: + +{% raw %} + +```yaml +automation: + - alias: "Alert on slow DNS" + triggers: + - trigger: numeric_state + entity_id: sensor.adguard_average_processing_speed + above: 50 + actions: + - action: notify.mobile_app + data: + title: "DNS Performance Alert" + message: "AdGuard DNS response time is {{ states('sensor.adguard_average_processing_speed') }}ms" +``` + +{% endraw %} + + +## Data updates + +The AdGuard Home integration polls for updates every 10 seconds to provide near real-time statistics and ensure switch states remain synchronized. + +## Troubleshooting + +### Integration fails to connect + +#### Symptom: "Cannot connect to AdGuard Home" + +When setting up the integration, you receive a connection error. + +##### Resolution + +1. Verify AdGuard Home is running: + + - Access the AdGuard Home web interface at `http://YOUR_IP:3000`. + - Check the service status on your server. + +2. Check network connectivity: + + - Ensure Home Assistant can reach the AdGuard Home instance. + - Verify no firewall rules block port 3000. + +3. Confirm credentials: + - Test login via the AdGuard Home web interface. + - Ensure you're using admin credentials. + +### Sensors show unavailable + +If sensors display as unavailable: + +1. Check that **Query log** switch is enabled. +2. Verify AdGuard Home is processing DNS queries. +3. Ensure at least one device uses AdGuard Home as DNS server. + +### Actions fail with "Filter URL not found" + +This error occurs when trying to enable, disable, or remove a non-existent filter URL. Verify the exact URL using the AdGuard Home web interface under **Filters** > **DNS blocklists**. + +## Removing the integration + +This integration follows standard integration removal. After removal, your AdGuard Home instance continues running with its current configuration. + +{% include integrations/remove_device_service.md %}