adguard-control-hub/wiki/Configuration.md

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

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

# secrets.yaml
adguard_password: "your-secure-password"
adguard_host: "192.168.1.100"

Next Steps

After configuration:

• Explore available features
• Set up Lovelace cards
• Create automations
• Monitor performance