244
wiki/Configuration.md
Normal file
244
wiki/Configuration.md
Normal file
@@ -0,0 +1,244 @@
|
||||
# Configuration Guide
|
||||
|
||||
This guide covers all configuration options for AdGuard Control Hub integration.
|
||||
|
||||
## Initial Setup
|
||||
|
||||
### Basic Configuration
|
||||
|
||||
When adding the integration for the first time, you'll need to provide:
|
||||
|
||||
| Field | Description | Required | Default |
|
||||
|-------|-------------|----------|---------|
|
||||
| **Host** | IP address or hostname of AdGuard Home | ✅ | - |
|
||||
| **Port** | Port number AdGuard Home is running on | ✅ | 3000 |
|
||||
| **Username** | Admin username (if authentication enabled) | ❌ | - |
|
||||
| **Password** | Admin password (if authentication enabled) | ❌ | - |
|
||||
| **Use HTTPS** | Enable HTTPS connection | ❌ | false |
|
||||
| **Verify SSL** | Verify SSL certificates | ❌ | true |
|
||||
|
||||
### Step-by-Step Configuration
|
||||
|
||||
1. **Navigate to Integration Setup**
|
||||
- Go to **Settings** → **Devices & Services**
|
||||
- Click **"+ ADD INTEGRATION"**
|
||||
- Search for **"AdGuard Control Hub"**
|
||||
|
||||
2. **Enter Connection Details**
|
||||
```
|
||||
Host: 192.168.1.100
|
||||
Port: 3000
|
||||
Username: admin (optional)
|
||||
Password: your-password (optional)
|
||||
Use HTTPS: ☐ (check if using HTTPS)
|
||||
Verify SSL: ☑ (recommended)
|
||||
```
|
||||
|
||||
3. **Test Connection**
|
||||
- Click **"SUBMIT"**
|
||||
- Integration will test the connection
|
||||
- If successful, you'll see a success message
|
||||
|
||||
4. **Complete Setup**
|
||||
- Integration will create all entities
|
||||
- Device will appear in **Devices & Services**
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
### HTTPS Setup
|
||||
|
||||
If your AdGuard Home uses HTTPS:
|
||||
|
||||
1. **Enable HTTPS in AdGuard Home**
|
||||
- Open AdGuard Home web interface
|
||||
- Go to **Settings** → **Encryption**
|
||||
- Configure SSL certificate
|
||||
|
||||
2. **Configure Integration**
|
||||
- Check **"Use HTTPS"** during setup
|
||||
- Use HTTPS port (usually 443 or custom)
|
||||
|
||||
3. **SSL Certificate Verification**
|
||||
- **Verify SSL: ON** - Recommended for production
|
||||
- **Verify SSL: OFF** - Only for self-signed certificates
|
||||
|
||||
### Authentication Configuration
|
||||
|
||||
AdGuard Home supports optional authentication:
|
||||
|
||||
#### Without Authentication
|
||||
- Leave **Username** and **Password** empty
|
||||
- AdGuard Home must have authentication disabled
|
||||
|
||||
#### With Authentication
|
||||
- Enter your AdGuard Home admin credentials
|
||||
- User must have admin privileges
|
||||
- Credentials are stored securely in Home Assistant
|
||||
|
||||
### Network Configuration Examples
|
||||
|
||||
#### Local Network
|
||||
```
|
||||
Host: 192.168.1.100
|
||||
Port: 3000
|
||||
Use HTTPS: false
|
||||
```
|
||||
|
||||
#### Remote Server with SSL
|
||||
```
|
||||
Host: adguard.example.com
|
||||
Port: 443
|
||||
Use HTTPS: true
|
||||
Verify SSL: true
|
||||
Username: admin
|
||||
Password: secure-password
|
||||
```
|
||||
|
||||
#### Docker Installation
|
||||
```
|
||||
Host: adguard-home.local
|
||||
Port: 3000
|
||||
Use HTTPS: false
|
||||
```
|
||||
|
||||
## Multiple Instances
|
||||
|
||||
You can configure multiple AdGuard Home instances:
|
||||
|
||||
1. **Add each instance separately**
|
||||
- Each gets its own configuration entry
|
||||
- Entities are prefixed with instance name
|
||||
- All instances appear as separate devices
|
||||
|
||||
2. **Naming Convention**
|
||||
- Integration automatically names based on hostname
|
||||
- Example: "AdGuard Home (192.168.1.100)"
|
||||
- Example: "AdGuard Home (adguard.example.com)"
|
||||
|
||||
## Entity Configuration
|
||||
|
||||
### Entity Naming
|
||||
|
||||
Entities are automatically created with descriptive names:
|
||||
|
||||
**Switches:**
|
||||
- `switch.adguard_protection`
|
||||
- `switch.adguard_dns_filtering`
|
||||
- `switch.adguard_safe_browsing`
|
||||
- `switch.adguard_parental_control`
|
||||
- `switch.adguard_safe_search`
|
||||
- `switch.adguard_query_log`
|
||||
|
||||
**Sensors:**
|
||||
- `sensor.adguard_dns_queries`
|
||||
- `sensor.adguard_blocked_queries`
|
||||
- `sensor.adguard_blocked_percentage`
|
||||
- `sensor.adguard_active_filter_rules`
|
||||
- `sensor.adguard_average_processing_time`
|
||||
|
||||
**Binary Sensors:**
|
||||
- `binary_sensor.adguard_home_running`
|
||||
|
||||
### Customizing Entities
|
||||
|
||||
You can customize entity names and icons:
|
||||
|
||||
1. **Entity Settings**
|
||||
- Go to **Settings** → **Devices & Services**
|
||||
- Find AdGuard Control Hub device
|
||||
- Click on any entity
|
||||
- Click gear icon (⚙️) to edit
|
||||
|
||||
2. **Available Customizations**
|
||||
- Entity ID
|
||||
- Friendly name
|
||||
- Icon
|
||||
- Device class
|
||||
- Area assignment
|
||||
|
||||
## Update Interval
|
||||
|
||||
The integration updates every 30 seconds by default. This provides a good balance between responsiveness and resource usage.
|
||||
|
||||
**Note:** Query log must be enabled in AdGuard Home for statistics to update. Disabling query log will stop sensor updates.
|
||||
|
||||
## Options Configuration
|
||||
|
||||
Currently, there are no additional options to configure after initial setup. All configuration is done during the initial integration setup.
|
||||
|
||||
## Configuration Troubleshooting
|
||||
|
||||
### Connection Issues
|
||||
|
||||
**Cannot connect to AdGuard Home:**
|
||||
1. Verify AdGuard Home is running
|
||||
2. Check network connectivity: `ping your-adguard-ip`
|
||||
3. Test API manually: `curl http://your-adguard-ip:port/control/status`
|
||||
4. Verify firewall allows connection
|
||||
|
||||
**SSL/HTTPS Issues:**
|
||||
1. Verify certificate is valid
|
||||
2. Check certificate matches hostname
|
||||
3. Try with SSL verification disabled temporarily
|
||||
4. Ensure correct port for HTTPS
|
||||
|
||||
### Authentication Issues
|
||||
|
||||
**Authentication failed:**
|
||||
1. Verify credentials in AdGuard Home
|
||||
2. Check user has admin privileges
|
||||
3. Test login in AdGuard Home web interface
|
||||
4. Ensure password doesn't contain special characters that need escaping
|
||||
|
||||
**Forbidden access:**
|
||||
1. User account may not have sufficient privileges
|
||||
2. Check AdGuard Home access control settings
|
||||
3. Verify IP is not blocked by AdGuard Home
|
||||
|
||||
### Entity Issues
|
||||
|
||||
**Entities not created:**
|
||||
1. Check Home Assistant logs for errors
|
||||
2. Verify AdGuard Home API is responding
|
||||
3. Restart Home Assistant
|
||||
4. Check entity registry for conflicts
|
||||
|
||||
**Entities showing unavailable:**
|
||||
1. Check AdGuard Home is running
|
||||
2. Verify network connectivity
|
||||
3. Check authentication status
|
||||
4. Review integration logs
|
||||
|
||||
## Configuration Files
|
||||
|
||||
### Example YAML (for reference only)
|
||||
*Configuration is done via UI, not YAML*
|
||||
|
||||
```yaml
|
||||
# This is for reference only - actual configuration is done via UI
|
||||
adguard_control_hub:
|
||||
host: 192.168.1.100
|
||||
port: 3000
|
||||
username: admin
|
||||
password: !secret adguard_password
|
||||
ssl: false
|
||||
verify_ssl: true
|
||||
```
|
||||
|
||||
### Secrets Management
|
||||
|
||||
Store sensitive information in `secrets.yaml`:
|
||||
|
||||
```yaml
|
||||
# secrets.yaml
|
||||
adguard_password: "your-secure-password"
|
||||
adguard_host: "192.168.1.100"
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
After configuration:
|
||||
- [Explore available features](Features.md)
|
||||
- [Set up Lovelace cards](Advanced-Usage.md#lovelace-cards)
|
||||
- [Create automations](Advanced-Usage.md#automations)
|
||||
- [Monitor performance](Features.md#sensors)
|
||||
Reference in New Issue
Block a user