NetAlertX/docs/PIHOLE_GUIDE.md

Integration with PiHole

NetAlertX comes with 3 plugins suitable for integrating with your existing PiHole instance. The first plugin uses the v6 API, the second plugin is using a direct SQLite DB connection, the other leverages the DHCP.leases file generated by PiHole. You can combine multiple approaches and also supplement scans with other plugins.

Approach 1: PIHOLEAPI Plugin - Import devices directly from PiHole v6 API

To use this approach make sure the Web UI password in Pi-hole is set.

Setting	Description	Recommended value
PIHOLEAPI_URL	Your Pi-hole base URL including port.	http://192.168.1.82:9880/
PIHOLEAPI_RUN_SCHD	If you run multiple device scanner plugins, align the schedules of all plugins to the same value.	*/5 * * * *
PIHOLEAPI_PASSWORD	The Web UI base64 encoded (en-/decoding handled by the app) admin password.	passw0rd
PIHOLEAPI_SSL_VERIFY	Whether to verify HTTPS certificates. Disable only for self-signed certificates.	False
PIHOLEAPI_API_MAXCLIENTS	Maximum number of devices to request from Pi-hole. Defaults are usually fine.	500
PIHOLEAPI_FAKE_MAC	Generate FAKE MAC from IP.	False

Check the PiHole API plugin readme for details and troubleshooting.

docker-compose changes

No changes needed

Approach 2: DHCPLSS Plugin - Import devices from the PiHole DHCP leases file

Settings

Setting	Description	Recommended value
DHCPLSS_RUN	When the plugin should run.	schedule
DHCPLSS_RUN_SCHD	If you run multiple device scanner plugins, align the schedules of all plugins to the same value.	*/5 * * * *
DHCPLSS_paths_to_check	You need to map the value in this setting in the docker-compose.yml file. The in-container path must contain pihole so it's parsed correctly.	['/etc/pihole/dhcp.leases']

Check the DHCPLSS plugin readme for details

docker-compose changes

Path	Description
:/etc/pihole/dhcp.leases	PiHole's dhcp.leases file. Required if you want to use PiHole dhcp.leases file. This has to be matched with a corresponding DHCPLSS_paths_to_check setting entry (the path in the container must contain pihole)

Approach 3: PIHOLE Plugin - Import devices directly from the PiHole database

Setting	Description	Recommended value
PIHOLE_RUN	When the plugin should run.	schedule
PIHOLE_RUN_SCHD	If you run multiple device scanner plugins, align the schedules of all plugins to the same value.	*/5 * * * *
PIHOLE_DB_PATH	You need to map the value in this setting in the docker-compose.yml file.	/etc/pihole/pihole-FTL.db

Check the PiHole plugin readme for details

docker-compose changes

Path	Description
:/etc/pihole/pihole-FTL.db	PiHole's pihole-FTL.db database file.

Check out other plugins that can help you discover more about your network or check how to scan Remote networks.