Rafal Zielinski
ed94d40e96
Some checks failed
Code Quality Check / Code Formatting (push) Failing after 21s
Code Quality Check / Security Analysis (push) Failing after 20s
Integration Testing / Integration Tests (2024.12.0, 3.13) (push) Failing after 1m32s
Integration Testing / Integration Tests (2025.9.4, 3.13) (push) Failing after 20s
Signed-off-by: Rafal Zielinski <sq4ind@gmail.com>
125 lines
4.5 KiB
Markdown
125 lines
4.5 KiB
Markdown
# 🛡️ AdGuard Control Hub
|
|
|
|
**The ultimate Home Assistant integration for AdGuard Home**
|
|
|
|
Transform your AdGuard Home into a smart network management powerhouse with comprehensive Home Assistant integration featuring client management, service blocking, and real-time monitoring.
|
|
|
|
## ✨ Features
|
|
|
|
### 🎯 Smart Client Management
|
|
- **Automatic Discovery**: Automatically discover and manage AdGuard clients
|
|
- **Individual Controls**: Per-client protection and filtering controls
|
|
- **Real-time Statistics**: Monitor client activity and blocking statistics
|
|
- **Bulk Operations**: Manage multiple clients simultaneously
|
|
|
|
### 🛡️ Advanced Service Blocking
|
|
- **Granular Control**: Block specific services (YouTube, Netflix, Gaming, etc.) per client
|
|
- **Emergency Access**: Quick emergency unblock for critical situations
|
|
- **Scheduled Blocking**: Time-based service restrictions via automations
|
|
- **Custom Services**: Support for custom service definitions
|
|
|
|
### 🏠 Rich Home Assistant Integration
|
|
- **🔧 Switches**: Global and per-client protection controls
|
|
- **📊 Sensors**: DNS queries, blocked queries, processing time, client counts
|
|
- **🚨 Binary Sensors**: Protection status, server status, safety features
|
|
- **⚙️ Services**: Comprehensive automation-friendly service calls
|
|
- **🔌 Device Integration**: Proper device registry with configuration URLs
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Prerequisites
|
|
- Home Assistant 2024.12.0 or later
|
|
- AdGuard Home with API access enabled
|
|
- Network connectivity between Home Assistant and AdGuard Home
|
|
|
|
### Installation via HACS (Recommended)
|
|
|
|
1. **Add Custom Repository**
|
|
- Open HACS → Integrations
|
|
- Click the three dots (⋮) → Custom repositories
|
|
- Repository: `https://git.sq4ind.eu/sq4ind/adguard-control-hub`
|
|
- Category: Integration
|
|
- Click "Add"
|
|
|
|
2. **Install Integration**
|
|
- Search for "AdGuard Control Hub"
|
|
- Click "Download"
|
|
- Restart Home Assistant
|
|
|
|
3. **Configure Integration**
|
|
- Go to Settings → Devices & Services
|
|
- Click "Add Integration"
|
|
- Search for "AdGuard Control Hub"
|
|
- Follow the configuration wizard
|
|
|
|
## ⚙️ Configuration
|
|
|
|
### Basic Configuration
|
|
| Field | Description | Default | Required |
|
|
|-------|-------------|---------|----------|
|
|
| **Host** | AdGuard Home IP or hostname | - | ✅ |
|
|
| **Port** | AdGuard Home web interface port | 3000 | ✅ |
|
|
| **Username** | Admin username | - | ❌ |
|
|
| **Password** | Admin password | - | ❌ |
|
|
| **Use SSL** | Enable HTTPS connection | False | ❌ |
|
|
| **Verify SSL** | Verify SSL certificates | True | ❌ |
|
|
|
|
## 📊 Available Entities
|
|
|
|
### Switches
|
|
- `switch.adguard_protection` - Global protection toggle
|
|
- `switch.adguard_{client_name}` - Per-client protection toggle
|
|
|
|
### Sensors
|
|
- `sensor.adguard_dns_queries` - Total DNS queries count
|
|
- `sensor.adguard_blocked_queries` - Total blocked queries count
|
|
- `sensor.adguard_blocking_percentage` - Blocking percentage
|
|
- `sensor.adguard_clients_count` - Number of configured clients
|
|
- `sensor.adguard_average_processing_time` - Query processing time
|
|
- `sensor.adguard_filtering_rules` - Number of filtering rules
|
|
|
|
### Binary Sensors
|
|
- `binary_sensor.adguard_protection_status` - Protection status
|
|
- `binary_sensor.adguard_server_running` - Server running status
|
|
- `binary_sensor.adguard_safebrowsing` - SafeBrowsing status
|
|
- `binary_sensor.adguard_parental_control` - Parental control status
|
|
- `binary_sensor.adguard_safe_search` - Safe search status
|
|
|
|
## 🔧 Available Services
|
|
|
|
- **`adguard_hub.block_services`**: Block specific services for clients
|
|
- **`adguard_hub.unblock_services`**: Unblock services for clients
|
|
- **`adguard_hub.emergency_unblock`**: Temporarily disable protection
|
|
- **`adguard_hub.add_client`**: Add new client configuration
|
|
- **`adguard_hub.remove_client`**: Remove client configuration
|
|
- **`adguard_hub.refresh_data`**: Manually refresh data from AdGuard Home
|
|
|
|
## 🐛 Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
**Connection Failed**
|
|
- Verify AdGuard Home is running and accessible
|
|
- Check firewall settings on AdGuard Home server
|
|
- Ensure correct host and port configuration
|
|
|
|
**Authentication Errors**
|
|
- Verify username and password are correct
|
|
- Check if AdGuard Home has authentication enabled
|
|
|
|
**Missing Clients**
|
|
- Wait for next refresh cycle (30 seconds by default)
|
|
- Use the "Refresh Data" service to force update
|
|
|
|
## 🤝 Contributing
|
|
|
|
We welcome contributions! Please see our Contributing Guide for details.
|
|
|
|
## 📄 License
|
|
|
|
This project is licensed under the MIT License.
|
|
|
|
---
|
|
|
|
Made with ❤️ for the Home Assistant community
|