245 lines
6.2 KiB
Markdown
245 lines
6.2 KiB
Markdown
# 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)
|