The Pi-hole plugin goes back to the abandoned plugin by Xorfor and was continued for Pi-hole v6 by Wojtek Sawasciuk (Voyo). I have rewritten it from the ground up, keeping its plugin key, hardware type name, settings and device units. An existing installation is therefore upgraded by replacing the files.
Repository: https://github.com/janreimen/Domoticz-PiHole-Control
License: Apache 2.0, as in the predecessor.
What it does
Monitors a Pi-hole v6 and lets Domoticz switch its blocking, block lists and groups, for example for parental-control schedules ("Kids" group off at 20:00) or "pause the blocking for 15 minutes".
Why a rewrite
The old single-file plugin (about 800 lines, no tests) had a few problems:
- the heartbeat was set to the update interval (60 s by default), but Domoticz treats a heartbeat above 30 s as "plugin not responding"
- every command except "On" was treated as "Off"
- lists and groups were fetched twice per poll
- the search for a free group unit had no upper bound and could create units above 255
- group names were hard-coded (0 = Default, 1 = Kids)
- a new login was made every 10 heartbeats without a logout, which uses up the Pi-hole's limited number of sessions
- a leftover debug line was written to the log each time a group was switched
- Modular package (API client, settings, device layer, polling logic); only plugin.py touches Domoticz. No Python packages needed: standard library only, Python 3.7 or newer.
- Settings are validated with clear messages (URL, password, update interval, certificate file).
- One login session, reused and renewed in time, and logged out when the hardware stops. The app password is recommended (it also works with two-factor authentication).
- http and https. Certificates are always verified; for a private CA you give a PEM chain file. Redirects are never followed, so the password cannot be sent somewhere you did not configure.
- Quiet logging: a problem is logged once and its recovery once, with back-off after failed polls. Four debug levels; the password and the session id are masked in every log line.
- "Pi-hole Status" shows the connection (On while the Pi-hole answers, Off while it does not).
- Commands are verified by reading the state back from the Pi-hole; a change that did not take effect is reported and the device shows the truth again.
- One switch per block list and per group. Lists and groups you add, rename or delete in the Pi-hole appear, change and disappear in Domoticz by themselves (a device is removed only after the list was gone for three polls in a row). Devices are matched by their Pi-hole id, never by name.
- Heartbeat 10 s, polling by time; unchanged values are rewritten every 300 s so Domoticz' sensor time-out never marks them dead.
- Test suite with a fake Pi-hole (a real HTTP and TLS server) and a Domoticz stub, deploy.sh (local or over SSH, with backup and rollback), full documentation.
Found by reading the Pi-hole API specification and the Domoticz plugin framework source against the 0.1.0 code.
- Units on the counters (queries, blocked, domains, clients). A counter that exists without a unit gets it at start; a unit you set yourself is never changed.
- Devices Domoticz refused are created later. While Setup > Settings > System > Accept new Hardware Devices is off, Domoticz refuses new devices. The plugin now explains that once in the log, asks again every five minutes and creates everything as soon as the setting is on, without restarting the hardware.
- Renaming a list or group device keeps the "hardware name - " prefix Domoticz puts in front of plugin devices and no longer rewrites the device's value (which could fire notifications and scenes).
- The statistics devices are checked at every poll, not only at start.
- A comparison of the whole Pi-hole API (92 operations) with the plugin, with ranked candidates for further devices.
- Global blocking as three devices:
- Pi-hole Blocking: On/Off switch for the Pi-hole's blocking. Off means off until you switch it on again.
- Pi-hole Pause: selector with Not paused, 5 min, 15 min, 30 min, 1 hour and Until on. The Pi-hole switches the blocking back on by itself when the time is up, even if Domoticz is down. A pause started in the Pi-hole web interface shows up too.
- Pi-hole Blocking State: text such as "Blocking off, back on in 4 min 12 s".
- Queries per Second, Gravity Updated (an alert with age and date: green up to 8 days, yellow up to 15 days, then red) and the SERVFAIL / NXDOMAIN / REFUSED replies and the queries blocked by regex / by denylist (last 24 hours). They come from the summary the plugin already reads, so they cost no extra request.
- A pause that ends is noticed within about ten seconds, whatever the update interval is. If the Pi-hole's DNS resolver is not running, the plugin logs one error, the text says so and the switches keep their last state.
Install
Code: Select all
cd /srv/domoticz/plugins
git clone https://github.com/janreimen/Domoticz-PiHole-Control.git
sudo systemctl restart domoticzUpgrading from the old plugin: replace the files in the existing plugin directory and restart Domoticz; your devices, their history, scenes and schedules are kept. Please do not leave the old copy in a second directory: both plugins use the same key (PiHole), and Domoticz then runs only one of them, often the wrong one.
Status
Requires Pi-hole v6 (v5 has no REST API). Version 0.1.1 was tested on Domoticz 2026.3 and a Pi-hole, both under Linux. The 0.1.2 devices have so far been tested against the simulated Pi-hole and Domoticz of the test suite, so please look at the log on your first run. Reports from real installations are very welcome, as an issue on GitHub or here in the thread.