sebingel
98f5b81cc8
With PIHOLEAPI_GET_OFFLINE enabled, PIHOLEAPI imports devices it considers offline, but every row still counted as a live sighting. The plugin computed the online state, yet never passed it on, and its config.json mapped nothing to CurrentScan.scanPresence, so each row got the column default 1. An offline device imported only for its name, vendor and IP was marked online. ADGUARDIMP had the same problem in #1813 and fixed it the same way. Changes: - main() passes the online state as helpVal4 '1' or '0' to add_object() (server/plugins/pihole_api_scan/pihole_api_scan.py). - config.json maps helpVal4 to scanPresence, the same column definition adguard_import uses. The GET_OFFLINE description says offline devices are imported without being marked online; the README says the same. - test/db_test_helpers.py: make_plugin_event_row() takes an optional help_val4, and CREATE_CURRENT_SCAN gets the CHECK (scanPresence IN (0, 1)) of the real schema (db_upgrade.py), so a test sees the same constraint as production. - New test/scan/test_piholeapi_scan_presence_mapping.py runs the real PIHOLEAPI config.json through process_plugin_events() and checks that a helpVal4 '0' row lands in CurrentScan with scanPresence 0. - test/plugins/test_pihole_api_scan.py: main() writes helpVal4 '0' for an offline device and '1' for every IP row of an online device. Both new tests fail without this change. Impact: Devices imported only because of PIHOLEAPI_GET_OFFLINE keep their name, vendor and IP data but no longer mark the device as online. Live check against Pi-hole v6.8: 28 rows with helpVal4 '0', 5 with '1'; the absent phone got devPresentLastScan 0 and only a New Device event. With GET_OFFLINE disabled (the default) every imported row is online, so nothing changes there.
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
- Time of the last DNS query
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_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. |
| 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
-
Online status comes from DNS activity. A device counts as online when its last DNS query to Pi-hole is at most
PIHOLEAPI_CONSIDER_ONLINEseconds old. Pi-hole's per-IP "last seen" value is not used, because Pi-hole keeps refreshing it for as long as it holds the client in memory (about 24 hours in practice), also after the device has left. -
Devices that send a DNS query only every few hours, such as smart plugs, powerline adapters or speakers, can show as offline although they are on. Run a presence scanner such as ARPSCAN on the same schedule. If PIHOLEAPI is your only presence source, raise
PIHOLEAPI_CONSIDER_ONLINEinstead (for example to3600). A device that has left the network then also counts as online for that long. -
With
PIHOLEAPI_GET_OFFLINEenabled, offline devices are still imported (name, vendor, IP), but they are not marked as online. -
Version: 1.0.0
-
Author:
jokob-sk,leiweibau -
Release Date:
11-2025