Home
Relevant source files
The following files were used as context for generating this wiki page:The Overlord Network Kill Switch is a web server designed to simplify network control for households using Apple's HomeKit. It provides a user-friendly way for non-technical users to manage network access by integrating with Pi-hole for DNS-level domain blocking and Ubiquiti network controllers for device-level or network-range blocking. The primary use cases are implementing parental controls and creating "focus time" by blocking distracting websites.
The system acts as a bridge, translating simple on/off actions from HomeKit switches into API calls to Pi-hole and Ubiquiti services. This is orchestrated through a combination of Homebridge, MQTT, Node-RED, and a central FastAPI web application. The project supports Pi-hole v6 and has been tested with Ubiquiti Control 9.4.19.
Sources: README.md:4-11, README.md:17-19, AGENTS.md:5-6
System Architecture
The project follows a multi-layered architecture that decouples the user interface from the backend network services. The flow begins with a user action in HomeKit and propagates through a message broker and an orchestration layer to the target services.
Sources: README.md:92-117, AGENTS.md:8-10
This diagram illustrates the overall data flow from the user to the target network services and back.
Sources: README.md:92-117
System Components
The system is composed of several key external and internal components that work together.
| Component | Description |
|---|---|
| HomeKit | Apple's smart home framework, providing the user interface on iOS devices. |
| Homebridge | A lightweight server that emulates the HomeKit API, allowing non-certified devices to appear in HomeKit. |
| homebridge-mqttthing | A Homebridge plugin that creates HomeKit accessories (like switches) controlled via MQTT topics. |
| MQTT Broker | A message broker that facilitates communication between homebridge-mqttthing and Node-RED. |
| Node-RED | A flow-based development tool used for orchestration. It subscribes to MQTT topics, parses messages, and makes HTTP requests to the FastAPI server. |
| FastAPI Server | The core of the project. A Python web server that exposes a REST API to control Pi-hole and Ubiquiti devices. |
| Pi-hole | A network-level ad and tracker blocking application. Used here for DNS-based domain filtering. |
| Ubiquiti Network Controller | The management software for Ubiquiti networking hardware. Used here to control firewall rules and block/unblock client devices. |
Sources: README.md:13-18, AGENTS.md:8-10
Project Structure
The repository is organized into directories for the web application, libraries, configuration, and examples.
| Directory | Purpose |
|---|---|
cgi-bin/ | Contains the FastAPI application source code, including the main controller, WSGI entry point, and Gunicorn configuration. |
lib/ | Houses the core logic for interacting with external services. Subdirectories pihole/ and ubiquity/ contain the respective integration classes. |
etc/ | Holds configuration files, including config.ini.sample, envfile.sample, and Python dependency list webserver_requirements.txt. |
node_red_flows/ | Provides an example Node-RED flow (dns.json) for parsing MQTT messages and calling the API. |
Sources: AGENTS.md:15-33
Core Application (FastAPI Server)
The heart of the system is a FastAPI application, run by a Gunicorn server, that provides the control logic and API endpoints.
Sources: cgi-bin/controller.py, cgi-bin/gunicorn_config.py
Application Lifespan
The application uses FastAPI's lifespan context manager to initialize and shut down resources gracefully.
This flowchart shows the sequence of initialization and shutdown events managed by the lifespan function in controller.py.
Sources: cgi-bin/controller.py:170-194
Configuration Loading
On startup, the init_config function reads settings from ../etc/config.ini and environment variables. It populates an app_config dictionary that is passed to the Pi-hole and Ubiquiti modules. This function determines which features (Pi-hole control, Ubiquiti control, MQTT announcements) are enabled.
Sources: cgi-bin/controller.py:65-155
API Endpoints
The FastAPI server exposes endpoints to manage Pi-hole and Ubiquiti devices.
Sources: AGENTS.md:35-55, lib/pihole/pihole_router.py, lib/ubiquity/ubiquity.py
Pi-hole Control (/pihole)
| Method | Endpoint | Description |
|---|---|---|
GET | /pihole/status/{domain_block} | Checks if a specific domain block group is enabled. |
POST | /pihole/enable/{domain_block} | Enables a domain block group. |
POST | /pihole/disable/{domain_block} | Disables a domain block group. |
Sources: AGENTS.md:38-40, lib/pihole/pihole_router.py:46-58
Global DNS Control (/alldns)
| Method | Endpoint | Description |
|---|---|---|
GET | /alldns/ | Gets the global DNS blocking status across all Pi-holes. |
POST | /alldns/ | Disables DNS blocking. Accepts an optional timer query parameter. |
DELETE | /alldns/ | Enables DNS blocking. |
Sources: AGENTS.md:42-44, lib/pihole/pihole_router.py:68-79
Ubiquiti Control (/ubiquiti)
| Method | Endpoint | Description |
|---|---|---|
GET | /ubiquiti/status_rule/{target} | Gets the status of a firewall rule. |
GET | /ubiquiti/enable_rule/{target} | Enables a firewall rule. |
GET | /ubiquiti/disable_rule/{target} | Disables a firewall rule. |
GET | /ubiquiti/status_device/{target} | Gets the block status of a device group. |
GET | /ubiquiti/enable_device/{target} | Unblocks a device group (sets to 'online'). |
GET | /ubiquiti/disable_device/{target} | Blocks a device group (sets to 'offline'). |
GET | /ubiquiti/refresh | Forces a refresh of the cached firewall rules from the controller. |
Sources: AGENTS.md:46-55, lib/ubiquity/ubiquity.py:488-518
Key Classes
The core logic is encapsulated in several Pydantic BaseModel classes that manage state and interaction with the target APIs.
Sources: AGENTS.md:68-72, lib/pihole/base.py, lib/pihole/pihole.py, lib/pihole/alldns.py, lib/ubiquity/ubiquity.py
This diagram shows the main classes. PiHoleOverlord and MasterEnabler inherit from a common BaseHTTPHandler for managing connections to Pi-hole instances, while UbiquitiOverlord manages the connection to the UniFi controller.
Sources: lib/pihole/base.py:11, lib/pihole/pihole.py:25, lib/pihole/alldns.py:21, lib/ubiquity/ubiquity.py:34
Data Flow: HomeKit to Pi-hole
The following sequence diagram details the process of a user toggling a switch in HomeKit to block a domain group (e.g., "hbomax").
This flow demonstrates how a simple user action is translated through multiple components to execute a command on the Pi-hole and then report the updated status back to the user interface.
Sources: README.md:62-70, node_red_flows/dns.json, README.md:92-117
Summary
The Overlord Network Kill Switch provides a powerful yet simple solution for home network management. By leveraging standard home automation tools like Homebridge and MQTT, it creates a seamless bridge between the user-friendly HomeKit environment and the technical backends of Pi-hole and Ubiquiti. Its modular architecture, centered around a FastAPI server, allows for clear separation of concerns and easy extension, making it a flexible tool for parental controls, productivity, and general network administration.
Sources: README.md:4-11, AGENTS.md:5-6