# 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)