Prerequisites
Relevant source files
The following files were used as context for generating this wiki page:The Overlord Network Kill Switch project acts as a central orchestration server that integrates with several other systems to provide its functionality. A proper setup requires specific hardware, software, and configurations across these systems. This document outlines all the necessary prerequisites for deploying and running the application.
The core function is to provide a simple, one-touch interface via HomeKit to control network access by manipulating Pi-hole DNS filters and Ubiquiti firewall rules. The system is composed of a Python-based web server that exposes an API, which is then called by a Node-RED instance acting as a bridge to an MQTT broker.
Sources: README.md:5-12, AGENTS.md:5-9
System Architecture & Required Services
The project relies on an ecosystem of services working in concert. The following diagram illustrates the high-level architecture and the relationship between the required components.
This diagram shows the flow of a user action from a HomeKit device through the various required services to the target Pi-hole or Ubiquiti device.
Sources: README.md:101-122, AGENTS.md:7-9
The following table details the external services that must be installed and configured for the system to operate.
| Service | Version/Plugin | Purpose |
|---|---|---|
| Homebridge | homebridge-mqttthing | Exposes MQTT topics as switches within Apple HomeKit. |
| Node-RED | N/A | Subscribes to MQTT topics from Homebridge and translates them into API calls to the Overlord web server. |
| MQTT Broker | N/A | A central message broker for communication between Homebridge/MQTT-Thing and Node-RED. |
| Pi-hole | v6 | The DNS filtering service. The API is used to enable/disable domain blocklists. |
| Ubiquiti Network Controller | 9.4.19 (Last Tested) | The network management service. The API is used to enable/disable firewall rules and block/unblock devices. |
| PiHole6API | 0.2.0 | A Python library used internally to communicate with the Pi-hole v6 API. |
Sources: README.md:15-20, README.md:25-26, etc/webserver_requirements.txt:21
Python Environment
The core application is a Python web server built with FastAPI and run using Gunicorn.
Sources: README.md:17, AGENTS.md:12
Python Version
The project requires a specific version of Python to run.
- Required Version:
>=3.12
Sources: pyproject.toml:5, AGENTS.md:11
Key Dependencies
The application relies on several key Python packages. These are installed via the etc/webserver_requirements.txt file.
| Package | Version | Role |
|---|---|---|
fastapi | >=0.115.12 | The web framework used to build the API. |
gunicorn | >=23.0.0 | The WSGI HTTP server used to run the application in production. |
uvicorn | 0.34.2 | The ASGI server used for local development. |
pihole6api | 0.2.0 | Client library for interacting with the Pi-hole v6 API. |
requests | 2.32.4 | Used to make HTTP requests to the Ubiquiti Network API. |
aiomqtt | 2.4.0 | Asynchronous client for publishing "Last Will and Testament" (LWT) status messages to the MQTT broker. |
pydantic | 2.11.4 | Used for data validation and settings management in the FastAPI application. |
Sources: etc/webserver_requirements.txt, AGENTS.md:12-13, AGENTS.md:72-77
Configuration
The application is configured through a combination of a config.ini file and environment variables.
Sources: cgi-bin/controller.py:53-56, README.md:36-43
Environment Variables
These variables are typically set in an envfile when running the container.
| Variable | Description | Example |
|---|---|---|
DNS_SERVERS | Comma-separated list of Pi-hole server IP addresses. | 192.168.1.10,192.168.1.11 |
REMOTE_PI_PASSWORD | The admin password for the Pi-hole instances. | your_pihole_password |
REMOTE_PI_LIST | Space-separated list of Pi-hole server IP addresses. | "192.168.1.10 192.168.1.11" |
MQTT_BROKER | The IP address of the MQTT broker. | 192.168.1.5 |
MQTT_PORT | The port for the MQTT broker. | 1883 |
REMOTE_UBIQUITI_DEVICE | The IP address of the UniFi controller. | 192.168.1.1 |
REMOTE_UBIQUITI_API_KEY | The API key for the UniFi controller. | your_unifi_api_key |
Sources: README.md:37-43, AGENTS.md:54-61
config.ini File
The config.ini file provides more detailed configuration for the application's features. The application reads this file on startup to enable/disable modules and define targets.
Sources: cgi-bin/controller.py:53-145
| Section | Key | Description |
|---|---|---|
[general] | pihole_control_enabled | Set to true to enable Pi-hole integration. |
[general] | ubiquiti_control_enabled | Set to true to enable Ubiquiti integration. |
[general] | mqtt_announce_enabled | Set to true to publish service status to MQTT LWT topics. |
[mqtt] | broker, port, lwt_topics | Defines MQTT connection details and topics for status announcements. |
[ubiquiti] | remote_ubiquiti_device, remote_ubiquiti_api_key | Defines UniFi controller connection details. |
[ubiquiti_targets] | (custom_name) | Defines groups of MAC addresses to be controlled as a single target. |
[ubiquiti_rules] | (custom_name) | Defines firewall rule names to be controlled. |
[block_domains] | (custom_name) | Defines groups of regex domains to be blocked on Pi-hole. |
[allow_domains] | (custom_name) | Defines groups of regex domains to be allowed on Pi-hole. |
Sources: AGENTS.md:63-70, cgi-bin/controller.py:61-145
Integration Setup
Node-RED Flow
Node-RED is the critical link between the MQTT messages sent by HomeKit and the web server's API. An example flow is provided in node_red_flows/dns.json. This flow must be imported into your Node-RED instance and configured with the correct MQTT broker and web server endpoint.
The flow listens to specific MQTT topics, parses the target and command, and constructs the appropriate HTTP request to the Overlord API.
The following diagram shows the logic for handling a Pi-hole media domain change request.
This flowchart illustrates how a command received on an MQTT topic is processed by Node-RED and sent to the web server, with the resulting status published back to a status topic.
Sources: node_red_flows/dns.json, README.md:50-52
Homebridge MQTT-Thing Configuration
To create the switches in HomeKit, you must configure the homebridge-mqttthing plugin. The configuration maps a switch's state and actions to MQTT topics that Node-RED subscribes to.
Here is an example configuration for a switch named "HBO" that controls a domain block.
{
"type": "switch",
"name": "HBO",
"debounceRecvms": 100,
"topics": {
"getOnline": "stat/dns_controller/master/service_status",
"getOn": "stat/dns_controller/media/hbomax/status",
"setOn": "cmnd/dns_controller/media/hbomax/change"
},
"accessory": "mqttthing"
}
getOn: The topic MQTT-Thing subscribes to for the switch's current state (on/off).setOn: The topic MQTT-Thing publishes to when the switch is toggled.
Sources: README.md:56-70