mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-14 21:06:50 +00:00
AdGuard integration documentation improvements (#39749)
Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>
This commit is contained in:
Franck Nijhof
GitHub
parent
0fe9fa7fe1
commit
fd6a816b0c
@ -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 %}
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user