49 lines
2.1 KiB
Markdown
49 lines
2.1 KiB
Markdown
# AdGuard Monitor
|
|
|
|
Monitoring service for AdGuard DNS queries with notifications sent to Home Assistant.
|
|
|
|
## Who is this for?
|
|
> This is for me mainly, so let's see if you need it too.
|
|
Adguard Monitor is designed for openclaw, which should usually NEVER make a request that needs to be blocked. If it does, I want to know about it immediately.
|
|
|
|
## Features
|
|
- **Multi-Client Support**: Monitor specific IP addresses and receive nicknamed notifications (e.g., "BLOCKED: My Laptop").
|
|
- **Strict Configuration**: Fails fast if environment variables are missing.
|
|
- **Home Assistant Notifications**: Native mobile push messages for blocked queries.
|
|
- **Custom Domain Monitoring**: Monitor specific domains using [list.txt](list.txt) (wildcards supported).
|
|
- **Structured Logging**: UTF-8 encoded logging for unicode emoji support.
|
|
|
|
## Setup
|
|
|
|
1. **Clone the repository.**
|
|
2. **Install dependencies**:
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
3. **Configure environment**:
|
|
Copy `.env.example` to `.env` and fill in your details:
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
4. **Custom Domains (Optional)**:
|
|
Copy [list.example.txt](list.example.txt) to `list.txt` and add domains:
|
|
```bash
|
|
cp list.example.txt list.txt
|
|
```
|
|
- Lines starting with `!` are **negative filters** (they will be ignored).
|
|
- Wildcards like `*.example.com` are supported.
|
|
|
|
5. **Run the monitor**:
|
|
```bash
|
|
python monitor.py --interval 15
|
|
```
|
|
|
|
## Environment Variables
|
|
- `ADGUARD_URL`: Full URL of your AdGuard instance (e.g., `http://192.168.1.50`).
|
|
- `ADGUARD_USER/PASSWORD`: API credentials.
|
|
- `CLIENTS`: A JSON-formatted dictionary mapping IPs to display names.
|
|
- `HASS_URL/TOKEN`: Home Assistant mobile notification endpoint and Long-Lived Access Token.
|
|
- `HASS_TITLE_TEMPLATE`: (Optional) Template for notification title. Available: `{event_type}`, `{client_name}`, `{host}`, `{reason}`. Default: `{event_type}`.
|
|
- `HASS_MSG_TEMPLATE`: (Optional) Template for notification body. Available: same as title. Default: `{client_name} tried to access "{host}"`.
|
|
|