Core Feature: Per-Device Control
Relevant source files
The following files were used as context for generating this wiki page:The Overlord Network Kill Switch provides a simplified interface for managing network access on a per-device or per-service basis. The primary goal is to allow non-technical users to perform actions like enabling parental controls or focus time by toggling switches in Apple's HomeKit. This is achieved by abstracting the complexities of Pi-hole DNS filtering and Ubiquiti network device management into a simple API, which is then orchestrated via MQTT and Node-RED.
This system offers two main methods of control: direct device blocking using a Ubiquiti controller to block MAC addresses, and service-level blocking by enabling or disabling domain groups (regex lists) on Pi-hole instances. While Pi-hole control affects all devices using it for DNS, it is presented to the end-user as a service-specific switch (e.g., "Block HBO Max").
Sources: README.md:4-10, AGENTS.md:5-7
System Architecture
The control flow begins with a user action in HomeKit, which is translated into an MQTT message by homebridge-mqttthing. A Node-RED instance subscribes to these MQTT topics, parses the message, and makes a corresponding HTTP request to the Gunicorn/FastAPI web server. The server then executes the command against the appropriate backend service, either a Pi-hole or a Ubiquiti Network Controller.
Sources: README.md:104-124, AGENTS.md:8-10
The following diagram illustrates the high-level data flow from the user to the target network services.
Sources: README.md:104-124, node_red_flows/dns.json
Control Modules
The core logic is divided into modules for Pi-hole and Ubiquiti, each managed by a primary class. The main application in controller.py initializes these modules based on the config.ini settings.
Sources: cgi-bin/controller.py:186-193
Ubiquiti Device & Rule Control
This is the most direct form of per-device control, enabling the blocking and unblocking of specific clients based on their MAC addresses. It can also manage firewall rules. This functionality is encapsulated within the UbiquitiOverlord class.
Sources: lib/ubiquity/ubiquity.py, AGENTS.md:41-47
Key Components
UbiquitiOverlordClass: Manages the session and API communication with the Ubiquiti Network Controller. It uses an API key for authentication.- Configuration (
config.ini): Device and rule targets are defined in the configuration file.[ubiquiti_targets]: Defines groups of MAC addresses.[ubiquiti_rules]: Defines firewall rules to be managed.
- API Endpoints: The module exposes FastAPI endpoints to trigger actions.
Sources: lib/ubiquity/ubiquity.py:53-89, cgi-bin/controller.py:121-133
Device Blocking Flow
The sequence diagram below shows how a request to disable a device group is processed.
Pi-hole Domain Control
This module allows for enabling and disabling groups of domains, which are defined as regex patterns in the configuration. This is used to block specific services (e.g., streaming, social media) across all devices that use the Pi-hole for DNS resolution.
Sources: lib/pihole/pihole.py, README.md:5-7
Key Components
PiHoleOverlordClass: A handler that connects to one or more Pi-hole instances using thepihole6apilibrary and manages domain lists. It inherits fromBaseHTTPHandler.MasterEnablerClass: Manages global enabling/disabling of DNS blocking across all configured Pi-holes.- Configuration (
config.ini):[block_domains]: Defines groups of regex patterns to be added to the Pi-hole blocklist.[allow_domains]: Defines groups of regex patterns to be added to the Pi-hole allowlist.
- API Endpoints: FastAPI routes for enabling, disabling, and checking the status of domain blocks.
Sources: lib/pihole/pihole.py:27-33, lib/pihole/alldns.py:20-26, lib/pihole/base.py:10-23, cgi-bin/controller.py:97-101
Domain Blocking Flow
The following diagram shows the process of disabling a domain block group (e.g., hbomax).
Configuration
Control targets are defined in etc/config.ini. The main application parses this file to configure the Pi-hole and Ubiquiti modules.
Sources: cgi-bin/controller.py:72-154
| Section | Key | Description | Example |
|---|---|---|---|
[general] | ubiquiti_control_enabled | Enables or disables the Ubiquiti control module. | true |
[general] | pihole_control_enabled | Enables or disables the Pi-hole control module. | true |
[ubiquiti_targets] | {group_name} | A named group of MAC addresses to be controlled as a single unit. | kids_devices = 00:11:22:.. |
[ubiquiti_rules] | {group_name} | A named firewall rule to be managed. | streaming_block = Block Streaming |
[block_domains] | {service_name} | A named group of domains (regex) to be blocked via Pi-hole. | hbomax = hbo.com (.*\.)?hbo.com |
[allow_domains] | {service_name} | A named group of domains (regex) to be allowed (whitelisted) via Pi-hole. | school_work = google.com |
Sources: cgi-bin/controller.py:82-133, AGENTS.md:51-55
API Endpoints
The FastAPI application exposes several endpoints that are consumed by the Node-RED orchestration layer.
Sources: lib/pihole/pihole_router.py:33-71, lib/ubiquity/ubiquity.py:587-626, [AGENTS.md:29-47]
| Method | Endpoint | Controller Class | Description |
|---|---|---|---|
GET | /ubiquiti/status_device/{target} | UbiquitiOverlord | Gets the block/unblock status of a device group. |
GET | /ubiquiti/enable_device/{target} | UbiquitiOverlord | Unblocks a device group (online). |
GET | /ubiquiti/disable_device/{target} | UbiquitiOverlord | Blocks a device group (offline). |
GET | /ubiquiti/status_rule/{target} | UbiquitiOverlord | Gets the enabled/disabled status of a firewall rule. |
GET | /ubiquiti/enable_rule/{target} | UbiquitiOverlord | Enables a firewall rule. |
GET | /ubiquiti/disable_rule/{target} | UbiquitiOverlord | Disables a firewall rule. |
GET | /pihole/status/{domain_block} | PiHoleOverlord | Checks if all domains in a block group are enabled. |
POST | /pihole/enable/{domain_block} | PiHoleOverlord | Enables a domain block group. |
POST | /pihole/disable/{domain_block} | PiHoleOverlord | Disables a domain block group. |
GET | /alldns/ | MasterEnabler | Gets the global DNS blocking status. |
POST | /alldns/ | MasterEnabler | Disables global DNS blocking, with an optional timer. |
DELETE | /alldns/ | MasterEnabler | Enables global DNS blocking. |
Summary
The "Per-Device Control" feature is a powerful abstraction layer over standard network management tools. By combining Ubiquiti's device-level MAC blocking and Pi-hole's service-level domain filtering, the system provides a flexible and user-friendly way to manage network access. The architecture, centered around a FastAPI server and orchestrated by MQTT, allows for seamless integration with home automation platforms like HomeKit, effectively simplifying complex network administration tasks into the toggle of a switch.
Sources: README.md:4-10, AGENTS.md:5-7