jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-15 13:26:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

AdGuard integration documentation improvements (#39749)

Browse Source 
Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>
This commit is contained in:
Franck Nijhof 2025-06-30 10:54:00 +02:00 committed by GitHub
parent 0fe9fa7fe1
commit fd6a816b0c
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 190 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

233
source/_integrations/adguard.markdown
View File

@ -9,7 +9,7 @@ ha_release: 0.95
ha_iot_class: Local Polling ha_iot_class: Local Polling
ha_config_flow: true ha_config_flow: true
ha_codeowners: ha_codeowners:
- '@frenck' - "@frenck"
ha_domain: adguard ha_domain: adguard
ha_platforms: ha_platforms:
- sensor - sensor
@ -17,15 +17,38 @@ ha_platforms:
ha_integration_type: service ha_integration_type: service
--- ---
AdGuard Home is a network-wide DNS server that supports ad, tracker, 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.
and adult content blocking. The **AdGuard** integration allows you to control and
monitor your AdGuard Home 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 %} {% 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 DNS queries.
- Number of blocked 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. - Total number of active filter rules loaded.
- Average response time of AdGuard's DNS server in milliseconds. - 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). - **AdGuard protection**: Master switch that controls all AdGuard features
- Filtering. - **Filtering**: Enables DNS filtering using blocklists
- Safe Browsing. - **Safe browsing**: Blocks known phishing and malware sites
- Parental Control. - **Parental control**: Blocks adult content
- Safe Search. - **Safe search**: Enforces safe search on search engines
- Query Log. - **Query log**: Records DNS queries for statistics
These switches allow you to automate things easily. For example, one could These switches enable powerful automations. For example, you could automatically enable parental controls during school hours or disable ad blocking for specific time periods.
write an automation to turn off Safe Search after the kids' bedtime.
The "AdGuard Protection" switch is a master switch. It will turn off and The **AdGuard protection** switch acts as a master control. When turned off, it bypasses all AdGuard features regardless of individual switch states.
bypass all AdGuard features, regardless of whether they are switched on or not.
{% important %} {% important %}
Turning off Query Log will result in all sensors not receiving updates anymore. Turning off **Query log** stops all sensor updates. AdGuard requires query logging to provide statistics.
AdGuard relies on Query Log to provide stats.
{% endimportant %} {% endimportant %}
## Actions ## Actions
These {% term actions %} allow one to manage filter subscriptions in AdGuard Home. 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.
Using these actions in automations could be helpful to block certain
sites/domains at certain times.
For example, you could create a custom filter list that blocks social media sites For example, you could create automations that:
during the day and releases them during the evening.
### 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`
Adds a new filter subscription to AdGuard Home.
| Data attribute | Optional | Description | | Data attribute | Optional | Description |
| ---------------------- | -------- | ------------------------------------------------------------ | | -------------- | -------- | --------------------------------------------- |
| `name` | No | The name of the filter subscription. | | `name` | No | The name of the filter subscription |
| `url` | No | The filter URL to subscribe to, containing the filter rules. | | `url` | No | The filter list URL containing blocking rules |
### Action `remove_url` ### Action `adguard.remove_url`
Removes a filter subscription from AdGuard Home. Removes a filter subscription from AdGuard Home.
| Data attribute | Optional | Description | | Data attribute | Optional | Description |
| ---------------------- | -------- | -------------------------------------- | | -------------- | -------- | ------------------------------------- |
| `url` | No | The filter subscription URL to remove. | | `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 | | Data attribute | Optional | Description |
| ---------------------- | -------- | -------------------------------------- | | -------------- | -------- | ------------------------------------- |
| `url` | No | The filter subscription URL to enable. | | `url` | No | The filter subscription URL to enable |
### Action `disable_url` ### Action `adguard.disable_url`
Disables a filter subscription in AdGuard Home. Temporarily disables a filter subscription without removing it.
| Data attribute | Optional | Description | | Data attribute | Optional | Description |
| ---------------------- | -------- | --------------------------------------- | | -------------- | -------- | -------------------------------------- |
| `url` | No | The filter subscription URL to disable. | | `url` | No | The filter subscription URL to disable |
### Action `refresh` ### Action `adguard.refresh`
Refresh all filter subscriptions in AdGuard Home. Refreshes all filter subscriptions to get the latest blocking rules.
| Data attribute | Optional | Description | | Data attribute | Optional | Description |
| ---------------------- | -------- | ------------------------------------------------- | | -------------- | -------- | ----------------------------------------------- |
| `force` | Yes | Force update (bypasses AdGuard Home throttling). | | `force` | Yes | Force update (bypasses AdGuard Home throttling) |
By default, `force` is set to `false`. Forcing an update bypasses AdGuard Home's By default, `force` is `false`. AdGuard Home normally throttles filter updates to reduce server load. Use forced updates sparingly.
throttling logic, so use with care.
## Examples
### Block social media during work hours
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 %}