528 lines
13 KiB
Markdown
528 lines
13 KiB
Markdown
# Advanced Usage
|
|
|
|
This guide covers advanced features, automations, and customizations for AdGuard Control Hub.
|
|
|
|
## Lovelace Dashboard Cards
|
|
|
|
Create informative dashboard cards to monitor and control your AdGuard Home instance.
|
|
|
|
### Protection Status Card
|
|
|
|
```yaml
|
|
type: entities
|
|
title: AdGuard Protection
|
|
entities:
|
|
- switch.adguard_protection
|
|
- switch.adguard_dns_filtering
|
|
- switch.adguard_safe_browsing
|
|
- switch.adguard_parental_control
|
|
- switch.adguard_safe_search
|
|
- switch.adguard_query_log
|
|
show_header_toggle: true
|
|
state_color: true
|
|
```
|
|
|
|
### Statistics Overview Card
|
|
|
|
```yaml
|
|
type: glance
|
|
title: AdGuard Statistics
|
|
entities:
|
|
- entity: sensor.adguard_dns_queries
|
|
name: Total Queries
|
|
- entity: sensor.adguard_blocked_queries
|
|
name: Blocked
|
|
- entity: sensor.adguard_blocked_percentage
|
|
name: Blocked %
|
|
- entity: sensor.adguard_average_processing_time
|
|
name: Avg Time
|
|
columns: 2
|
|
show_state: true
|
|
show_name: true
|
|
```
|
|
|
|
### Historical Chart Card
|
|
|
|
```yaml
|
|
type: history-graph
|
|
title: DNS Activity (24h)
|
|
entities:
|
|
- sensor.adguard_dns_queries
|
|
- sensor.adguard_blocked_queries
|
|
hours_to_show: 24
|
|
refresh_interval: 60
|
|
```
|
|
|
|
### Protection Control Card
|
|
|
|
```yaml
|
|
type: custom:mushroom-chips-card
|
|
chips:
|
|
- type: entity
|
|
entity: switch.adguard_protection
|
|
icon_color: green
|
|
tap_action:
|
|
action: toggle
|
|
- type: entity
|
|
entity: switch.adguard_parental_control
|
|
icon_color: blue
|
|
tap_action:
|
|
action: toggle
|
|
- type: entity
|
|
entity: binary_sensor.adguard_home_running
|
|
icon_color: red
|
|
```
|
|
|
|
## Automations
|
|
|
|
### Basic Automations
|
|
|
|
#### Enable Parental Controls During School Hours
|
|
|
|
```yaml
|
|
automation:
|
|
- alias: "AdGuard: Enable Parental Controls - School Hours"
|
|
trigger:
|
|
- platform: time
|
|
at: "08:00:00"
|
|
condition:
|
|
- condition: time
|
|
weekday:
|
|
- mon
|
|
- tue
|
|
- wed
|
|
- thu
|
|
- fri
|
|
action:
|
|
- service: switch.turn_on
|
|
target:
|
|
entity_id: switch.adguard_parental_control
|
|
- service: notify.mobile_app_your_phone
|
|
data:
|
|
title: "AdGuard"
|
|
message: "Parental controls enabled for school hours"
|
|
|
|
- alias: "AdGuard: Disable Parental Controls - After School"
|
|
trigger:
|
|
- platform: time
|
|
at: "16:00:00"
|
|
condition:
|
|
- condition: time
|
|
weekday:
|
|
- mon
|
|
- tue
|
|
- wed
|
|
- thu
|
|
- fri
|
|
action:
|
|
- service: switch.turn_off
|
|
target:
|
|
entity_id: switch.adguard_parental_control
|
|
- service: notify.mobile_app_your_phone
|
|
data:
|
|
title: "AdGuard"
|
|
message: "Parental controls disabled - school day ended"
|
|
```
|
|
|
|
#### Temporarily Disable Filtering
|
|
|
|
```yaml
|
|
automation:
|
|
- alias: "AdGuard: Temporary Disable Protection"
|
|
trigger:
|
|
- platform: event
|
|
event_type: call_service
|
|
event_data:
|
|
domain: script
|
|
service: disable_adguard_temporarily
|
|
action:
|
|
- service: switch.turn_off
|
|
target:
|
|
entity_id: switch.adguard_protection
|
|
- delay: "00:10:00" # 10 minutes
|
|
- service: switch.turn_on
|
|
target:
|
|
entity_id: switch.adguard_protection
|
|
- service: notify.mobile_app_your_phone
|
|
data:
|
|
title: "AdGuard"
|
|
message: "Protection re-enabled after temporary disable"
|
|
|
|
script:
|
|
disable_adguard_temporarily:
|
|
alias: "Disable AdGuard for 10 minutes"
|
|
sequence:
|
|
- event: call_service
|
|
event_data:
|
|
domain: script
|
|
service: disable_adguard_temporarily
|
|
```
|
|
|
|
### Advanced Automations
|
|
|
|
#### Dynamic Protection Based on Network Activity
|
|
|
|
```yaml
|
|
automation:
|
|
- alias: "AdGuard: High Activity Alert"
|
|
trigger:
|
|
- platform: numeric_state
|
|
entity_id: sensor.adguard_dns_queries
|
|
above: 5000
|
|
for: "00:05:00"
|
|
action:
|
|
- service: notify.mobile_app_your_phone
|
|
data:
|
|
title: "AdGuard Alert"
|
|
message: "High DNS activity detected: {{ states('sensor.adguard_dns_queries') }} queries"
|
|
- service: switch.turn_on
|
|
target:
|
|
entity_id: switch.adguard_safe_browsing
|
|
- service: switch.turn_on
|
|
target:
|
|
entity_id: switch.adguard_dns_filtering
|
|
|
|
- alias: "AdGuard: Performance Monitoring"
|
|
trigger:
|
|
- platform: numeric_state
|
|
entity_id: sensor.adguard_average_processing_time
|
|
above: 100
|
|
for: "00:02:00"
|
|
action:
|
|
- service: persistent_notification.create
|
|
data:
|
|
title: "AdGuard Performance Warning"
|
|
message: |
|
|
DNS response time is high: {{ states('sensor.adguard_average_processing_time') }}ms
|
|
Current queries: {{ states('sensor.adguard_dns_queries') }}
|
|
Active rules: {{ states('sensor.adguard_active_filter_rules') }}
|
|
notification_id: adguard_performance
|
|
```
|
|
|
|
#### Guest Network Protection
|
|
|
|
```yaml
|
|
automation:
|
|
- alias: "AdGuard: Guest Network - Enable Strict Filtering"
|
|
trigger:
|
|
- platform: device_tracker
|
|
entity_id: device_tracker.guest_device
|
|
to: "home"
|
|
action:
|
|
- service: switch.turn_on
|
|
target:
|
|
entity_id:
|
|
- switch.adguard_safe_browsing
|
|
- switch.adguard_parental_control
|
|
- switch.adguard_safe_search
|
|
- service: notify.mobile_app_your_phone
|
|
data:
|
|
title: "AdGuard"
|
|
message: "Guest device connected - strict filtering enabled"
|
|
|
|
- alias: "AdGuard: Guest Network - Restore Normal Settings"
|
|
trigger:
|
|
- platform: device_tracker
|
|
entity_id: device_tracker.guest_device
|
|
to: "not_home"
|
|
for: "00:05:00"
|
|
action:
|
|
- service: switch.turn_off
|
|
target:
|
|
entity_id: switch.adguard_parental_control
|
|
- service: notify.mobile_app_your_phone
|
|
data:
|
|
title: "AdGuard"
|
|
message: "Guest device disconnected - normal filtering restored"
|
|
```
|
|
|
|
### Monitoring and Alerting
|
|
|
|
#### AdGuard Home Downtime Alert
|
|
|
|
```yaml
|
|
automation:
|
|
- alias: "AdGuard: Downtime Alert"
|
|
trigger:
|
|
- platform: state
|
|
entity_id: binary_sensor.adguard_home_running
|
|
to: "off"
|
|
for: "00:02:00"
|
|
action:
|
|
- service: notify.mobile_app_your_phone
|
|
data:
|
|
title: "AdGuard Home Down"
|
|
message: "AdGuard Home is not responding. Check the service status."
|
|
data:
|
|
priority: high
|
|
color: red
|
|
|
|
- alias: "AdGuard: Service Restored"
|
|
trigger:
|
|
- platform: state
|
|
entity_id: binary_sensor.adguard_home_running
|
|
to: "on"
|
|
condition:
|
|
- condition: state
|
|
entity_id: binary_sensor.adguard_home_running
|
|
state: "off"
|
|
for: "00:01:00"
|
|
action:
|
|
- service: notify.mobile_app_your_phone
|
|
data:
|
|
title: "AdGuard Home Restored"
|
|
message: "AdGuard Home is responding again."
|
|
data:
|
|
color: green
|
|
```
|
|
|
|
## Scripts
|
|
|
|
### Quick Control Scripts
|
|
|
|
#### Emergency Bypass Script
|
|
|
|
```yaml
|
|
script:
|
|
adguard_emergency_bypass:
|
|
alias: "AdGuard Emergency Bypass"
|
|
description: "Quickly disable all protection for troubleshooting"
|
|
sequence:
|
|
- service: switch.turn_off
|
|
target:
|
|
entity_id: switch.adguard_protection
|
|
- service: timer.start
|
|
target:
|
|
entity_id: timer.adguard_bypass
|
|
data:
|
|
duration: "00:15:00"
|
|
- service: persistent_notification.create
|
|
data:
|
|
title: "AdGuard Bypass Active"
|
|
message: "All protection disabled for 15 minutes"
|
|
notification_id: adguard_bypass
|
|
|
|
timer:
|
|
adguard_bypass:
|
|
duration: "00:15:00"
|
|
restore: true
|
|
```
|
|
|
|
#### Weekly Statistics Report
|
|
|
|
```yaml
|
|
script:
|
|
adguard_weekly_report:
|
|
alias: "AdGuard Weekly Report"
|
|
sequence:
|
|
- service: notify.mobile_app_your_phone
|
|
data:
|
|
title: "AdGuard Weekly Report"
|
|
message: |
|
|
Total Queries: {{ states('sensor.adguard_dns_queries') }}
|
|
Blocked: {{ states('sensor.adguard_blocked_queries') }}
|
|
Block Rate: {{ states('sensor.adguard_blocked_percentage') }}%
|
|
Avg Response Time: {{ states('sensor.adguard_average_processing_time') }}ms
|
|
Filter Rules: {{ states('sensor.adguard_active_filter_rules') }}
|
|
|
|
automation:
|
|
- alias: "AdGuard: Weekly Report"
|
|
trigger:
|
|
- platform: time
|
|
at: "09:00:00"
|
|
condition:
|
|
- condition: time
|
|
weekday:
|
|
- sun
|
|
action:
|
|
- service: script.adguard_weekly_report
|
|
```
|
|
|
|
## Custom Templates
|
|
|
|
### Template Sensors
|
|
|
|
#### Protection Status Summary
|
|
|
|
```yaml
|
|
template:
|
|
- sensor:
|
|
- name: "AdGuard Protection Summary"
|
|
state: >
|
|
{% set protection = states('switch.adguard_protection') %}
|
|
{% set filtering = states('switch.adguard_dns_filtering') %}
|
|
{% set safebrowsing = states('switch.adguard_safe_browsing') %}
|
|
{% set parental = states('switch.adguard_parental_control') %}
|
|
|
|
{% if protection == 'off' %}
|
|
Disabled
|
|
{% else %}
|
|
{% set active = [filtering, safebrowsing, parental] | select('eq', 'on') | list | length %}
|
|
{% if active == 3 %}
|
|
Full Protection
|
|
{% elif active == 0 %}
|
|
Basic Protection
|
|
{% else %}
|
|
Partial Protection ({{ active }}/3)
|
|
{% endif %}
|
|
{% endif %}
|
|
icon: >
|
|
{% set protection = states('switch.adguard_protection') %}
|
|
{% if protection == 'off' %}
|
|
mdi:shield-off
|
|
{% else %}
|
|
mdi:shield-check
|
|
{% endif %}
|
|
```
|
|
|
|
#### Daily Block Statistics
|
|
|
|
```yaml
|
|
template:
|
|
- sensor:
|
|
- name: "AdGuard Daily Block Rate"
|
|
state: >
|
|
{% set queries = states('sensor.adguard_dns_queries') | int(0) %}
|
|
{% set blocked = states('sensor.adguard_blocked_queries') | int(0) %}
|
|
{% if queries > 0 %}
|
|
{{ ((blocked / queries) * 100) | round(1) }}
|
|
{% else %}
|
|
0
|
|
{% endif %}
|
|
unit_of_measurement: "%"
|
|
device_class: None
|
|
attributes:
|
|
daily_queries: "{{ states('sensor.adguard_dns_queries') }}"
|
|
daily_blocked: "{{ states('sensor.adguard_blocked_queries') }}"
|
|
effectiveness: >
|
|
{% set rate = states('sensor.adguard_daily_block_rate') | float(0) %}
|
|
{% if rate > 20 %}
|
|
High
|
|
{% elif rate > 10 %}
|
|
Medium
|
|
{% elif rate > 5 %}
|
|
Low
|
|
{% else %}
|
|
Very Low
|
|
{% endif %}
|
|
```
|
|
|
|
## Node-RED Integration
|
|
|
|
### Flow Examples
|
|
|
|
#### AdGuard Control Flow
|
|
|
|
```json
|
|
[
|
|
{
|
|
"id": "adguard-control",
|
|
"type": "api-call-service",
|
|
"name": "Toggle AdGuard Protection",
|
|
"service_domain": "switch",
|
|
"service": "toggle",
|
|
"entityId": "switch.adguard_protection",
|
|
"data": {},
|
|
"wires": [["notification-node"]]
|
|
},
|
|
{
|
|
"id": "notification-node",
|
|
"type": "api-call-service",
|
|
"name": "Send Notification",
|
|
"service_domain": "notify",
|
|
"service": "mobile_app_your_phone",
|
|
"data": {
|
|
"title": "AdGuard",
|
|
"message": "Protection toggled via Node-RED"
|
|
}
|
|
}
|
|
]
|
|
```
|
|
|
|
## API Integration
|
|
|
|
### REST Commands
|
|
|
|
Add REST commands to your configuration.yaml for direct API access:
|
|
|
|
```yaml
|
|
rest_command:
|
|
adguard_enable_protection:
|
|
url: "http://192.168.1.100:3000/control/dns_config"
|
|
method: POST
|
|
headers:
|
|
Content-Type: application/json
|
|
Authorization: "Basic {{ ('admin:password') | b64encode }}"
|
|
payload: '{"protection_enabled": true}'
|
|
|
|
adguard_get_status:
|
|
url: "http://192.168.1.100:3000/control/status"
|
|
method: GET
|
|
headers:
|
|
Authorization: "Basic {{ ('admin:password') | b64encode }}"
|
|
```
|
|
|
|
## Troubleshooting Advanced Features
|
|
|
|
### Automation Issues
|
|
|
|
**Automations not triggering:**
|
|
1. Check automation conditions and triggers
|
|
2. Verify entity IDs are correct
|
|
3. Check timezone settings
|
|
4. Review automation traces in Developer Tools
|
|
|
|
**State changes not detected:**
|
|
1. Verify update intervals
|
|
2. Check network connectivity
|
|
3. Review entity history
|
|
4. Confirm AdGuard Home is responding
|
|
|
|
### Template Issues
|
|
|
|
**Templates showing unavailable:**
|
|
1. Check template syntax
|
|
2. Verify referenced entities exist
|
|
3. Test templates in Developer Tools → Template
|
|
4. Review Home Assistant logs for template errors
|
|
|
|
### Performance Optimization
|
|
|
|
**High resource usage:**
|
|
1. Reduce automation frequency
|
|
2. Optimize template sensors
|
|
3. Use conditions to prevent unnecessary actions
|
|
4. Monitor Home Assistant performance
|
|
|
|
**Slow response times:**
|
|
1. Check AdGuard Home performance
|
|
2. Verify network latency
|
|
3. Reduce update frequency if needed
|
|
4. Monitor integration logs
|
|
|
|
## Best Practices
|
|
|
|
### Security
|
|
- Use HTTPS when possible
|
|
- Store credentials in secrets.yaml
|
|
- Limit API access to required functions
|
|
- Regular security updates
|
|
|
|
### Reliability
|
|
- Add error handling to automations
|
|
- Use conditions to prevent conflicts
|
|
- Monitor integration health
|
|
- Have fallback procedures
|
|
|
|
### Performance
|
|
- Balance update frequency with resources
|
|
- Use efficient templates
|
|
- Avoid excessive API calls
|
|
- Monitor system resources
|
|
|
|
## Next Steps
|
|
|
|
- [Review troubleshooting guide](Troubleshooting.md)
|
|
- [Learn about API endpoints](API-Reference.md)
|
|
- [Contribute to development](Development.md)
|