128 lines
4.4 KiB
Markdown
128 lines
4.4 KiB
Markdown
# AdGuard Control Hub
|
|
|
|
[![GitHub Release][releases-shield]][releases]
|
|
[![GitHub Activity][commits-shield]][commits]
|
|
[![License][license-shield]](LICENSE)
|
|
[![hacs][hacsbadge]][hacs]
|
|
|
|
A comprehensive Home Assistant integration for managing your AdGuard Home instance with advanced control and monitoring capabilities.
|
|
|
|
## Features
|
|
|
|
### Switches
|
|
- **AdGuard Protection**: Master switch that controls all AdGuard features
|
|
- **DNS Filtering**: Enables DNS filtering using blocklists
|
|
- **Safe Browsing**: Blocks known phishing and malware sites
|
|
- **Parental Control**: Blocks adult content
|
|
- **Safe Search**: Enforces safe search on search engines
|
|
- **Query Log**: Records DNS queries for statistics
|
|
|
|
### Sensors
|
|
- **DNS Queries**: Total number of DNS queries processed
|
|
- **Blocked Queries**: Number of queries blocked by filtering
|
|
- **Blocked Percentage**: Percentage of queries that were blocked
|
|
- **Active Filter Rules**: Number of active filtering rules loaded
|
|
- **Average Processing Time**: Average DNS query processing time
|
|
|
|
### Binary Sensors
|
|
- **AdGuard Home Running**: Shows if AdGuard Home is responsive
|
|
|
|
## Installation
|
|
|
|
### HACS (Recommended)
|
|
|
|
1. Install [HACS](https://hacs.xyz/) if you haven't already
|
|
2. In HACS, go to "Integrations"
|
|
3. Click the "+" button and search for "AdGuard Control Hub"
|
|
4. Click "Install"
|
|
5. Restart Home Assistant
|
|
|
|
### Manual Installation
|
|
|
|
1. Download the latest release from the [releases page](https://github.com/your-username/adguard-control-hub/releases)
|
|
2. Extract the `adguard-control-hub.zip` file
|
|
3. Copy the `custom_components/adguard_control_hub` folder to your Home Assistant's `custom_components` directory
|
|
4. Restart Home Assistant
|
|
|
|
## Configuration
|
|
|
|
1. In Home Assistant, go to **Settings** → **Devices & Services**
|
|
2. Click **"+ ADD INTEGRATION"**
|
|
3. Search for "AdGuard Control Hub" and select it
|
|
4. Fill in your AdGuard Home connection details:
|
|
- **Host**: IP address or hostname of your AdGuard Home instance
|
|
- **Port**: Port number (default: 3000)
|
|
- **Username**: Admin username (if authentication is enabled)
|
|
- **Password**: Admin password (if authentication is enabled)
|
|
- **Use HTTPS**: Enable if using HTTPS
|
|
- **Verify SSL**: Verify SSL certificates
|
|
|
|
## Requirements
|
|
|
|
- AdGuard Home v0.107.0 or newer
|
|
- Home Assistant 2023.5.0 or newer
|
|
- Network access to your AdGuard Home instance
|
|
|
|
## Supported AdGuard Home Versions
|
|
|
|
This integration has been tested with:
|
|
- AdGuard Home v0.107.50+
|
|
- AdGuard Home v0.108.x
|
|
- AdGuard Home v0.109.x
|
|
|
|
## Troubleshooting
|
|
|
|
### Connection Issues
|
|
- Ensure AdGuard Home is running and accessible from Home Assistant
|
|
- Check firewall settings on the AdGuard Home host
|
|
- Verify the correct port is being used
|
|
- Test connection manually using curl: `curl http://your-adguard-ip:port/control/status`
|
|
|
|
### Authentication Issues
|
|
- Verify username and password are correct
|
|
- Ensure the user account has admin privileges in AdGuard Home
|
|
- Try connecting without authentication first to isolate the issue
|
|
|
|
### Feature Not Working
|
|
- Check AdGuard Home logs for any error messages
|
|
- Verify the specific feature is enabled in AdGuard Home
|
|
- Some features require specific AdGuard Home configurations
|
|
|
|
## Development
|
|
|
|
### Setting up Development Environment
|
|
|
|
1. Clone the repository
|
|
2. Install development dependencies: `pip install -r requirements_test.txt`
|
|
3. Run tests: `pytest tests/`
|
|
4. Run linting: `black custom_components/ && isort custom_components/`
|
|
|
|
### Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Make your changes
|
|
4. Add tests for new functionality
|
|
5. Ensure all tests pass
|
|
6. Submit a pull request
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
|
|
## Acknowledgments
|
|
|
|
- AdGuard Team for creating AdGuard Home
|
|
- Home Assistant community for the integration framework
|
|
- All contributors and testers
|
|
|
|
---
|
|
|
|
[releases-shield]: https://img.shields.io/github/release/your-username/adguard-control-hub.svg?style=for-the-badge
|
|
[releases]: https://github.com/your-username/adguard-control-hub/releases
|
|
[commits-shield]: https://img.shields.io/github/commit-activity/y/your-username/adguard-control-hub.svg?style=for-the-badge
|
|
[commits]: https://github.com/your-username/adguard-control-hub/commits/main
|
|
[license-shield]: https://img.shields.io/github/license/your-username/adguard-control-hub.svg?style=for-the-badge
|
|
[hacs]: https://github.com/hacs/integration
|
|
[hacsbadge]: https://img.shields.io/badge/HACS-Custom-orange.svg?style=for-the-badge
|