Core Feature: Service Groups

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• AGENTS.md
• lib/ubiquity/ubiquity.py
• node_red_flows/dns.json
• pyproject.toml
• cgi-bin/controller.py
• lib/pihole/pihole_router.py
• etc/webserver_requirements.txt
• lib/pihole/alldns.py
• lib/pihole/pihole.py
• pyrightconfig.json
• lib/pihole/base.py
• cgi-bin/gunicorn_config.py
• cgi-bin/wsgi.py

Introduction

Service Groups are a core concept in the Overlord Network Kill Switch project, providing a way to logically bundle network targets—such as domains, client devices, or firewall rules—into manageable units. The primary goal is to simplify network control for non-technical users, allowing them to enable or disable access to specific services (e.g., streaming media, school-related websites) with a single action, typically through a HomeKit switch.

These groups are defined in a central configuration file and are acted upon by the system's main components: the PiHoleOverlord for DNS-level domain blocking and the UbiquitiOverlord for firewall rule and device-level network control. The entire system is orchestrated via an MQTT and HTTP-based architecture, translating simple user commands into complex network configuration changes.

Sources: README.md:5-11, AGENTS.md:5-7, cgi-bin/controller.py:82-131

System Architecture and Data Flow

The system translates a user's action in HomeKit into an API call that manipulates a pre-defined Service Group. This flow involves multiple components, from the user interface to the target network services.

The following diagram illustrates the high-level data flow from a user toggling a switch to the final action on a Pi-hole or Ubiquiti device.

Sources: README.md:100-119, node_red_flows/dns.json

Configuration of Service Groups

Service Groups are defined within the etc/config.ini file. The main application parses this file at startup to configure the behavior of the Pi-hole and Ubiquiti controllers.

Sources: cgi-bin/controller.py:70-74

The following diagram shows how the controller.py module reads the config.ini file and initializes the respective service handlers.

Sources: cgi-bin/controller.py:82-131, lib/pihole/pihole_router.py:25-27, lib/ubiquity/ubiquity.py:530-532

Configuration Sections

The config.ini file uses specific sections to define the different types of service groups.

Section	Purpose	Example Key/Value
[block_domains]	Defines groups of domains (regex) to be blocked by Pi-hole.	hbomax = hbomax.com another.domain.net
[allow_domains]	Defines groups of domains (regex) to be allowed (whitelisted).	school_work = classroom.google.com
[ubiquiti_targets]	Defines groups of client MAC addresses for device-level blocking.	kids_devices = 00:11:22:AA:BB:CC 33:44:55:DD:EE:FF
[ubiquiti_rules]	Defines groups of firewall rules by name to be enabled/disabled.	streaming_rules = Block Streaming Another Rule Name

Sources: cgi-bin/controller.py:91-131, AGENTS.md:65-70

Pi-hole Service Groups (Domain Control)

Pi-hole integration is managed by the PiHoleOverlord and MasterEnabler classes, which handle domain-specific and global DNS blocking, respectively. These classes inherit from BaseHTTPHandler, which manages the connection to the Pi-hole instances using the pihole6api library.

Sources: lib/pihole/pihole.py:21, lib/pihole/alldns.py:21, lib/pihole/base.py:10

Key Classes

Sources: lib/pihole/base.py:10, lib/pihole/pihole.py:21, lib/pihole/alldns.py:21

Domain Group Control Flow

When a request to change a domain group's state is received, the PiHoleOverlord class iterates through the domains defined for that group in config.ini and enables or disables them on all configured Pi-hole instances.

The following sequence diagram shows the process of enabling a domain block group named hbomax.

Sources: node_red_flows/dns.json, lib/pihole/pihole_router.py:50-52, lib/pihole/pihole.py:117-135

Global DNS Control

The MasterEnabler class provides a way to globally enable or disable all DNS blocking on the Pi-hole instances, optionally with a timer.

Sources: lib/pihole/alldns.py:64-74

API Endpoints for Pi-hole Groups

Method	Endpoint	Controller Class	Description
GET	/pihole/status/{domain_block}	PiHoleOverlord	Checks if a domain group is 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 optional timer).
DELETE	/alldns/	MasterEnabler	Enables global DNS blocking.

Sources: lib/pihole/pihole_router.py:38-69, AGENTS.md:32-42

Ubiquiti Service Groups (Firewall & Device Control)

Ubiquiti network control is handled by the UbiquitiOverlord class. It interacts with the UniFi Network Controller API to manage firewall rules and block/unblock client devices based on their MAC addresses. A key feature is the use of a UniFi API Key for authentication, which simplifies the connection process.

Sources: lib/ubiquity/ubiquity.py:51, 186-189

Firewall Rule Groups

The UbiquitiOverlord class can enable or disable firewall rules by name. It maintains a cache of firewall rules, which is refreshed periodically or on-demand to ensure the system has the correct rule IDs.

The change_rule method constructs a payload to update the enabled state of a specific firewall rule and sends it to the UniFi controller's batch update endpoint.

Sources: lib/ubiquity/ubiquity.py:133-152, 321-361

The sequence diagram below illustrates enabling a firewall rule.

Sources: lib/ubiquity/ubiquity.py:321-361, 554-556

Device Groups (MAC-based)

Device groups are collections of MAC addresses defined in config.ini. The change_device method iterates through the MACs in a specified group and sends a command to either block (block-sta) or unblock (unblock-sta) each device.

Sources: lib/ubiquity/ubiquity.py:387-425

API Endpoints for Ubiquiti Groups

Method	Endpoint	Description
GET	/ubiquiti/status_rule/{target}	Get the status (enabled/disabled) of a firewall rule.
GET	/ubiquiti/enable_rule/{target}	Enable a firewall rule by name.
GET	/ubiquiti/disable_rule/{target}	Disable a firewall rule by name.
GET	/ubiquiti/status_device/{target}	Get the block status of a device group.
GET	/ubiquiti/enable_device/{target}	Unblock a group of devices.
GET	/ubiquiti/disable_device/{target}	Block a group of devices.
GET	/ubiquiti/refresh	Force a refresh of the firewall rule cache.

Sources: lib/ubiquity/ubiquity.py:535-565, AGENTS.md:45-56

Conclusion

The "Service Groups" feature is the central abstraction that makes the Overlord Network Kill Switch powerful yet simple to use. By defining logical groups of domains, devices, and firewall rules in a single configuration file, the system provides a unified interface for complex network control tasks. This allows users to manage parental controls or focus time policies with simple on/off switches in their home automation system, abstracting away the underlying interactions with Pi-hole and Ubiquiti APIs.

Sources: README.md:5-11, cgi-bin/controller.py:70-131