mirror of
https://github.com/jokob-sk/NetAlertX.git
synced 2025-12-07 09:36:05 -08:00
134 lines
3.6 KiB
Markdown
134 lines
3.6 KiB
Markdown
## 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`
|
||
|
||
---
|
||
|
||
|