294
wiki/Features.md
Normal file
294
wiki/Features.md
Normal file
@@ -0,0 +1,294 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user