AdGuard Home Smart-Home-Integration, kostenlos und Open Source
Control AdGuard Home DNS protection and follow its blocking statistics in Gladys.
Veröffentlicht von cicoub13
- Geräte
- Version 0.1.1
- Erfordert Gladys >=5.1.0
- ★ 0
Die Dokumentation dieser Integration wird von ihrem Autor geschrieben und ist bisher nur auf Englisch verfügbar.
Requires Gladys 5.1 or later. The dashboard widgets and scene actions of this integration ship with Gladys 5.1; on an earlier version the integration cannot be installed.
Control the DNS protection of your AdGuard Home server from Gladys and follow its blocking statistics: switches for the protection and its filters, 24-hour counters, two dashboard widgets and two scene actions (timed pause, blocking of services such as YouTube or TikTok).
Requirements
- An AdGuard Home server reachable over the network from the machine running Gladys.
- The account you use to log in to the AdGuard Home web interface. If your AdGuard Home runs without authentication, no account is needed.
Configuration
Open the integration's configuration screen and fill in:
| Field | Description |
|---|---|
| AdGuard Home address | The address of the web interface, the one you open in your browser, port included: for example http://192.168.1.10:3000, or https://adguard.example.com behind a reverse proxy. http:// is assumed when omitted. |
| Username | Your AdGuard Home login. Leave empty if AdGuard Home has no authentication. |
| Password | The matching password. Leave empty if AdGuard Home has no authentication. |
| Refresh frequency | How often AdGuard Home is read: 30 seconds, 1 minute (default) or 5 minutes. |
Then click Test the connection. On success it answers
Connected to AdGuard Home <version>.; otherwise it shows one of the messages
listed under "Troubleshooting" below.
Prefer the local IP address of the machine running AdGuard Home to localhost
or 127.0.0.1: the integration runs in its own container, where localhost
may not point to that machine. Do not put the username and password in the
address itself.
The AdGuard Home device
Once the connection works, an AdGuard Home device appears automatically in the Discovery tab of the integration, with no scan needed. Create it to get its features:
| Feature | Type | Description |
|---|---|---|
| DNS protection | Switch | Turns the whole AdGuard Home filtering on or off (off until you turn it on again). |
| Safe browsing | Switch | AdGuard's blocking of malware and phishing domains. |
| Parental control | Switch | AdGuard's blocking of adult content. |
| Safe search | Switch | Forces safe search on search engines; the per-engine choices of AdGuard are kept. |
| DNS queries (24 h) | Sensor | Number of DNS queries over the last 24 hours. |
| Blocked queries (24 h) | Sensor | Number of blocked queries over the last 24 hours. |
| Blocked queries ratio (24 h) | Sensor | Share of blocked queries over the last 24 hours, in %, rounded to a whole number. |
| Average processing time | Sensor | Average time AdGuard Home takes to answer a query, in milliseconds, as it reports it. |
The switches reflect the real state of AdGuard Home: a change made from its web interface shows up in Gladys at the next refresh. After a command sent from Gladys, the values are refreshed right away.
About "24 h". AdGuard Home reports its statistics per hour or per day depending on its statistics retention setting. With hourly statistics, the figures cover the last 24 hours (sliding window). With daily statistics, AdGuard gives no hourly detail: the figures are those of the current day, and the chart of the Overview widget is not shown.
Dashboard widgets
Add them from the dashboard editor.
Overview
- Three tiles: Queries (24 h), Blocked (24 h) and Blocked share (24 h) (with one decimal, highlighted as a warning above 50 %).
- A Last 24 hours chart of queries and blocked queries per hour (only with hourly statistics, see above).
- Status rows: Protection (On, Off, or "Paused until 16:30" in the time zone of your Gladys instance), Safe browsing, Parental control, Safe search and the AdGuard Home version.
- A button: Pause 10 min while the protection is on, Resume protection while it is paused or off. AdGuard Home resumes the protection by itself at the end of a pause.
Top lists
Choose the list in the widget settings: Most blocked domains, Most queried domains or Most active clients (client name and IP address). Up to 10 entries with their count.
These lists come from AdGuard Home's own rankings and cover its whole statistics retention period (for example 24 hours or 7 days), not 24 hours.
Scene actions
Pause DNS protection
Pauses the protection for 30 seconds, 1 minute, 10 minutes (default), 1 hour, 8 hours or 24 hours. AdGuard Home resumes it by itself.
Outputs, usable as {{…}} variables in the following actions of the scene:
- Resume time (HH:MM) (
resume_time): when the protection resumes, in the time zone of your Gladys instance (for example16:30), ready for a notification message; - Protection resumes at (ISO date) (
resume_at): the same instant as an ISO 8601 date with the local UTC offset (for example2026-09-26T16:30:00+02:00).
Block or unblock services
- Operation: Block or Unblock.
- Services: one or more of 25 services: YouTube, TikTok, Instagram, Facebook, Snapchat, X (Twitter), Reddit, Pinterest, WhatsApp, Discord, Telegram, Netflix, Disney+, Prime Video, Twitch, Spotify, Roblox, Minecraft, Epic Games (Fortnite), Steam, PlayStation, Xbox Live, Nintendo, League of Legends, ChatGPT.
- Client (name, IP or ClientID, empty for the whole network):
- empty: the global list of blocked services of AdGuard Home is changed, for the whole network;
- otherwise: only that client is changed. It must be a persistent client, declared in AdGuard Home under Settings > Client settings, and is matched by its name (case-insensitive) or one of its identifiers (IP, ClientID…). The client is switched to its own list of blocked services, starting from the global list if it was following it: later changes of the global list no longer apply to it. To make it follow the global list again, tick "Use global blocked services" in its AdGuard Home settings.
Services outside the list above, blocked from the AdGuard Home web interface, are kept, and so is the blocking schedule.
Output: Services now blocked (blocked_services), the AdGuard identifiers
of the services blocked after the change, comma-separated (for example
youtube, tiktok).
If an action fails (AdGuard Home unreachable, unknown client…), the error is written in the scene logs and the rest of the scene carries on.
Troubleshooting
Error messages appear in the integration's connection status, under the Test the connection button, and in the widgets.
"Enter the AdGuard Home address in the configuration." Fill in AdGuard Home address.
"The AdGuard Home address is not valid: use http(s)://host:port, without
username or password in it." The address is not an http:// or https://
address, or it contains a username and password: put those in their own fields.
"AdGuard Home refused the username or password. Check them in the integration settings. Polling is suspended until then." Check the username and password (those of the AdGuard Home web interface), then save the configuration or click Test the connection. Read "Locked out after wrong passwords" below.
"AdGuard Home cannot be reached. Check its address and that it is running." AdGuard Home is stopped, the address or port is wrong, or a firewall blocks the connection. Use the address you open in your browser, with the port of the web interface (not the DNS port 53).
"AdGuard Home did not answer in time. Check that it is running and that the address is right." No answer within 10 seconds: often a wrong IP address, or a firewall that silently drops the connection.
"The HTTPS certificate of AdGuard Home is not trusted. Use its http://
address or a valid certificate." AdGuard Home (or your reverse proxy) uses a
self-signed certificate. Use its http:// address on your local network, or a
certificate issued by a recognized authority.
"The address does not lead to the AdGuard Home API (unexpected answer). Check
the address, the username and the password." The address answers with a web
page instead of AdGuard Home: another application on that port, or the login
page of a reverse proxy (Authelia, Authentik…). Use the direct address of
AdGuard Home, or let the /control/ path through the proxy without its login.
"AdGuard Home answered with an error (HTTP …). Check that it is up to date." AdGuard Home refused the request: update it to a recent version. A 404 can also mean that the address leads to another web server.
"Unexpected error while talking to AdGuard Home. Check the integration logs." Look at the integration logs in Gladys, and report the problem if it persists.
"No data from AdGuard Home yet. If this lasts, check the address and the account in the integration settings." Shown by the widgets until the first successful read. Click Test the connection to see the actual error.
When a read fails after a successful one, the widgets keep showing the last data with a Last update: Failed, data may be outdated row.
Locked out after wrong passwords
AdGuard Home blocks an IP address after several failed logins (by default 5 attempts, then 15 minutes), its web interface included: during that time the machine running Gladys, and anything sharing its address, cannot log in to AdGuard Home, even with the right password.
To avoid causing this, the integration stops polling as soon as AdGuard Home refuses the username or password, instead of retrying at every refresh. Polling resumes when you save the configuration or click Test the connection. If you already tried several times, wait 15 minutes before testing again.
Privacy
- The Top lists widget shows the domains visited on your network and the names and IP addresses of your devices to anyone who can see the dashboard. Only add it to dashboards whose viewers may see that.
- The password is stored by Gladys as a secret and is only sent to your AdGuard Home server. The integration talks to nothing else.
Konfigurationseinstellungen
Diese Einstellungen fragt AdGuard Home in seinem Konfigurationsbildschirm in Gladys ab.
| Einstellung | Typ | Pflichtfeld | Beschreibung |
|---|---|---|---|
| Connect to AdGuard Home | section | Nein | Enter the address of the AdGuard Home web interface (the one you open in your browser) and the account you log in with. |
| AdGuard Home address | string | Ja | |
| Username | string | Nein | |
| Password | secret | Nein | |
| Refresh frequency | select | Nein |
So installierst du AdGuard Home in Gladys
- Öffne in Gladys Integrationen: AdGuard Home erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
- Klicke auf Installieren. Gladys lädt das Docker-Image (
ghcr.io/cicoub13/gladys-adguard-home:0.1.1) herunter, startet es in einer vom Kern isolierten Sandbox und erzeugt die Oberfläche der Integration (Geräte, Erkennung und Konfiguration). - Öffne den Bildschirm Konfiguration der Integration, fülle die Einstellungen aus und speichere.
- Du kannst sie auch direkt über die URL ihres Repositorys installieren: https://github.com/cicoub13/gladys-adguard-home.
AdGuard Home benötigt Gladys >=5.1.0. Der Katalog in Gladys wird stündlich aktualisiert, eine neue Version ist also spätestens eine Stunde nach ihrer Veröffentlichung verfügbar.
Du nutzt Gladys noch nicht? Es ist kostenlos und Open Source: folge der Installationsanleitung, um loszulegen.
Über externe Integrationen
AdGuard Home ist eine externe Integration: eine Community-Integration, die als Docker-Container verpackt und auf GitHub veröffentlicht wird. Gladys installiert sie mit einem Klick und führt sie in einer vom Kern isolierten Sandbox aus. Sie wird von cicoub13 veröffentlicht und gepflegt, nicht vom Gladys-Kernteam.
- Alle externen Integrationen durchsuchen
- Die nativen Integrationen entdecken, die in Gladys eingebaut sind
- Deine eigene externe Integration bauen und veröffentlichen
- Quellcode auf GitHub — Quelle dieser Dokumentation