295 lines
8.1 KiB
Markdown
295 lines
8.1 KiB
Markdown
# 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
|
||
```yaml
|
||
friendly_name: "AdGuard Protection"
|
||
device_class: switch
|
||
icon: "mdi:shield-check"
|
||
state: "on"
|
||
```
|
||
|
||
### Sensor Attributes
|
||
```yaml
|
||
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](Advanced-Usage.md)
|
||
- [Troubleshoot issues](Troubleshooting.md)
|
||
- [Learn about the API](API-Reference.md)
|