Backend API Endpoints

Relevant source files

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

• cgi-bin/controller.py
• cgi-bin/wsgi.py
• lib/ubiquity/ubiquity.py
• lib/pihole/pihole_router.py
• lib/pihole/pihole.py
• lib/pihole/alldns.py
• lib/pihole/base.py
• AGENTS.md

The backend is a FastAPI application that serves as the central control plane for the Overlord Network Kill Switch. Its primary purpose is to expose a simple HTTP API to manage network access controls on Pi-hole DNS servers and Ubiquiti network gateways. This allows orchestration tools like Node-RED to translate MQTT messages from HomeKit into specific actions, such as blocking a domain or disabling a firewall rule.

The API is designed for compatibility with Pi-hole v6 (via the pihole6api library) and Ubiquiti Network controllers. The application is launched using Gunicorn and Uvicorn, as specified in cgi-bin/wsgi.py and cgi-bin/gunicorn_config.py. It is structured into modular routers for different services, making it extensible.

Sources: cgi-bin/controller.py:18-32, README.md:4-8, cgi-bin/wsgi.py

Application Initialization and Lifespan

The application's startup and shutdown logic is managed by an asynccontextmanager function named lifespan within cgi-bin/controller.py. This function is responsible for initializing all necessary components before the server starts accepting requests and cleaning them up on shutdown.

The initialization process follows these steps:

1. Configuration Loading: The init_config function reads settings from ../etc/config.ini. It parses general settings, Pi-hole domain lists, Ubiquiti targets, and MQTT broker details.
2. Controller Initialization: Based on the loaded configuration, it initializes the PiHoleOverlord, MasterEnabler, and UbiquitiOverlord controllers if they are enabled (pihole_control_enabled, ubiquiti_control_enabled).
3. Router Inclusion: The FastAPI routers for Pi-hole (/pihole, /alldns) and Ubiquiti (/ubiquiti) are included in the main application.
4. MQTT LWT Publication: If enabled, it publishes a "true" message to the configured MQTT Last Will and Testament (LWT) topics to signal that the service is online.

Upon shutdown, the lifespan manager calls the shutdown() method on each active controller to close sessions and publishes a "false" message to the MQTT LWT topics.

Sources: cgi-bin/controller.py:195-220

The diagram below illustrates the application startup flow.

Pi-hole Control Endpoints

These endpoints manage DNS filtering on the configured Pi-hole instances. The logic is handled by the PiHoleOverlord and MasterEnabler classes, which are built upon a common BaseHTTPHandler.

Sources: lib/pihole/pihole_router.py, lib/pihole/pihole.py, lib/pihole/alldns.py

The following diagram shows the class inheritance for Pi-hole controllers.

Domain Group Management (/pihole)

This router, prefixed with /pihole, allows for enabling and disabling predefined groups of domains. These groups are configured in config.ini under [block_domains] and [allow_domains]. The PiHoleOverlord class uses the pihole6api library to communicate with Pi-hole instances.

Sources: lib/pihole/pihole_router.py:40-59, lib/pihole/pihole.py

Method	Path	Description
GET	/pihole/status/{domain_block}	Checks if a 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: lib/pihole/pihole_router.py:46-59, AGENTS.md:31-33

The sequence diagram below shows the process of disabling a domain block.

Global DNS Control (/alldns)

This router, prefixed with /alldns, controls the global blocking status of all connected Pi-hole instances. The MasterEnabler class handles this functionality.

Sources: lib/pihole/pihole_router.py:62-83, lib/pihole/alldns.py

Method	Path	Query Param	Description
GET	/alldns/	-	Gets the global DNS blocking status. Returns true if enabled, false if disabled.
POST	/alldns/	timer: int	Disables DNS blocking globally. An optional timer can be set in seconds.
DELETE	/alldns/	-	Enables DNS blocking globally.

Sources: lib/pihole/pihole_router.py:72-83, AGENTS.md:36-38

The flip_mode method in MasterEnabler is the core of this functionality, calling set_blocking_status on each Pi-hole session. It verifies that all instances report a consistent state afterward.

Sources: lib/pihole/alldns.py:73-90

Ubiquiti Control Endpoints (/ubiquiti)

These endpoints, prefixed with /ubiquiti, interact with a Ubiquiti Network controller (e.g., UniFi Dream Machine) to manage firewall rules and client device connectivity. The logic is encapsulated in the UbiquitiOverlord class. Authentication is performed using an API key, which is a change from previous username/password methods.

Sources: lib/ubiquity/ubiquity.py:60-63, 203-205

Key Features

• API Key Authentication: Connects to the Ubiquiti controller using an X-API-KEY header.
• Firewall Rule Caching: To improve performance, firewall rules are fetched and cached. The cache is considered stale after 60 seconds (rule_cache_ttl), at which point a new fetch is triggered.
• Rule and Device Management: Provides distinct functions for changing the state of firewall rules and blocking/unblocking client devices by MAC address.

Sources: lib/ubiquity/ubiquity.py:203-205, 321-332

The following table details the available endpoints.

Method	Path	Description
GET	/ubiquiti/status_rule/{target}	Gets the status (enabled/disabled) of a named 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 status (online/offline) of a named group of MAC addresses.
GET	/ubiquiti/enable_device/{target}	Unblocks a client device group (sets state to online).
GET	/ubiquiti/disable_device/{target}	Blocks a client device group (sets state to offline).
GET	/ubiquiti/refresh	Forces a refresh of the firewall rules cache from the controller.

Sources: lib/ubiquity/ubiquity.py:539-568, AGENTS.md:41-47

The sequence diagram below illustrates the process of disabling a firewall rule.

Summary

The backend API provides a robust and modular interface for controlling network services. By leveraging FastAPI, it exposes a clear set of endpoints for Pi-hole and Ubiquiti management. The application's lifecycle management ensures reliable initialization and clean shutdown, while features like MQTT LWT integration and caching in the Ubiquiti controller provide status visibility and performance. This architecture effectively decouples the home automation layer (HomeKit/MQTT) from the low-level network device APIs.

Sources: cgi-bin/controller.py, lib/ubiquity/ubiquity.py, lib/pihole/pihole_router.py