PLG: PIHOLEAPI #1282

Signed-off-by: jokob-sk <jokob.sk@gmail.com>
2025-12-07 09:36:05 -08:00 · 2025-11-15 13:36:22 +11:00
parent ec417b0dac
commit 972654dc78
3 changed files with 904 additions and 0 deletions
--- a/front/plugins/pihole_api_scan/README.md
+++ b/front/plugins/pihole_api_scan/README.md
@@ -0,0 +1,133 @@
+## 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`
+
+---
+
+