Add Troubleshooting
517
Troubleshooting.md
Normal file
517
Troubleshooting.md
Normal file
@@ -0,0 +1,517 @@
|
|||||||
|
# 🔧 Troubleshooting Guide
|
||||||
|
|
||||||
|
Having issues with AdGuard Control Hub? This comprehensive guide covers common problems and their solutions.
|
||||||
|
|
||||||
|
## 🚨 Common Issues
|
||||||
|
|
||||||
|
### Integration Not Found
|
||||||
|
|
||||||
|
**Problem**: AdGuard Control Hub doesn't appear in the integrations list.
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
|
||||||
|
1. **HACS Users**:
|
||||||
|
```bash
|
||||||
|
# Verify repository was added correctly
|
||||||
|
# Go to HACS > Integrations > Menu > Custom repositories
|
||||||
|
# Check if your repository URL is listed
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Manual Installation**:
|
||||||
|
```bash
|
||||||
|
# Check file location
|
||||||
|
ls -la /config/custom_components/adguard_hub/
|
||||||
|
|
||||||
|
# Should show:
|
||||||
|
# __init__.py, manifest.json, config_flow.py, etc.
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **General**:
|
||||||
|
- Restart Home Assistant
|
||||||
|
- Clear browser cache (Ctrl+F5)
|
||||||
|
- Check Home Assistant logs for errors
|
||||||
|
|
||||||
|
### Cannot Connect to AdGuard Home
|
||||||
|
|
||||||
|
**Error**: "Failed to connect to AdGuard Home"
|
||||||
|
|
||||||
|
**Diagnostic Steps**:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Test basic connectivity
|
||||||
|
ping 192.168.1.100 # Replace with your AdGuard IP
|
||||||
|
|
||||||
|
# Test HTTP access
|
||||||
|
curl -I http://192.168.1.100:3000/
|
||||||
|
|
||||||
|
# Test with authentication
|
||||||
|
curl -u admin:password http://192.168.1.100:3000/control/status
|
||||||
|
```
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
|
||||||
|
1. **Check IP Address and Port**:
|
||||||
|
- Verify AdGuard Home IP address
|
||||||
|
- Confirm port (usually 3000)
|
||||||
|
- Test from Home Assistant server directly
|
||||||
|
|
||||||
|
2. **Authentication Issues**:
|
||||||
|
- Verify username/password in AdGuard Home web interface
|
||||||
|
- Create dedicated user for Home Assistant
|
||||||
|
- Ensure user has admin privileges
|
||||||
|
|
||||||
|
3. **Network Issues**:
|
||||||
|
```bash
|
||||||
|
# Check if AdGuard Home is running
|
||||||
|
sudo systemctl status AdGuardHome
|
||||||
|
|
||||||
|
# Check listening ports
|
||||||
|
netstat -tlnp | grep :3000
|
||||||
|
|
||||||
|
# Check firewall
|
||||||
|
sudo ufw status
|
||||||
|
```
|
||||||
|
|
||||||
|
4. **SSL/TLS Issues**:
|
||||||
|
- Disable "Verify SSL" for self-signed certificates
|
||||||
|
- Use HTTP instead of HTTPS for testing
|
||||||
|
- Check certificate validity
|
||||||
|
|
||||||
|
### No Entities Created
|
||||||
|
|
||||||
|
**Problem**: Integration connects but creates no entities.
|
||||||
|
|
||||||
|
**Diagnostic**:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# Enable debug logging in configuration.yaml
|
||||||
|
logger:
|
||||||
|
default: warning
|
||||||
|
logs:
|
||||||
|
custom_components.adguard_hub: debug
|
||||||
|
```
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
|
||||||
|
1. **Check AdGuard Home Configuration**:
|
||||||
|
- Ensure AdGuard Home has clients configured
|
||||||
|
- Verify API endpoints are accessible
|
||||||
|
- Check AdGuard Home logs for errors
|
||||||
|
|
||||||
|
2. **Integration Issues**:
|
||||||
|
- Reload integration: Settings > Devices & Services > AdGuard Control Hub > Reload
|
||||||
|
- Remove and re-add integration
|
||||||
|
- Check entity registry for disabled entities
|
||||||
|
|
||||||
|
3. **Permissions**:
|
||||||
|
```bash
|
||||||
|
# Check file permissions
|
||||||
|
sudo chown -R homeassistant:homeassistant /config/custom_components/
|
||||||
|
sudo chmod -R 755 /config/custom_components/
|
||||||
|
```
|
||||||
|
|
||||||
|
### Services Not Working
|
||||||
|
|
||||||
|
**Problem**: Service calls fail or don't have expected effect.
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
|
||||||
|
1. **Check Service Calls**:
|
||||||
|
```yaml
|
||||||
|
# Test in Developer Tools > Services
|
||||||
|
service: adguard_hub.emergency_unblock
|
||||||
|
data:
|
||||||
|
duration: 60
|
||||||
|
clients: ["all"]
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Verify Client Names**:
|
||||||
|
- Use exact client names as they appear in AdGuard Home
|
||||||
|
- Check entity names in Home Assistant
|
||||||
|
- Use Developer Tools > States to verify entity IDs
|
||||||
|
|
||||||
|
3. **API Limitations**:
|
||||||
|
- Some AdGuard Home versions have API limitations
|
||||||
|
- Check AdGuard Home version compatibility
|
||||||
|
- Review AdGuard Home documentation
|
||||||
|
|
||||||
|
## 📊 Performance Issues
|
||||||
|
|
||||||
|
### Slow Response Times
|
||||||
|
|
||||||
|
**Symptoms**: Long delays when toggling switches or calling services.
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
|
||||||
|
1. **Adjust Scan Interval**:
|
||||||
|
```yaml
|
||||||
|
# In configuration.yaml
|
||||||
|
adguard_hub:
|
||||||
|
scan_interval: 60 # Increase from default 30
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Reduce Entity Count**:
|
||||||
|
```yaml
|
||||||
|
# Disable unnecessary features
|
||||||
|
adguard_hub:
|
||||||
|
blocked_services_as_switches: false
|
||||||
|
enable_statistics: false
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Network Optimization**:
|
||||||
|
- Use wired connection instead of Wi-Fi
|
||||||
|
- Check network latency to AdGuard Home
|
||||||
|
- Consider AdGuard Home hardware resources
|
||||||
|
|
||||||
|
### High CPU Usage
|
||||||
|
|
||||||
|
**Problem**: Home Assistant shows high CPU usage from the integration.
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
|
||||||
|
1. **Optimize Configuration**:
|
||||||
|
```yaml
|
||||||
|
adguard_hub:
|
||||||
|
scan_interval: 120 # Reduce update frequency
|
||||||
|
auto_create_clients: false # Manual client management
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Check Logs**:
|
||||||
|
```bash
|
||||||
|
# Look for excessive API calls or errors
|
||||||
|
grep "adguard_hub" /config/home-assistant.log
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **System Resources**:
|
||||||
|
- Monitor AdGuard Home resource usage
|
||||||
|
- Check Home Assistant system resources
|
||||||
|
- Consider hardware upgrades
|
||||||
|
|
||||||
|
## 🔐 Authentication & Security Issues
|
||||||
|
|
||||||
|
### Authentication Failures
|
||||||
|
|
||||||
|
**Error**: "Invalid username or password"
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
|
||||||
|
1. **Verify Credentials**:
|
||||||
|
- Test login in AdGuard Home web interface
|
||||||
|
- Check for special characters in password
|
||||||
|
- Ensure caps lock and keyboard layout
|
||||||
|
|
||||||
|
2. **Create Dedicated User**:
|
||||||
|
```
|
||||||
|
AdGuard Home Web Interface:
|
||||||
|
Settings > General Settings > Authentication
|
||||||
|
Add user: "homeassistant" with admin privileges
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Check Account Status**:
|
||||||
|
- Ensure account isn't locked or disabled
|
||||||
|
- Verify admin privileges
|
||||||
|
- Check AdGuard Home user management
|
||||||
|
|
||||||
|
### SSL Certificate Issues
|
||||||
|
|
||||||
|
**Error**: "SSL certificate verification failed"
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
|
||||||
|
1. **For Self-Signed Certificates**:
|
||||||
|
- Disable "Verify SSL" in integration settings
|
||||||
|
- Or add certificate to trusted store
|
||||||
|
|
||||||
|
2. **For Invalid Certificates**:
|
||||||
|
```bash
|
||||||
|
# Check certificate validity
|
||||||
|
openssl s_client -connect 192.168.1.100:443 -servername your-domain
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Use HTTP for Testing**:
|
||||||
|
- Temporarily switch to HTTP
|
||||||
|
- Test basic functionality
|
||||||
|
- Re-enable HTTPS after fixing certificates
|
||||||
|
|
||||||
|
## 📡 Network & Connectivity Issues
|
||||||
|
|
||||||
|
### DNS Resolution Problems
|
||||||
|
|
||||||
|
**Problem**: Home Assistant can't resolve AdGuard Home hostname.
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
|
||||||
|
1. **Use IP Address**:
|
||||||
|
- Replace hostname with IP address
|
||||||
|
- Test connectivity with IP first
|
||||||
|
|
||||||
|
2. **Check DNS Configuration**:
|
||||||
|
```bash
|
||||||
|
# Test DNS resolution
|
||||||
|
nslookup adguard.local
|
||||||
|
dig adguard.local
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Update /etc/hosts**:
|
||||||
|
```bash
|
||||||
|
# Add to /etc/hosts if needed
|
||||||
|
echo "192.168.1.100 adguard.local" >> /etc/hosts
|
||||||
|
```
|
||||||
|
|
||||||
|
### Port Conflicts
|
||||||
|
|
||||||
|
**Problem**: Port 3000 is not accessible or in use by another service.
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
|
||||||
|
1. **Check Port Usage**:
|
||||||
|
```bash
|
||||||
|
# See what's using port 3000
|
||||||
|
sudo lsof -i :3000
|
||||||
|
netstat -tlnp | grep :3000
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Change AdGuard Home Port**:
|
||||||
|
```yaml
|
||||||
|
# In AdGuard Home configuration
|
||||||
|
http:
|
||||||
|
address: 0.0.0.0:3001 # Change port
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Update Integration Configuration**:
|
||||||
|
- Remove and re-add integration
|
||||||
|
- Use new port number
|
||||||
|
|
||||||
|
### Firewall Issues
|
||||||
|
|
||||||
|
**Problem**: Connection blocked by firewall.
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
|
||||||
|
1. **Check Firewall Status**:
|
||||||
|
```bash
|
||||||
|
# Ubuntu/Debian
|
||||||
|
sudo ufw status
|
||||||
|
|
||||||
|
# CentOS/RHEL
|
||||||
|
sudo firewall-cmd --list-all
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Allow AdGuard Home Port**:
|
||||||
|
```bash
|
||||||
|
# UFW
|
||||||
|
sudo ufw allow from 192.168.1.10 to any port 3000
|
||||||
|
|
||||||
|
# firewalld
|
||||||
|
sudo firewall-cmd --add-port=3000/tcp --permanent
|
||||||
|
sudo firewall-cmd --reload
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Test Without Firewall** (temporarily):
|
||||||
|
```bash
|
||||||
|
# Disable firewall for testing (CAUTION)
|
||||||
|
sudo ufw disable
|
||||||
|
# Test connection, then re-enable
|
||||||
|
sudo ufw enable
|
||||||
|
```
|
||||||
|
|
||||||
|
## 🔄 Update & Upgrade Issues
|
||||||
|
|
||||||
|
### Update Failures
|
||||||
|
|
||||||
|
**Problem**: Integration fails to update via HACS.
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
|
||||||
|
1. **Manual Update**:
|
||||||
|
```bash
|
||||||
|
# Remove old version
|
||||||
|
rm -rf /config/custom_components/adguard_hub
|
||||||
|
|
||||||
|
# Download and install new version
|
||||||
|
# (Follow manual installation steps)
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **HACS Cache Issues**:
|
||||||
|
- Restart Home Assistant
|
||||||
|
- Clear HACS cache
|
||||||
|
- Re-add custom repository if needed
|
||||||
|
|
||||||
|
3. **Version Conflicts**:
|
||||||
|
- Check Home Assistant version compatibility
|
||||||
|
- Review integration changelog
|
||||||
|
- Consider rolling back if needed
|
||||||
|
|
||||||
|
### Configuration Migration
|
||||||
|
|
||||||
|
**Problem**: Settings lost after update.
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
|
||||||
|
1. **Backup Before Updates**:
|
||||||
|
```bash
|
||||||
|
# Backup configuration
|
||||||
|
cp -r /config/custom_components/adguard_hub /config/backup/
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Reconfigure Integration**:
|
||||||
|
- Remove integration
|
||||||
|
- Re-add with previous settings
|
||||||
|
- Verify entity names haven't changed
|
||||||
|
|
||||||
|
## 🐛 Debugging Steps
|
||||||
|
|
||||||
|
### Enable Debug Logging
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# configuration.yaml
|
||||||
|
logger:
|
||||||
|
default: warning
|
||||||
|
logs:
|
||||||
|
custom_components.adguard_hub: debug
|
||||||
|
custom_components.adguard_hub.api: debug
|
||||||
|
custom_components.adguard_hub.config_flow: debug
|
||||||
|
```
|
||||||
|
|
||||||
|
### Collect Diagnostic Information
|
||||||
|
|
||||||
|
When reporting issues, collect:
|
||||||
|
|
||||||
|
1. **Home Assistant Version**:
|
||||||
|
```bash
|
||||||
|
# In Home Assistant
|
||||||
|
Settings > System > Repairs > Three dots > System Information
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Integration Version**:
|
||||||
|
```bash
|
||||||
|
# Check manifest.json
|
||||||
|
cat /config/custom_components/adguard_hub/manifest.json | grep version
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **AdGuard Home Version**:
|
||||||
|
```bash
|
||||||
|
# Check in AdGuard Home web interface or API
|
||||||
|
curl -u admin:password http://192.168.1.100:3000/control/status | grep version
|
||||||
|
```
|
||||||
|
|
||||||
|
4. **Error Logs**:
|
||||||
|
```bash
|
||||||
|
# Extract relevant logs
|
||||||
|
grep -i "adguard" /config/home-assistant.log
|
||||||
|
```
|
||||||
|
|
||||||
|
### Test API Manually
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Test basic connectivity
|
||||||
|
curl -u admin:password http://192.168.1.100:3000/control/status
|
||||||
|
|
||||||
|
# Test client list
|
||||||
|
curl -u admin:password http://192.168.1.100:3000/control/clients
|
||||||
|
|
||||||
|
# Test statistics
|
||||||
|
curl -u admin:password http://192.168.1.100:3000/control/stats
|
||||||
|
```
|
||||||
|
|
||||||
|
## 📞 Getting Help
|
||||||
|
|
||||||
|
### Before Seeking Support
|
||||||
|
|
||||||
|
1. ✅ Check this troubleshooting guide
|
||||||
|
2. ✅ Enable debug logging
|
||||||
|
3. ✅ Collect diagnostic information
|
||||||
|
4. ✅ Test with minimal configuration
|
||||||
|
5. ✅ Review recent changes
|
||||||
|
|
||||||
|
### Where to Get Help
|
||||||
|
|
||||||
|
1. **GitHub Issues**: [Repository Issues](https://your-gitea-domain.com/your-username/adguard-control-hub/issues)
|
||||||
|
- Search existing issues first
|
||||||
|
- Provide detailed information
|
||||||
|
- Include logs and configuration
|
||||||
|
|
||||||
|
2. **Home Assistant Community**: [Community Forum](https://community.home-assistant.io/)
|
||||||
|
- General Home Assistant questions
|
||||||
|
- Integration discussions
|
||||||
|
|
||||||
|
3. **AdGuard Home Support**: [AdGuard Home GitHub](https://github.com/AdguardTeam/AdGuardHome)
|
||||||
|
- AdGuard Home specific issues
|
||||||
|
- API-related questions
|
||||||
|
|
||||||
|
### Issue Report Template
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
**Environment**:
|
||||||
|
- Home Assistant Version:
|
||||||
|
- Integration Version:
|
||||||
|
- AdGuard Home Version:
|
||||||
|
- Installation Method: HACS/Manual
|
||||||
|
|
||||||
|
**Problem Description**:
|
||||||
|
Brief description of the issue
|
||||||
|
|
||||||
|
**Steps to Reproduce**:
|
||||||
|
1. Step one
|
||||||
|
2. Step two
|
||||||
|
3. Step three
|
||||||
|
|
||||||
|
**Expected Behavior**:
|
||||||
|
What you expected to happen
|
||||||
|
|
||||||
|
**Actual Behavior**:
|
||||||
|
What actually happened
|
||||||
|
|
||||||
|
**Logs**:
|
||||||
|
```
|
||||||
|
[Paste relevant logs here]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Configuration**:
|
||||||
|
```yaml
|
||||||
|
# Paste relevant configuration (sanitize passwords)
|
||||||
|
```
|
||||||
|
```
|
||||||
|
|
||||||
|
## 🔧 Quick Fixes
|
||||||
|
|
||||||
|
### Reset Integration
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Complete reset
|
||||||
|
1. Remove integration from UI
|
||||||
|
2. Restart Home Assistant
|
||||||
|
3. rm -rf /config/custom_components/adguard_hub
|
||||||
|
4. Reinstall integration
|
||||||
|
5. Restart Home Assistant
|
||||||
|
6. Re-add integration
|
||||||
|
```
|
||||||
|
|
||||||
|
### Emergency Recovery
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# If automations are causing issues
|
||||||
|
# Disable automations temporarily
|
||||||
|
automation: []
|
||||||
|
|
||||||
|
# Or disable specific automation
|
||||||
|
automation old_automation_id:
|
||||||
|
mode: single
|
||||||
|
trigger: []
|
||||||
|
action: []
|
||||||
|
```
|
||||||
|
|
||||||
|
### Test Configuration
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# Minimal test configuration
|
||||||
|
adguard_hub:
|
||||||
|
scan_interval: 60
|
||||||
|
auto_create_clients: false
|
||||||
|
enable_statistics: false
|
||||||
|
blocked_services_as_switches: false
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Still having issues?** Open an issue on the repository with detailed information, logs, and your configuration (remember to sanitize sensitive data).
|
||||||
Reference in New Issue
Block a user