From 5843a1a97a3fc516b355d2ba1e1f1d54090bb1aa Mon Sep 17 00:00:00 2001 From: sq4ind Date: Sun, 28 Sep 2025 12:47:50 +0000 Subject: [PATCH] Add Configuration --- Configuration.md | 290 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 290 insertions(+) create mode 100644 Configuration.md diff --git a/Configuration.md b/Configuration.md new file mode 100644 index 0000000..2662a44 --- /dev/null +++ b/Configuration.md @@ -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)! \ No newline at end of file