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.
Tip
Some tip.
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_SSL_VERIFY | 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. |
Example Configuration
| Setting Key | Sample Value |
|---|---|
| PIHOLEAPI_URL | http://pi.hole/ |
| PIHOLEAPI_PASSWORD | passw0rd |
| PIHOLEAPI_SSL_VERIFY | true |
| PIHOLEAPI_RUN_TIMEOUT | 30 |
| PIHOLEAPI_API_MAXCLIENTS | 500 |
⚠️ 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.
❌ 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