Skip to content

README.md

Latest commit

 

History

History
103 lines (72 loc) · 3.54 KB

README.md

File metadata and controls

103 lines (72 loc) · 3.54 KB

AdGuard Notifier for Home Assistant

Get real-time notifications from AdGuard Home directly into Home Assistant when blocked queries are detected.

Overview

This solution monitors AdGuard Home for blocked DNS queries and sends notifications to Home Assistant via webhooks. It consists of:

  • Python script: Queries the AdGuard WebUI to monitor blocked requests
  • Systemd service: Runs the script continuously in the background
  • Home Assistant automation: Receives webhooks and triggers notifications

The script queries the AdGuard WebUI instead of reading the query log directly because AdGuard stores logs in RAM and only flushes after 1000 queries by default.

Monitored Block Reasons

Reason Description
FilteredBlockList Domain found in manually added filter lists (EasyList, AdGuard DNS filter, etc.)
FilteredParental Blocked by Parental Control due to adult content
FilteredSafeBrowsing Blocked by Browsing Security (malware/phishing)
FilteredSafeSearch Query modified to enforce Safe Search (Google, Bing, YouTube)
FilteredBlockedService Service blocked via "Blocked Services" settings (TikTok, Facebook, YouTube, etc.)

Installation

Prerequisites

  • Linux machine with Python 3 installed (works best in AdGuard LXC container)
  • AdGuard Home
  • Home Assistant

Steps

  1. Clone the repository

    git clone github.com/gladsonsam/adguard-notifier.git
cd AdGuard-Notifier

  2. Configure the Python script

    Edit adguard-notifier.py and update the configuration variables:

    # Config
AGH_URL = "http://127.0.0.1:80/control/querylog?limit=10"
AGH_USER = "ADGUARD_USERNAME"
AGH_PASS = "ADGUARD_PASSWORD"
HA_WEBHOOK_URL = "http://YOUR_HA_IP:8123/api/webhook/..."
COOLDOWN_SECONDS = 60
TARGET_REASONS = "FilteredParental"

    Configuration Details:

    • AGH_URL: AdGuard Home API endpoint

      • 127.0.0.1:80 usually works when running in the same container
      • If not working, use the external IP (e.g., 192.168.1.20:80)

    • AGH_USER: Your AdGuard Home username

    • AGH_PASS: Your AdGuard Home password

    • HA_WEBHOOK_URL: Full webhook URL to your Home Assistant instance

      • Format: http://YOUR_HA_IP:8123/api/webhook/YOUR_UNIQUE_WEBHOOK_ID
      • Replace with your Home Assistant IP and webhook ID

    • COOLDOWN_SECONDS: Time (in seconds) to wait before sending another notification for the same domain/client combination

    • TARGET_REASONS: Comma-separated list of block reasons to monitor

      • Can be a single reason: "FilteredParental"
      • Or multiple reasons: "FilteredParental,FilteredBlockList,FilteredSafeBrowsing"

  3. Set up the systemd service

    • Copy adguard-notifier.service to /etc/systemd/system/
    • Update the script path in the service file if needed

  4. Enable and start the service

    systemctl daemon-reload
systemctl enable adguard-notifier.service
systemctl start adguard-notifier.service

  5. Verify the service is running

    systemctl status adguard-notifier.service

Home Assistant Configuration

  1. Open Home Assistant and navigate to Settings → Automations & Scenes
  2. Click Create Automation → Edit in YAML
  3. Paste the contents from automation.yaml
  4. Change the webhook ID to a unique value
  5. Ensure the webhook ID matches the one configured in adguard-notifier.py
  6. Save the automation

Your notifications should now appear when AdGuard blocks queries!