sebingel
71efcd0ba0
main() read the setting 'PIHOLEAPI_SSL_VERIFY', but config.json defines
the function VERIFY_SSL, so the real key is PIHOLEAPI_VERIFY_SSL.
get_setting_value() returns "" for a key nobody defined, so every Pi-hole
API request got verify="": certificate checks were always off and the
InsecureRequestWarning was suppressed, even when a user had turned on
"Verify SSL". The login request sends the Pi-hole web password to
api/auth. The plugin README and docs/PIHOLE_GUIDE.md used the wrong name
too. test_plugin_conventions.py did not catch it: it only looks at
get_setting_value("X") or <literal>, and this line had no fallback.
Changes:
- test/plugins/test_plugin_conventions.py: new
test_own_setting_keys_exist_in_config. Every literal
get_setting_value('<PREFIX>_X') in a plugin's scripts must name a
setting its own config.json defines; core settings and other plugins'
keys are not checked. Before the fix it fails for exactly one of the 54
plugins: pihole_api_scan.py, get_setting_value('PIHOLEAPI_SSL_VERIFY').
- New test/plugins/test_pihole_api_scan_verify_ssl.py: runs main() with
VERIFY_SSL true and false and checks the verify= value that reaches
requests.post() for api/auth. Only the HTTP call is mocked. It fails
before the fix (verify=None).
- server/plugins/pihole_api_scan/pihole_api_scan.py: main() reads
PIHOLEAPI_VERIFY_SSL.
- server/plugins/pihole_api_scan/README.md and docs/PIHOLE_GUIDE.md name
the setting PIHOLEAPI_VERIFY_SSL.
- docs/PLUGINS_DEV.md, Conventions Checklist: read a setting under the
exact key config.json defines; names the new check.
Impact:
"Verify SSL" now works. The default stays false, so default installs
behave as before. A user who turned it on while Pi-hole uses a
self-signed certificate will now see the login fail, as the setting
description says ("Disable if you are using a self-signed certificate").
Live check against Pi-hole v6.8 behind a proxy with an untrusted
certificate: with "Verify SSL" on the fixed code refused to log in, the
old code logged in and imported 33 entries.
Overview - PIHOLEAPI Plugin — Pi-hole v6 Device Import
The PIHOLEAPI plugin lets NetAlertX import network devices directly from a Pi-hole v6 instance. This turns Pi-hole into an additional discovery source, helping NetAlertX stay aware of devices seen by your DNS server.
The plugin connects to your Pi-hole’s API and retrieves:
- MAC addresses
- IP addresses
- Hostnames (if available)
- Vendor info
- Last-seen timestamps
NetAlertX then uses this information to match or create devices in your system.
See the Pi-hole guide for a walkthrough covering this plugin alongside the other Pi-hole integrations (PIHOLE, PIHOLEMON, DHCPLSS).
Quick setup guide
- You are running Pi-hole v6 or newer.
- The Web UI password in Pi-hole is set.
- Local network devices appear under Settings → Network in Pi-hole.
No additional Pi-hole configuration is required.
Usage
- Head to Settings > Plugin name to adjust the default values.
| Setting Key | Description |
|---|---|
| PIHOLEAPI_URL | Your Pi-hole base URL. |
| PIHOLEAPI_PASSWORD | The Web UI base64 encoded (en-/decoding handled by the app) admin password. |
| PIHOLEAPI_VERIFY_SSL | Whether to verify HTTPS certificates. Disable only for self-signed certificates. |
| PIHOLEAPI_RUN_TIMEOUT | Request timeout in seconds. |
| PIHOLEAPI_API_MAXCLIENTS | Maximum number of devices to request from Pi-hole. Defaults are usually fine. |
| PIHOLEAPI_FAKE_MAC | Generate FAKE MAC from IP. |
⚠️ Troubleshooting
Below are the most common issues and how to resolve them.
❌ Authentication failed
Check the following:
-
The Pi-hole URL is correct and includes a trailing slash
http://192.168.1.10/✔http://192.168.1.10/admin❌
-
Your Pi-hole password is correct
-
You are using Pi-hole v6, not v5
-
SSL verification matches your setup (disable for self-signed certificates)
❌ Connection error
Usually caused by:
- Wrong URL
- Wrong HTTP/HTTPS selection
- Timeout too low
Try:
PIHOLEAPI_URL = http://<pi-hole-ip>/
PIHOLEAPI_RUN_TIMEOUT = 60
❌ No devices imported
Check:
- Pi-hole shows devices under Settings → Network
- NetAlertX logs contain:
[PIHOLEAPI] Pi-hole API returned data
If nothing appears:
- Pi-hole might be returning empty results
- Your network interface list may be empty
- A firewall or reverse proxy is blocking access
Try enabling debug logging:
LOG_LEVEL = debug
Then re-run the plugin.
❌ Some devices are missing
Check:
- Pi-hole shows devices under Settings → Network
- NetAlertX logs contain:
[PIHOLEAPI] Skipping invalid MAC (see PIHOLEAPI_FAKE_MAC setting) ...
If devices are missing:
- The app skipps devices with invalid MACs
- Enable PIHOLEAPI_FAKE_MAC if you want to import these devices with a fake mac and you are not concerned with data inconsistencies later on
Try enabling PIHOLEAPI_FAKE_MAC:
PIHOLEAPI_FAKE_MAC = 1
Then re-run the plugin.
❌ Wrong or missing hostnames
Pi-hole only reports names it knows from:
- Local DNS
- DHCP leases
- Previously seen queries
If names are missing, confirm they appear in Pi-hole’s own UI first.
Notes
-
Additional notes, limitations, Author info.
-
Version: 1.0.0
-
Author:
jokob-sk,leiweibau -
Release Date:
11-2025