Add Configuration
290
Configuration.md
Normal file
290
Configuration.md
Normal file
@@ -0,0 +1,290 @@
|
||||
# ⚙️ Configuration Guide
|
||||
|
||||
This guide covers all configuration options for **AdGuard Control Hub**, from basic setup to advanced customization.
|
||||
|
||||
## 🔧 Basic Configuration
|
||||
|
||||
### Integration Setup
|
||||
|
||||
After installation, configure your AdGuard Home connection:
|
||||
|
||||
1. **Settings** → **Devices & Services** → **"+ Add Integration"**
|
||||
2. Search for **"AdGuard Control Hub"**
|
||||
3. Enter your connection details
|
||||
|
||||
### Connection Settings
|
||||
|
||||
| Setting | Description | Example |
|
||||
|---------|-------------|---------|
|
||||
| **Host** | IP address or hostname of AdGuard Home | `192.168.1.100` |
|
||||
| **Port** | Web interface port | `3000` (default) |
|
||||
| **Username** | Admin username | `admin` |
|
||||
| **Password** | Admin password | `your-password` |
|
||||
| **SSL** | Use HTTPS connection | `false` (for HTTP) |
|
||||
| **Verify SSL** | Verify SSL certificates | `true` (recommended) |
|
||||
|
||||
## 🏠 Advanced Configuration
|
||||
|
||||
### Custom Configuration (configuration.yaml)
|
||||
|
||||
Add advanced settings to your `configuration.yaml`:
|
||||
|
||||
```yaml
|
||||
adguard_hub:
|
||||
# Update frequency in seconds (default: 30)
|
||||
scan_interval: 30
|
||||
|
||||
# Automatically create entities for new clients (default: true)
|
||||
auto_create_clients: true
|
||||
|
||||
# Enable detailed statistics collection (default: true)
|
||||
enable_statistics: true
|
||||
|
||||
# Create service blocking switches (default: true)
|
||||
blocked_services_as_switches: true
|
||||
|
||||
# Entity naming pattern (default: "adguard_{name}")
|
||||
client_naming_pattern: "adguard_{name}"
|
||||
```
|
||||
|
||||
### Configuration Options Explained
|
||||
|
||||
#### **scan_interval**
|
||||
Controls how often Home Assistant fetches data from AdGuard Home.
|
||||
- **Lower values** (10-20s): More responsive, higher network usage
|
||||
- **Higher values** (60-120s): Less responsive, lower network usage
|
||||
- **Recommended**: 30 seconds for most setups
|
||||
|
||||
#### **auto_create_clients**
|
||||
Automatically creates switches for new AdGuard clients.
|
||||
- **true**: New devices automatically get entities
|
||||
- **false**: Only manually configured clients get entities
|
||||
|
||||
#### **enable_statistics**
|
||||
Controls whether to collect detailed DNS statistics.
|
||||
- **true**: Full statistics with per-client metrics
|
||||
- **false**: Basic statistics only (better performance)
|
||||
|
||||
#### **blocked_services_as_switches**
|
||||
Creates individual switches for each service per client.
|
||||
- **true**: Granular control (many entities)
|
||||
- **false**: Simplified interface (fewer entities)
|
||||
|
||||
## 🌐 Multiple AdGuard Instances
|
||||
|
||||
You can configure multiple AdGuard Home instances:
|
||||
|
||||
### Adding Multiple Instances
|
||||
1. Repeat the integration setup process
|
||||
2. Use different host/port for each instance
|
||||
3. Each instance gets its own device in Home Assistant
|
||||
|
||||
### Targeting Specific Instances
|
||||
Services can target specific instances using device targeting:
|
||||
|
||||
```yaml
|
||||
service: adguard_hub.emergency_unblock
|
||||
target:
|
||||
device_id: "adguard_hub_192_168_1_100_3000"
|
||||
data:
|
||||
duration: 600
|
||||
clients: ["all"]
|
||||
```
|
||||
|
||||
## 📊 Entity Configuration
|
||||
|
||||
### Customizing Entity Names
|
||||
|
||||
Rename entities for better organization:
|
||||
|
||||
1. **Settings** → **Devices & Services** → **AdGuard Control Hub**
|
||||
2. Click on an entity
|
||||
3. Click the gear icon ⚙️
|
||||
4. Change **"Name"** and **"Entity ID"**
|
||||
|
||||
### Hiding Unwanted Entities
|
||||
|
||||
Disable entities you don't need:
|
||||
|
||||
1. Go to the entity settings (as above)
|
||||
2. Toggle **"Enabled"** off
|
||||
3. The entity will be hidden from the UI
|
||||
|
||||
### Creating Groups
|
||||
|
||||
Group related entities for easier management:
|
||||
|
||||
```yaml
|
||||
# configuration.yaml
|
||||
group:
|
||||
adguard_family_devices:
|
||||
name: "Family Devices"
|
||||
entities:
|
||||
- switch.adguard_client_kids_ipad
|
||||
- switch.adguard_client_kids_laptop
|
||||
- switch.adguard_client_kids_phone
|
||||
|
||||
adguard_work_devices:
|
||||
name: "Work Devices"
|
||||
entities:
|
||||
- switch.adguard_client_work_laptop
|
||||
- switch.adguard_client_work_phone
|
||||
```
|
||||
|
||||
## 🔐 Security Configuration
|
||||
|
||||
### Securing AdGuard Home API
|
||||
|
||||
#### Create Dedicated User
|
||||
Create a separate user for Home Assistant:
|
||||
|
||||
1. Open AdGuard Home web interface
|
||||
2. **Settings** → **General Settings** → **Authentication**
|
||||
3. Add new user with username like `homeassistant`
|
||||
4. Grant admin privileges
|
||||
5. Use these credentials in Home Assistant
|
||||
|
||||
#### Enable HTTPS
|
||||
For secure communication:
|
||||
|
||||
1. Configure SSL certificate in AdGuard Home
|
||||
2. Enable **SSL** option in integration settings
|
||||
3. Set **Verify SSL** based on your certificate type
|
||||
|
||||
### Network Security
|
||||
|
||||
#### Firewall Configuration
|
||||
Ensure Home Assistant can reach AdGuard Home:
|
||||
|
||||
```bash
|
||||
# Allow Home Assistant to reach AdGuard Home
|
||||
# Replace IPs with your actual addresses
|
||||
iptables -A INPUT -s 192.168.1.10 -d 192.168.1.100 -p tcp --dport 3000 -j ACCEPT
|
||||
```
|
||||
|
||||
#### VPN Access
|
||||
For remote access, consider VPN instead of exposing AdGuard Home directly.
|
||||
|
||||
## 📈 Performance Optimization
|
||||
|
||||
### Reducing Resource Usage
|
||||
|
||||
#### Adjust Scan Interval
|
||||
```yaml
|
||||
adguard_hub:
|
||||
scan_interval: 60 # Reduce update frequency
|
||||
```
|
||||
|
||||
#### Disable Unnecessary Features
|
||||
```yaml
|
||||
adguard_hub:
|
||||
enable_statistics: false # Disable if not needed
|
||||
blocked_services_as_switches: false # Reduce entity count
|
||||
```
|
||||
|
||||
#### Limit Client Auto-Discovery
|
||||
```yaml
|
||||
adguard_hub:
|
||||
auto_create_clients: false # Manual client management
|
||||
```
|
||||
|
||||
### Monitoring Performance
|
||||
|
||||
#### Check Integration Load
|
||||
Monitor the integration's resource usage:
|
||||
|
||||
1. **Developer Tools** → **Statistics**
|
||||
2. Look for `adguard_hub` related metrics
|
||||
3. Check update times and success rates
|
||||
|
||||
#### Log Analysis
|
||||
Enable debug logging to monitor performance:
|
||||
|
||||
```yaml
|
||||
logger:
|
||||
logs:
|
||||
custom_components.adguard_hub: debug
|
||||
```
|
||||
|
||||
## 🚨 Troubleshooting Configuration
|
||||
|
||||
### Common Configuration Issues
|
||||
|
||||
#### Invalid Credentials
|
||||
**Error**: "Failed to connect to AdGuard Home"
|
||||
**Solution**: Verify username/password in AdGuard Home web interface
|
||||
|
||||
#### Network Issues
|
||||
**Error**: "Connection timeout"
|
||||
**Solutions**:
|
||||
- Check IP address and port
|
||||
- Verify network connectivity
|
||||
- Check firewall rules
|
||||
|
||||
#### SSL Certificate Issues
|
||||
**Error**: "SSL verification failed"
|
||||
**Solutions**:
|
||||
- Disable "Verify SSL" for self-signed certificates
|
||||
- Install proper SSL certificate
|
||||
- Use HTTP instead of HTTPS
|
||||
|
||||
### Configuration Validation
|
||||
|
||||
#### Test Configuration
|
||||
```bash
|
||||
# Test API access manually
|
||||
curl -u username:password http://192.168.1.100:3000/control/status
|
||||
|
||||
# Expected response should include:
|
||||
# {"protection_enabled": true, "version": "..."}
|
||||
```
|
||||
|
||||
#### Validate YAML Syntax
|
||||
Use Home Assistant's configuration check:
|
||||
|
||||
1. **Developer Tools** → **YAML Configuration Reloading**
|
||||
2. Click **"Check Configuration"**
|
||||
3. Fix any YAML syntax errors
|
||||
|
||||
## 🔄 Configuration Updates
|
||||
|
||||
### Updating Integration Settings
|
||||
|
||||
To change integration settings:
|
||||
|
||||
1. **Settings** → **Devices & Services**
|
||||
2. Find **AdGuard Control Hub**
|
||||
3. Click **"Configure"** (if available)
|
||||
4. Or remove and re-add the integration
|
||||
|
||||
### Reloading Configuration
|
||||
|
||||
After changing `configuration.yaml`:
|
||||
|
||||
1. **Developer Tools** → **YAML Configuration Reloading**
|
||||
2. Click **"All YAML Configuration"**
|
||||
3. Or restart Home Assistant for major changes
|
||||
|
||||
## ✅ Configuration Best Practices
|
||||
|
||||
### Security
|
||||
- ✅ Use dedicated AdGuard Home user for Home Assistant
|
||||
- ✅ Enable HTTPS when possible
|
||||
- ✅ Regularly update passwords
|
||||
- ✅ Monitor access logs
|
||||
|
||||
### Performance
|
||||
- ✅ Set appropriate scan interval (30-60 seconds)
|
||||
- ✅ Disable unused features
|
||||
- ✅ Group related entities
|
||||
- ✅ Use automation for bulk operations
|
||||
|
||||
### Maintenance
|
||||
- ✅ Document your configuration
|
||||
- ✅ Test configuration changes in staging
|
||||
- ✅ Keep backups of working configurations
|
||||
- ✅ Monitor integration health regularly
|
||||
|
||||
---
|
||||
|
||||
**Next Steps**: Set up your [Dashboard](Dashboard-Examples) and [Automations](Automation-Examples)!
|
||||
Reference in New Issue
Block a user