62 lines
2.5 KiB
Markdown
62 lines
2.5 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.
|
|
|
|
### Docker (Recommended)
|
|
You can run the monitor as a Docker container using the provided `docker-compose.yml`.
|
|
|
|
1. **Configure environment**:
|
|
Copy `.env.example` to `.env` and fill in your details.
|
|
2. **Start the container**:
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
### Manual 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`: API username.
|
|
- `ADGUARD_PASSWORD`: API password.
|
|
- `CLIENTS`: A JSON-formatted dictionary mapping IPs to display names.
|
|
- Example: `{"192.168.1.100": "My Laptop", "192.168.1.101": "My Phone"}`
|
|
- `HASS_URL`: Home Assistant mobile notification endpoint (e.g. `https://your-hass.com/api/services/notify/mobile_app_phone`).
|
|
- `HASS_TOKEN`: Home Assistant 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}"`.
|
|
|