Pi-hole Integration Library
Relevant source files
The following files were used as context for generating this wiki page:
The Pi-hole Integration Library provides a crucial link between the Overlord Network Kill Switch application and one or more Pi-hole instances. Its primary purpose is to offer programmatic control over DNS filtering, abstracting the underlying Pi-hole API calls into a simplified, task-oriented interface. This allows the main application to enable or disable DNS blocking for specific domain groups or to toggle DNS filtering globally across all configured Pi-hole devices.
This library is exposed via a set of FastAPI endpoints, enabling control through simple HTTP requests. It relies on the pihole6api library to communicate with Pi-hole v6 instances, managing authentication and API interactions for domain and DNS control. The functionality is split into two main components: per-domain-group management and global DNS control.
Sources: README.md, cgi-bin/controller.py:42-50, lib/pihole/pihole.py:15
Architecture and Core Components
The library is built around three main classes that inherit from Pydantic's BaseModel for data validation and configuration management. The BaseHTTPHandler class provides a common foundation for connecting to and managing sessions with multiple Pi-hole instances.
Sources: lib/pihole/base.py:11, lib/pihole/pihole.py:25, lib/pihole/alldns.py:21
The diagram below illustrates the class hierarchy and their primary responsibilities.
BaseHTTPHandler
This is the base class for all Pi-hole handler modules. It is responsible for:
- Reading Pi-hole connection details (
remote_pi_list,remote_pi_password) from the application configuration. - Establishing and storing
PiHole6Clientsessions for each configured Pi-hole instance. - Managing the login state (
logged_in) and providing afirst_connect()method to authenticate with all Pi-holes. - Providing a
shutdown()method to properly close all active sessions.
Sources: lib/pihole/base.py:11-80
PiHoleOverlord
This class manages domain-specific blocking rules. It handles the logic for enabling or disabling predefined groups of domains (regex filters) on the Pi-hole instances. It uses the allow_domains and block_domains configurations to determine which domains to act upon.
Sources: lib/pihole/pihole.py:25-151
MasterEnabler
This class provides global control over DNS filtering. It can enable or disable DNS blocking entirely on all connected Pi-holes. It also supports a timer to automatically re-enable blocking after a specified duration.
Sources: lib/pihole/alldns.py:21-119
Initialization and Configuration
The Pi-hole library is initialized during the application's startup lifespan event. The main controller.py script calls pihole_router.init(), which instantiates both PiHoleOverlord and MasterEnabler with the global application configuration.
The following diagram shows the initialization flow.
Configuration is loaded from etc/config.ini and relevant environment variables. The key settings for this library are:
| Section | Key | Description | Source File |
|---|---|---|---|
[general] | pihole_control_enabled | A boolean flag to enable or disable the entire Pi-hole integration module. | cgi-bin/controller.py:75 |
[general] | remote_pi_list | A space-separated list of Pi-hole IP addresses or hostnames. | cgi-bin/controller.py:91 |
[general] | remote_pi_password | The password for the Pi-hole web admin interface. | cgi-bin/controller.py:98 |
[block_domains] | (custom_name) | A named group of regex domains to be managed as a blocklist. | cgi-bin/controller.py:86 |
[allow_domains] | (custom_name) | A named group of regex domains to be managed as an allowlist. | cgi-bin/controller.py:86 |
Sources: cgi-bin/controller.py:72-102
API Endpoints
The library's functionality is exposed through two sets of API endpoints, mounted on the /pihole and /alldns prefixes.
Sources: lib/pihole/pihole_router.py:44-89, cgi-bin/controller.py:158-159
Domain Group Management (/pihole)
These endpoints control specific domain groups defined in the configuration.
| Method | Path | Description | Handler Function |
|---|---|---|---|
GET | /status/{domain_block} | Checks if all domains in the specified group are enabled and active. | get_pihole |
POST | /enable/{domain_block} | Enables (adds) all domains in the specified group as regex filters. | delete_pihole |
POST | /disable/{domain_block} | Disables (deletes) all domains in the specified group. | post_pihole |
Sources: lib/pihole/pihole_router.py:51-67
Global DNS Control (/alldns)
These endpoints control the overall DNS blocking status for all Pi-holes.
| Method | Path | Parameters | Description | Handler Function |
|---|---|---|---|---|
GET | / | - | Gets the current global DNS blocking status. | get_all_dns |
POST | / | timer (int, optional) | Disables DNS blocking, optionally for a set duration. | post_all_dns |
DELETE | / | - | Enables DNS blocking. | delete_all_dns |
Sources: lib/pihole/pihole_router.py:78-89
Operational Flows
Disabling a Domain Group
When a request is made to disable a domain group, the PiHoleOverlord class iterates through each domain in the configured group and sends a delete_domain command to each connected Pi-hole instance.
The sequence diagram below details this process.
Disabling Global DNS with a Timer
A request to the /alldns endpoint with a timer will trigger the MasterEnabler to disable blocking on all Pi-hole instances for the specified duration.
The sequence diagram below shows this flow.
Summary
The Pi-hole Integration Library is a well-defined module that provides robust, centralized control over multiple Pi-hole instances. By leveraging the pihole6api library and a clear, class-based architecture, it abstracts complex interactions into simple API calls. This enables the broader Overlord Network Kill Switch project to easily integrate DNS-based filtering into its automation workflows, such as those triggered by HomeKit via MQTT and Node-RED.