adguard-control-hub/wiki/Features.md

Features Overview

AdGuard Control Hub provides comprehensive control and monitoring of your AdGuard Home instance through Home Assistant.

Switches

All switches provide instant control over AdGuard Home's protection features with real-time status updates.

AdGuard Protection

• Entity ID: switch.adguard_protection
• Function: Master switch that controls all AdGuard features
• Icon: mdi:shield-check

Behavior:

• ON: All AdGuard features are active
• OFF: Bypasses all AdGuard features (DNS queries pass through without filtering)
• Acts as a master override for all other protection features

Use Cases:

• Temporarily disable all filtering for troubleshooting
• Emergency bypass for important downloads
• Scheduled maintenance windows

DNS Filtering

• Entity ID: switch.adguard_dns_filtering
• Function: Enables DNS filtering using configured blocklists
• Icon: mdi:filter

Behavior:

• ON: DNS queries are filtered against blocklists
• OFF: DNS filtering is disabled, but other features remain active
• Only affects blocklist-based filtering

Use Cases:

• Disable filtering for specific time periods
• Allow access to falsely blocked domains temporarily
• Maintenance of filter lists

Safe Browsing

• Entity ID: switch.adguard_safe_browsing
• Function: Blocks known phishing and malware sites
• Icon: mdi:shield-bug

Behavior:

• ON: Queries to malicious domains are blocked
• OFF: Safe browsing protection is disabled
• Uses AdGuard's malware and phishing database

Use Cases:

• Enhanced security for family networks
• Protection for less tech-savvy users
• Corporate security policies

Parental Control

• Entity ID: switch.adguard_parental_control
• Function: Blocks adult content and inappropriate websites
• Icon: mdi:account-child-circle

Behavior:

• ON: Adult content domains are blocked
• OFF: Parental controls are disabled
• Blocks based on content category classification

Use Cases:

• Protect children from inappropriate content
• School or educational environments
• Time-based content filtering

Safe Search

• Entity ID: switch.adguard_safe_search
• Function: Enforces safe search on major search engines
• Icon: mdi:shield-search

Behavior:

• ON: Forces safe search mode on Google, Bing, Yandex, etc.
• OFF: Search engines operate in normal mode
• Redirects search queries to safe search variants

Use Cases:

• Additional layer of content protection
• Compliance with content policies
• Educational institution requirements

Query Log

• Entity ID: switch.adguard_query_log
• Function: Records DNS queries for statistics and analysis
• Icon: mdi:file-document-multiple

Behavior:

• ON: All DNS queries are logged and stored
• OFF: Query logging is disabled, statistics stop updating
• Required for sensor data and analytics

Use Cases:

• Monitor network activity
• Troubleshoot DNS issues
• Privacy mode (disable logging)

Sensors

Sensors provide real-time statistics and monitoring data from your AdGuard Home instance.

DNS Queries

• Entity ID: sensor.adguard_dns_queries
• Unit: queries
• Function: Total number of DNS queries processed
• Icon: mdi:dns

Data Points:

• Total queries since last statistics reset
• Updates every 30 seconds
• Includes all query types (A, AAAA, CNAME, etc.)

Usage:

• Monitor network activity levels
• Track DNS server load
• Historical trending

Blocked Queries

• Entity ID: sensor.adguard_blocked_queries
• Unit: queries
• Function: Number of queries blocked by filtering
• Icon: mdi:shield-check

Data Points:

• Queries blocked by all filtering mechanisms
• Includes blocklist, parental control, and safe browsing blocks
• Updates every 30 seconds

Usage:

• Measure filtering effectiveness
• Identify potential threats blocked
• Compare blocking trends

Blocked Percentage

• Entity ID: sensor.adguard_blocked_percentage
• Unit: %
• Function: Percentage of queries that were blocked
• Icon: mdi:percent

Calculation:

• (Blocked Queries / Total Queries) × 100
• Automatically calculated by integration
• Provides ratio view of filtering activity

Usage:

• Quick assessment of filtering impact
• Performance monitoring
• Historical comparison

Active Filter Rules

• Entity ID: sensor.adguard_active_filter_rules
• Unit: rules
• Function: Number of active filtering rules loaded
• Icon: mdi:filter-check

Data Points:

• Total rules from all enabled filter lists
• Includes custom rules
• Updated when filter lists are refreshed

Usage:

• Monitor filter list size and complexity
• Track filter performance impact
• Troubleshoot over-blocking

Average Processing Time

• Entity ID: sensor.adguard_average_processing_time
• Unit: ms
• Function: Average DNS query processing time
• Icon: mdi:clock-fast

Measurement:

• Time from query receipt to response
• Rolling average over recent queries
• Includes upstream server response time

Usage:

• Monitor DNS performance
• Identify performance bottlenecks
• Compare different upstream servers

Binary Sensors

Binary sensors provide simple on/off status information.

AdGuard Home Running

• Entity ID: binary_sensor.adguard_home_running
• Function: Shows if AdGuard Home is responsive
• Icon: mdi:shield-check-outline

States:

• ON: AdGuard Home is responding to API requests
• OFF: AdGuard Home is unreachable or not responding
• UNAVAILABLE: Integration cannot determine status

Usage:

• Monitor AdGuard Home availability
• Trigger alerts for downtime
• Automation conditions

Device Information

The integration creates a single device representing your AdGuard Home instance:

Device Attributes:

• Name: "AdGuard Control Hub"
• Manufacturer: "AdGuard"
• Model: "AdGuard Home"
• Software Version: Detected from AdGuard Home API
• Configuration URL: Direct link to AdGuard Home web interface

Device Identifiers:

• Unique identifier based on host and port
• Allows multiple instances without conflicts
• Persistent across restarts

Entity Attributes

Each entity provides additional information in its attributes:

Switch Attributes

friendly_name: "AdGuard Protection"
device_class: switch
icon: "mdi:shield-check"
state: "on"

Sensor Attributes

friendly_name: "DNS Queries"
device_class: null
unit_of_measurement: "queries"
state_class: "measurement"
icon: "mdi:dns"
state: 1247

Feature Dependencies

Understanding feature relationships:

1. Query Log Dependency

   • Most sensors require query log to be enabled
   • Disabling query log stops statistics updates
   • Binary sensor still works without query log

2. Master Protection Switch

   • When protection is OFF, individual switches show their configured state
   • But filtering is bypassed regardless of individual switch states
   • Protection switch overrides all other filtering

3. Network Connectivity

   • All features require network access to AdGuard Home
   • Connection loss makes all entities unavailable
   • Integration automatically reconnects when connection is restored

Feature Limitations

Current Limitations:

• Client-specific controls not yet implemented
• Custom filter list management not available
• DNS rewrite rules not supported
• DHCP settings not exposed

Planned Features:

• Individual client management
• Custom filtering rules via HA
• DNS rewrite configuration
• Advanced statistics and reporting

Performance Considerations

Update Frequency:

• Default: 30-second intervals
• Balances responsiveness vs. resource usage
• Configurable in future versions

Resource Usage:

• Minimal CPU impact on AdGuard Home
• Uses standard AdGuard Home API endpoints
• No additional logging or processing required

Network Traffic:

• Small API requests every 30 seconds
• Typical response size: < 1KB per request
• Negligible bandwidth impact

Next Steps

• Set up advanced automations
• Troubleshoot issues
• Learn about the API