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:

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

Repeat the integration setup process
Use different host/port for each instance
Each instance gets its own device in Home Assistant

Targeting Specific Instances

Services can target specific instances using device targeting:

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:

Settings → Devices & Services → AdGuard Control Hub
Click on an entity
Click the gear icon ⚙️
Change "Name" and "Entity ID"

Hiding Unwanted Entities

Disable entities you don't need:

Go to the entity settings (as above)
Toggle "Enabled" off
The entity will be hidden from the UI

Creating Groups

Group related entities for easier management:

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

Open AdGuard Home web interface
Settings → General Settings → Authentication
Add new user with username like homeassistant
Grant admin privileges
Use these credentials in Home Assistant

Enable HTTPS

For secure communication:

Configure SSL certificate in AdGuard Home
Enable SSL option in integration settings
Set Verify SSL based on your certificate type

Network Security

Firewall Configuration

Ensure Home Assistant can reach AdGuard Home:

# 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

adguard_hub:
  scan_interval: 60  # Reduce update frequency

Disable Unnecessary Features

adguard_hub:
  enable_statistics: false  # Disable if not needed
  blocked_services_as_switches: false  # Reduce entity count

Limit Client Auto-Discovery

adguard_hub:
  auto_create_clients: false  # Manual client management

Monitoring Performance

Check Integration Load

Monitor the integration's resource usage:

Developer Tools → Statistics
Look for adguard_hub related metrics
Check update times and success rates

Log Analysis

Enable debug logging to monitor performance:

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

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

Developer Tools → YAML Configuration Reloading
Click "Check Configuration"
Fix any YAML syntax errors

🔄 Configuration Updates

Updating Integration Settings

To change integration settings:

Settings → Devices & Services
Find AdGuard Control Hub
Click "Configure" (if available)
Or remove and re-add the integration

Reloading Configuration

After changing configuration.yaml:

Developer Tools → YAML Configuration Reloading
Click "All YAML Configuration"
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 and Automations!